Timer.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2019, 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
35  *
36  * @anchor ti_drivers_Timer_Overview
37  * # Overview
38  * The timer driver allows you to measure elapsed time with simple and
39  * portable APIs.This driver does not have PWM or capture functionalities.
40  * These functionalities are addressed in both the capture and PWM driver.
41  *
42  * The timer driver also handles the general purpose timer resource allocation.
43  * For each driver that requires use of a general purpose timer, it calls
44  * Timer_open() to occupy the specified timer, and calls Timer_close() to
45  * release the occupied timer resource.
46  *
47  * @anchor ti_drivers_Timer_Usage
48  * # Usage
49  *
50  * This documentation provides a basic @ref ti_drivers_Timer_Synopsis
51  * "usage summary" and a set of @ref ti_drivers_Timer_Examples "examples"
52  * in the form of commented code fragments. Detailed descriptions of the
53  * APIs are provided in subsequent sections.
54  *
55  * @anchor ti_drivers_Timer_Synopsis
56  * ## Synopsis
57  * @anchor ti_drivers_Timer_Synopsis_Code
58  * @code
59  * // Import Timer Driver definitions
60  * #include <ti/drivers/Timer.h>
61  *
62  * Timer_Handle handle;
63  * Timer_Params params;
64  *
65  * Timer_Params_init(&params);
66  * params.periodUnits = Timer_PERIOD_HZ;
67  * params.period = 1000;
68  * params.timerMode = Timer_CONTINUOUS_CALLBACK;
69  * params.timerCallback = UserCallbackFunction;
70  *
71  * handle = Timer_open(CONFIG_TIMER0, &params);
72  *
73  * @code
74  * // Import Timer Driver definitions
75  * #include <ti/drivers/Timer.h>
76  *
77  * Timer_Handle handle;
78  * Timer_Params params;
79  *
80  * // Initialize Timer parameters
81  * Timer_Params_init(&params);
82  * params.periodUnits = Timer_PERIOD_HZ;
83  * params.period = 1000;
84  * params.timerMode = Timer_CONTINUOUS_CALLBACK;
85  * params.timerCallback = UserCallbackFunction;
86  *
87  * // Open Timer instance
88  * handle = Timer_open(CONFIG_TIMER0, &params);
89  *
90  * sleep(10000);
91  *
92  * Timer_stop(handle);
93  * @endcode
94  *
95  * <hr>
96  * @anchor ti_drivers_Timer_Examples
97  * # Examples
98  *
99  * @li @ref ti_drivers_Timer_Examples_open "Opening a Timer Instance"
100  * @li @ref ti_drivers_Timer_Examples_mode "Configuring Timer mode and period"
101  *
102  * @anchor ti_drivers_Timer_Examples_open
103  * ## Opening a Timer instance
104  *
105  * @code
106  * Timer_Handle handle;
107  * Timer_Params params;
108  *
109  * Timer_Params_init(&params);
110  * handle = Timer_open(CONFIG_TIMER0, &params);
111  *
112  * if (handle == NULL) {
113  * // Timer_open() failed
114  * while (1);
115  * }
116  @endcode
117  *
118  * @anchor ti_drivers_Timer_Examples_mode
119  * ##Configuring Timer mode and period
120  *
121  * The following example code opens a timer in continuous callback mode. The
122  * period is set to 1000 Hz.
123  *
124  * @code
125  * Timer_Handle handle;
126  * Timer_Params params;
127  *
128  * Timer_Params_init(&params);
129  * params.periodUnits = Timer_PERIOD_HZ;
130  * params.period = 1000;
131  * params.timerMode = Timer_CONTINUOUS_CALLBACK;
132  * params.timerCallback = UserCallbackFunction;
133  *
134  * handle = Timer_open(CONFIG_TIMER0, &params);
135  *
136  * if (handle == NULL) {
137  * // Timer_open() failed
138  * while (1);
139  * }
140  *
141  * status = Timer_start(handle);
142  *
143  * if (status == Timer_STATUS_ERROR) {
144  * //Timer_start() failed
145  * while (1);
146  * }
147  *
148  * sleep(10000);
149  *
150  * Timer_stop(handle);
151  * @endcode
152  *
153  * ### Initializing the Timer Driver #
154  *
155  * Timer_init() must be called before any other timer APIs. This function
156  * calls the device implementation's timer initialization function, for each
157  * element of Timer_config[].
158  *
159  * <hr>
160  * @anchor ti_drivers_Timer_Configuration
161  * # Configuration
162  *
163  * Refer to the @ref driver_configuration "Driver's Configuration" section
164  * for driver configuration information.
165  * <hr>
166 *******************************************************************************
167  */
168 
169 #ifndef ti_drivers_Timer__include
170 #define ti_drivers_Timer__include
171 
172 #include <stdint.h>
173 
174 #ifdef __cplusplus
175 extern "C"
176 {
177 #endif
178 
190 #define Timer_CMD_RESERVED (32)
191 
203 #define Timer_STATUS_RESERVED (-32)
204 
208 #define Timer_STATUS_SUCCESS (0)
209 
213 #define Timer_STATUS_ERROR (-1)
214 
222 #define Timer_STATUS_UNDEFINEDCMD (-2)
223 
227 typedef struct Timer_Config_ *Timer_Handle;
228 
239 typedef enum {
274 } Timer_Mode;
275 
282 typedef enum {
289 
299 typedef void (*Timer_CallBackFxn)(Timer_Handle handle);
300 
308 typedef struct {
310  Timer_Mode timerMode;
311 
313  Timer_PeriodUnits periodUnits;
314 
318 
320  uint32_t period;
321 } Timer_Params;
322 
327 typedef int_fast16_t (*Timer_ControlFxn)(Timer_Handle handle,
328  uint_fast16_t cmd, void *arg);
329 
334 typedef void (*Timer_CloseFxn)(Timer_Handle handle);
335 
340 typedef uint32_t (*Timer_GetCountFxn)(Timer_Handle handle);
341 
346 typedef void (*Timer_InitFxn)(Timer_Handle handle);
347 
352 typedef Timer_Handle (*Timer_OpenFxn)(Timer_Handle handle,
353  Timer_Params *params);
354 
359 typedef int32_t (*Timer_SetPeriodFxn)(Timer_Handle handle,
360  Timer_PeriodUnits periodUnits, uint32_t period);
361 
366 typedef int32_t (*Timer_StartFxn)(Timer_Handle handle);
367 
372 typedef void (*Timer_StopFxn)(Timer_Handle handle);
373 
379 typedef struct {
382 
385 
388 
391 
394 
397 
400 
404 
416 typedef struct Timer_Config_ {
419 
421  void *object;
422 
424  void const *hwAttrs;
425 } Timer_Config;
426 
437 extern void Timer_close(Timer_Handle handle);
438 
458 extern int_fast16_t Timer_control(Timer_Handle handle, uint_fast16_t cmd,
459  void *arg);
460 
477 extern uint32_t Timer_getCount(Timer_Handle handle);
478 
479 
490 extern void Timer_init(void);
491 
516 extern Timer_Handle Timer_open(uint_least8_t index, Timer_Params *params);
517 
538 extern int32_t Timer_setPeriod(Timer_Handle handle, Timer_PeriodUnits periodUnits, uint32_t period);
539 
552 extern void Timer_Params_init(Timer_Params *params);
553 
566 extern int32_t Timer_start(Timer_Handle handle);
567 
578 extern void Timer_stop(Timer_Handle handle);
579 
580 #ifdef __cplusplus
581 }
582 #endif
583 
584 #endif /* ti_drivers_Timer__include */
Timer_FxnTable const * fxnTablePtr
Definition: Timer.h:418
Timer_Handle(* Timer_OpenFxn)(Timer_Handle handle, Timer_Params *params)
A function pointer to a driver specific implementation of Timer_open().
Definition: Timer.h:352
Timer_CallBackFxn timerCallback
Definition: Timer.h:317
Timer_PeriodUnits
Timer period unit enum.
Definition: Timer.h:282
Timer_InitFxn initFxn
Definition: Timer.h:390
Timer_CloseFxn closeFxn
Definition: Timer.h:381
Timer_PeriodUnits periodUnits
Definition: Timer.h:313
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...
Definition: Timer.h:268
void Timer_init(void)
Function to initialize a timer module. This function will go through all available hardware resources...
Definition: Timer.h:284
struct Timer_Config_ Timer_Config
Timer Global configuration.
void const * hwAttrs
Definition: Timer.h:424
void Timer_Params_init(Timer_Params *params)
Function to initialize the Timer_Params struct to its defaults.
Timer Global configuration.
Definition: Timer.h:416
uint32_t(* Timer_GetCountFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_getCount().
Definition: Timer.h:340
Timer_StopFxn stopFxn
Definition: Timer.h:402
Definition: Timer.h:283
int32_t Timer_setPeriod(Timer_Handle handle, Timer_PeriodUnits periodUnits, uint32_t period)
Function to set the period of the timer module after it has been opened.
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:366
int32_t(* Timer_SetPeriodFxn)(Timer_Handle handle, Timer_PeriodUnits periodUnits, uint32_t period)
A function pointer to a driver specific implementation of Timer_setPeriod().
Definition: Timer.h:359
Definition: Timer.h:259
void(* Timer_CloseFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_close().
Definition: Timer.h:334
void * object
Definition: Timer.h:421
Timer_SetPeriodFxn setPeriodFxn
Definition: Timer.h:396
void(* Timer_StopFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_stop().
Definition: Timer.h:372
Timer_GetCountFxn getCountFxn
Definition: Timer.h:387
Definition: Timer.h:286
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...
Timer_OpenFxn openFxn
Definition: Timer.h:393
Timer_ControlFxn controlFxn
Definition: Timer.h:384
Timer Parameters.
Definition: Timer.h:308
void Timer_stop(Timer_Handle handle)
Function to stop timer. If the timer is already stopped, this function has no effect.
Timer_Mode
Timer mode settings.
Definition: Timer.h:239
The definition of a timer function table that contains the required set of functions to control a spe...
Definition: Timer.h:379
uint32_t period
Definition: Timer.h:320
Definition: Timer.h:251
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:327
Timer_StartFxn startFxn
Definition: Timer.h:399
void(* Timer_CallBackFxn)(Timer_Handle handle)
Timer callback function.
Definition: Timer.h:299
void(* Timer_InitFxn)(Timer_Handle handle)
A function pointer to a driver specific implementation of Timer_init().
Definition: Timer.h:346
Definition: Timer.h:240
Timer_Mode timerMode
Definition: Timer.h:310
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:227
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale