Detailed Description

Clock interface for the RTOS Porting Interface.

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

The ClockP module can be used to schedule functions that run at intervals specified in the underlying kernel's system ticks. ClockP instances are one-shot. The one-shot function will be run once after the specified period has elapsed since calling ClockP_start().

The ClockP module can also be used to obtain the period of the kernel's system tick in micro seconds. This is useful for determining the number of ticks needed for setting a Clock object's period.

When using the TI-RTOS kernel, ClockP functions are run at software interrupt level. With FreeRTOS, the ClockP functions are either run by a timer service task with priority configured by the application, or in hardware interrupt directly, depending on the device platform.

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for ClockP.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
union	ClockP_Struct
	ClockP structure. More...

struct	ClockP_FreqHz
	Frequency-in-hertz struct. More...

struct	ClockP_Params
	Basic ClockP Parameters. More...

Macros
#define	ClockP_STRUCT_SIZE (68)
	Number of bytes greater than or equal to the size of any RTOS ClockP object. More...

#define	ClockP_handle(x) ((ClockP_Handle)(x))

Typedefs
typedef union ClockP_Struct	ClockP_Struct
	ClockP structure. More...

typedef void *	ClockP_Handle
	Opaque client reference to an instance of a ClockP. More...

typedef void(*	ClockP_Fxn) (uintptr_t arg)
	Prototype for a ClockP callback function. More...

Enumerations
enum	ClockP_Status { ClockP_OK = 0, ClockP_FAILURE = -1 }
	Status codes for ClockP APIs. More...

Functions
ClockP_Handle	ClockP_construct (ClockP_Struct clockP, ClockP_Fxn clockFxn, uint32_t timeout, ClockP_Params params)
	Function to construct a clock object. More...

void	ClockP_destruct (ClockP_Struct *clockP)
	Function to destruct a clock object. More...

ClockP_Handle	ClockP_create (ClockP_Fxn clockFxn, uint32_t timeout, ClockP_Params *params)
	Function to create a clock object. More...

void	ClockP_delete (ClockP_Handle handle)
	Function to delete a clock. More...

void	ClockP_getCpuFreq (ClockP_FreqHz *freq)
	Get CPU frequency in Hertz. More...

uint32_t	ClockP_getSystemTickPeriod (void)
	Get the system tick period in number of micro seconds. More...

uint32_t	ClockP_getSystemTicks (void)
	Get the current tick value in number of system ticks. More...

uint32_t	ClockP_getTicksUntilInterrupt (void)
	Get number of ClockP tick periods expected to expire between now and the next interrupt from the timer peripheral. More...

uint32_t	ClockP_getTimeout (ClockP_Handle handle)
	Get timeout of clock instance. More...

bool	ClockP_isActive (ClockP_Handle handle)
	Determine if a clock object is currently active (i.e., running) More...

void	ClockP_Params_init (ClockP_Params *params)
	Initialize params structure to default values. More...

void	ClockP_setFunc (ClockP_Handle handle, ClockP_Fxn clockFxn, uintptr_t arg)
	Function to overwrite ClockP callback function and arg. More...

void	ClockP_setTimeout (ClockP_Handle handle, uint32_t timeout)
	Set the initial timeout. More...

void	ClockP_setPeriod (ClockP_Handle handle, uint32_t period)
	Set the clock period. More...

void	ClockP_start (ClockP_Handle handle)
	Function to start a clock. More...

void	ClockP_stop (ClockP_Handle handle)
	Function to stop a clock. More...

void	ClockP_usleep (uint32_t usec)
	Set delay in micro seconds. More...

void	ClockP_sleep (uint32_t sec)
	Set delay in seconds. More...

Macro Definition Documentation

§ ClockP_STRUCT_SIZE

#define ClockP_STRUCT_SIZE (68)

Number of bytes greater than or equal to the size of any RTOS ClockP object.

NoRTOS: 32 (biggest of the HW-specific ClockP instance structs) BIOS 6.x: 40 BIOS 7.x: 36 FreeRTOS: 68

§ ClockP_handle

#define ClockP_handle ( x ) ((ClockP_Handle)(x))

Typedef Documentation

§ ClockP_Struct

typedef union ClockP_Struct ClockP_Struct

ClockP structure.

Opaque structure that should be large enough to hold any of the RTOS specific ClockP objects.

§ ClockP_Handle

typedef void* ClockP_Handle

Opaque client reference to an instance of a ClockP.

A ClockP_Handle returned from ClockP_create() or ClockP_construct() represents that instance. It is then is used in the other instance based functions (e.g. ClockP_start(), ClockP_stop(), etc.).

§ ClockP_Fxn

typedef void(* ClockP_Fxn) (uintptr_t arg)

Prototype for a ClockP callback function.

Enumeration Type Documentation

§ ClockP_Status

enum ClockP_Status

Status codes for ClockP APIs.

Enumerator
ClockP_OK
ClockP_FAILURE

Function Documentation

§ ClockP_construct()

ClockP_Handle ClockP_construct	(	ClockP_Struct *	clockP,
		ClockP_Fxn	clockFxn,
		uint32_t	timeout,
		ClockP_Params *	params
	)

Function to construct a clock object.

Parameters

clockP	Pointer to ClockP_Struct object.
timeout	The startup timeout, if supported by the RTOS.
clockFxn	Function called when timeout or period expires.
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters. The ClockP default parameters are noted in ClockP_Params_init().

Returns: A ClockP_Handle on success or NULL on an error.

§ ClockP_destruct()

void ClockP_destruct ( ClockP_Struct * clockP )

Function to destruct a clock object.

Parameters

clockP Pointer to a ClockP_Struct object that was passed to ClockP_construct().

The clock object must be stopped before calling destruct.

§ ClockP_create()

ClockP_Handle ClockP_create	(	ClockP_Fxn	clockFxn,
		uint32_t	timeout,
		ClockP_Params *	params
	)

Function to create a clock object.

This function will allocate memory for the instance's ClockP_Struct.

Parameters

clockFxn	Function called when timeout or period expires.
timeout	The startup timeout, if supported by the RTOS.
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters. The ClockP default parameters are noted in ClockP_Params_init().

Returns: A ClockP_Handle on success or NULL on an error.

§ ClockP_delete()

void ClockP_delete ( ClockP_Handle handle )

Function to delete a clock.

Parameters

handle A ClockP_Handle returned from ClockP_create()

The clock object must be stopped before calling delete.

§ ClockP_getCpuFreq()

void ClockP_getCpuFreq ( ClockP_FreqHz * freq )

Get CPU frequency in Hertz.

Parameters

freq	Pointer to the FreqHz structure

§ ClockP_getSystemTickPeriod()

uint32_t ClockP_getSystemTickPeriod ( void )

Get the system tick period in number of micro seconds.

Returns: The kernel's system tick period in micro seconds.

§ ClockP_getSystemTicks()

uint32_t ClockP_getSystemTicks ( void )

Get the current tick value in number of system ticks.

The value returned will wrap back to zero after it reaches the max value that can be stored in 32 bits.

Returns: Time in system clock ticks

§ ClockP_getTicksUntilInterrupt()

uint32_t ClockP_getTicksUntilInterrupt ( void )

Get number of ClockP tick periods expected to expire between now and the next interrupt from the timer peripheral.

Returns the number of ClockP tick periods that are expected to expire between now and the next interrupt from the timer peripheral.

Used internally by various Power modules

Returns: Count in ticks

§ ClockP_getTimeout()

uint32_t ClockP_getTimeout ( ClockP_Handle handle )

Get timeout of clock instance.

Parameters

handle A ClockP_Handle returned from ClockP_create() or ClockP_construct()

Returns the remaining time in clock ticks if the instance has been started. If the clock is not active, the initial timeout value is returned.

Returns: Remaining timeout in clock ticks.

§ ClockP_isActive()

bool ClockP_isActive ( ClockP_Handle handle )

Determine if a clock object is currently active (i.e., running)

Parameters

handle A ClockP_Handle returned from ClockP_create() or ClockP_construct()

Returns true if the clock object is currently active, otherwise returns false.

Returns: active state

§ ClockP_Params_init()

void ClockP_Params_init ( ClockP_Params * params )

Initialize params structure to default values.

The default parameters are:

startFlag: false
period: 0
arg: 0

Parameters

params Pointer to the configuration parameters instance.

§ ClockP_setFunc()

void ClockP_setFunc	(	ClockP_Handle	handle,
		ClockP_Fxn	clockFxn,
		uintptr_t	arg
	)

Function to overwrite ClockP callback function and arg.

Parameters

handle	A ClockP_Handle returned from ClockP_create() or ClockP_construct()
clockFxn	Function called when timeout or period expires.
arg	Argument passed to `clockFxn`

§ ClockP_setTimeout()

void ClockP_setTimeout	(	ClockP_Handle	handle,
		uint32_t	timeout
	)

Set the initial timeout.

Parameters

handle	A ClockP_Handle returned from ClockP_create() or ClockP_construct()
timeout	Initial timeout in ClockP ticks

Cannot be used to set the initial timeout if the clock has been started.

§ ClockP_setPeriod()

void ClockP_setPeriod	(	ClockP_Handle	handle,
		uint32_t	period
	)

Set the clock period.

Parameters

handle	A ClockP_Handle returned from ClockP_create() or ClockP_construct()
period	Periodic interval in ClockP ticks

Cannot be used to set the clock period to zero.

§ ClockP_start()

void ClockP_start ( ClockP_Handle handle )

Function to start a clock.

Remarks: In some implementations, it may not always be possible to to start a ClockP object with maximum timeout. This situation can occur when a very fast tick period is used, and when ClockP_start() is called (by another ISR, by a higher-priority SwiP, or within a clock function) while ClockP is in-process of servicing its timeout queue. In this case the timeout of the newly-started object may occur in the near future rather than in the far future. For one-shot objects there will be a single early timeout; for periodic objects there will be an early timeout, but the next timeout will occur correctly offset from the first timeout. This condition is due to a ClockP tick count wrap, and only occurs when there is a very fast ClockP tick period such that there are virtual ClockP tick period increments between the last timer interrupt to the invocation of ClockP_start(). For example, if the ClockP tick period is 10 usec, and if the ClockP tick count is 0x10000005 when the interrupt occurs, and if there are 3 intervening tick periods (30 usec) before the call to ClockP_start() in a clock function, then the future timeout will be computed as 0x10000005 + 3 + 0xFFFFFFFF = 0x10000007, only 2 ticks in the future. In this case, the maximum timeout should be limited to 0xFFFFFFFD to achieve the maximum delay from the last timer interrupt.

Parameters

handle A ClockP_Handle returned from ClockP_create() or ClockP_construct()

§ ClockP_stop()

void ClockP_stop ( ClockP_Handle handle )

Function to stop a clock.

Parameters

handle A ClockP_Handle returned from ClockP_create() or ClockP_construct()

It is ok to call ClockP_stop() for a clock that has not been started.

§ ClockP_usleep()

void ClockP_usleep ( uint32_t usec )

Set delay in micro seconds.

Parameters

usec	A duration in micro seconds

§ ClockP_sleep()

void ClockP_sleep ( uint32_t sec )

Set delay in seconds.

Parameters

sec	A duration in seconds

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ ClockP_STRUCT_SIZE

§ ClockP_handle

Typedef Documentation

§ ClockP_Struct

§ ClockP_Handle

§ ClockP_Fxn

Enumeration Type Documentation

§ ClockP_Status

Function Documentation

§ ClockP_construct()

§ ClockP_destruct()

§ ClockP_create()

§ ClockP_delete()

§ ClockP_getCpuFreq()

§ ClockP_getSystemTickPeriod()

§ ClockP_getSystemTicks()

§ ClockP_getTicksUntilInterrupt()

§ ClockP_getTimeout()

§ ClockP_isActive()

§ ClockP_Params_init()

§ ClockP_setFunc()

§ ClockP_setTimeout()

§ ClockP_setPeriod()

§ ClockP_start()

§ ClockP_stop()

§ ClockP_usleep()

§ ClockP_sleep()