module ti.sysbios.knl.Clock

System Clock Manager

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation

The System Clock manager is responsible for all timing services in 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 BIOS modules are specified in terms of Clock ticks. [ more ... ]

XDCspec summary sourced in ti/sysbios/knl/Clock.xdc

@ModuleStartup

module Clock { ...

// inherits xdc.runtime.IModule

instance: ...

C synopsis target-domain

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

module-wide constants & types

typedef enum Clock_TickSource// Clock Tick Source {

Clock_TickSource_TIMER// Timer Instance used to generate tick,

Clock_TickSource_USER// Clock_tick() run in user's ISR,

Clock_TickSource_NULL// No clock tick

} Clock_TickSource;

typedef Void (*Clock_FuncPtr// Instance function prototype)(UArg);

module-wide config parameters

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 UInt32 Clock_tickPeriod// Tick period specified in microseconds;

extern const Clock_TickSource Clock_tickSource// Default is TickSource_TIMER;

extern const UInt Clock_timerId// Timer Id for Timer Instance created by Clock. The default value is Timer.ANY (~0). The maximum timerId possible is family specific;

module-wide functions

UInt32 Clock_getTicks// Time in Clock ticks( );

Timer_Handle Clock_getTimerHandle// Get timer Handle( );

Void Clock_tick// Function called by the timer isr when tickSource is TickSource_TIMER( );

Bool Clock_tickReconfig// Reconfigure clock for new cpu frequency( );

Void Clock_tickStart// Start clock after reconfiguration( );

Void Clock_tickStop// Stop clock for reconfiguration( );

module-wide built-ins

Types_ModuleId Clock_Module_id// Get this module's unique id( );

Bool Clock_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle Clock_Module_heap// The heap from which this module allocates memory( );

Bool Clock_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 Clock_Module_getMask// Returns the diagnostics mask for this module( );

Void Clock_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

per-instance object types

typedef struct Clock_Object// Opaque internal representation of an instance object Clock_Object;

typedef Clock_Object *Clock_Handle// Client reference to an instance object;

typedef struct Clock_Struct// Opaque client structure large enough to hold an instance object Clock_Struct;

Clock_Handle Clock_handle// Convert this instance structure pointer into an instance handle( Clock_Struct *structP );

Clock_Struct *Clock_struct// Convert this instance handle into an instance structure pointer( Clock_Handle handle );

per-instance config parameters

typedef struct Clock_Params// Instance config-params structure {

IInstance_Params *instance;

UArg arg// UArg for Clock Instance function. Default is null;

UInt period// Instance period. Default is 0;

Bool startFlag// Set if instance needs to be started. Default is false;

} Clock_Params;

Void Clock_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation( Clock_Params *params );

per-instance creation

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_construct// Initialize a new instance object inside the provided structure( Clock_Struct *structP, Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params );

per-instance deletion

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

per-instance functions

UInt Clock_getTimeout// Get timeout of instance( Clock_Handle handle );

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

per-instance built-ins

Int Clock_Object_count// The number of statically-created instance objects( );

Clock_Handle Clock_Object_get// The handle of the i-th statically-created instance object (array == NULL)( Clock_Object *array, Int i );

Clock_Handle Clock_Object_first// The handle of the first dynamically-created instance object, or NULL( );

Clock_Handle Clock_Object_next// The handle of the next dynamically-created instance object, or NULL( Clock_Handle handle );

IHeap_Handle Clock_Object_heap// The heap used to allocate dynamically-created instance objects( );

Types_Label *Clock_Handle_label// The label associated with this instance object( Clock_Handle handle, Types_Label *buf );

String Clock_Handle_name// The name of this instance object( Clock_Handle handle );

XDCscript usage meta-domain

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

module-wide constants & types

values of type Clock.TickSource// Clock Tick Source

const Clock.TickSource_TIMER// Timer Instance used to generate tick;

const Clock.TickSource_USER// Clock_tick() run in user's ISR;

const Clock.TickSource_NULL// No clock tick;

var obj = new Clock.BasicView// ;

obj.label = String ...

obj.timeout = UInt32 ...

obj.period = UInt ...

obj.fxn = String[] ...

obj.arg = UArg ...

obj.started = Bool ...

obj.tRemaining = UInt32 ...

obj.periodic = Bool ...

var obj = new Clock.ModuleView// ;

obj.ticks = UInt32 ...

obj.tickSource = String ...

obj.timerHandle = String ...

obj.timerId = UInt ...

obj.swiPriority = UInt ...

obj.tickPeriod = UInt32 ...

module-wide config parameters

Clock.A_badThreadType// Asserted in Clock_create and Clock_delete = Assert.Desc {

msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."

};

Clock.A_clockDisabled// Asserted in Clock_create() = Assert.Desc {

msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."

};

Clock.LM_begin// Logged just prior to calling each Clock function = Log.EventDesc {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_begin: clk: 0x%x, func: 0x%x"

};

Clock.LM_tick// Logged in every Clock tick interrupt = Log.EventDesc {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_tick: tick: %d"

};

Clock.LW_delayed// Logged if Clock swi delayed by >= 1 tick = Log.EventDesc {

mask: Diags.USER3,

msg: "LW_delayed: delay: %d"

};

Clock.tickPeriod// Tick period specified in microseconds = UInt32 undefined;

Clock.tickSource// Default is TickSource_TIMER = Clock.TickSource Clock.TickSource_TIMER;

Clock.timerId// Timer Id for Timer Instance created by Clock. The default value is Timer.ANY (~0). The maximum timerId possible is family specific = UInt ~0;

Clock.common$// Common module configuration parameters = Types.Common$ undefined;

Clock.swiPriority// Set the priority of swi used by Clock module to process its instances = UInt undefined;

per-instance config parameters

var params = new Clock.Params// Instance config-params object;

params.arg// UArg for Clock Instance function. Default is null = UArg null;

params.period// Instance period. Default is 0 = UInt 0;

params.startFlag// Set if instance needs to be started. Default is false = Bool false;

per-instance creation

var inst = Clock.create// Create an instance-object( Void(*)(UArg) clockFxn, UInt timeout, params );

XDCspec declarations sourced in ti/sysbios/knl/Clock.xdc

package ti.sysbios.knl;

@ModuleStartup

module Clock {

module-wide constants & types

enum TickSource// Clock Tick Source {

TickSource_TIMER// Timer Instance used to generate tick,

TickSource_USER// Clock_tick() run in user's ISR,

TickSource_NULL// No clock tick

};

typedef Void (*FuncPtr// Instance function prototype)(UArg);

metaonly struct BasicView// {

String label;

UInt32 timeout;

UInt period;

String fxn[];

UArg arg;

Bool started;

UInt32 tRemaining;

Bool periodic;

};

metaonly struct ModuleView// {

UInt32 ticks;

String tickSource;

String timerHandle;

UInt timerId;

UInt swiPriority;

UInt32 tickPeriod;

};

module-wide config parameters

config Assert.Id A_badThreadType// Asserted in Clock_create and Clock_delete = {

msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."

};

config Assert.Id A_clockDisabled// Asserted in Clock_create() = {

msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."

};

config Log.Event LM_begin// Logged just prior to calling each Clock function = {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_begin: clk: 0x%x, func: 0x%x"

};

config Log.Event LM_tick// Logged in every Clock tick interrupt = {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_tick: tick: %d"

};

config Log.Event LW_delayed// Logged if Clock swi delayed by >= 1 tick = {

mask: Diags.USER3,

msg: "LW_delayed: delay: %d"

};

config UInt32 tickPeriod// Tick period specified in microseconds;

config Clock.TickSource tickSource// Default is TickSource_TIMER = Clock.TickSource_TIMER;

config UInt timerId// Timer Id for Timer Instance created by Clock. The default value is Timer.ANY (~0). The maximum timerId possible is family specific = ~0;

metaonly config Types.Common$ common$// Common module configuration parameters;

metaonly config UInt swiPriority// Set the priority of swi used by Clock module to process its instances;

module-wide functions

UInt32 getTicks// Time in Clock ticks( );

Timer.Handle getTimerHandle// Get timer Handle( );

Void tick// Function called by the timer isr when tickSource is TickSource_TIMER( );

Bool tickReconfig// Reconfigure clock for new cpu frequency( );

Void tickStart// Start clock after reconfiguration( );

Void tickStop// Stop clock for reconfiguration( );

instance:

per-instance config parameters

config UArg arg// UArg for Clock Instance function. Default is null = null;

config UInt period// Instance period. Default is 0 = 0;

config Bool startFlag// Set if instance needs to be started. Default is false = false;

per-instance creation

create// Create an instance-object( Clock.FuncPtr clockFxn, UInt timeout );

per-instance functions

UInt getTimeout// Get timeout of instance( );

Void setFunc// Overwrite Clock function and arg( Clock.FuncPtr fxn, UArg arg );

Void setPeriod// Set periodic interval( UInt period );

Void setTimeout// Set the initial timeout( UInt timeout );

Void start// Start instance( );

Void stop// Stop instance( );

}

DETAILS

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.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
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
construct	N	N	Y	Y	N
create	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getTimeout	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.TickSource