module ti.sysbios.knl.Clock

System Clock Manager

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;
 
    typedef Void (*Clock_FuncPtr// Instance function prototype)(UArg);
module-wide config parameters
module-wide functions
module-wide built-ins
per-instance object types
 
per-instance config parameters
        IInstance_Params *instance;
    } Clock_Params;
 
per-instance creation
per-instance deletion
per-instance functions
    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
 
XDCscript usage meta-domain
var Clock = xdc.useModule('ti.sysbios.knl.Clock');
module-wide constants & types
    values of type Clock.TickSource// Clock Tick Source
 
    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
        msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
    };
        msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: clk: 0x%x, func: 0x%x"
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_tick: tick: %d"
    };
        mask: Diags.USER3,
        msg: "LW_delayed: delay: %d"
    };
 
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;
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
    };
 
    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
        msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
    };
        msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: clk: 0x%x, func: 0x%x"
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_tick: tick: %d"
    };
        mask: Diags.USER3,
        msg: "LW_delayed: delay: %d"
    };
 
module-wide functions
    UInt32 getTicks// Time in Clock ticks( );
 
 
instance:
per-instance config parameters
    config UInt period// Instance period. Default is 0 = 0;
per-instance creation
    create// Create an instance-object( Clock.FuncPtr clockFxn, UInt timeout );
per-instance functions
    Void setPeriod// Set periodic interval( UInt period );
    Void setTimeout// Set the initial timeout( UInt timeout );
    Void start// Start instance( );
    Void stop// Stop instance( );
}
DETAILS
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.

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

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
C synopsis target-domain
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

C synopsis target-domain
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
Clock.A_badThreadType = Assert.Desc {
    msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
};
C synopsis target-domain
extern const Assert_Id Clock_A_badThreadType;
 
 
config Clock.A_clockDisabled  // module-wide

Asserted in Clock_create()

XDCscript usage meta-domain
Clock.A_clockDisabled = Assert.Desc {
    msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
};
C synopsis target-domain
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
Clock.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: clk: 0x%x, func: 0x%x"
};
C synopsis target-domain
extern const Log_Event Clock_LM_begin;
 
 
config Clock.LM_tick  // module-wide

Logged in every Clock tick interrupt

XDCscript usage meta-domain
Clock.LM_tick = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_tick: tick: %d"
};
C synopsis target-domain
extern const Log_Event Clock_LM_tick;
 
 
config Clock.LW_delayed  // module-wide

Logged if Clock swi delayed by >= 1 tick

XDCscript usage meta-domain
Clock.LW_delayed = Log.EventDesc {
    mask: Diags.USER3,
    msg: "LW_delayed: delay: %d"
};
C synopsis target-domain
extern const Log_Event Clock_LW_delayed;
 
 
config Clock.tickPeriod  // module-wide

Tick period specified in microseconds

XDCscript usage meta-domain
Clock.tickPeriod = UInt32 undefined;
C synopsis target-domain
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
C synopsis target-domain
extern const Clock_TickSource Clock_tickSource;
 
 
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
Clock.timerId = UInt ~0;
C synopsis target-domain
extern const UInt Clock_timerId;
 
 
metaonly config Clock.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
Clock.common$ = Types.Common$ undefined;
 
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

C synopsis target-domain
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

C synopsis target-domain
Timer_Handle Clock_getTimerHandle( );
 
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

C synopsis target-domain
Void Clock_tick( );
 
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

C synopsis target-domain
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

C synopsis target-domain
Void Clock_tickStart( );
 
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

C synopsis target-domain
Void Clock_tickStop( );
 
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

C synopsis target-domain
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( Bits16 mask );
// Set the diagnostics mask for this module
 
per-instance object types

C synopsis target-domain
typedef struct Clock_Object Clock_Object;
// Opaque internal representation of an instance object
 
typedef Clock_Object *Clock_Handle;
// Client reference to an instance object
 
typedef struct Clock_Struct Clock_Struct;
// Opaque client structure large enough to hold an instance object
 
Clock_Handle Clock_handle( Clock_Struct *structP );
// Convert this instance structure pointer into an instance handle
 
Clock_Struct *Clock_struct( Clock_Handle 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
C synopsis target-domain
typedef struct Clock_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // 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;
 
Void Clock_Params_init( Clock_Params *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;
C synopsis target-domain
struct Clock_Params {
      ...
    UArg arg;
 
 
config Clock.period  // per-instance

Instance period. Default is 0

XDCscript usage meta-domain
var params = new Clock.Params;
  ...
params.period = UInt 0;
C synopsis target-domain
struct Clock_Params {
      ...
    UInt period;
 
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;
C synopsis target-domain
struct Clock_Params {
      ...
    Bool startFlag;
 
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
C synopsis target-domain
Clock_Handle Clock_create( Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params, Error_Block *eb );
// Allocate and initialize a new instance object and return its handle
 
Void Clock_construct( Clock_Struct *structP, Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params );
// 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

C synopsis target-domain
Void Clock_delete( Clock_Handle *handleP );
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Clock_destruct( Clock_Struct *structP );
// Finalize the instance object inside the provided structure
 
Clock.getTimeout( )  // per-instance

Get timeout of instance

C synopsis target-domain
UInt Clock_getTimeout( Clock_Handle handle );
 
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

C synopsis target-domain
Void Clock_setFunc( Clock_Handle handle, Clock_FuncPtr fxn, UArg 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

C synopsis target-domain
Void Clock_setPeriod( Clock_Handle handle, UInt period );
 
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

C synopsis target-domain
Void Clock_setTimeout( Clock_Handle handle, UInt 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

C synopsis target-domain
Void Clock_start( Clock_Handle handle );
 
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

C synopsis target-domain
Void Clock_stop( Clock_Handle handle );
 
ARGUMENTS
handle — handle of a previously-created Clock instance object
 
per-instance built-ins

C synopsis target-domain
Int Clock_Object_count( );
// The number of statically-created instance objects
 
Clock_Handle Clock_Object_get( Clock_Object *array, Int i );
// The handle of the i-th statically-created instance object (array == NULL)
 
Clock_Handle Clock_Object_first( );
// The handle of the first dynamically-created instance object, or NULL
 
Clock_Handle Clock_Object_next( Clock_Handle handle );
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Clock_Object_heap( );
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Clock_Handle_label( Clock_Handle handle, Types_Label *buf );
// The label associated with this instance object
 
String Clock_Handle_name( Clock_Handle handle );
// The name of this instance object
generated on Mon, 21 Dec 2009 19:43:37 GMT