Detailed Description

System Clock Manager.

The System Clock Manager is responsible for all timing services in SYS/BIOS. It generates the periodic system tick. The tick period is configurable. The timeout and period for all Clock Instances and timeout values in other SYS/BIOS modules are specified in terms of Clock ticks.

The Clock Manager supports two tick "modes": a periodic mode with an interrupt on each tick (TickMode_PERIODIC), and a tick suppression mode (TickMode_DYNAMIC), which reduces the number of timer interrupts to the minimum required to support the scheduled timeouts. For devices that support it (e.g., CC13xx/CC26xx devices), TickMode_DYNAMIC may be the default mode if one is not specified in the application configuration; otherwise, the default mode will be TickMode_PERIODIC. The following example shows how the tick mode can be specified in the application configuration:

const Clock = scripting.addModule("ti/sysbios/knl/Clock");
// Tell the Clock module to use TickMode_PERIODIC
Clock.tickMode = "Clock_TickMode_PERIODIC";

Clock objects contain functions that can be scheduled to run after a certain number of Clock ticks. Clock objects are either one-shot or periodic. Instances are started when created or they are started later using the Clock_start() function. Instances can be stopped using the Clock_stop() function. All Clock Instances are executed when they expire in the context of a software interrupt.

Clock objects are placed in the Clock object service list when created/constructed and remain there until deleted/destructed. To minimize processing overhead, unused or expired Clock objects should be deleted or destructed.

By default, all Clock functions run in the context of a Swi. That is, the Clock module automatically creates a Swi for its use and runs the Clock functions within that Swi. The priority of the Swi used by Clock can be changed the Clock.swiPriority configuration parameter.

If Swis are disabled in an application (if config parameter 'BIOS.swiEnabled' is set to false), then all Clock functions are executed within the context of a Timer Hwi.

Note

As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.

The getTicks() function returns number of clock ticks since startup.

If you want to use a custom configured timer for the Clock module's tick source, use the following example configuration as a guide:

const Clock = scripting.addModule("ti/sysbios/knl/Clock");
// Tell the Clock module that YOU are providing the periodic interrupt
Clock.tickSource = "Clock_TickSource_USER";
// this example uses the ti.sysbios.timers.dmtimer.Timer module
const Timer = scripting.addModule("/ti/sysbios/family/arm/m3/Timer");

In your 'C' code, construct your timer, and add your timer interrupt handler and have it call Clock_tick(), which will perform all of the Clock module tick duties:

#include <ti/sysbios/knl/Clock.h>
#include <ti/sysbios/family/arm/m3/Timer.h>
Timer_Struct timer0Struct;
Timer_Handle timer0;
main() {
    Timer_Params timerParams0;
    Timer_Params_init(&timerParams0);
    timerParams0.period = 1000;
    timer0 = Timer_construct(&timer0Struct, Timer_ANY, myTimerTick, &timerParams0, NULL);
}
void myTimerTick(uintptr_t arg)
{
     Clock_tick();
     ...
}

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Clock_construct	N	N	Y	Y	N
Clock_create	N	N	Y	Y	N
Clock_delete	N	N	Y	Y	N
Clock_destruct	N	N	Y	Y	N
Clock_getTicks	Y	Y	Y	N	N
Clock_getTimerHandle	Y	Y	Y	Y	Y
Clock_Params_init	Y	Y	Y	Y	Y
Clock_tick	Y	Y	Y	N	N
Clock_tickReconfig	Y	Y	Y	N	N
Clock_tickStart	Y	Y	Y	N	N
Clock_tickStop	Y	Y	Y	N	N
Clock_getTimeout	Y	Y	Y	Y	N
Clock_isActive	Y	Y	Y	Y	N
Clock_setFunc	Y	Y	Y	Y	N
Clock_setPeriod	Y	Y	Y	Y	N
Clock_setTimeout	Y	Y	Y	Y	N
Clock_start	Y	Y	Y	Y	N
Clock_stop	Y	Y	Y	Y	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module has been initialized (e.g. after Clock_init() has been called). During Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During Startup.firstFxns. In your module startup before this module has been initialized (e.g. before Clock_init() has been called).

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Swi.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for Clock.h:

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

Go to the source code of this file.

Data Structures
struct	Clock_Params

struct	Clock_Module_State

struct	Clock_Struct

Macros
#define	Clock_A_clockDisabled "Cannot create a clock instance when BIOS.clockEnabled is false."
	Asserted in Clock_create. More...

#define	Clock_A_badThreadType "Cannot create/delete a Clock from a Hwi or Swi thread."
	Asserted in Clock_create and Clock_delete. More...

#define	Clock_A_badTimeout "Bad timeout value."
	Asserted in Clock_create and Clock_delete. More...

Typedefs
typedef struct Clock_Module_State	Clock_Module_State

typedef struct Clock_Params	Clock_Params

typedef struct Clock_Struct	Clock_Struct

typedef struct Clock_Struct	Clock_Object

typedef Clock_Object *	Clock_Handle

typedef Clock_Object *	Clock_Instance

typedef enum Clock_TickSource	Clock_TickSource

typedef enum Clock_TickMode	Clock_TickMode
	Clock Tick Mode. More...

typedef void(*	Clock_FuncPtr) (uintptr_t arg1)
	Instance function prototype. More...

Enumerations
enum	Clock_TickSource { Clock_TickSource_TIMER, Clock_TickSource_USER, Clock_TickSource_NULL }
	Clock tick source. More...

enum	Clock_TickMode { Clock_TickMode_PERIODIC, Clock_TickMode_DYNAMIC }
	Clock Tick Mode. More...

Functions
Clock_Handle	Clock_create (Clock_FuncPtr clockFxn, unsigned int timeout, const Clock_Params prms, Error_Block eb)
	Creates a Clock Instance. More...

Clock_Handle	Clock_construct (Clock_Struct obj, Clock_FuncPtr clockFxn, unsigned int timeout, const Clock_Params prms)
	Construct a Clock. More...

void	Clock_delete (Clock_Handle *clock)
	Delete a Clock. More...

void	Clock_destruct (Clock_Struct *obj)
	Destruct a Clock. More...

void	Clock_Params_init (Clock_Params *prms)
	Initialize the Clock_Params structure with default values. More...

Clock_Handle	Clock_Object_first (void)
	return handle of the first Clock on Clock list More...

Clock_Handle	Clock_Object_next (Clock_Handle clock)
	return handle of the next Clock on Clock list More...

uint32_t	Clock_getTicks (void)
	Time in Clock ticks. More...

void	Clock_tickStop (void)
	Stop clock for reconfiguration. More...

bool	Clock_tickReconfig (void)
	Reconfigure clock for new cpu frequency. More...

void	Clock_tickStart (void)
	Start clock after reconfiguration. More...

void	Clock_tick (void)
	Advance Clock time by one tick. More...

void	Clock_start (Clock_Handle clock)
	Start instance. More...

void	Clock_stop (Clock_Handle clock)
	Stop instance. More...

void	Clock_setPeriod (Clock_Handle clock, uint32_t period)
	Set periodic interval. More...

void	Clock_setTimeout (Clock_Handle clock, uint32_t timeout)
	Set the initial timeout. More...

void	Clock_setFunc (Clock_Handle clock, Clock_FuncPtr fxn, uintptr_t arg)
	Overwrite Clock function and arg. More...

uint32_t	Clock_getPeriod (Clock_Handle clock)
	Get period of instance. More...

uint32_t	Clock_getTimeout (Clock_Handle clock)
	Get timeout of instance. More...

bool	Clock_isActive (Clock_Handle clock)
	Determine if Clock object is currently active (ie running) More...

Variables
const Clock_TickSource	Clock_tickSource
	Source of clock ticks. More...

const Clock_TickMode	Clock_tickMode
	Timer tick mode. More...

const unsigned int	Clock_timerId
	Timer Id used to create a Timer instance. More...

const uint32_t	Clock_tickPeriod
	Tick period specified in microseconds. More...

Macro Definition Documentation

§ Clock_A_clockDisabled

#define Clock_A_clockDisabled "Cannot create a clock instance when BIOS.clockEnabled is false."

Asserted in Clock_create.

§ Clock_A_badThreadType

#define Clock_A_badThreadType "Cannot create/delete a Clock from a Hwi or Swi thread."

Asserted in Clock_create and Clock_delete.

§ Clock_A_badTimeout

#define Clock_A_badTimeout "Bad timeout value."

Asserted in Clock_create and Clock_delete.

Typedef Documentation

§ Clock_Module_State

typedef struct Clock_Module_State Clock_Module_State

§ Clock_Params

typedef struct Clock_Params Clock_Params

§ Clock_Struct

typedef struct Clock_Struct Clock_Struct

§ Clock_Object

typedef struct Clock_Struct Clock_Object

§ Clock_Handle

typedef Clock_Object* Clock_Handle

§ Clock_Instance

typedef Clock_Object* Clock_Instance

§ Clock_TickSource

typedef enum Clock_TickSource Clock_TickSource

§ Clock_TickMode

typedef enum Clock_TickMode Clock_TickMode

Clock Tick Mode.

§ Clock_FuncPtr

typedef void(* Clock_FuncPtr) (uintptr_t arg1)

Instance function prototype.

Enumeration Type Documentation

§ Clock_TickSource

enum Clock_TickSource

Clock tick source.

Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".

See also: Clock_tickPeriod

Enumerator
Clock_TickSource_TIMER	The Clock module automatically configures a a Timer instance to drive the Clock tick. The specific timer and its period can be controlled via Clock_timerId and Clock_tickPeriod.
Clock_TickSource_USER	The Application is responsible for calling Clock_tick periodically. Make sure Clock_tickPeriod is set to the period that Clock_tick() is called.
Clock_TickSource_NULL	The Clock module is disabled. In this case, it is an error for the application to ever call Clock_tick().

§ Clock_TickMode

enum Clock_TickMode

Clock Tick Mode.

Enumerator
Clock_TickMode_PERIODIC
Clock_TickMode_DYNAMIC

Function Documentation

§ Clock_create()

Clock_Handle Clock_create	(	Clock_FuncPtr	clockFxn,
		unsigned int	timeout,
		const Clock_Params *	prms,
		Error_Block *	eb
	)

Creates a Clock Instance.

The first argument is the function that gets called when the timeout expires.

The 'timeout' argument is used to specify the startup timeout for both one- shot and periodic Clock instances (in Clock ticks). This timeout is applied when the Clock instance is started. For periodic instances, the configured Clock function will be called initially after an interval equal to the timeout, and will be subsequently called at the rate specified by the period parameter. For one-shot instances (where the period parameter is 0), once the Clock instance is started (with Clock_start or automatically if 'startFlag' is true) the configured Clock function will be called once after an interval equal to the timeout.

When instances are created they are placed upon a linked list managed by the Clock module. For this reason, instances cannot be created from either Hwi or Swi context.

By default, all Clock functions run in the context of a Swi. That is, the Clock module automatically creates a Swi for its use and runs the Clock functions within that Swi. The priority of the Swi used by Clock can be changed with the Clock.swiPriority configuration parameter.

If Swis are disabled in an application (config parmeter BIOS.swiEnabled is set to false), then all Clock functions are executed within the context of a Timer Hwi.

constraint

As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.

Parameters

clockFxn	Function that runs upon timeout
timeout	One-shot timeout or initial start delay (in clock ticks)
prms	Clock parameters
eb	Error block

Return values

Clock handle

§ Clock_construct()

Clock_Handle Clock_construct	(	Clock_Struct *	obj,
		Clock_FuncPtr	clockFxn,
		unsigned int	timeout,
		const Clock_Params *	prms
	)

Construct a Clock.

Clock_construct is equivalent to Clock_create except that the Clock_Struct is pre-allocated. See Clock_create() for a description of this API.

Parameters

obj	pointer to a Clock object
clockFxn	Clock function
timeout	One-shot timeout or initial start delay (in clock ticks)
prms	Clock parameters

Return values

Clock handle (NULL on failure)

§ Clock_delete()

void Clock_delete ( Clock_Handle * clock )

Delete a Clock.

Clock_delete deletes a Clock object. Note that Clock_delete takes a pointer to a Clock_Handle which enables Clock_delete to set the Clock_handle to NULL.

Parameters

clock pointer to Clock handle

§ Clock_destruct()

void Clock_destruct ( Clock_Struct * obj )

Destruct a Clock.

Clock_destruct destructs a Clock object.

Parameters

obj	pointer to Clock object

§ Clock_Params_init()

void Clock_Params_init ( Clock_Params * prms )

Initialize the Clock_Params structure with default values.

Clock_Params_init initializes the Clock_Params structure with default values. Clock_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

§ Clock_Object_first()

Clock_Handle Clock_Object_first ( void )

return handle of the first Clock on Clock list

Return the handle of the first Clock on the create/construct list. NULL if no Clocks have been created or constructed.

Return values

Clock handle

§ Clock_Object_next()

Clock_Handle Clock_Object_next ( Clock_Handle clock )

return handle of the next Clock on Clock list

Return the handle of the next Clock on the create/construct list. NULL if no more Clocks are on the list.

Parameters

clock Clock handle

Return values

Clock handle

§ Clock_getTicks()

uint32_t Clock_getTicks ( void )

Time in Clock ticks.

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

Return values

time	in clock ticks

§ Clock_tickStop()

void Clock_tickStop ( void )

Stop clock for reconfiguration.

This function is used to stop the timer used for generation of clock ticks. It is used along with Clock_tickStart() and Clock_tickReconfig() to allow reconfiguration of timer at runtime.

Stopping the timer may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this this function call will have no effect.

Precondition: This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.

§ Clock_tickReconfig()

bool Clock_tickReconfig ( void )

Reconfigure clock for new cpu frequency.

This function uses the new cpu frequency to reconfigure the timer used for generation of clock ticks such that tick period is accurate. This function is used along with Clock_tickStop() and Clock_tickStart() to allow reconfiguration of timer at runtime.

Reconfiguration may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this this function call will have no effect, and will return false.

When calling Clock_tickReconfig outside of main(), you must also call Clock_tickStop and Clock_tickStart to stop and restart the timer. Use the following call sequence:

// disable interrupts if an interrupt could lead to
// another call to Clock_tickReconfig or if interrupt
// processing relies on having a running timer
Hwi_disable() or Swi_disable();
BIOS_setCpuFreq(&freq);
Clock_tickStop();
Clock_tickReconfig();
Clock_tickStart();
Hwi_restore() or Swi_enable()

When calling Clock_tickReconfig from main(), the timer has not yet been started because the timer is started as part of BIOS_start(). As a result, you can use the following simplified call sequence in main():

BIOS_setCpuFrequency(Types.FreqHz *freq);

Clock_tickReconfig(void);

The return value is false if the timer cannot support the new frequency

Precondition: This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.

Return values

true	if successful

§ Clock_tickStart()

void Clock_tickStart ( void )

Start clock after reconfiguration.

This function starts the timer used for generation of clock ticks It is used along with Clock_tickStop() and Clock_tickReconfig() to allow reconfiguration of timer at runtime. The new timer configuration reflects changes caused by a call to reconfig().

Reconfiguration and restart of a timer may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this function call will have no effect.

Precondition: This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.

§ Clock_tick()

void Clock_tick ( void )

Advance Clock time by one tick.

After incrementing a global tick counter, this function posts a Swi that processes the clock instances.

This function is automatically called by a timer ISR when Clock_tickSource is set to Clock_TickSource_TIMER.

When Clock_tickSource is set to Clock_TickSource_USER, Clock_tick() must be called by the application. Usually, this is done within a user defined ISR.

Note that this function is not re-entrant. The application is responsible for ensuring that invocations of this function are serialized: either only one thread in the system ever calls this function or all calls are "wrapped" by an appropriate mutex.

§ Clock_start()

void Clock_start ( Clock_Handle clock )

Start instance.

The timeout and period values set during create() or by calling Clock_setTimeout() and Clock_setPeriod() are used and the expiry is recomputed. Note that for periodic instances, the first expiry is computed using the timeout specified. All subsequent expiries use the period value.

Precondition: Timeout of instance cannot be zero

§ Clock_stop()

void Clock_stop ( Clock_Handle clock )

Stop instance.

Parameters

clock Clock handle

§ Clock_setPeriod()

void Clock_setPeriod	(	Clock_Handle	clock,
		uint32_t	period
	)

Set periodic interval.

Precondition: Cannot change period of instance that has been started.

Parameters

clock	Clock handle
period	periodic interval in Clock ticks

§ Clock_setTimeout()

void Clock_setTimeout	(	Clock_Handle	clock,
		uint32_t	timeout
	)

Set the initial timeout.

Precondition: Cannot change the initial timeout of instance that has been started.

Parameters

clock	Clock handle
timeout	initial timeout in Clock ticks

§ Clock_setFunc()

void Clock_setFunc	(	Clock_Handle	clock,
		Clock_FuncPtr	fxn,
		uintptr_t	arg
	)

Overwrite Clock function and arg.

Replaces a Clock object's clockFxn function originally provided in Clock_create.

Precondition: Cannot change function and arg of Clock object that has been started.

Parameters

clock	Clock handle
fxn	Clock function
arg	argument to clock function

§ Clock_getPeriod()

uint32_t Clock_getPeriod ( Clock_Handle clock )

Get period of instance.

Returns the period of an instance.

Parameters

clock Clock handle

Return values

returns periodic interval in Clock ticks

§ Clock_getTimeout()

uint32_t Clock_getTimeout ( Clock_Handle clock )

Get timeout of instance.

Returns the remaining time if the instance is active; if the instance is not active, returns zero.

Parameters

clock Clock handle

Return values

returns timeout in clock ticks

§ Clock_isActive()

bool Clock_isActive ( Clock_Handle clock )

Determine if Clock object is currently active (ie running)

Returns true if Clock object is currently active

Parameters

clock Clock handle

Return values

returns active state

Variable Documentation

§ Clock_tickSource

const Clock_TickSource Clock_tickSource

Source of clock ticks.

If this parameter is not set to TickSource_TIMER, Clock_tickStart, Clock_tickStop, and Clock_tickReconfig, have no effect.

The default is Clock_TickSource_TIMER.

§ Clock_tickMode

const Clock_TickMode Clock_tickMode

Timer tick mode.

This parameter specifies the tick mode to be used by the underlying Timer.

With TickMode_PERIODIC the timer will interrupt the CPU at a fixed rate, defined by the tickPeriod.

With TickMode_DYNAMIC the timer can be dynamically reprogrammed by Clock, to interrupt the CPU when the next tick is actually needed for a scheduled timeout. TickMode_DYNAMIC is not supported on all devices, and may have some application constraints.

§ Clock_timerId

const unsigned int Clock_timerId

Timer Id used to create a Timer instance.

If Clock_tickSource is set to TickSource_TIMER, the Clock module internally creates a static Timer instance that automatically calls Clock_tick() on a periodic basis (as specified by Clock_tickPeriod.)

This configuration parameter allows you to control which timer is used to drive the Clock module.

The default value is Timer_ANY (~0) and the maximum timerId possible is device specific.

§ Clock_tickPeriod

const uint32_t Clock_tickPeriod

Tick period specified in microseconds.

Default value is family dependent. For example, Linux systems often only support a minimum period of 10000 us and multiples of 10000 us. TI platforms have a default of 1000 us.

Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".

Detailed Description

Calling Context

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ Clock_A_clockDisabled

§ Clock_A_badThreadType

§ Clock_A_badTimeout

Typedef Documentation

§ Clock_Module_State

§ Clock_Params

§ Clock_Struct

§ Clock_Object

§ Clock_Handle

§ Clock_Instance

§ Clock_TickSource

§ Clock_TickMode

§ Clock_FuncPtr

Enumeration Type Documentation

§ Clock_TickSource

§ Clock_TickMode

Function Documentation

§ Clock_create()

constraint

§ Clock_construct()

§ Clock_delete()

§ Clock_destruct()

§ Clock_Params_init()

§ Clock_Object_first()

§ Clock_Object_next()

§ Clock_getTicks()

§ Clock_tickStop()

§ Clock_tickReconfig()

§ Clock_tickStart()

§ Clock_tick()

§ Clock_start()

§ Clock_stop()

§ Clock_setPeriod()

§ Clock_setTimeout()

§ Clock_setFunc()

§ Clock_getPeriod()

§ Clock_getTimeout()

§ Clock_isActive()

Variable Documentation

§ Clock_tickSource

§ Clock_tickMode

§ Clock_timerId

§ Clock_tickPeriod