| /* |
| * Copyright (c) 2016-2017, Texas Instruments Incorporated |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions |
| * are met: |
| * |
| * * Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * |
| * * Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in the |
| * documentation and/or other materials provided with the distribution. |
| * |
| * * Neither the name of Texas Instruments Incorporated nor the names of |
| * its contributors may be used to endorse or promote products derived |
| * from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, |
| * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR |
| * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; |
| * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
| * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR |
| * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, |
| * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| */ |
| /*!***************************************************************************** |
| * @file Timer.h |
| * @brief Timer driver interface |
| * |
| * The timer header file should be included in an application as follows: |
| * @code |
| * #include <ti/drivers/Timer.h> |
| * @endcode |
| * |
| * # Overview # |
| * The timer driver serves as the main interface for a typical RTOS |
| * application. Its purpose is to redirect the timer APIs to device specific |
| * implementations which are specified using a pointer to a #Timer_FxnTable. |
| * The device specific implementations are responsible for creating all the |
| * RTOS specific primitives to allow for thead-safe operation. This driver |
| * does not have PWM or capture functionalities. These functionalities are |
| * addressed in both the capture and PWM driver. |
| * |
| * The timer driver also handles the general purpose timer resource allocation. |
| * For each driver that requires use of a general purpose timer, it calls |
| * Timer_open() to occupy the specified timer, and calls Timer_close() to |
| * release the occupied timer resource. |
| * |
| * # Usage # |
| * The following example code opens a timer in continuous callback mode. The |
| * period is set to 1000 Hz. |
| * |
| * @code |
| * Timer_Handle handle; |
| * Timer_Params params; |
| * |
| * Timer_Params_init(¶ms); |
| * params.periodUnits = Timer_PERIOD_HZ; |
| * params.period = 1000; |
| * params.timerMode = Timer_CONTINUOUS_CALLBACK; |
| * params.timerCallback = someTimerCallbackFunction; |
| * |
| * handle = Timer_open(Board_TIMER0, ¶ms); |
| * |
| * if (handle == NULL) { |
| * // Timer_open() failed |
| * while (1); |
| * } |
| * |
| * status = Timer_start(handle); |
| * |
| * if (status == Timer_STATUS_ERROR) { |
| * //Timer_start() failed |
| * while (1); |
| * } |
| * |
| * sleep(10000); |
| * |
| * Timer_stop(handle); |
| * @endcode |
| * |
| * ### Timer Driver Configuration # |
| * |
| * In order to use the timer APIs, the application is required to provide |
| * device specific timer configuration in the Board.c file. The timer driver |
| * interface defines a configuration data structure: |
| * |
| * @code |
| * typedef struct Timer_Config_ { |
| * Timer_FxnTable const *fxnTablePtr; |
| * void *object; |
| * void const *hwAttrs; |
| * } Timer_Config; |
| * @endcode |
| * |
| * The application must declare an array of Timer_Config elements, named |
| * Timer_config[]. Each element of Timer_config[] are populated with |
| * pointers to a device specific timer driver implementation's function |
| * table, driver object, and hardware attributes. The hardware attributes |
| * define properties such as the timer peripheral's base address, interrupt |
| * number and interrupt priority. Each element in Timer_config[] corresponds |
| * to a timer instance, and none of the elements should have NULL pointers. |
| * There is no correlation between the index and the peripheral designation |
| * (such as TIMER0 or TIMER1). For example, it is possible to use |
| * Timer_config[0] for TIMER1. |
| * |
| * You will need to check the device specific timer driver implementation's |
| * header file for example configuration. |
| * |
| * ### Initializing the Timer Driver # |
| * |
| * Timer_init() must be called before any other timer APIs. This function |
| * calls the device implementation's timer initialization function, for each |
| * element of Timer_config[]. |
| * |
| * ### Modes of Operation # |
| * |
| * The timer driver supports four modes of operation which may be specified in |
| * the Timer_Params. The device specific implementation may configure the timer |
| * peripheral as an up or down counter. In any case, Timer_getCount() will |
| * return a value characteristic of an up counter. |
| * |
| * #Timer_ONESHOT_CALLBACK is non-blocking. After Timer_start() is called, |
| * the calling thread will continue execution. When the timer interrupt |
| * is triggered, the specified callback function will be called. The timer |
| * will not generate another interrupt unless Timer_start() is called again. |
| * Calling Timer_stop() or Timer_close() after Timer_start() but, before the |
| * timer interrupt, will prevent the specified callback from ever being |
| * invoked. |
| * |
| * #Timer_ONESHOT_BLOCKING is a blocking call. A semaphore is used to block |
| * the calling thread's execution until the timer generates an interrupt. If |
| * Timer_stop() is called, the calling thread will become unblocked |
| * immediately. The behavior of the timer in this mode is similar to a sleep |
| * function. |
| * |
| * #Timer_CONTINUOUS_CALLBACK is non-blocking. After Timer_start() is called, |
| * the calling thread will continue execution. When the timer interrupt is |
| * treiggered, the specified callback function will be called. The timer is |
| * automatically restarted and will continue to periodically generate |
| * interrupts until Timer_stop() is called. |
| * |
| * #Timer_FREE_RUNNING is non-blocking. After Timer_start() is called, |
| * the calling thread will continue execution. The timer will not |
| * generate an interrupt in this mode. The timer hardware will run until |
| * Timer_stop() is called. |
| * |
| * # Implementation # |
| * |
| * The timer driver interface module is joined (at link time) to an |
| * array of Timer_Config data structures named *Timer_config*. |
| * Timer_config is implemented in the application with each entry being an |
| * instance of a timer peripheral. Each entry in *Timer_config* contains a: |
| * - (Timer_FxnTable *) to a set of functions that implement a timer peripheral |
| * - (void *) data object that is associated with the Timer_FxnTable |
| * - (void *) hardware attributes that are associated with the Timer_FxnTable |
| * |
| * The timer APIs are redirected to the device specific implementations |
| * using the Timer_FxnTable pointer of the Timer_config entry. |
| * In order to use device specific functions of the timer driver directly, |
| * link in the correct driver library for your device and include the |
| * device specific timer driver header file (which in turn includes Timer.h). |
| * For example, for the MSP432 family of devices, you would include the |
| * following header file: |
| * |
| * @code |
| * #include <ti/drivers/timer/TimerMSP432.h> |
| * @endcode |
| * |
| * ============================================================================ |
| */ |
| |
| #ifndef ti_drivers_Timer__include |
| #define ti_drivers_Timer__include |
| |
| #ifdef __cplusplus |
| extern "C" |
| { |
| #endif |
| |
| #include <stdint.h> |
| |
| /*! |
| * Common Timer_control command code reservation offset. |
| * Timer driver implementations should offset command codes with Timer_CMD_RESERVED |
| * growing positively |
| * |
| * Example implementation specific command codes: |
| * @code |
| * #define TimerXYZ_CMD_COMMAND0 Timer_CMD_RESERVED + 0 |
| * #define TimerXYZ_CMD_COMMAND1 Timer_CMD_RESERVED + 1 |
| * @endcode |
| */ |
| #define Timer_CMD_RESERVED (32) |
| |
| /*! |
| * Common Timer_control status code reservation offset. |
| * Timer driver implementations should offset status codes with |
| * Timer_STATUS_RESERVED growing negatively. |
| * |
| * Example implementation specific status codes: |
| * @code |
| * #define TimerXYZ_STATUS_ERROR0 Timer_STATUS_RESERVED - 0 |
| * #define TimerXYZ_STATUS_ERROR1 Timer_STATUS_RESERVED - 1 |
| * @endcode |
| */ |
| #define Timer_STATUS_RESERVED (-32) |
| |
| /*! |
| * @brief Successful status code. |
| */ |
| #define Timer_STATUS_SUCCESS (0) |
| |
| /*! |
| * @brief Generic error status code. |
| */ |
| #define Timer_STATUS_ERROR (-1) |
| |
| /*! |
| * @brief An error status code returned by Timer_control() for undefined |
| * command codes. |
| * |
| * Timer_control() returns Timer_STATUS_UNDEFINEDCMD if the control code is not |
| * recognized by the driver implementation. |
| */ |
| #define Timer_STATUS_UNDEFINEDCMD (-2) |
| |
| /*! |
| * @brief A handle that is returned from a Timer_open() call. |
| */ |
| typedef struct Timer_Config_ *Timer_Handle; |
| |
| /*! |
| * @brief Timer mode settings |
| * |
| * This enum defines the timer modes that may be specified in #Timer_Params. |
| */ |
| typedef enum Timer_Mode_ { |
| Timer_ONESHOT_CALLBACK, /*!< User routine doesn't get blocked and |
| user-specified callback function is |
| invoked once the timer interrupt happens |
| for only one time */ |
| Timer_ONESHOT_BLOCKING, /*!< User routine gets blocked until timer |
| interrupt happens for only one time. */ |
| Timer_CONTINUOUS_CALLBACK, /*!< User routine doesn't get blocked and |
| user-specified callback function is |
| invoked with every timer interrupt. */ |
| Timer_FREE_RUNNING |
| } Timer_Mode; |
| |
| /*! |
| * @brief Timer period unit enum |
| * |
| * This enum defines the units that may be specified for the period |
| * in #Timer_Params. This unit has no effect with Timer_getCounts. |
| */ |
| typedef enum Timer_PeriodUnits_ { |
| Timer_PERIOD_US, /*!< Period specified in micro seconds. */ |
| Timer_PERIOD_HZ, /*!< Period specified in hertz; interrupts per |
| second. */ |
| Timer_PERIOD_COUNTS /*!< Period specified in ticks or counts. Varies |
| from board to board. */ |
| } Timer_PeriodUnits; |
| |
| /*! |
| * @brief Timer callback function |
| * |
| * User definable callback function prototype. The timer driver will call the |
| * defined function and pass in the timer driver's handle and the pointer to the |
| * user-specified the argument. |
| * |
| * @param handle Timer_Handle |
| */ |
| typedef void (*Timer_CallBackFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief Timer Parameters |
| * |
| * Timer parameters are used to with the Timer_open() call. Default values for |
| * these parameters are set using Timer_Params_init(). |
| * |
| */ |
| typedef struct Timer_Params_ { |
| /*!< Mode to be used by the timer driver. */ |
| Timer_Mode timerMode; |
| |
| /*!< Units used to specify the period. */ |
| Timer_PeriodUnits periodUnits; |
| |
| /*!< Callback function called when timerMode is Timer_ONESHOT_CALLBACK or |
| Timer_CONTINUOUS_CALLBACK. */ |
| Timer_CallBackFxn timerCallback; |
| |
| /*!< Period in units of periodUnits. */ |
| uint32_t period; |
| } Timer_Params; |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_control(). |
| */ |
| typedef int_fast16_t (*Timer_ControlFxn)(Timer_Handle handle, |
| uint_fast16_t cmd, void *arg); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_close(). |
| */ |
| typedef void (*Timer_CloseFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_getCount(). |
| */ |
| typedef uint32_t (*Timer_GetCountFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_init(). |
| */ |
| typedef void (*Timer_InitFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_open(). |
| */ |
| typedef Timer_Handle (*Timer_OpenFxn)(Timer_Handle handle, |
| Timer_Params *params); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_start(). |
| */ |
| typedef int32_t (*Timer_StartFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * Timer_stop(). |
| */ |
| typedef void (*Timer_StopFxn)(Timer_Handle handle); |
| |
| /*! |
| * @brief The definition of a timer function table that contains the |
| * required set of functions to control a specific timer driver |
| * implementation. |
| */ |
| typedef struct Timer_FxnTable_ { |
| /*!< Function to close the specified peripheral. */ |
| Timer_CloseFxn closeFxn; |
| |
| /*!< Function to implementation specific control function. */ |
| Timer_ControlFxn controlFxn; |
| |
| /*!< Function to get the count of the specified peripheral. */ |
| Timer_GetCountFxn getCountFxn; |
| |
| /*!< Function to initialize the given data object. */ |
| Timer_InitFxn initFxn; |
| |
| /*!< Function to open the specified peripheral. */ |
| Timer_OpenFxn openFxn; |
| |
| /*!< Function to start the specified peripheral. */ |
| Timer_StartFxn startFxn; |
| |
| /*!< Function to stop the specified peripheral. */ |
| Timer_StopFxn stopFxn; |
| } Timer_FxnTable; |
| |
| /*! |
| * @brief Timer Global configuration |
| * |
| * The Timer_Config structure contains a set of pointers used to characterize |
| * the timer driver implementation. |
| * |
| * This structure needs to be defined before calling Timer_init() and it must |
| * not be changed thereafter. |
| * |
| * @sa Timer_init() |
| */ |
| typedef struct Timer_Config_ { |
| /*! Pointer to a table of driver-specific implementations of timer APIs. */ |
| Timer_FxnTable const *fxnTablePtr; |
| |
| /*! Pointer to a driver specific data object. */ |
| void *object; |
| |
| /*! Pointer to a driver specific hardware attributes structure. */ |
| void const *hwAttrs; |
| } Timer_Config; |
| |
| /*! |
| * @brief Function to close a timer. The corresponding timer to the |
| * Timer_Handle becomes an available timer resource. |
| * |
| * @pre Timer_open() has been called. |
| * |
| * @param handle A Timer_Handle returned from Timer_open(). |
| * |
| * @sa Timer_open() |
| */ |
| extern void Timer_close(Timer_Handle handle); |
| |
| /*! |
| * @brief Function performs device specific features on a given |
| * Timer_Handle. |
| * |
| * @pre Timer_open() has been called. |
| * |
| * @param handle A Timer_Handle returned from Timer_open(). |
| * |
| * @param cmd A command value defined by the driver specific |
| * implementation. |
| * |
| * @param arg A pointer to an optional R/W (read/write) argument that |
| * is accompanied with cmd. |
| * |
| * @return A Timer_Status describing an error or success state. Negative values |
| * indicate an error occurred. |
| * |
| * @sa Timer_open() |
| */ |
| extern int_fast16_t Timer_control(Timer_Handle handle, uint_fast16_t cmd, |
| void *arg); |
| |
| /*! |
| * @brief Function to get the current count of a timer. The value returned |
| * represents timer counts. The value returned is always |
| * characteristic of an up counter. This is true even if the timer |
| * peripheral is counting down. Some device specific implementations |
| * may employ a prescaler in addition to this timer count. |
| * |
| * @pre Timer_open() has been called. |
| * |
| * @param handle A Timer_Handle returned from Timer_open(). |
| * |
| * @sa Timer_open() |
| * |
| * @return The current count of the timer in timer ticks. |
| * |
| */ |
| extern uint32_t Timer_getCount(Timer_Handle handle); |
| |
| |
| /*! |
| * @brief Function to initialize a timer module. This function will go through |
| * all available hardware resources and mark them as "available". |
| * |
| * @pre The Timer_config structure must exist and be persistent before this |
| * function can be called. This function must also be called before |
| * any other timer driver APIs. |
| * |
| * @sa Timer_open() |
| */ |
| extern void Timer_init(void); |
| |
| /*! |
| * @brief Function to initialize a given timer peripheral specified by the |
| * index argument. The Timer_Params specifies which mode the timer |
| * will operate. The accuracy of the desired period is limited by the |
| * the clock. For example, a 100 MHz clock will have a tick resolution |
| * of 10 nanoseconds. This function takes care of timer resource |
| * allocation. If the particular timer is available to use, the timer |
| * driver owns it and returns a Timer_Handle. |
| * |
| * @pre Timer_init() has been called. |
| * |
| * @param index Logical peripheral number for the timer indexed into |
| * the Timer_config table. |
| * |
| * @param params Pointer to an parameter block, if NULL it will use |
| * default values. |
| * |
| * @return A Timer_Handle upon success or NULL. If the desired period results |
| * in overflow, or saturation, of the timer, NULL is returned. If the |
| * timer resource is already in use, NULL is returned. |
| * |
| * @sa Timer_init() |
| * @sa Timer_close() |
| */ |
| extern Timer_Handle Timer_open(uint_least8_t index, Timer_Params *params); |
| |
| /*! |
| * @brief Function to initialize the Timer_Params struct to its defaults. |
| * |
| * @param params A pointer to Timer_Params structure for |
| * initialization. |
| * |
| * Defaults values are: |
| * timerMode = Timer_ONESHOT_BLOCKING |
| * periodUnit = Timer_PERIOD_COUNTS |
| * timerCallback = NULL |
| * period = (uint16_t) ~0 |
| */ |
| extern void Timer_Params_init(Timer_Params *params); |
| |
| /*! |
| * @brief Function to start the timer. |
| * |
| * @pre Timer_open() has been called. |
| * |
| * @param handle A Timer_Handle returned from Timer_open(). |
| * |
| * @return Timer_STATUS_SUCCESS or Timer_STATUS_ERROR. |
| * |
| * @sa Timer_stop() |
| */ |
| extern int32_t Timer_start(Timer_Handle handle); |
| |
| /*! |
| * @brief Function to stop timer. If the timer is already stopped, this |
| * function has no effect. |
| * |
| * @pre Timer_open() has been called. |
| * |
| * @param handle A Timer_Handle returned from Timer_open(). |
| * |
| * @sa Timer_start() |
| */ |
| extern void Timer_stop(Timer_Handle handle); |
| |
| /* The following are included for backwards compatibility. These should not be |
| * used by the application. |
| */ |
| #define TIMER_CMD_RESERVED Timer_CMD_RESERVED |
| #define TIMER_STATUS_RESERVED Timer_STATUS_RESERVED |
| #define TIMER_STATUS_SUCCESS Timer_STATUS_SUCCESS |
| #define TIMER_STATUS_ERROR Timer_STATUS_ERROR |
| #define TIMER_STATUS_UNDEFINEDCMD Timer_STATUS_UNDEFINEDCMD |
| #define TIMER_ONESHOT_CB Timer_ONESHOT_CALLBACK |
| #define TIMER_ONESHOT_BLOCK Timer_ONESHOT_BLOCKING |
| #define TIMER_CONTINUOUS_CB Timer_CONTINUOUS_CALLBACK |
| #define TIMER_MODE_FREE_RUNNING Timer_FREE_RUNNING |
| #define TIMER_PERIOD_US Timer_PERIOD_US |
| #define TIMER_PERIOD_HZ Timer_PERIOD_HZ |
| #define TIMER_PERIOD_COUNTS Timer_PERIOD_COUNTS |
| #define Timer_Period_Units Timer_PeriodUnits |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* ti_drivers_Timer__include */ |
