module ti.sysbios.knl.Clock

System Clock Manager

C synopsis
Individual elements
Configuration settings
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);
UInt32	Clock_getPeriod// Get period of instance(Clock_Handle handle);
UInt32	Clock_getTicks// Time in Clock ticks();
UInt32	Clock_getTimeout// Get timeout of instance(Clock_Handle handle);
Bool	Clock_isActive// Determine if Clock object is currently active (ie running)(Clock_Handle 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, UInt32 period);
Void	Clock_setTimeout// Set the initial timeout(Clock_Handle handle, UInt32 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 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:

  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 Timer module defined by TimerProxy is used to statically create a timer instance that provides a 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');

  // Change Timer 3 frequency to 24 Mhz from default if necessary
  Timer.intFreqs[3] = { hi:0, lo:24000000 };

  // 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.
  // Provide your own timer interrupt handler function.
  Timer.create(3, '&myTimerTick', timerParams);

In your 'C' code, 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>

  Void myTimerTick(UArg arg)
  {
       Clock_tick();
       ...
  }

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
getTimerHandle	Y	Y	Y	Y	Y
Params_init	Y	Y	Y	Y	Y
tick	Y	Y	Y	N	N
tickReconfig	Y	Y	Y	N	N
tickStart	Y	Y	Y	N	N
tickStop	Y	Y	Y	N	N
getTimeout	Y	Y	Y	Y	N
isActive	Y	Y	Y	Y	N
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
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