module ti.sysbios.knl.Clock

System Clock Manager

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
Void
Void
UInt32 
UInt32 
UInt32 
Bool 
Void
Void 
Void 
Void 
Void 
Void 
Void 
Bool 
Void 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef Void 
typedef Clock_Object *
typedef struct
typedef struct
typedef struct
typedef enum
typedef enum
Constants
extern const Assert_Id 
extern const Assert_Id 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const Clock_TickMode 
extern const UInt32 
extern const Clock_TickSource 
extern const UInt 
 
DETAILS
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.
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 objects contain functions that can be scheduled to run after a certain number of Clock ticks. Clock objects 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.
By default, all Clock functions run in the context of a Swi. That is, the Clock module automatically creates a Swi for its use and runs the Clock functions within that Swi. The priority of the Swi used by Clock can be changed by configuring Clock.swiPriority.
If Swis are disabled in an application (ie BIOS.swiEnabled = false), then all Clock functions are executed within the context of a Timer Hwi.
NOTE
  • As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.
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

Clock Tick Mode

C synopsis target-domain
typedef enum Clock_TickMode {
    Clock_TickMode_PERIODIC,
    // Timer will interrupt every period
    Clock_TickMode_DYNAMIC
    // Unnecessary timer ticks will be suppressed
} Clock_TickMode;
 
 
enum Clock_TickSource

Clock tick source

C synopsis target-domain
typedef enum Clock_TickSource {
    Clock_TickSource_TIMER,
    // Internally configure a Timer to periodically call Clock_tick()
    Clock_TickSource_USER,
    // Application code calls Clock_tick()
    Clock_TickSource_NULL
    // The Clock module is disabled
} Clock_TickSource;
 
VALUES
TickSource_TIMER — The Clock module automatically configures a a Timer instance (see TimerProxy) to drive the Clock tick. The specific timer and its period can be controlled via timerId and tickPeriod.
TickSource_USER — The Application is responsible for calling Clock_tick() periodically. Make sure Clock.tickPeriod is set to the period that Clock_tick() is called.
Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".
TickSource_NULL — The Clock module is disabled. In this case, it is an error for the application to ever call Clock_tick().
SEE
 
typedef Clock_FuncPtr

Instance function prototype

C synopsis target-domain
typedef Void (*Clock_FuncPtr)(UArg);
 
 
config Clock_A_badThreadType  // module-wide

Asserted in Clock_create and Clock_delete

C synopsis target-domain
extern const Assert_Id Clock_A_badThreadType;
 
 
config Clock_A_clockDisabled  // module-wide

Asserted in Clock_create()

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

C synopsis target-domain
extern const Log_Event Clock_LM_begin;
 
 
config Clock_LM_tick  // module-wide

Logged in every Clock tick interrupt

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

C synopsis target-domain
extern const Log_Event Clock_LW_delayed;
 
 
config Clock_tickMode  // module-wide

Timer tick mode

C synopsis target-domain
extern const Clock_TickMode Clock_tickMode;
 
DETAILS
This parameter specifies the tick mode to be used by the underlying Timer.
With TickMode_PERIODIC the timer will interrupt the CPU at a fixed rate, defined by the tickPeriod.
With TickMode_DYNAMIC the timer can be dynamically reprogrammed by Clock, to interrupt the CPU when the next tick is actually needed for a scheduled timeout. TickMode_DYNAMIC is not supported on all devices, and may have some application constraints (for example, for MSP430, see a description on this wiki page: https://processors.wiki.ti.com/index.php/SYS/BIOS_for_the_MSP430#Clock_Tick_Suppression).
 
config Clock_tickPeriod  // module-wide

Tick period specified in microseconds

C synopsis target-domain
extern const UInt32 Clock_tickPeriod;
 
DETAILS
Default value is family dependent. For example, Linux systems often only support a minimum period of 10000 us and multiples of 10000 us. TI platforms have a default of 1000 us.
Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".
 
config Clock_tickSource  // module-wide

Source of clock ticks

C synopsis target-domain
extern const Clock_TickSource Clock_tickSource;
 
DETAILS
If this parameter is not set to TickSource_TIMER, Clock_tickStart(), Clock_tickStop(), and Clock_tickReconfig(), have no effect.
The default is TickSource_TIMER.
 
config Clock_timerId  // module-wide

Timer Id used to create a Timer instance

C synopsis target-domain
extern const UInt Clock_timerId;
 
DETAILS
If Clock.tickSource is set to TickSource_TIMER, the Clock module internally creates a static Timer instance (see TimerProxy) that automatically calls Clock_doTick() on a periodic basis (as specified by tickPeriod and periodType.)
This configuration parameter allows you to control which timer is used to drive the Clock module.
The default value is Timer.ANY (~0) and the maximum timerId possible is family and device specific.
 
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_tick()  // module-wide

Advance Clock time by one tick

C synopsis target-domain
Void Clock_tick();
 
DETAILS
After incrementing a global tick counter, this function posts a Swi that processes the clock instances.
This function is automatically called by a timer ISR when tickSource is set to TickSource_TIMER.
When tickSource is set to TickSource_USER, Clock_tick() must be called by the application. Usually, this is done within a user defined Hwi, Swi, or Task.
Note that this function is not re-entrant. The application is responsible for ensuring that invocations of this function are serialized: either only one thread in the system ever calls this function or all calls are "wrapped" by an appropriate mutex.
SEE
 
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.
Reconfiguration may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this this function call will have no effect, and will return false.
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_setCpuFreq(&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().
Reconfiguration and restart of a timer may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this function call will have no effect.
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.
Stopping the timer may not be supported for some types of timers, and is not supported for Clock.TickMode_DYNAMIC; in these cases, this this function call will have no effect.
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
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
Instance Config Parameters

C synopsis target-domain
typedef struct Clock_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Uninterpreted argument passed to instance function
    UInt32 period;
    // Period of this instance (in clock ticks)
    Bool startFlag;
    // Start immediately after instance is created
} Clock_Params;
 
Void Clock_Params_init(Clock_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config Clock_Params.arg  // instance

Uninterpreted argument passed to instance function

C synopsis target-domain
struct Clock_Params {
      ...
    UArg arg;
 
DETAILS
The default is null.
 
config Clock_Params.period  // instance

Period of this instance (in clock ticks)

C synopsis target-domain
struct Clock_Params {
      ...
    UInt32 period;
 
DETAILS
This parameter is used to set the subsequent timeout interval (in Clock ticks) for periodic instances.
The default value of this parameter is 0, which indicates this is a one-shot Clock object.
A non zero value for this parameter specifies that the Clock object is to be called periodically, and also specifies the rate (in Clock ticks) that the Clock function will be called AFTER the initial 'timeout' argument period.
For one-shot Clock instances, this parameter must be set to zero.
 
config Clock_Params.startFlag  // instance

Start immediately after instance is created

C synopsis target-domain
struct Clock_Params {
      ...
    Bool startFlag;
 
DETAILS
When this flag is set to false, the user will have to call Clock_start() to start the instance.
When set to true, both statically created Clock objects and Clock objects created in main() are started at the end of main() when the user calls BIOS_start(). Dynamically created Clock objects created after main() (ie within a task) will be started immediately.
The default setting for this parameter is false.
The configured Clock function will be called initially after an interval equal to the 'timeout' argument for both one-shot and periodic Clock objects.
Periodic Clock objects will subsequently be called at the rate specified by the period parameter.
Runtime Instance Creation

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 — One-shot timeout or initial start delay (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 argument is the function that gets called when the timeout expires.
The 'timeout' argument is used to specify the startup timeout for both one-shot and periodic Clock instances (in Clock ticks). This timeout is applied when the Clock instance is started. For periodic instances, the configured Clock function will be called initially after an interval equal to the timeout, and will be subsequently called at the rate specified by the period parameter. For one-shot instances (where the period parameter is 0), once the Clock instance is started (with Clock_start() or automatically if startFlag is true) the configured Clock function will be called once after an interval equal to the timeout.
When instances are created they are placed upon a linked list managed by the Clock module. For this reason, instances cannot be created from either Hwi or Swi context.
By default, all Clock functions run in the context of a Swi. That is, the Clock module automatically creates a Swi for its use and runs the Clock functions within that Swi. The priority of the Swi used by Clock can be changed by configuring Clock.swiPriority.
If Swis are disabled in an application (ie BIOS.swiEnabled = false), then all Clock functions are executed within the context of a Timer Hwi.
CONSTRAINT
  • As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.
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_getPeriod()  // instance

Get period of instance

C synopsis target-domain
UInt32 Clock_getPeriod(Clock_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Clock instance object
RETURNS
returns periodic interval in Clock ticks
DETAILS
Returns the period of an instance.
 
Clock_getTimeout()  // instance

Get timeout of instance

C synopsis target-domain
UInt32 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_isActive()  // instance

Determine if Clock object is currently active (ie running)

C synopsis target-domain
Bool Clock_isActive(Clock_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Clock instance object
RETURNS
returns active state
DETAILS
Returns TRUE if Clock object is currently active
 
Clock_setFunc()  // 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()  // instance

Set periodic interval

C synopsis target-domain
Void Clock_setPeriod(Clock_Handle handle, UInt32 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()  // instance

Set the initial timeout

C synopsis target-domain
Void Clock_setTimeout(Clock_Handle handle, UInt32 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()  // 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()  // instance

Stop instance

C synopsis target-domain
Void Clock_stop(Clock_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Clock instance object
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
 
Configuration settings sourced in ti/sysbios/knl/Clock.xdc
var Clock = xdc.useModule('ti.sysbios.knl.Clock');
local proxy modules
        Clock.TimerProxy.delegate$ = ITimer.Module null
        Clock.TimerProxy.abstractInstances$ = false
module-wide constants & types
    values of type Clock.TickMode// Clock Tick Mode
 
    values of type Clock.TickSource// Clock tick source
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// Uninterpreted argument passed to instance function = UArg null;
        params.period// Period of this instance (in clock ticks) = UInt32 0;
        params.startFlag// Start immediately after instance is created = Bool false;
per-instance creation
    var inst = Clock.create// Create an instance-object(Void(*)(UArg) clockFxn, UInt timeout, params);
 
 
proxy Clock.TimerProxy

target/device-specific Timer implementation

Configuration settings
Clock.TimerProxy = ITimer.Module null
// some delegate module inheriting the ITimer interface
    Clock.TimerProxy.delegate$ = ITimer.Module null
    // explicit access to the currently bound delegate module
    Clock.TimerProxy.abstractInstances$ = false
    // use indirect runtime function calls if true
 
DETAILS
The Timer module used by the Clock module to create a Timer instance when Clock.tickSource_TIMER is configured.
By default, a target specific Timer module is internally selected for this purpose. If the user wishes to use a different Timer module then the following configuration script will serve as an example for achieving that:
  var Clock = xdc.useModule('ti.sysbios.knl.Clock');

  // Use a dmtimer Timer instance
  Clock.TimerProxy = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
 
enum Clock.TickMode

Clock Tick Mode

Configuration settings
values of type Clock.TickMode
    const Clock.TickMode_PERIODIC;
    // Timer will interrupt every period
    const Clock.TickMode_DYNAMIC;
    // Unnecessary timer ticks will be suppressed
 
C SYNOPSIS
 
enum Clock.TickSource

Clock tick source

Configuration settings
values of type Clock.TickSource
    const Clock.TickSource_TIMER;
    // Internally configure a Timer to periodically call Clock_tick()
    const Clock.TickSource_USER;
    // Application code calls Clock_tick()
    const Clock.TickSource_NULL;
    // The Clock module is disabled
 
VALUES
TickSource_TIMER — The Clock module automatically configures a a Timer instance (see TimerProxy) to drive the Clock tick. The specific timer and its period can be controlled via timerId and tickPeriod.
TickSource_USER — The Application is responsible for calling Clock_tick() periodically. Make sure Clock.tickPeriod is set to the period that Clock_tick() is called.
Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".
TickSource_NULL — The Clock module is disabled. In this case, it is an error for the application to ever call Clock_tick().
SEE
C SYNOPSIS
 
config Clock.A_badThreadType  // module-wide

Asserted in Clock_create and Clock_delete

Configuration settings
Clock.A_badThreadType = Assert.Desc {
    msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
};
 
C SYNOPSIS
 
config Clock.A_clockDisabled  // module-wide

Asserted in Clock_create()

Configuration settings
Clock.A_clockDisabled = Assert.Desc {
    msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
};
 
C SYNOPSIS
 
config Clock.LM_begin  // module-wide

Logged just prior to calling each Clock function

Configuration settings
Clock.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: clk: 0x%x, func: 0x%x"
};
 
C SYNOPSIS
 
config Clock.LM_tick  // module-wide

Logged in every Clock tick interrupt

Configuration settings
Clock.LM_tick = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_tick: tick: %d"
};
 
C SYNOPSIS
 
config Clock.LW_delayed  // module-wide

Logged if Clock Swi delayed by >= 1 tick

Configuration settings
Clock.LW_delayed = Log.EventDesc {
    mask: Diags.USER3,
    msg: "LW_delayed: delay: %d"
};
 
C SYNOPSIS
 
config Clock.tickMode  // module-wide

Timer tick mode

Configuration settings
Clock.tickMode = Clock.TickMode undefined;
 
DETAILS
This parameter specifies the tick mode to be used by the underlying Timer.
With TickMode_PERIODIC the timer will interrupt the CPU at a fixed rate, defined by the tickPeriod.
With TickMode_DYNAMIC the timer can be dynamically reprogrammed by Clock, to interrupt the CPU when the next tick is actually needed for a scheduled timeout. TickMode_DYNAMIC is not supported on all devices, and may have some application constraints (for example, for MSP430, see a description on this wiki page: https://processors.wiki.ti.com/index.php/SYS/BIOS_for_the_MSP430#Clock_Tick_Suppression).
C SYNOPSIS
 
config Clock.tickPeriod  // module-wide

Tick period specified in microseconds

Configuration settings
Clock.tickPeriod = UInt32 undefined;
 
DETAILS
Default value is family dependent. For example, Linux systems often only support a minimum period of 10000 us and multiples of 10000 us. TI platforms have a default of 1000 us.
Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".
C SYNOPSIS
 
config Clock.tickSource  // module-wide

Source of clock ticks

Configuration settings
 
DETAILS
If this parameter is not set to TickSource_TIMER, Clock_tickStart(), Clock_tickStop(), and Clock_tickReconfig(), have no effect.
The default is TickSource_TIMER.
C SYNOPSIS
 
config Clock.timerId  // module-wide

Timer Id used to create a Timer instance

Configuration settings
Clock.timerId = UInt ~0;
 
DETAILS
If Clock.tickSource is set to TickSource_TIMER, the Clock module internally creates a static Timer instance (see TimerProxy) that automatically calls Clock_doTick() on a periodic basis (as specified by tickPeriod and periodType.)
This configuration parameter allows you to control which timer is used to drive the Clock module.
The default value is Timer.ANY (~0) and the maximum timerId possible is family and device specific.
C SYNOPSIS
 
metaonly config Clock.common$  // module-wide

Common module configuration parameters

Configuration settings
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.rovViewInfo  // module-wide
Configuration settings
Clock.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly config Clock.swiPriority  // module-wide

The priority of Swi used by Clock to process its instances

Configuration settings
Clock.swiPriority = UInt undefined;
 
DETAILS
All Clock instances are executed in the context of a single Swi. This parameter allows you to control the priority of that Swi.
The default value of this parameter is Swi.numPriorities - 1; i.e., the maximum Swi priority.
SEE
Instance Config Parameters

Configuration settings
var params = new Clock.Params;
// Instance config-params object
    params.arg = UArg null;
    // Uninterpreted argument passed to instance function
    params.period = UInt32 0;
    // Period of this instance (in clock ticks)
    params.startFlag = Bool false;
    // Start immediately after instance is created
 
config Clock.Params.arg  // instance

Uninterpreted argument passed to instance function

Configuration settings
var params = new Clock.Params;
  ...
params.arg = UArg null;
 
DETAILS
The default is null.
C SYNOPSIS
 
config Clock.Params.period  // instance

Period of this instance (in clock ticks)

Configuration settings
var params = new Clock.Params;
  ...
params.period = UInt32 0;
 
DETAILS
This parameter is used to set the subsequent timeout interval (in Clock ticks) for periodic instances.
The default value of this parameter is 0, which indicates this is a one-shot Clock object.
A non zero value for this parameter specifies that the Clock object is to be called periodically, and also specifies the rate (in Clock ticks) that the Clock function will be called AFTER the initial 'timeout' argument period.
For one-shot Clock instances, this parameter must be set to zero.
C SYNOPSIS
 
config Clock.Params.startFlag  // instance

Start immediately after instance is created

Configuration settings
var params = new Clock.Params;
  ...
params.startFlag = Bool false;
 
DETAILS
When this flag is set to false, the user will have to call Clock_start() to start the instance.
When set to true, both statically created Clock objects and Clock objects created in main() are started at the end of main() when the user calls BIOS_start(). Dynamically created Clock objects created after main() (ie within a task) will be started immediately.
The default setting for this parameter is false.
The configured Clock function will be called initially after an interval equal to the 'timeout' argument for both one-shot and periodic Clock objects.
Periodic Clock objects will subsequently be called at the rate specified by the period parameter.
C SYNOPSIS
Static Instance Creation

Configuration settings
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
ARGUMENTS
clockFxn — Function that runs upon timeout
timeout — One-shot timeout or initial start delay (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 argument is the function that gets called when the timeout expires.
The 'timeout' argument is used to specify the startup timeout for both one-shot and periodic Clock instances (in Clock ticks). This timeout is applied when the Clock instance is started. For periodic instances, the configured Clock function will be called initially after an interval equal to the timeout, and will be subsequently called at the rate specified by the period parameter. For one-shot instances (where the period parameter is 0), once the Clock instance is started (with Clock_start() or automatically if startFlag is true) the configured Clock function will be called once after an interval equal to the timeout.
When instances are created they are placed upon a linked list managed by the Clock module. For this reason, instances cannot be created from either Hwi or Swi context.
By default, all Clock functions run in the context of a Swi. That is, the Clock module automatically creates a Swi for its use and runs the Clock functions within that Swi. The priority of the Swi used by Clock can be changed by configuring Clock.swiPriority.
If Swis are disabled in an application (ie BIOS.swiEnabled = false), then all Clock functions are executed within the context of a Timer Hwi.
CONSTRAINT
  • As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.
generated on Tue, 09 Oct 2018 20:57:33 GMT