module ti.sysbios.knl.Clock

System Clock Manager

C synopsis
Individual elements
XDCscript usage
Individual elements

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. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/knl/Clock.xdc

#include <ti/sysbios/knl/Clock.h>

Functions
Void	Clock_construct// Initialize a new instance object inside the provided structure(Clock_Struct structP, Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params params);
Clock_Handle	Clock_create// Allocate and initialize a new instance object and return its handle(Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params params, Error_Block eb);
Void	Clock_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Clock_Handle *handleP);
Void	Clock_destruct// Finalize the instance object inside the provided structure(Clock_Struct *structP);
UInt	Clock_getPeriod// Get period of instance(Clock_Handle handle);
UInt32	Clock_getTicks// Time in Clock ticks();
UInt	Clock_getTimeout// Get timeout of instance(Clock_Handle handle);
Timer_Handle	Clock_getTimerHandle// Get timer Handle();
Void	Clock_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Clock_Params *params);
Void	Clock_setFunc// Overwrite Clock function and arg(Clock_Handle handle, Clock_FuncPtr fxn, UArg arg);
Void	Clock_setPeriod// Set periodic interval(Clock_Handle handle, UInt period);
Void	Clock_setTimeout// Set the initial timeout(Clock_Handle handle, UInt timeout);
Void	Clock_start// Start instance(Clock_Handle handle);
Void	Clock_stop// Stop instance(Clock_Handle handle);
Void	Clock_tick// Advance Clock time by one tick();
Bool	Clock_tickReconfig// Reconfigure clock for new cpu frequency();
Void	Clock_tickStart// Start clock after reconfiguration();
Void	Clock_tickStop// Stop clock for reconfiguration();
Functions common to all target instances
	Clock_handle// Convert this instance structure pointer into an instance handle, Clock_Handle_label// The label associated with this instance object, Clock_Handle_name// The name of this instance object, Clock_Object_count// The number of statically-created instance objects, Clock_Object_first// The handle of the first dynamically-created instance object, or NULL, Clock_Object_get// The handle of the i-th statically-created instance object (array == NULL), Clock_Object_heap// The heap used to allocate dynamically-created instance objects, Clock_Object_next// The handle of the next dynamically-created instance object, or NULL, Clock_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	Clock_Module_getMask// Returns the diagnostics mask for this module, Clock_Module_hasMask// Test whether this module has a diagnostics mask, Clock_Module_heap// The heap from which this module allocates memory, Clock_Module_id// Get this module's unique id, Clock_Module_setMask// Set the diagnostics mask for this module, Clock_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void	(*Clock_FuncPtr// Instance function prototype)(UArg);
typedef Clock_Object *	Clock_Handle// Client reference to an instance object;
typedef struct	Clock_Object// Opaque internal representation of an instance object Clock_Object;
typedef struct	Clock_Params// Instance config-params structure ...
typedef struct	Clock_Struct// Opaque client structure large enough to hold an instance object Clock_Struct;
typedef enum	Clock_TickMode// Clock Tick Mode ...
typedef enum	Clock_TickSource// Clock tick source ...
Constants
extern const Assert_Id	Clock_A_badThreadType// Asserted in Clock_create and Clock_delete;
extern const Assert_Id	Clock_A_clockDisabled// Asserted in Clock_create();
extern const Log_Event	Clock_LM_begin// Logged just prior to calling each Clock function;
extern const Log_Event	Clock_LM_tick// Logged in every Clock tick interrupt;
extern const Log_Event	Clock_LW_delayed// Logged if Clock Swi delayed by >= 1 tick;
extern const Clock_TickMode	Clock_tickMode// Timer tick mode;
extern const UInt32	Clock_tickPeriod// Tick period specified in microseconds;
extern const Clock_TickSource	Clock_tickSource// Source of clock ticks;
extern const UInt	Clock_timerId// Timer Id used to create a Timer instance;

DETAILS

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., MSP430 devices), TickMode_DYNAMIC will 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:

  var Clock = xdc.useModule('ti.sysbios.knl.Clock');

  // Tell the Clock module to use TickMode_PERIODIC
  Clock.tickMode = Clock.TickMode_PERIODIC;

Clock Instances are functions that can be scheduled to run after a certain number of Clock ticks. Clock instances 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.

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

By default, the Clock module statically configures a ti.sysbios.hal.Timer timer instance to provide the periodic 1 ms tick interrupt. If you want to use a custom configured timer for the Clock module's tick source, use the following example configuration as a guide:

  var Clock = xdc.useModule('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
  var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');

  // create a dmtimer config parameter object
  var timerParams = new Timer.Params();

  // make sure you set the period to 1000 us (1ms)
  timerParams.period = 1000;

  // custom dmtimer config parameters here...
  timerParams.twer.ovf_wup_ena = 1;

  // Create the timer.
  // This example uses timer id 3.
  // The timer interrupt handler must be set to 'Clock.tick'. 
  Timer.create(3, Clock.tick, timerParams);

Calling Context

Function	Hwi	Swi	Task	Main	Startup
construct	N	N	Y	Y	N
create	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getTicks	Y	Y	Y	N	N
getTimeout	Y	Y	Y	Y	N
getTimerHandle	Y	Y	Y	Y	Y
Params_init	Y	Y	Y	Y	Y
setFunc	Y	Y	Y	Y	N
setPeriod	Y	Y	Y	Y	N
setTimeout	Y	Y	Y	Y	N
start	Y	Y	Y	Y	N
stop	Y	Y	Y	Y	N
tick	Y	Y	Y	N	N
tickReconfig	Y	Y	Y	N	N
tickStart	Y	Y	Y	N	N
tickStop	Y	Y	Y	N	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 is started (e.g. Clock_Module_startupDone() returns TRUE). 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 is started (e.g. Clock_Module_startupDone() returns FALSE).

enum Clock_TickMode