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.
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.
enum Clock.TickSource |
|
Clock Tick Source
XDCscript usage |
meta-domain |
values of type Clock.TickSource
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
typedef enum Clock_TickSource {
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 Clock.FuncPtr |
|
Instance function prototype
typedef Void (*Clock_FuncPtr)(UArg);
metaonly struct Clock.BasicView |
|
XDCscript usage |
meta-domain |
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 ...
metaonly struct Clock.ModuleView |
|
XDCscript usage |
meta-domain |
var obj = new Clock.ModuleView;
obj.ticks = UInt32 ...
obj.tickSource = String ...
obj.timerHandle = String ...
obj.timerId = UInt ...
obj.swiPriority = UInt ...
obj.tickPeriod = UInt32 ...
config Clock.A_badThreadType // module-wide |
|
Asserted in Clock_create and Clock_delete
XDCscript usage |
meta-domain |
msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
};
extern const Assert_Id Clock_A_badThreadType;
config Clock.A_clockDisabled // module-wide |
|
Asserted in Clock_create()
XDCscript usage |
meta-domain |
msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
};
extern const Assert_Id Clock_A_clockDisabled;
config Clock.LM_begin // module-wide |
|
Logged just prior to calling each Clock function
XDCscript usage |
meta-domain |
msg: "LM_begin: clk: 0x%x, func: 0x%x"
};
config Clock.LM_tick // module-wide |
|
Logged in every Clock tick interrupt
XDCscript usage |
meta-domain |
msg: "LM_tick: tick: %d"
};
config Clock.LW_delayed // module-wide |
|
Logged if Clock swi delayed by >= 1 tick
XDCscript usage |
meta-domain |
msg: "LW_delayed: delay: %d"
};
config Clock.tickPeriod // module-wide |
|
Tick period specified in microseconds
XDCscript usage |
meta-domain |
Clock.tickPeriod = UInt32 undefined;
extern const UInt32 Clock_tickPeriod;
DETAILS
Default value is family dependent. For example, linux86 supports a
minimum of 10000us and supports only multiples of 10000us. TI
targets have a default of 1000 microseconds.
config Clock.tickSource // module-wide |
|
Default is TickSource_TIMER
XDCscript usage |
meta-domain |
config Clock.timerId // module-wide |
|
Timer Id for Timer Instance created by Clock.
The default value is Timer.ANY (~0).
The maximum timerId possible is family specific
XDCscript usage |
meta-domain |
extern const UInt Clock_timerId;
metaonly config Clock.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config Clock.swiPriority // module-wide |
|
Set the priority of swi used by Clock module to process its instances
XDCscript usage |
meta-domain |
Clock.swiPriority = UInt undefined;
DETAILS
Default is Swi.numPriorities - 1;
Clock.getTicks( ) // module-wide |
|
Time in Clock ticks
UInt32 Clock_getTicks( );
RETURNS
time in clock ticks
DETAILS
The value returned will wrap back to zero after it reaches the max
value that can be stored in 32 bits.
Clock.getTimerHandle( ) // module-wide |
|
Get timer Handle
RETURNS
Timer Handle
DETAILS
Used when is it necessary to change family
specific options for the timer and its Hwi Object.
Clock.tick( ) // module-wide |
|
Function called by the timer isr when tickSource is
TickSource_TIMER
DETAILS
When
tickSource is set to
TickSource_USER, Clock_tick() is called by a user isr,
Swi or Task. Note that this function is not re-entrant and
appropriate locks should be used.
This function posts a swi that processes the clock instances.
Clock.tickReconfig( ) // module-wide |
|
Reconfigure clock for new cpu frequency
Bool Clock_tickReconfig( );
RETURNS
true if successful
DETAILS
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.
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_setCpuFrequency(Types.FreqHz *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
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to
protect against re-entrancy.
Clock.tickStart( ) // module-wide |
|
Start clock after reconfiguration
DETAILS
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().
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to
protect against re-entrancy.
Clock.tickStop( ) // module-wide |
|
Stop clock for reconfiguration
DETAILS
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.
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to
protect against re-entrancy.
module-wide built-ins |
|
// Get this module's unique id
Bool Clock_Module_startupDone( );
// Test if this module has completed startup
// 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( Bits16 mask );
// Set the diagnostics mask for this module
per-instance object types |
|
typedef struct Clock_Object Clock_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Clock_Struct Clock_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
per-instance config parameters |
|
XDCscript usage |
meta-domain |
var params = new Clock.Params;
// Instance config-params object
params.arg = UArg null;
// UArg for Clock Instance function. Default is null
params.period = UInt 0;
// Instance period. Default is 0
params.startFlag = Bool false;
// Set if instance needs to be started. Default is false
typedef struct Clock_Params {
// Instance config-params structure
// Common per-instance configs
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;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Clock.arg // per-instance |
|
UArg for Clock Instance function. Default is null
XDCscript usage |
meta-domain |
var params = new Clock.Params;
...
params.arg = UArg null;
config Clock.period // per-instance |
|
Instance period. Default is 0
XDCscript usage |
meta-domain |
var params = new Clock.Params;
...
params.period = UInt 0;
DETAILS
For periodic Clock instances this parameter specifies the periodic
timeout interval (in Clock ticks).
For one-shot Clock instances this parameter must be set to zero.
config Clock.startFlag // per-instance |
|
Set if instance needs to be started. Default is false
XDCscript usage |
meta-domain |
var params = new Clock.Params;
...
params.startFlag = Bool false;
DETAILS
When this flag is set the instance created will be started
and the instance function will get called after an interval
equal to its timeout. When set to false, the user has to call
Clock_start() to start the instance.
per-instance creation |
|
XDCscript usage |
meta-domain |
var params =
new Clock.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Clock.create( Void(*)(UArg) clockFxn, UInt timeout, params );
// Create an instance-object
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
clockFxn
function that runs upon timeout
timeout
timeout in clock ticks
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
The first parameter is the function that gets called when the timeout
expires.
The timeout parameter is used to specify the initial timeout
for both one-shot and periodic Clock instances (in Clock ticks).
The
period parameter is used to set the subsequent timeout
interval (in Clock ticks) for periodic instances.
For one-shot instances, the period parameter must be set to zero.
per-instance deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Clock.getTimeout( ) // per-instance |
|
Get timeout of instance
ARGUMENTS
handle
handle of a previously-created Clock instance object
RETURNS
returns timeout in clock ticks
DETAILS
Returns the remaining time if instance has been started.
Clock.setFunc( ) // per-instance |
|
Overwrite Clock function and arg
ARGUMENTS
handle
handle of a previously-created Clock instance object
clockFxn
function of type FuncPtr
arg
argument to clockFxn
DETAILS
Replaces a Clock object's clockFxn function originally
provided in
create.
CONSTRAINTS
Cannot change function and arg of Clock object that has been started.
Clock.setPeriod( ) // per-instance |
|
Set periodic interval
ARGUMENTS
handle
handle of a previously-created Clock instance object
period
periodic interval in Clock ticks
CONSTRAINTS
Cannot change period of instance that has been started.
Clock.setTimeout( ) // per-instance |
|
Set the initial timeout
ARGUMENTS
handle
handle of a previously-created Clock instance object
timeout
initial timeout in Clock ticks
CONSTRAINTS
Cannot change the initial timeout of instance that has been started.
Clock.start( ) // per-instance |
|
Start instance
ARGUMENTS
handle
handle of a previously-created Clock instance object
DETAILS
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.
CONSTRAINTS
Timeout of instance cannot be zero
Clock.stop( ) // per-instance |
|
Stop instance
ARGUMENTS
handle
handle of a previously-created Clock instance object
per-instance built-ins |
|
Int Clock_Object_count( );
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object