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

Detailed Description

Timer driver interface.


The timer header file should be included in an application as follows:

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.

Timer_Handle handle;
Timer_Params params;
params.period = 1000;
params.timerCallback = someTimerCallbackFunction;
handle = Timer_open(Board_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);

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:

typedef struct Timer_Config_ {
void *object;
void const *hwAttrs;

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:

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:

#include <ti/drivers/timer/TimerMSP432.h>

#include <stdint.h>

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

Typedefs

typedef struct Timer_Config_Timer_Handle
 A handle that is returned from a Timer_open() call. More...
 
typedef enum Timer_Mode_ Timer_Mode
 Timer mode settings. More...
 
typedef enum Timer_PeriodUnits_ Timer_PeriodUnits
 Timer period unit enum. More...
 
typedef void(* Timer_CallBackFxn) (Timer_Handle handle)
 Timer callback function. More...
 
typedef struct Timer_Params_ Timer_Params
 Timer Parameters. 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_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_FxnTable_ Timer_FxnTable
 The definition of a timer function table that contains the required set of functions to control a specific timer driver implementation. 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...
 
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.

§ TIMER_CMD_RESERVED

#define TIMER_CMD_RESERVED   Timer_CMD_RESERVED

§ TIMER_STATUS_RESERVED

#define TIMER_STATUS_RESERVED   Timer_STATUS_RESERVED

§ TIMER_STATUS_SUCCESS

#define TIMER_STATUS_SUCCESS   Timer_STATUS_SUCCESS

§ TIMER_STATUS_ERROR

#define TIMER_STATUS_ERROR   Timer_STATUS_ERROR

§ TIMER_STATUS_UNDEFINEDCMD

#define TIMER_STATUS_UNDEFINEDCMD   Timer_STATUS_UNDEFINEDCMD

§ TIMER_ONESHOT_CB

#define TIMER_ONESHOT_CB   Timer_ONESHOT_CALLBACK

§ TIMER_ONESHOT_BLOCK

#define TIMER_ONESHOT_BLOCK   Timer_ONESHOT_BLOCKING

§ TIMER_CONTINUOUS_CB

#define TIMER_CONTINUOUS_CB   Timer_CONTINUOUS_CALLBACK

§ TIMER_MODE_FREE_RUNNING

#define TIMER_MODE_FREE_RUNNING   Timer_FREE_RUNNING

§ TIMER_PERIOD_US

#define TIMER_PERIOD_US   Timer_PERIOD_US

§ TIMER_PERIOD_HZ

#define TIMER_PERIOD_HZ   Timer_PERIOD_HZ

§ TIMER_PERIOD_COUNTS

#define TIMER_PERIOD_COUNTS   Timer_PERIOD_COUNTS

§ Timer_Period_Units

#define Timer_Period_Units   Timer_PeriodUnits

Typedef Documentation

§ Timer_Handle

typedef struct Timer_Config_* Timer_Handle

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

§ Timer_Mode

typedef enum Timer_Mode_ Timer_Mode

Timer mode settings.

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

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

§ 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
handleTimer_Handle

§ Timer_Params

typedef struct Timer_Params_ Timer_Params

Timer Parameters.

Timer parameters are used to with the Timer_open() call. Default values for these parameters are set using Timer_Params_init().

§ 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_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_FxnTable

The definition of a timer function table that contains the required set of functions to control a specific timer driver implementation.

§ 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_

Timer mode settings.

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

Enumerator
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_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
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
handleA Timer_Handle returned from Timer_open().
cmdA command value defined by the driver specific implementation.
argA pointer to an optional R/W (read/write) argument that is accompanied with cmd.
Returns
A Timer_Status describing an error or success state. Negative values indicate an error occurred.
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
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
indexLogical peripheral number for the timer indexed into the Timer_config table.
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_Params_init()

void Timer_Params_init ( Timer_Params params)

Function to initialize the Timer_Params struct to its defaults.

Parameters
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
handleA Timer_Handle returned from Timer_open().
Returns
Timer_STATUS_SUCCESS or Timer_STATUS_ERROR.
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
handleA Timer_Handle returned from Timer_open().
See also
Timer_start()
Copyright 2017, Texas Instruments Incorporated