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;
Timer_Params_init(&params);
params.periodUnits = Timer_PERIOD_HZ;
params.period = 1000;
params.timerMode  = Timer_CONTINUOUS_CALLBACK;
params.timerCallback = UserCallbackFunction;
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_ {
    Timer_FxnTable const *fxnTablePtr;
    void                 *object;
    void           const *hwAttrs;
} Timer_Config;

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:

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

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

#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

typedef enum Timer_PeriodUnits_ 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

handle Timer_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

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.

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

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_

enum 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

handle A 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

handle	A Timer_Handle returned from Timer_open().
cmd	A command value defined by the driver specific implementation.
arg	A 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

handle A 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

index	Logical peripheral number for the timer indexed into the Timer_config table.
params	Pointer 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

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

§ Timer_start()

int32_t Timer_start ( Timer_Handle handle )

Function to start the timer.

Precondition: Timer_open() has been called.

Parameters

handle A 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

handle A Timer_Handle returned from Timer_open().

See also: Timer_start()

Detailed Description

Overview

Usage

Timer Driver Configuration

Initializing the Timer Driver

Modes of Operation

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Timer_CMD_RESERVED

§ Timer_STATUS_RESERVED

§ Timer_STATUS_SUCCESS

§ Timer_STATUS_ERROR

§ Timer_STATUS_UNDEFINEDCMD

§ TIMER_CMD_RESERVED

§ TIMER_STATUS_RESERVED

§ TIMER_STATUS_SUCCESS

§ TIMER_STATUS_ERROR

§ TIMER_STATUS_UNDEFINEDCMD

§ TIMER_ONESHOT_CB

§ TIMER_ONESHOT_BLOCK

§ TIMER_CONTINUOUS_CB

§ TIMER_MODE_FREE_RUNNING

§ TIMER_PERIOD_US

§ TIMER_PERIOD_HZ

§ TIMER_PERIOD_COUNTS

§ Timer_Period_Units

Typedef Documentation

§ Timer_Handle

§ Timer_Mode

§ Timer_PeriodUnits

§ Timer_CallBackFxn

§ Timer_Params

§ Timer_ControlFxn

§ Timer_CloseFxn

§ Timer_GetCountFxn

§ Timer_InitFxn

§ Timer_OpenFxn

§ Timer_StartFxn

§ Timer_StopFxn

§ Timer_FxnTable

§ Timer_Config

Enumeration Type Documentation

§ Timer_Mode_

§ Timer_PeriodUnits_

Function Documentation

§ Timer_close()

§ Timer_control()

§ Timer_getCount()

§ Timer_init()

§ Timer_open()

§ Timer_Params_init()

§ Timer_start()

§ Timer_stop()