SYS/BIOS
7.00
|
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.
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., CC13xx/CC26xx 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:
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 the Clock.swiPriority configuration parameter.
If Swis are disabled in an application (if config parameter 'BIOS.swiEnabled' is set to false), then all Clock functions are executed within the context of a Timer Hwi.
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.
If you want to use a custom configured timer for the Clock module's tick source, use the following example configuration as a guide:
In your 'C' code, construct your timer, and add your timer interrupt handler and have it call Clock_tick(), which will perform all of the Clock module tick duties:
Function | Hwi | Swi | Task | Main | Startup |
---|---|---|---|---|---|
Clock_construct | N | N | Y | Y | N |
Clock_create | N | N | Y | Y | N |
Clock_delete | N | N | Y | Y | N |
Clock_destruct | N | N | Y | Y | N |
Clock_getTicks | Y | Y | Y | N | N |
Clock_getTimerHandle | Y | Y | Y | Y | Y |
Clock_Params_init | Y | Y | Y | Y | Y |
Clock_tick | Y | Y | Y | N | N |
Clock_tickReconfig | Y | Y | Y | N | N |
Clock_tickStart | Y | Y | Y | N | N |
Clock_tickStop | Y | Y | Y | N | N |
Clock_getTimeout | Y | Y | Y | Y | N |
Clock_isActive | Y | Y | Y | Y | N |
Clock_setFunc | Y | Y | Y | Y | N |
Clock_setPeriod | Y | Y | Y | Y | N |
Clock_setTimeout | Y | Y | Y | Y | N |
Clock_start | Y | Y | Y | Y | N |
Clock_stop | Y | Y | Y | Y | N |
Definitions:
|
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Swi.h>
#include <ti/sysbios/runtime/Error.h>
Go to the source code of this file.
Data Structures | |
struct | Clock_Params |
struct | Clock_Module_State |
struct | Clock_Struct |
Macros | |
#define | Clock_A_clockDisabled "Cannot create a clock instance when BIOS.clockEnabled is false." |
Asserted in Clock_create. More... | |
#define | Clock_A_badThreadType "Cannot create/delete a Clock from a Hwi or Swi thread." |
Asserted in Clock_create and Clock_delete. More... | |
#define | Clock_A_badTimeout "Bad timeout value." |
Asserted in Clock_create and Clock_delete. More... | |
Typedefs | |
typedef struct Clock_Module_State | Clock_Module_State |
typedef struct Clock_Params | Clock_Params |
typedef struct Clock_Struct | Clock_Struct |
typedef struct Clock_Struct | Clock_Object |
typedef Clock_Object * | Clock_Handle |
typedef Clock_Object * | Clock_Instance |
typedef enum Clock_TickSource | Clock_TickSource |
typedef enum Clock_TickMode | Clock_TickMode |
Clock Tick Mode. More... | |
typedef void(* | Clock_FuncPtr) (uintptr_t arg1) |
Instance function prototype. More... | |
Enumerations | |
enum | Clock_TickSource { Clock_TickSource_TIMER, Clock_TickSource_USER, Clock_TickSource_NULL } |
Clock tick source. More... | |
enum | Clock_TickMode { Clock_TickMode_PERIODIC, Clock_TickMode_DYNAMIC } |
Clock Tick Mode. More... | |
Functions | |
Clock_Handle | Clock_create (Clock_FuncPtr clockFxn, unsigned int timeout, const Clock_Params *prms, Error_Block *eb) |
Creates a Clock Instance. More... | |
Clock_Handle | Clock_construct (Clock_Struct *obj, Clock_FuncPtr clockFxn, unsigned int timeout, const Clock_Params *prms) |
Construct a Clock. More... | |
void | Clock_delete (Clock_Handle *clock) |
Delete a Clock. More... | |
void | Clock_destruct (Clock_Struct *obj) |
Destruct a Clock. More... | |
void | Clock_Params_init (Clock_Params *prms) |
Initialize the Clock_Params structure with default values. More... | |
Clock_Handle | Clock_Object_first (void) |
return handle of the first Clock on Clock list More... | |
Clock_Handle | Clock_Object_next (Clock_Handle clock) |
return handle of the next Clock on Clock list More... | |
uint32_t | Clock_getTicks (void) |
Time in Clock ticks. More... | |
void | Clock_tickStop (void) |
Stop clock for reconfiguration. More... | |
bool | Clock_tickReconfig (void) |
Reconfigure clock for new cpu frequency. More... | |
void | Clock_tickStart (void) |
Start clock after reconfiguration. More... | |
void | Clock_tick (void) |
Advance Clock time by one tick. More... | |
void | Clock_start (Clock_Handle clock) |
Start instance. More... | |
void | Clock_stop (Clock_Handle clock) |
Stop instance. More... | |
void | Clock_setPeriod (Clock_Handle clock, uint32_t period) |
Set periodic interval. More... | |
void | Clock_setTimeout (Clock_Handle clock, uint32_t timeout) |
Set the initial timeout. More... | |
void | Clock_setFunc (Clock_Handle clock, Clock_FuncPtr fxn, uintptr_t arg) |
Overwrite Clock function and arg. More... | |
uint32_t | Clock_getPeriod (Clock_Handle clock) |
Get period of instance. More... | |
uint32_t | Clock_getTimeout (Clock_Handle clock) |
Get timeout of instance. More... | |
bool | Clock_isActive (Clock_Handle clock) |
Determine if Clock object is currently active (ie running) More... | |
Variables | |
const Clock_TickSource | Clock_tickSource |
Source of clock ticks. More... | |
const Clock_TickMode | Clock_tickMode |
Timer tick mode. More... | |
const unsigned int | Clock_timerId |
Timer Id used to create a Timer instance. More... | |
const uint32_t | Clock_tickPeriod |
Tick period specified in microseconds. More... | |
#define Clock_A_clockDisabled "Cannot create a clock instance when BIOS.clockEnabled is false." |
Asserted in Clock_create.
#define Clock_A_badThreadType "Cannot create/delete a Clock from a Hwi or Swi thread." |
Asserted in Clock_create and Clock_delete.
#define Clock_A_badTimeout "Bad timeout value." |
Asserted in Clock_create and Clock_delete.
typedef struct Clock_Module_State Clock_Module_State |
typedef struct Clock_Params Clock_Params |
typedef struct Clock_Struct Clock_Struct |
typedef struct Clock_Struct Clock_Object |
typedef Clock_Object* Clock_Handle |
typedef Clock_Object* Clock_Instance |
typedef enum Clock_TickSource Clock_TickSource |
typedef enum Clock_TickMode Clock_TickMode |
Clock Tick Mode.
typedef void(* Clock_FuncPtr) (uintptr_t arg1) |
Instance function prototype.
enum Clock_TickSource |
Clock tick source.
Like most other module configuration parameters, the Clock.tickPeriod config parameter value is accessible in runtime C code as "Clock_tickPeriod".
Enumerator | |
---|---|
Clock_TickSource_TIMER | The Clock module automatically configures a a Timer instance to drive the Clock tick. The specific timer and its period can be controlled via Clock_timerId and Clock_tickPeriod. |
Clock_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. |
Clock_TickSource_NULL | The Clock module is disabled. In this case, it is an error for the application to ever call Clock_tick(). |
enum Clock_TickMode |
Clock_Handle Clock_create | ( | Clock_FuncPtr | clockFxn, |
unsigned int | timeout, | ||
const Clock_Params * | prms, | ||
Error_Block * | eb | ||
) |
Creates a Clock Instance.
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 with the Clock.swiPriority configuration parameter.
If Swis are disabled in an application (config parmeter BIOS.swiEnabled is set to false), then all Clock functions are executed within the context of a Timer Hwi.
As Clock functions execute in either a Swi or Hwi context, they are not permitted to call blocking APIs.
clockFxn | Function that runs upon timeout |
timeout | One-shot timeout or initial start delay (in clock ticks) |
prms | Clock parameters |
eb | Error block |
Clock | handle |
Clock_Handle Clock_construct | ( | Clock_Struct * | obj, |
Clock_FuncPtr | clockFxn, | ||
unsigned int | timeout, | ||
const Clock_Params * | prms | ||
) |
Construct a Clock.
Clock_construct is equivalent to Clock_create except that the Clock_Struct is pre-allocated. See Clock_create() for a description of this API.
obj | pointer to a Clock object |
clockFxn | Clock function |
timeout | One-shot timeout or initial start delay (in clock ticks) |
prms | Clock parameters |
Clock | handle (NULL on failure) |
void Clock_delete | ( | Clock_Handle * | clock | ) |
Delete a Clock.
Clock_delete deletes a Clock object. Note that Clock_delete takes a pointer to a Clock_Handle which enables Clock_delete to set the Clock_handle to NULL.
clock | pointer to Clock handle |
void Clock_destruct | ( | Clock_Struct * | obj | ) |
Destruct a Clock.
Clock_destruct destructs a Clock object.
obj | pointer to Clock object |
void Clock_Params_init | ( | Clock_Params * | prms | ) |
Initialize the Clock_Params structure with default values.
Clock_Params_init initializes the Clock_Params structure with default values. Clock_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.
prms | pointer to uninitialized params structure |
Clock_Handle Clock_Object_first | ( | void | ) |
return handle of the first Clock on Clock list
Return the handle of the first Clock on the create/construct list. NULL if no Clocks have been created or constructed.
Clock | handle |
Clock_Handle Clock_Object_next | ( | Clock_Handle | clock | ) |
return handle of the next Clock on Clock list
Return the handle of the next Clock on the create/construct list. NULL if no more Clocks are on the list.
clock | Clock handle |
Clock | handle |
uint32_t Clock_getTicks | ( | void | ) |
Time in Clock ticks.
The value returned will wrap back to zero after it reaches the max value that can be stored in 32 bits.
time | in clock ticks |
void Clock_tickStop | ( | void | ) |
Stop clock for reconfiguration.
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.
bool Clock_tickReconfig | ( | void | ) |
Reconfigure clock for new cpu frequency.
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:
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():
The return value is false if the timer cannot support the new frequency
true | if successful |
void Clock_tickStart | ( | void | ) |
Start clock after reconfiguration.
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.
void Clock_tick | ( | void | ) |
Advance Clock time by one tick.
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 Clock_tickSource is set to Clock_TickSource_TIMER.
When Clock_tickSource is set to Clock_TickSource_USER, Clock_tick() must be called by the application. Usually, this is done within a user defined ISR.
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.
void Clock_start | ( | Clock_Handle | clock | ) |
Start instance.
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.
void Clock_stop | ( | Clock_Handle | clock | ) |
Stop instance.
clock | Clock handle |
void Clock_setPeriod | ( | Clock_Handle | clock, |
uint32_t | period | ||
) |
Set periodic interval.
clock | Clock handle |
period | periodic interval in Clock ticks |
void Clock_setTimeout | ( | Clock_Handle | clock, |
uint32_t | timeout | ||
) |
Set the initial timeout.
clock | Clock handle |
timeout | initial timeout in Clock ticks |
void Clock_setFunc | ( | Clock_Handle | clock, |
Clock_FuncPtr | fxn, | ||
uintptr_t | arg | ||
) |
Overwrite Clock function and arg.
Replaces a Clock object's clockFxn function originally provided in Clock_create.
clock | Clock handle |
fxn | Clock function |
arg | argument to clock function |
uint32_t Clock_getPeriod | ( | Clock_Handle | clock | ) |
Get period of instance.
Returns the period of an instance.
clock | Clock handle |
returns | periodic interval in Clock ticks |
uint32_t Clock_getTimeout | ( | Clock_Handle | clock | ) |
Get timeout of instance.
Returns the remaining time if the instance is active; if the instance is not active, returns zero.
clock | Clock handle |
returns | timeout in clock ticks |
bool Clock_isActive | ( | Clock_Handle | clock | ) |
Determine if Clock object is currently active (ie running)
Returns true if Clock object is currently active
clock | Clock handle |
returns | active state |
const Clock_TickSource Clock_tickSource |
Source of clock ticks.
If this parameter is not set to TickSource_TIMER, Clock_tickStart, Clock_tickStop, and Clock_tickReconfig, have no effect.
The default is Clock_TickSource_TIMER.
const Clock_TickMode Clock_tickMode |
Timer tick mode.
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.
const unsigned int Clock_timerId |
Timer Id used to create a Timer instance.
If Clock_tickSource is set to TickSource_TIMER, the Clock module internally creates a static Timer instance that automatically calls Clock_tick() on a periodic basis (as specified by Clock_tickPeriod.)
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 device specific.
const uint32_t Clock_tickPeriod |
Tick period specified in microseconds.
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".