Detailed Description

Timer driver interface.

============================================================================

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

Operation

The Timer driver operates as a generic timer interface for timing interval handling. It can be configured to run in one-shot blocking mode, one-shot callback mode, continuous callback mode, or free-run mode. This driver does not have PWM or capture functionalities. These functionalities are addressed in both the Capture and PWM driver modules.

The Timer driver also handles the general purpose timer resource allocation. For the driver that requires to use the general purpose timer, it calls Timer_open() to occupy the specified timer, and calls Timer_close() to release the occupied timer resource.

Opening the Driver

Timer_Handle      handle;
Timer_Params      params;
Timer_Params_init(&params);
params.mode  = TIMER_MODE_CONTINUOUS_CALLBACK;
params.callbackFxn = someTimerCallbackFunction;
params.periodUnit = TIMER_PERIOD_US;
params.period = 5000000
handle = Timer_open(someTimer_configIndexValue, &params);
if (!handle)
{
    System_printf("Timer did not open");
}
## Starting the Driver ##
@code
status = Timer_start(handle);
if (status == TIMER_STATUS_ERROR)
{
    System_printf("Timer cannot start at specified period");
}

Stopping the driver

Timer_stop(handle);

closing the driver

Timer_close(handle);

Implementation

This module serves as the main interface for TI Drivers applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a Timer_FxnTable.

The Timer driver interface module is joined (at link time) to a NULL-terminated 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 to the Timer_FxnTable

Instrumentation

The Timer driver interface produces log statements if instrumentation is enabled.

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

Macros
#define	TIMER_CMD_RESERVED (32)

#define	TIMER_STATUS_RESERVED (-32)

#define	TIMER_STATUS_SUCCESS (0)
	Successful status code returned by Timer_control(). More...

#define	TIMER_STATUS_ERROR (-1)
	Generic error status code returned by Timer_control(). 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 enum Timer_Mode_	Timer_Mode
	Timer mode enum. More...

typedef enum Timer_Period_Units_	Timer_Period_Units
	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 void(*	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

Enumerations
enum	Timer_Mode_ { TIMER_ONESHOT_CB, TIMER_ONESHOT_BLOCK, TIMER_CONTINUOUS_CB, TIMER_MODE_FREE_RUNNING }
	Timer mode enum. More...

enum	Timer_Period_Units_ { TIMER_PERIOD_US, TIMER_PERIOD_HZ, TIMER_PERIOD_COUNTS }
	Timer period unit enum. More...

Functions
int_fast16_t	Timer_control (Timer_Handle handle, uint_fast16_t cmd, void *arg)
	Function performs implementation specific features on a given Timer_Handle. More...

void	Timer_close (Timer_Handle handle)
	Function to close a Timer peripheral specified by the Timer handle. More...

uint32_t	Timer_getCount (Timer_Handle handle)
	Function to get the current count of a started timer. 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 particular index value. The parameter specifies which mode the Timer will operate. More...

void	Timer_Params_init (Timer_Params *params)
	Function to initialize the Timer_Params struct to its defaults. More...

void	Timer_start (Timer_Handle handle)
	Function to start Timer with the given period. The timer running mode and interval period unit are specified in the Timer_Params when calling Timer_open(). More...

void	Timer_stop (Timer_Handle handle)
	Function to stop timer after Timer_start() is called with success. More...

Macro Definition Documentation

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

1 #define TIMERXYZ_CMD_COMMAND0 TIMER_CMD_RESERVED + 0

2 #define TIMERXYZ_CMD_COMMAND1 TIMER_CMD_RESERVED + 1

#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
 #define TIMERXYZ_STATUS_ERROR2     TIMER_STATUS_RESERVED - 2

#define TIMER_STATUS_SUCCESS (0)

Successful status code returned by Timer_control().

Timer_control() returns TIMER_STATUS_SUCCESS if the control code was executed successfully.

#define TIMER_STATUS_ERROR (-1)

Generic error status code returned by Timer_control().

Timer_control() returns TIMER_STATUS_ERROR if the control code was not executed successfully.

#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

typedef struct Timer_Config_* Timer_Handle

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

typedef enum Timer_Mode_ Timer_Mode

Timer mode enum.

The Timer mode needs to be passed in Timer_open() to specify the timer running mode which handles the interrupt differently.

typedef enum Timer_Period_Units_ Timer_Period_Units

Timer period unit enum.

The Timer period unit needs to be passed in Timer_open() to specify the unit of timing interval.

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

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

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

typedef void(* Timer_CloseFxn) (Timer_Handle handle)

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

typedef uint32_t(* Timer_GetCountFxn) (Timer_Handle handle)

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

typedef void(* Timer_InitFxn) (Timer_Handle handle)

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

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

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

typedef void(* Timer_StartFxn) (Timer_Handle handle)

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

typedef void(* Timer_StopFxn) (Timer_Handle handle)

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

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.

typedef struct Timer_Config_ Timer_Config

Enumeration Type Documentation

enum Timer_Mode_

Timer mode enum.

The Timer mode needs to be passed in Timer_open() to specify the timer running mode which handles the interrupt differently.

Enumerator
TIMER_ONESHOT_CB	User routine doesn't get blocked and user-specified callback function is invoked once the timer interrupt happens for only one time
TIMER_ONESHOT_BLOCK	User routine gets blocked until timer interrupt happens for only one time
TIMER_CONTINUOUS_CB	User routine doesn't get blocked and user-specified callback function is invoked every time the timer interrupt happens
TIMER_MODE_FREE_RUNNING

enum Timer_Period_Units_

Timer period unit enum.

The Timer period unit needs to be passed in Timer_open() to specify the unit of timing interval.

Enumerator
TIMER_PERIOD_US
TIMER_PERIOD_HZ
TIMER_PERIOD_COUNTS

Function Documentation

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

Function performs implementation specific features on a given Timer_Handle.

Precondition: Timer_open() must have been called first.

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

void Timer_close ( Timer_Handle handle )

Function to close a Timer peripheral specified by the Timer handle.

The function takes care of timer resource allocation. The corresponding timer resource to the Timer_Handle is released to be an available timer resource.

Precondition: Timer_open() had to be called first.

Parameters

handle A Timer_Handle returned from Timer_open

See also: Timer_open()

uint32_t Timer_getCount ( Timer_Handle handle )

Function to get the current count of a started timer.

Precondition: Timer_open() had to be called first.

Parameters

handle A Timer_Handle returned from Timer_open

See also: Timer_open()

Returns: The current count of the specified Timer

void Timer_init ( void )

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

See also: Timer_open()

Timer_Handle Timer_open	(	uint_least8_t	index,
		Timer_Params *	params
	)

Function to initialize a given Timer peripheral specified by the particular index value. The parameter specifies which mode the Timer will operate.

The function takes care of timer resource allocation. If the particular timer passed by user has already been used by other modules, the return value is NULL. If the particular timer is available to use, Timer module owns it and returns a Timer_Handle.

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. All the fields in this structure are RO (read-only).

Returns: A Timer_Handle on success or a NULL on an error if it has been opened already or used by other modules.

See also: Timer_init(); Timer_close()

void Timer_Params_init ( Timer_Params * params )

Function to initialize the Timer_Params struct to its defaults.

Parameters

params An pointer to Timer_Params structure for initialization

Defaults values are: mode = TIMER_MODE_ONESHOT_BLOCKING callbackFxn = NULL periodUnit = TIMER_PERIOD_US period = 0xFFFF

void Timer_start ( Timer_Handle handle )

Function to start Timer with the given period. The timer running mode and interval period unit are specified in the Timer_Params when calling Timer_open().

Parameters

handle Timer_Handle

Returns: TIMER_STATUS_SUCCESS if timer starts successfully. TIMER_STATUS_ERROR if timer fails to start.

void Timer_stop ( Timer_Handle handle )

Function to stop timer after Timer_start() is called with success.

Parameters

handle Timer_Handle

Detailed Description

Operation

Opening the Driver

Stopping the driver

closing the driver

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation