Timer.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2017, 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  * @brief Timer driver interface
35  *
36  * The timer header file should be included in an application as follows:
37  * @code
38  * #include <ti/drivers/Timer.h>
39  * @endcode
40  *
41  * # Overview #
42  * The timer driver serves as the main interface for a typical RTOS
43  * application. Its purpose is to redirect the timer APIs to device specific
44  * implementations which are specified using a pointer to a #Timer_FxnTable.
45  * The device specific implementations are responsible for creating all the
46  * RTOS specific primitives to allow for thead-safe operation. This driver
47  * does not have PWM or capture functionalities. These functionalities are
48  * addressed in both the capture and PWM driver.
49  *
50  * The timer driver also handles the general purpose timer resource allocation.
51  * For each driver that requires use of a general purpose timer, it calls
52  * Timer_open() to occupy the specified timer, and calls Timer_close() to
53  * release the occupied timer resource.
54  *
55  * # Usage #
56  * The following example code opens a timer in continuous callback mode. The
57  * period is set to 1000 Hz.
58  *
59  * @code
60  * Timer_Handle handle;
61  * Timer_Params params;
62  *
63  * Timer_Params_init(&params);
64  * params.periodUnits = Timer_PERIOD_HZ;
65  * params.period = 1000;
66  * params.timerMode = Timer_CONTINUOUS_CALLBACK;
67  * params.timerCallback = someTimerCallbackFunction;
68  *
69  * handle = Timer_open(Board_TIMER0, &params);
70  *
71  * if (handle == NULL) {
72  * // Timer_open() failed
73  * while (1);
74  * }
75  *
76  * status = Timer_start(handle);
77  *
78  * if (status == Timer_STATUS_ERROR) {
79  * //Timer_start() failed
80  * while (1);
81  * }
82  *
83  * sleep(10000);
84  *
85  * Timer_stop(handle);
86  * @endcode
87  *
88  * ### Timer Driver Configuration #
89  *
90  * In order to use the timer APIs, the application is required to provide
91  * device specific timer configuration in the Board.c file. The timer driver
92  * interface defines a configuration data structure:
93  *
94  * @code
95  * typedef struct Timer_Config_ {
96  * Timer_FxnTable const *fxnTablePtr;
97  * void *object;
98  * void const *hwAttrs;
99  * } Timer_Config;
100  * @endcode
101  *
102  * The application must declare an array of Timer_Config elements, named
103  * Timer_config[]. Each element of Timer_config[] are populated with
104  * pointers to a device specific timer driver implementation's function
105  * table, driver object, and hardware attributes. The hardware attributes
106  * define properties such as the timer peripheral's base address, interrupt
107  * number and interrupt priority. Each element in Timer_config[] corresponds
108  * to a timer instance, and none of the elements should have NULL pointers.
109  * There is no correlation between the index and the peripheral designation
110  * (such as TIMER0 or TIMER1). For example, it is possible to use
111  * Timer_config[0] for TIMER1.
112  *
113  * You will need to check the device specific timer driver implementation's
114  * header file for example configuration.
115  *
116  * ### Initializing the Timer Driver #
117  *
118  * Timer_init() must be called before any other timer APIs. This function
119  * calls the device implementation's timer initialization function, for each
120  * element of Timer_config[].
121  *
122  * ### Modes of Operation #
123  *
124  * The timer driver supports four modes of operation which may be specified in
125  * the Timer_Params. The device specific implementation may configure the timer
126  * peripheral as an up or down counter. In any case, Timer_getCount() will
127  * return a value characteristic of an up counter.
128  *
129  * #Timer_ONESHOT_CALLBACK is non-blocking. After Timer_start() is called,
130  * the calling thread will continue execution. When the timer interrupt
131  * is triggered, the specified callback function will be called. The timer
132  * will not generate another interrupt unless Timer_start() is called again.
133  * Calling Timer_stop() or Timer_close() after Timer_start() but, before the
134  * timer interrupt, will prevent the specified callback from ever being
135  * invoked.
136  *
137  * #Timer_ONESHOT_BLOCKING is a blocking call. A semaphore is used to block
138  * the calling thread's execution until the timer generates an interrupt. If
139  * Timer_stop() is called, the calling thread will become unblocked
140  * immediately. The behavior of the timer in this mode is similar to a sleep
141  * function.
142  *
143  * #Timer_CONTINUOUS_CALLBACK is non-blocking. After Timer_start() is called,
144  * the calling thread will continue execution. When the timer interrupt is
145  * treiggered, the specified callback function will be called. The timer is
146  * automatically restarted and will continue to periodically generate
147  * interrupts until Timer_stop() is called.
148  *
149  * #Timer_FREE_RUNNING is non-blocking. After Timer_start() is called,
150  * the calling thread will continue execution. The timer will not
151  * generate an interrupt in this mode. The timer hardware will run until
152  * Timer_stop() is called.
153  *
154  * # Implementation #
155  *
156  * The timer driver interface module is joined (at link time) to an
157  * array of Timer_Config data structures named *Timer_config*.
158  * Timer_config is implemented in the application with each entry being an
159  * instance of a timer peripheral. Each entry in *Timer_config* contains a:
160  * - (Timer_FxnTable *) to a set of functions that implement a timer peripheral
161  * - (void *) data object that is associated with the Timer_FxnTable
162  * - (void *) hardware attributes that are associated with the Timer_FxnTable
163  *
164  * The timer APIs are redirected to the device specific implementations
165  * using the Timer_FxnTable pointer of the Timer_config entry.
166  * In order to use device specific functions of the timer driver directly,
167  * link in the correct driver library for your device and include the
168  * device specific timer driver header file (which in turn includes Timer.h).
169  * For example, for the MSP432 family of devices, you would include the
170  * following header file:
171  *
172  * @code
173  * #include <ti/drivers/timer/TimerMSP432.h>
174  * @endcode
175  *
176  * ============================================================================
177  */
178 
179 #ifndef ti_drivers_Timer__include
180 #define ti_drivers_Timer__include
181 
182 #ifdef __cplusplus
183 extern "C"
184 {
185 #endif
186 
187 #include <stdint.h>
188 
200 #define Timer_CMD_RESERVED (32)
201 
213 #define Timer_STATUS_RESERVED (-32)
214 
218 #define Timer_STATUS_SUCCESS (0)
219 
223 #define Timer_STATUS_ERROR (-1)
224 
232 #define Timer_STATUS_UNDEFINEDCMD (-2)
233 
237 typedef struct Timer_Config_ *Timer_Handle;
238 
244 typedef enum Timer_Mode_ {
255 } Timer_Mode;
256 
263 typedef enum Timer_PeriodUnits_ {
270 
280 typedef void (*Timer_CallBackFxn)(Timer_Handle handle);
281 
289 typedef struct Timer_Params_ {
291  Timer_Mode timerMode;
292 
294  Timer_PeriodUnits periodUnits;
295 
299 
301  uint32_t period;
302 } Timer_Params;
303 
308 typedef int_fast16_t (*Timer_ControlFxn)(Timer_Handle handle,
309  uint_fast16_t cmd, void *arg);
310 
315 typedef void (*Timer_CloseFxn)(Timer_Handle handle);
316 
321 typedef uint32_t (*Timer_GetCountFxn)(Timer_Handle handle);
322 
327 typedef void (*Timer_InitFxn)(Timer_Handle handle);
328 
333 typedef Timer_Handle (*Timer_OpenFxn)(Timer_Handle handle,
334  Timer_Params *params);
335 
340 typedef int32_t (*Timer_StartFxn)(Timer_Handle handle);
341 
346 typedef void (*Timer_StopFxn)(Timer_Handle handle);
347 
353 typedef struct Timer_FxnTable_ {
356 
359 
362 
365 
368 
371 
375 
387 typedef struct Timer_Config_ {
390 
392  void *object;
393 
395  void const *hwAttrs;
396 } Timer_Config;
397 
408 extern void Timer_close(Timer_Handle handle);
409 
429 extern int_fast16_t Timer_control(Timer_Handle handle, uint_fast16_t cmd,
430  void *arg);
431 
448 extern uint32_t Timer_getCount(Timer_Handle handle);
449 
450 
461 extern void Timer_init(void);
462 
487 extern Timer_Handle Timer_open(uint_least8_t index, Timer_Params *params);
488 
501 extern void Timer_Params_init(Timer_Params *params);
502 
514 extern int32_t Timer_start(Timer_Handle handle);
515 
526 extern void Timer_stop(Timer_Handle handle);
527 
528 /* The following are included for backwards compatibility. These should not be
529  * used by the application.
530  */
531 #define TIMER_CMD_RESERVED Timer_CMD_RESERVED
532 #define TIMER_STATUS_RESERVED Timer_STATUS_RESERVED
533 #define TIMER_STATUS_SUCCESS Timer_STATUS_SUCCESS
534 #define TIMER_STATUS_ERROR Timer_STATUS_ERROR
535 #define TIMER_STATUS_UNDEFINEDCMD Timer_STATUS_UNDEFINEDCMD
536 #define TIMER_ONESHOT_CB Timer_ONESHOT_CALLBACK
537 #define TIMER_ONESHOT_BLOCK Timer_ONESHOT_BLOCKING
538 #define TIMER_CONTINUOUS_CB Timer_CONTINUOUS_CALLBACK
539 #define TIMER_MODE_FREE_RUNNING Timer_FREE_RUNNING
540 #define TIMER_PERIOD_US Timer_PERIOD_US
541 #define TIMER_PERIOD_HZ Timer_PERIOD_HZ
542 #define TIMER_PERIOD_COUNTS Timer_PERIOD_COUNTS
543 #define Timer_Period_Units Timer_PeriodUnits
544 
545 #ifdef __cplusplus
546 }
547 #endif
548 
549 #endif /* ti_drivers_Timer__include */
Timer_Mode timerMode
Definition: Timer.h:291
Timer_FxnTable const * fxnTablePtr
Definition: Timer.h:389
Timer_Handle(* Timer_OpenFxn)(Timer_Handle handle, Timer_Params *params)
A function pointer to a driver specific implementation of Timer_open().
Definition: Timer.h:333
struct Timer_FxnTable_ Timer_FxnTable
The definition of a timer function table that contains the required set of functions to control a spe...
Definition: Timer.h:267
Timer Parameters.
Definition: Timer.h:289
The definition of a timer function table that contains the required set of functions to control a spe...
Definition: Timer.h:353
Timer_Handle Timer_open(uint_least8_t index, Timer_Params *params)
Function to initialize a given timer peripheral specified by the index argument. The Timer_Params spe...
Timer_Mode_
Timer mode settings.
Definition: Timer.h:244
void Timer_init(void)
Function to initialize a timer module. This function will go through all available hardware resources...
struct Timer_Config_ Timer_Config
Timer Global configuration.
void const * hwAttrs
Definition: Timer.h:395
void Timer_Params_init(Timer_Params *params)
Function to initialize the Timer_Params struct to its defaults.
Timer Global configuration.
Definition: Timer.h:387
Timer_OpenFxn openFxn
Definition: Timer.h:367
uint32_t(* Timer_GetCountFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_getCount().
Definition: Timer.h:321
enum Timer_Mode_ Timer_Mode
Timer mode settings.
Timer_CloseFxn closeFxn
Definition: Timer.h:355
Timer_PeriodUnits_
Timer period unit enum.
Definition: Timer.h:263
Definition: Timer.h:251
uint32_t period
Definition: Timer.h:301
Timer_PeriodUnits periodUnits
Definition: Timer.h:294
void Timer_close(Timer_Handle handle)
Function to close a timer. The corresponding timer to the Timer_Handle becomes an available timer res...
int32_t(* Timer_StartFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_start().
Definition: Timer.h:340
enum Timer_PeriodUnits_ Timer_PeriodUnits
Timer period unit enum.
Timer_StartFxn startFxn
Definition: Timer.h:370
Timer_GetCountFxn getCountFxn
Definition: Timer.h:361
void(* Timer_CloseFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_close().
Definition: Timer.h:315
Definition: Timer.h:265
void * object
Definition: Timer.h:392
void(* Timer_StopFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_stop().
Definition: Timer.h:346
Definition: Timer.h:254
int_fast16_t Timer_control(Timer_Handle handle, uint_fast16_t cmd, void *arg)
Function performs device specific features on a given Timer_Handle.
uint32_t Timer_getCount(Timer_Handle handle)
Function to get the current count of a timer. The value returned represents timer counts...
Definition: Timer.h:249
Timer_ControlFxn controlFxn
Definition: Timer.h:358
void Timer_stop(Timer_Handle handle)
Function to stop timer. If the timer is already stopped, this function has no effect.
Timer_StopFxn stopFxn
Definition: Timer.h:373
struct Timer_Params_ Timer_Params
Timer Parameters.
Timer_InitFxn initFxn
Definition: Timer.h:364
Timer_CallBackFxn timerCallback
Definition: Timer.h:298
int_fast16_t(* Timer_ControlFxn)(Timer_Handle handle, uint_fast16_t cmd, void *arg)
A function pointer to a driver specific implementation of Timer_control().
Definition: Timer.h:308
Definition: Timer.h:264
Definition: Timer.h:245
void(* Timer_CallBackFxn)(Timer_Handle handle)
Timer callback function.
Definition: Timer.h:280
void(* Timer_InitFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_init().
Definition: Timer.h:327
int32_t Timer_start(Timer_Handle handle)
Function to start the timer.
struct Timer_Config_ * Timer_Handle
A handle that is returned from a Timer_open() call.
Definition: Timer.h:237
Copyright 2017, Texas Instruments Incorporated