Data Structures | Macros | Typedefs | Enumerations | Functions
Timer.h File Reference

Detailed Description

Timer driver.


Overview

The timer driver allows you to measure elapsed time with simple and portable APIs.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

This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.

Synopsis

// Import Timer Driver definitions
Timer_Handle handle;
Timer_Params params;
params.period = 1000;
params.timerCallback = UserCallbackFunction;
handle = Timer_open(CONFIG_TIMER0, &params);
@code
// Import Timer Driver definitions
Timer_Handle handle;
Timer_Params params;
// Initialize Timer parameters
params.period = 1000;
params.timerCallback = UserCallbackFunction;
// Open Timer instance
handle = Timer_open(CONFIG_TIMER0, &params);
sleep(10000);
Timer_stop(handle);

Examples

Opening a Timer instance

Timer_Handle handle;
Timer_Params params;
handle = Timer_open(CONFIG_TIMER0, &params);
if (handle == NULL) {
// Timer_open() failed
while (1);
}

Configuring Timer mode and period

The following example code opens a timer in continuous callback mode. The period is set to 1000 Hz.

Timer_Handle handle;
Timer_Params params;
params.period = 1000;
params.timerCallback = UserCallbackFunction;
handle = Timer_open(CONFIG_TIMER0, &params);
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);

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[].


Configuration

Refer to the Driver's Configuration section for driver configuration information.


#include <stdint.h>
Include dependency graph for Timer.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Timer_Params
 Timer Parameters. More...
 
struct  Timer_FxnTable
 The definition of a timer function table that contains the required set of functions to control a specific timer driver implementation. More...
 
struct  Timer_Config_
 Timer Global configuration. More...
 

Macros

#define Timer_CMD_RESERVED   (32)
 
#define Timer_STATUS_RESERVED   (-32)
 
#define Timer_STATUS_SUCCESS   (0)
 Successful status code. More...
 
#define Timer_STATUS_ERROR   (-1)
 Generic error status code. More...
 
#define Timer_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by Timer_control() for undefined command codes. More...
 

Typedefs

typedef struct Timer_Config_Timer_Handle
 A handle that is returned from a Timer_open() call. More...
 
typedef void(* Timer_CallBackFxn) (Timer_Handle handle)
 Timer callback function. More...
 
typedef 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(). More...
 
typedef void(* Timer_CloseFxn) (Timer_Handle handle)
 A function pointer to a driver specific implementation of Timer_close(). More...
 
typedef uint32_t(* Timer_GetCountFxn) (Timer_Handle handle)
 A function pointer to a driver specific implementation of Timer_getCount(). More...
 
typedef void(* Timer_InitFxn) (Timer_Handle handle)
 A function pointer to a driver specific implementation of Timer_init(). More...
 
typedef Timer_Handle(* Timer_OpenFxn) (Timer_Handle handle, Timer_Params *params)
 A function pointer to a driver specific implementation of Timer_open(). More...
 
typedef int32_t(* Timer_SetPeriodFxn) (Timer_Handle handle, Timer_PeriodUnits periodUnits, uint32_t period)
 A function pointer to a driver specific implementation of Timer_setPeriod(). More...
 
typedef int32_t(* Timer_StartFxn) (Timer_Handle handle)
 A function pointer to a driver specific implementation of Timer_start(). More...
 
typedef void(* Timer_StopFxn) (Timer_Handle handle)
 A function pointer to a driver specific implementation of Timer_stop(). More...
 
typedef struct Timer_Config_ Timer_Config
 Timer Global configuration. More...
 

Enumerations

enum  Timer_Mode { Timer_ONESHOT_CALLBACK, Timer_ONESHOT_BLOCKING, Timer_CONTINUOUS_CALLBACK, Timer_FREE_RUNNING }
 Timer mode settings. More...
 
enum  Timer_PeriodUnits { Timer_PERIOD_US, Timer_PERIOD_HZ, Timer_PERIOD_COUNTS }
 Timer period unit enum. More...
 

Functions

void Timer_close (Timer_Handle handle)
 Function to close a timer. The corresponding timer to the Timer_Handle becomes an available timer resource. More...
 
int_fast16_t Timer_control (Timer_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs device specific features on a given Timer_Handle. More...
 
uint32_t Timer_getCount (Timer_Handle handle)
 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. More...
 
void Timer_init (void)
 Function to initialize a timer module. This function will go through all available hardware resources and mark them as "available". More...
 
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 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. More...
 
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. More...
 
void Timer_Params_init (Timer_Params *params)
 Function to initialize the Timer_Params struct to its defaults. More...
 
int32_t Timer_start (Timer_Handle handle)
 Function to start the timer. More...
 
void Timer_stop (Timer_Handle handle)
 Function to stop timer. If the timer is already stopped, this function has no effect. More...
 

Macro Definition Documentation

§ Timer_CMD_RESERVED

#define Timer_CMD_RESERVED   (32)

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:

#define TimerXYZ_CMD_COMMAND0 Timer_CMD_RESERVED + 0
#define TimerXYZ_CMD_COMMAND1 Timer_CMD_RESERVED + 1

§ Timer_STATUS_RESERVED

#define Timer_STATUS_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:

#define TimerXYZ_STATUS_ERROR0 Timer_STATUS_RESERVED - 0
#define TimerXYZ_STATUS_ERROR1 Timer_STATUS_RESERVED - 1

§ Timer_STATUS_SUCCESS

#define Timer_STATUS_SUCCESS   (0)

Successful status code.

§ Timer_STATUS_ERROR

#define Timer_STATUS_ERROR   (-1)

Generic error status code.

§ Timer_STATUS_UNDEFINEDCMD

#define Timer_STATUS_UNDEFINEDCMD   (-2)

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.

Typedef Documentation

§ Timer_Handle

typedef struct Timer_Config_* Timer_Handle

A handle that is returned from a Timer_open() call.

§ Timer_CallBackFxn

typedef void(* Timer_CallBackFxn) (Timer_Handle handle)

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.

Parameters
[in]handleTimer_Handle

§ Timer_ControlFxn

typedef 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().

§ Timer_CloseFxn

typedef void(* Timer_CloseFxn) (Timer_Handle handle)

A function pointer to a driver specific implementation of Timer_close().

§ Timer_GetCountFxn

typedef uint32_t(* Timer_GetCountFxn) (Timer_Handle handle)

A function pointer to a driver specific implementation of Timer_getCount().

§ Timer_InitFxn

typedef void(* Timer_InitFxn) (Timer_Handle handle)

A function pointer to a driver specific implementation of Timer_init().

§ Timer_OpenFxn

typedef Timer_Handle(* Timer_OpenFxn) (Timer_Handle handle, Timer_Params *params)

A function pointer to a driver specific implementation of Timer_open().

§ Timer_SetPeriodFxn

typedef int32_t(* Timer_SetPeriodFxn) (Timer_Handle handle, Timer_PeriodUnits periodUnits, uint32_t period)

A function pointer to a driver specific implementation of Timer_setPeriod().

§ Timer_StartFxn

typedef int32_t(* Timer_StartFxn) (Timer_Handle handle)

A function pointer to a driver specific implementation of Timer_start().

§ Timer_StopFxn

typedef void(* Timer_StopFxn) (Timer_Handle handle)

A function pointer to a driver specific implementation of Timer_stop().

§ Timer_Config

typedef struct Timer_Config_ Timer_Config

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.

See also
Timer_init()

Enumeration Type Documentation

§ Timer_Mode

enum Timer_Mode

Timer mode settings.

This enum defines the timer modes that may be specified in Timer_Params.

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.

Enumerator
Timer_ONESHOT_CALLBACK 

Is a non-blocking call. 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 unblockedimmediately. The behavior of the timer in this mode is similar to a sleep function.

Timer_CONTINUOUS_CALLBACK 

Is a non-blocking call. 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 is automatically restarted and will continue to periodically generate interrupts until Timer_stop() is called.

Timer_FREE_RUNNING 

Is a non-blocking call. 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.

§ Timer_PeriodUnits

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.

Enumerator
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.

Function Documentation

§ Timer_close()

void Timer_close ( Timer_Handle  handle)

Function to close a timer. The corresponding timer to the Timer_Handle becomes an available timer resource.

Precondition
Timer_open() has been called.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
See also
Timer_open()

§ Timer_control()

int_fast16_t Timer_control ( Timer_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs device specific features on a given Timer_Handle.

Precondition
Timer_open() has been called.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
[in]cmdA command value defined by the driver specific implementation.
[in]argA pointer to an optional R/W (read/write) argument that is accompanied with cmd.
Return values
Timer_STATUS_SUCCESSThe control call was successful.
Timer_STATUS_ERRORThe control call failed
See also
Timer_open()

§ Timer_getCount()

uint32_t Timer_getCount ( Timer_Handle  handle)

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.

Precondition
Timer_open() has been called.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
See also
Timer_open()
Returns
The current count of the timer in timer ticks.

§ Timer_init()

void Timer_init ( void  )

Function to initialize a timer module. This function will go through all available hardware resources and mark them as "available".

Precondition
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.
See also
Timer_open()

§ Timer_open()

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 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.

Precondition
Timer_init() has been called.
Parameters
[in]indexLogical peripheral number for the timer indexed into the Timer_config table.
[in]paramsPointer to an parameter block, if NULL it will use default values.
Returns
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.
See also
Timer_init()
Timer_close()

§ Timer_setPeriod()

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.

Precondition
Timer_open() has been called. It is also recommended Timer_stop() has been called on an already running timer before calling this API as the period is updated asynchronously.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
[in]periodUnitsTimer_PeriodUnits of the desired period value.
[in]periodPeriod value to set.
Return values
Timer_STATUS_SUCCESSThe setPeriod call was successful.
Timer_STATUS_ERRORThe setPeriod call failed
See also
Timer_open()
Timer_stop()

§ Timer_Params_init()

void Timer_Params_init ( Timer_Params params)

Function to initialize the Timer_Params struct to its defaults.

Parameters
[in]paramsA pointer to Timer_Params structure for initialization.

Defaults values are: timerMode = Timer_ONESHOT_BLOCKING periodUnit = Timer_PERIOD_COUNTS timerCallback = NULL period = (uint16_t) ~0

§ Timer_start()

int32_t Timer_start ( Timer_Handle  handle)

Function to start the timer.

Precondition
Timer_open() has been called.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
Return values
Timer_STATUS_SUCCESSThe start call was successful.
Timer_STATUS_ERRORThe start call failed
See also
Timer_stop()

§ Timer_stop()

void Timer_stop ( Timer_Handle  handle)

Function to stop timer. If the timer is already stopped, this function has no effect.

Precondition
Timer_open() has been called.
Parameters
[in]handleA Timer_Handle returned from Timer_open().
See also
Timer_start()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale