git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/Timer.h

   1 /*
   2  * Copyright (c) 2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       Timer.h
  34  *
  35  *  @brief      Timer driver interface
  36  *
  37  *  The Timer header file should be included in an application as follows:
  38  *  @code
  39  *  #include <ti/drivers/Timer.h>
  40  *  @endcode
  41  *
  42  *  # Operation #
  43  *  The Timer driver operates as a generic timer interface for timing interval
  44  *  handling. It can be configured to run in one-shot blocking mode,
  45  *  one-shot callback mode, continuous callback mode, or free-run mode. This
  46  *  driver does not have PWM or capture functionalities. These functionalities
  47  *  are addressed in both the Capture and PWM driver modules.
  48  *
  49  *  The Timer driver also handles the general purpose timer resource allocation.
  50  *  For the driver that requires to use the general purpose timer, it calls
  51  *  Timer_open() to occupy the specified timer, and calls Timer_close() to release
  52  *  the occupied timer resource.
  53  *
  54  *  ## Opening the Driver ##
  55  *
  56  *  @code
  57  *  Timer_Handle      handle;
  58  *  Timer_Params      params;
  59  *
  60  *  Timer_Params_init(&params);
  61  *  params.mode  = TIMER_MODE_CONTINUOUS_CALLBACK;
  62  *  params.callbackFxn = someTimerCallbackFunction;
  63  *  params.periodUnit = TIMER_PERIOD_US;
  64  *  params.period = 5000000
  65  *  handle = Timer_open(someTimer_configIndexValue, &params);
  66  *  if (!handle)
  67  *  {
  68  *      System_printf("Timer did not open");
  69  *  }
  70  *
  71  *  ## Starting the Driver ##
  72
  73  *  @code
  74  *  status = Timer_start(handle);
  75  *  if (status == TIMER_STATUS_ERROR)
  76  *  {
  77  *      System_printf("Timer cannot start at specified period");
  78  *  }
  79  *  @endcode
  80  *
  81  *  ## Stopping the driver ##
  82  *
  83  *  @code
  84  *  Timer_stop(handle);
  85  *  @endcode
  86  *
  87  *  ## closing the driver ##
  88  *
  89  *  @code
  90  *  Timer_close(handle);
  91  *  @endcode
  92  *
  93  *  # Implementation #
  94  *
  95  *  This module serves as the main interface for TI Drivers
  96  *  applications. Its purpose is to redirect the module's APIs to specific
  97  *  peripheral implementations which are specified using a pointer to a
  98  *  Timer_FxnTable.
  99  *
 100  *  The Timer driver interface module is joined (at link time) to a
 101  *  NULL-terminated array of Timer_Config data structures named *Timer_config*.
 102  *  *Timer_config* is implemented in the application with each entry being an
 103  *  instance of a Timer peripheral. Each entry in *Timer_config* contains a:
 104  *  - (Timer_FxnTable *) to a set of functions that implement a Timer peripheral
 105  *  - (void *) data object that is associated with the Timer_FxnTable
 106  *  - (void *) hardware attributes that are associated to the Timer_FxnTable
 107  *
 108  *  # Instrumentation #
 109  *  The Timer driver interface produces log statements if instrumentation is
 110  *  enabled.
 111  *
 112  *  ============================================================================
 113  */
 114 #ifndef ti_drivers_Timer__include
 115 #define ti_drivers_Timer__include
 116
 117 #include <stdint.h>
 118
 119 #ifdef __cplusplus
 120 extern "C"
 121 {
 122 #endif
 123
 124 /*!
 125  *  @brief      A handle that is returned from a Timer_open() call.
 126  */
 127 typedef struct Timer_Config_ *Timer_Handle;
 128
 129 /*!
 130  * Common Timer_control command code reservation offset.
 131  * Timer driver implementations should offset command codes with TIMER_CMD_RESERVED
 132  * growing positively
 133  *
 134  * Example implementation specific command codes:
 135  * @code
 136  * #define TIMERXYZ_CMD_COMMAND0      TIMER_CMD_RESERVED + 0
 137  * #define TIMERXYZ_CMD_COMMAND1      TIMER_CMD_RESERVED + 1
 138  * @endcode
 139  */
 140 #define TIMER_CMD_RESERVED                (32)
 141
 142 /*!
 143  * Common Timer_control status code reservation offset.
 144  * Timer driver implementations should offset status codes with
 145  * TIMER_STATUS_RESERVED growing negatively.
 146  *
 147  * Example implementation specific status codes:
 148  * @code
 149  * #define TIMERXYZ_STATUS_ERROR0     TIMER_STATUS_RESERVED - 0
 150  * #define TIMERXYZ_STATUS_ERROR1     TIMER_STATUS_RESERVED - 1
 151  * #define TIMERXYZ_STATUS_ERROR2     TIMER_STATUS_RESERVED - 2
 152  * @endcode
 153  */
 154 #define TIMER_STATUS_RESERVED            (-32)
 155
 156 /*!
 157  * @brief   Successful status code returned by Timer_control().
 158  *
 159  * Timer_control() returns TIMER_STATUS_SUCCESS if the control code was executed
 160  * successfully.
 161  */
 162 #define TIMER_STATUS_SUCCESS               (0)
 163
 164 /*!
 165  * @brief   Generic error status code returned by Timer_control().
 166  *
 167  * Timer_control() returns TIMER_STATUS_ERROR if the control code was not executed
 168  * successfully.
 169  */
 170 #define TIMER_STATUS_ERROR                (-1)
 171
 172 /*!
 173  * @brief   An error status code returned by Timer_control() for undefined
 174  * command codes.
 175  *
 176  * Timer_control() returns TIMER_STATUS_UNDEFINEDCMD if the control code is not
 177  * recognized by the driver implementation.
 178  */
 179 #define TIMER_STATUS_UNDEFINEDCMD         (-2)
 180
 181 /*!
 182  *  @brief Timer mode enum
 183  *
 184  *  The Timer mode needs to be passed in Timer_open() to specify the timer running
 185  *  mode which handles the interrupt differently.
 186  *
 187  */
 188 typedef enum Timer_Mode_
 189 {
 190     TIMER_ONESHOT_CB, /*!< User routine doesn't get blocked and user-specified
 191      callback function is invoked once the timer interrupt happens for only one time */
 192     TIMER_ONESHOT_BLOCK, /*!< User routine gets blocked until timer interrupt
 193      happens for only one time */
 194     TIMER_CONTINUOUS_CB, /*!< User routine doesn't get blocked and user-specified
 195      callback function is invoked every time the timer interrupt happens */
 196     TIMER_MODE_FREE_RUNNING
 197 } Timer_Mode;
 198
 199 /*!
 200  *  @brief Timer period unit enum
 201  *
 202  *  The Timer period unit needs to be passed in Timer_open() to
 203  *  specify the unit of timing interval.
 204  *
 205  */
 206 typedef enum Timer_Period_Units_
 207 {
 208     TIMER_PERIOD_US, /* Period in microseconds */
 209     TIMER_PERIOD_HZ, /* Period in frequency */
 210     TIMER_PERIOD_COUNTS /* Period in counts */
 211 } Timer_Period_Units;
 212
 213 /*!
 214  *  @brief  Timer callback function
 215  *
 216  *  User definable callback function prototype. The Timer driver will call the
 217  *  defined function and pass in the Timer driver's handle and the pointer to the
 218  *  user-specified the argument.
 219  *
 220  *  @param  handle         Timer_Handle
 221  */
 222 typedef void (*Timer_CallBackFxn)(Timer_Handle handle);
 223
 224 /*!
 225  *  @brief Timer Parameters
 226  *
 227  *  Timer parameters are used to with the Timer_open() call. Default values for
 228  *  these parameters are set using Timer_Params_init().
 229  *
 230  */
 231 typedef struct Timer_Params_
 232 {
 233     Timer_Mode timerMode;
 234     Timer_Period_Units periodUnits;
 235     Timer_CallBackFxn timerCallback;
 236     uint32_t period;
 237 } Timer_Params;
 238
 239 /*!
 240  *  @brief      A function pointer to a driver specific implementation of
 241  *              Timer_control().
 242  */
 243 typedef int_fast16_t (*Timer_ControlFxn)(Timer_Handle handle, uint_fast16_t cmd,
 244         void *arg);
 245
 246 /*!
 247  *  @brief      A function pointer to a driver specific implementation of
 248  *              Timer_close().
 249  */
 250 typedef void (*Timer_CloseFxn)(Timer_Handle handle);
 251
 252 /*!
 253  *  @brief      A function pointer to a driver specific implementation of
 254  *              Timer_getCount().
 255  */
 256 typedef uint32_t (*Timer_GetCountFxn)(Timer_Handle handle);
 257
 258 /*!
 259  *  @brief      A function pointer to a driver specific implementation of
 260  *              Timer_init().
 261  */
 262 typedef void (*Timer_InitFxn)(Timer_Handle handle);
 263
 264 /*!
 265  *  @brief      A function pointer to a driver specific implementation of
 266  *              Timer_open().
 267  */
 268 typedef Timer_Handle (*Timer_OpenFxn)(Timer_Handle handle,
 269         Timer_Params *params);
 270
 271 /*!
 272  *  @brief      A function pointer to a driver specific implementation of
 273  *              Timer_start().
 274  */
 275 typedef void (*Timer_StartFxn)(Timer_Handle handle);
 276
 277 /*!
 278  *  @brief      A function pointer to a driver specific implementation of
 279  *              Timer_stop().
 280  */
 281 typedef void (*Timer_StopFxn)(Timer_Handle handle);
 282
 283 /*!
 284  *  @brief      The definition of a Timer function table that contains the
 285  *              required set of functions to control a specific Timer driver
 286  *              implementation.
 287  */
 288 typedef struct Timer_FxnTable_
 289 {
 290     /*! Function to close the specified instance */
 291     Timer_CloseFxn closeFxn;
 292     /*! Function to send contorl commands to the counter for a specific instance */
 293     Timer_ControlFxn controlFxn;
 294     /*! Function to get the count of the timer for a specific instance */
 295     Timer_GetCountFxn getCountFxn;
 296     /*! Function to open the specified instance */
 297     Timer_InitFxn initFxn;
 298     /*! Function to open the specified instance */
 299     Timer_OpenFxn openFxn;
 300     /*! Function to start the timer for a specific instance */
 301     Timer_StartFxn startFxn;
 302     /*! Function to stop the timer for a specific instance */
 303     Timer_StopFxn stopFxn;
 304 } Timer_FxnTable;
 305
 306 typedef struct Timer_Config_
 307 {
 308     Timer_FxnTable const *fxnTablePtr;
 309     void *object;
 310     void const *hwAttrs;
 311 } Timer_Config;
 312
 313 /*!
 314  *  @brief  Function performs implementation specific features on a given
 315  *          Timer_Handle.
 316  *
 317  *  @pre    Timer_open() must have been called first.
 318  *
 319  *  @param  handle      A Timer_Handle returned from Timer_open().
 320  *
 321  *  @param  cmd         A command value defined by the driver specific
 322  *                      implementation.
 323  *
 324  *  @param  arg         A pointer to an optional R/W (read/write) argument that
 325  *                      is accompanied with cmd.
 326  *
 327  *  @return A Timer_Status describing an error or success state. Negative values
 328  *          indicate an error occurred.
 329  *
 330  *  @sa     Timer_open()
 331  */
 332 extern int_fast16_t Timer_control(Timer_Handle handle, uint_fast16_t cmd,
 333                                   void *arg);
 334
 335
 336 /*!
 337  *  @brief  Function to close a Timer peripheral specified by the Timer handle
 338  *
 339  *  The function takes care of timer resource allocation. The corresponding timer
 340  *  resource to the Timer_Handle is released to be an available timer resource.
 341  *
 342  *  @pre    Timer_open() had to be called first.
 343  *
 344  *  @param  handle  A Timer_Handle returned from Timer_open
 345  *
 346  *  @sa     Timer_open()
 347  */
 348 extern void Timer_close(Timer_Handle handle);
 349
 350 /*!
 351  *  @brief  Function to get the current count of a started timer
 352  *
 353  *  @pre    Timer_open() had to be called first.
 354  *
 355  *  @param  handle  A Timer_Handle returned from Timer_open
 356  *
 357  *  @sa     Timer_open()
 358  *
 359  *  @return The current count of the specified Timer
 360  *
 361  */
 362 extern uint32_t Timer_getCount(Timer_Handle handle);
 363
 364
 365 /*!
 366  *  @brief  Function to initialize a timer module. This function will go through
 367  *  all available hardware resources and mark them as "available"
 368  *
 369  *  @sa     Timer_open()
 370  */
 371 extern void Timer_init(void);
 372
 373 /*!
 374  *  @brief  Function to initialize a given Timer peripheral specified by the
 375  *          particular index value. The parameter specifies which mode the Timer
 376  *          will operate.
 377  *
 378  *  The function takes care of timer resource allocation. If the particular timer
 379  *  passed by user has already been used by other modules, the return value is NULL.
 380  *  If the particular timer is available to use, Timer module owns it and returns
 381  *  a Timer_Handle.
 382  *
 383  *  @param  index         Logical peripheral number for the Timer indexed into
 384  *                        the Timer_config table
 385  *
 386  *  @param  params        Pointer to an parameter block, if NULL it will use
 387  *                        default values. All the fields in this structure are
 388  *                        RO (read-only).
 389  *
 390  *  @return A Timer_Handle on success or a NULL on an error if it has been
 391  *          opened already or used by other modules.
 392  *
 393  *  @sa     Timer_init()
 394  *  @sa     Timer_close()
 395  */
 396 extern Timer_Handle Timer_open(uint_least8_t index, Timer_Params *params);
 397
 398 /*!
 399  *  @brief  Function to initialize the Timer_Params struct to its defaults
 400  *
 401  *  @param  params      An pointer to Timer_Params structure for
 402  *                      initialization
 403  *
 404  *  Defaults values are:
 405  *      mode = TIMER_MODE_ONESHOT_BLOCKING
 406  *      callbackFxn = NULL
 407  *      periodUnit = TIMER_PERIOD_US
 408  *      period = 0xFFFF
 409  */
 410 extern void Timer_Params_init(Timer_Params *params);
 411
 412 /*!
 413  *  @brief  Function to start Timer with the given period. The timer running mode
 414  *          and interval period unit are specified in the Timer_Params when calling
 415  *          Timer_open().
 416  *
 417  *  @param  handle        Timer_Handle
 418  *
 419  *  @return TIMER_STATUS_SUCCESS if timer starts successfully.
 420  *          TIMER_STATUS_ERROR if timer fails to start.
 421  *
 422  */
 423 extern void Timer_start(Timer_Handle handle);
 424
 425 /*!
 426  *  @brief  Function to stop timer after Timer_start() is called with success.
 427  *
 428  *  @param  handle        Timer_Handle
 429  *
 430  */
 431 extern void Timer_stop(Timer_Handle handle);
 432
 433 #ifdef __cplusplus
 434 }
 435 #endif
 436
 437 #endif /* ti_driver_Timer__include */