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
#include <ti/drivers/Timer.h>
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(CONFIG_TIMER0, &params);
@code
// Import Timer Driver definitions
#include <ti/drivers/Timer.h>
Timer_Handle    handle;
Timer_Params    params;
// Initialize Timer parameters
Timer_Params_init(&params);
params.periodUnits = Timer_PERIOD_HZ;
params.period = 1000;
params.timerMode  = Timer_CONTINUOUS_CALLBACK;
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;
Timer_Params_init(&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;
Timer_Params_init(&params);
params.periodUnits = Timer_PERIOD_HZ;
params.period = 1000;
params.timerMode  = Timer_CONTINUOUS_CALLBACK;
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] handle Timer_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

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

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

[in]	handle	A Timer_Handle returned from Timer_open().
[in]	cmd	A command value defined by the driver specific implementation.
[in]	arg	A pointer to an optional R/W (read/write) argument that is accompanied with cmd.

Return values

Timer_STATUS_SUCCESS	The control call was successful.
Timer_STATUS_ERROR	The 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] 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

[in]	index	Logical peripheral number for the timer indexed into the Timer_config table.
[in]	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_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]	handle	A Timer_Handle returned from Timer_open().
[in]	periodUnits	Timer_PeriodUnits of the desired period value.
[in]	period	Period value to set.

Return values

Timer_STATUS_SUCCESS	The setPeriod call was successful.
Timer_STATUS_ERROR	The 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] 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

[in] handle A Timer_Handle returned from Timer_open().

Return values

Timer_STATUS_SUCCESS	The start call was successful.
Timer_STATUS_ERROR	The 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] handle A Timer_Handle returned from Timer_open().

See also: Timer_start()

Detailed Description

Overview

Usage

Synopsis

Examples

Opening a Timer instance

Configuring Timer mode and period

Initializing the Timer Driver

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Timer_CMD_RESERVED

§ Timer_STATUS_RESERVED

§ Timer_STATUS_SUCCESS

§ Timer_STATUS_ERROR

§ Timer_STATUS_UNDEFINEDCMD

Typedef Documentation

§ Timer_Handle

§ Timer_CallBackFxn

§ Timer_ControlFxn

§ Timer_CloseFxn

§ Timer_GetCountFxn

§ Timer_InitFxn

§ Timer_OpenFxn

§ Timer_SetPeriodFxn

§ Timer_StartFxn

§ Timer_StopFxn

§ Timer_Config

Enumeration Type Documentation

§ Timer_Mode

§ Timer_PeriodUnits

Function Documentation

§ Timer_close()

§ Timer_control()

§ Timer_getCount()

§ Timer_init()

§ Timer_open()

§ Timer_setPeriod()

§ Timer_Params_init()

§ Timer_start()

§ Timer_stop()