module ti.sysbios.timers.rti.Timer
index URL

RTI Timer Peripheral Manager

This Timer module manages the RTI timer peripheral(s) available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/timers/rti/Timer.xdc
#include <ti/sysbios/timers/rti/Timer.h>
Functions
Void 
Timer_ackInterrupt// clear the current timer interrupt flag(Timer_Handle handle);
Void
Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle
Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void
Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void
Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void
Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void 
Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 
Timer_getCount// Read timer counter register(Timer_Handle handle);
Void 
Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr 
Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt 
Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 
Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status 
Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void 
Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void 
Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool 
Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void 
Timer_start// Reload and start the timer(Timer_Handle handle);
Void 
Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define
Timer_ANY// Const used to specify any timer (UInt)~0
#define
Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
Typedefs
typedef Void 
(*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object *
Timer_Handle// Client reference to an instance object;
typedef struct
Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct
Timer_Params// Instance config-params structure ...
typedef enum
Timer_PeriodType// Timer period units ...
typedef enum
Timer_RunMode// Timer Run Modes ...
typedef enum
Timer_StartMode// Timer Start Modes ...
typedef enum
Timer_Status// Timer Status ...
typedef struct
Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt 
Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Assert_Id 
Timer_A_invalidTimer// Assert raised when timer id specified is not supported;
extern const Bool 
Timer_continueOnSuspend// Continue counting during emulation halt. Default is false;
extern const Error_Id 
Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id 
Timer_E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on;
extern const Error_Id 
Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id 
Timer_E_notAvailable// Error raised when timer requested is in use;
 
DETAILS
This Timer module manages the RTI timer peripheral(s) available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information).

Calling Context

Function Hwi Swi Task Main Startup
getNumTimers Y Y Y Y N
getStatus Y Y Y Y N
Params_init Y Y Y Y N
construct Y Y Y Y N
create N N Y Y N
delete N N Y Y N
destruct Y Y Y Y N
getCount Y Y Y N N
getFreq Y Y Y Y N
getPeriod Y Y Y Y N
reconfig Y Y Y Y N
setPeriod Y Y Y Y N
setPeriodMicroSecs Y Y Y Y N
start Y Y Y N N
stop Y Y Y N 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. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
 
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
 
 
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
 
 
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
 
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
 
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed (available on subset of devices)
} Timer_RunMode;
 
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick. This mode is intended only for use by the Clock module when it is operating in TickMode_DYNAMIC; it is not applicable for user-created Timer instances.
 
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
 
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
 
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
 
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
 
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
 
 
config Timer_A_invalidTimer  // module-wide
index URL

Assert raised when timer id specified is not supported

C synopsis target-domain
extern const Assert_Id Timer_A_invalidTimer;
 
 
config Timer_E_cannotSupport  // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
 
 
config Timer_E_invalidHwiMask  // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

C synopsis target-domain
extern const Error_Id Timer_E_invalidHwiMask;
 
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
 
config Timer_E_invalidTimer  // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
 
 
config Timer_E_notAvailable  // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
 
 
config Timer_anyMask  // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
 
 
config Timer_continueOnSuspend  // module-wide
index URL

Continue counting during emulation halt. Default is false

C synopsis target-domain
extern const Bool Timer_continueOnSuspend;
 
DETAILS
When false, timer stops counting during emulation halt. When true, timer continues to count during emulation halt.
 
Timer_getNumTimers()  // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
 
RETURNS
Number of timer peripherals.
 
Timer_getStatus()  // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
 
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
 
Bool Timer_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
 
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
 
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
 
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
 
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
    Bool createHwi;
    // Controls whether the timer module creates a Hwi. Default is true
    Types_FreqHz extFreq;
    // Timer frequency
    Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
    ITimer_PeriodType periodType;
    // Period type
    UInt8 prescale;
    // Prescale factor. Default is 1 (0 is not recommended)
    ITimer_RunMode runMode;
    // Timer run mode
    ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
 
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config Timer_Params.arg  // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
      ...
    UArg arg;
 
DETAILS
Default is null.
 
config Timer_Params.createHwi  // instance
index URL

Controls whether the timer module creates a Hwi. Default is true

C synopsis target-domain
struct Timer_Params {
      ...
    Bool createHwi;
 
DETAILS
If an application needs to create a Hwi for the timer, it is possible to indicate to the timer module to not create a Hwi by setting this param to false. This feature may be useful if the application needs to create a Hwi using the family specific Hwi module or on certain ARM targets create a Hwi of FIQ type to minimize latency.
If the application creates its own Hwi, it needs to select an interrupt number corresponding to the timer Id (see Timer Mapping Tables).
Here's an example for the Cortex-R4 target that creates a custom Hwi of FIQ type and sets "Timer.createHwi" param to false when creating a Timer object, in order to prevent the Timer module from creating a Hwi.
  *.cfg:
  xdc.useModule('ti.sysbios.timers.rti.Timer');
  xdc.useModule('ti.sysbios.family.arm.v7r.vim.Hwi');

  *.c:
  #include <xdc/std.h>
  #include <xdc/runtime/Error.h>

  #include <ti/sysbios/timers/rti/Timer.h>
  #include <ti/sysbios/family/arm/v7r/vim/Hwi.h>
  ...

  Timer_Struct timer0;
  Timer_Handle handle0;

  interrupt Void myIsr()
  {
      // Timer needs to be stopped only if run mode is One shot.
      // For periodic run mode, this function needs to only ack
      // the timer interrupt.
      Timer_stop(handle0);
      Timer_ackInterrupt(handle0);
      ...
  }

  Int main(Int argc, char* argv[])
  {
      Timer_Params timerParams;
      Hwi_Params hwiParams;
      Error_Block eb;

      Error_init(&eb);

      // The interrupt number corresponding to a given Timer Id
      // can be determined from the Timer Mapping table. A link
      // to the table can be found in this document.
      Hwi_Params_init(&hwiParams);
      hwiParams.type = Hwi_Type_FIQ;
      Hwi_create(2, (Hwi_FuncPtr)(&myIsr), &hwiParams, &eb);

      Timer_Params_init(&timerParams);
      timerParams.period = 60000;
      timerParams.runMode = Timer_RunMode_ONESHOT;
      timerParams.periodType = Timer_PeriodType_MICROSECS;
      timerParams.createHwi = FALSE;
      Timer_construct(&timer0, 0, NULL, &timerParams, &eb);

      handle0 = Timer_handle(&timer0);
      ...

      BIOS_start();
      return(0);
  }
 
config Timer_Params.extFreq  // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
      ...
    Types_FreqHz extFreq;
 
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
 
config Timer_Params.hwiParams  // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
      ...
    Hwi_Params *hwiParams;
 
 
config Timer_Params.period  // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
      ...
    UInt32 period;
 
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
 
config Timer_Params.periodType  // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
      ...
    ITimer_PeriodType periodType;
 
DETAILS
Default is PeriodType_MICROSECS
 
config Timer_Params.prescale  // instance
index URL

Prescale factor. Default is 1 (0 is not recommended)

C synopsis target-domain
struct Timer_Params {
      ...
    UInt8 prescale;
 
DETAILS
The Prescale factor can be used to achieve longer timer periods. With a prescale factor specified, the actual timer period is period * (prescale + 1).
 
config Timer_Params.runMode  // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
      ...
    ITimer_RunMode runMode;
 
DETAILS
Default is RunMode_CONTINUOUS.
 
config Timer_Params.startMode  // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
      ...
    ITimer_StartMode startMode;
 
DETAILS
Default is StartMode_AUTO.
Runtime Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
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
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
 
Timer_ackInterrupt()  // instance
index URL

clear the current timer interrupt flag

C synopsis target-domain
Void Timer_ackInterrupt(Timer_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
 
Timer_getCount()  // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
 
Timer_getFreq()  // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
 
Timer_getFunc()  // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
 
Timer_getPeriod()  // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
 
Timer_reconfig()  // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires.
 
Timer_setFunc()  // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
 
Timer_setPeriod()  // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
 
Timer_setPeriodMicroSecs()  // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
 
Timer_start()  // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
 
Timer_stop()  // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
 
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/timers/rti/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.timers.rti.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
 
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
 
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed (available on subset of devices);
 
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
 
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
 
    var obj = new Timer.TimerSetting// Timer Settings;
        obj.baseAddr// specify the base address = Ptr  ...
        obj.intNum// specify which interrupt vector = Int  ...
        obj.eventId// specify which event number to use = Int  ...
        obj.name// specify the timer name = String  ...
module-wide config parameters
    Timer.A_invalidTimer// Assert raised when timer id specified is not supported = Assert.Desc {
        msg: "A_invalidTimer: Invalid Timer Id."
    };
    Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
    Timer.E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on = Error.Desc {
        msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
    };
    Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
    Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
    Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt undefined;
    Timer.continueOnSuspend// Continue counting during emulation halt. Default is false = Bool false;
 
    Timer.common$// Common module configuration parameters = Types.Common$ undefined;
    Timer.intFreqs// Default internal timer input clock frequency array = Types.FreqHz[] undefined;
    Timer.timerSettings// Global Control configuration for each physical timer = Timer.TimerSetting[] [ ];
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.createHwi// Controls whether the timer module creates a Hwi. Default is true = Bool true;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.prescale// Prescale factor. Default is 1 (0 is not recommended) = UInt8 1;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
 
 
const Timer.ANY
index URL

Const used to specify any timer

Configuration settings
const Timer.ANY = ~0;
 
C SYNOPSIS
Timer_ANY
 
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

Configuration settings
const Timer.MAX_PERIOD = 0xffffffff;
 
C SYNOPSIS
Timer_MAX_PERIOD
 
enum Timer.PeriodType
index URL

Timer period units

Configuration settings
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
 
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
 
enum Timer.RunMode
index URL

Timer Run Modes

Configuration settings
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed (available on subset of devices)
 
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick. This mode is intended only for use by the Clock module when it is operating in TickMode_DYNAMIC; it is not applicable for user-created Timer instances.
C SYNOPSIS
Timer_RunMode
 
enum Timer.StartMode
index URL

Timer Start Modes

Configuration settings
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
 
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
 
enum Timer.Status
index URL

Timer Status

Configuration settings
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
 
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
 
metaonly struct Timer.TimerSetting
index URL

Timer Settings

Configuration settings
var obj = new Timer.TimerSetting;
 
    obj.baseAddr = Ptr  ...
    // specify the base address
    obj.intNum = Int  ...
    // specify which interrupt vector
    obj.eventId = Int  ...
    // specify which event number to use
    obj.name = String  ...
    // specify the timer name
 
 
config Timer.A_invalidTimer  // module-wide
index URL

Assert raised when timer id specified is not supported

Configuration settings
Timer.A_invalidTimer = Assert.Desc {
    msg: "A_invalidTimer: Invalid Timer Id."
};
 
C SYNOPSIS
Timer_A_invalidTimer
 
config Timer.E_cannotSupport  // module-wide
index URL

Error raised when period requested is not supported

Configuration settings
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
 
C SYNOPSIS
Timer_E_cannotSupport
 
config Timer.E_invalidHwiMask  // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

Configuration settings
Timer.E_invalidHwiMask = Error.Desc {
    msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
};
 
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
C SYNOPSIS
Timer_E_invalidHwiMask
 
config Timer.E_invalidTimer  // module-wide
index URL

Error raised when timer id specified is not supported

Configuration settings
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
 
C SYNOPSIS
Timer_E_invalidTimer
 
config Timer.E_notAvailable  // module-wide
index URL

Error raised when timer requested is in use

Configuration settings
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
 
C SYNOPSIS
Timer_E_notAvailable
 
config Timer.anyMask  // module-wide
index URL

Available mask to be used when select = Timer_ANY

Configuration settings
Timer.anyMask = UInt undefined;
 
C SYNOPSIS
Timer_anyMask
 
config Timer.continueOnSuspend  // module-wide
index URL

Continue counting during emulation halt. Default is false

Configuration settings
Timer.continueOnSuspend = Bool false;
 
DETAILS
When false, timer stops counting during emulation halt. When true, timer continues to count during emulation halt.
C SYNOPSIS
Timer_continueOnSuspend
 
metaonly config Timer.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
Timer.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 Timer.intFreqs  // module-wide
index URL

Default internal timer input clock frequency array

Configuration settings
Timer.intFreqs = Types.FreqHz[] undefined;
 
DETAILS
This array can be used to change the input clock frequency for a particular timer.
For example, if it is required to change the input clock frequency for timer id 1 to 200MHz on a device that has 2 timers, the intFreqs[1] config param can be set to {hi:0, lo:200000000} in the config script.
  var Timer = xdc.useModule('ti.sysbios.timers.rti.Timer');
  Timer.intFreqs[1].lo = 200000000; // = CPU freq
  Timer.intFreqs[1].hi = 0;
 
metaonly config Timer.timerSettings  // module-wide
index URL

Global Control configuration for each physical timer

Configuration settings
Timer.timerSettings = Timer.TimerSetting[] [ ];
 
Instance Config Parameters
index URL

Configuration settings
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.createHwi = Bool true;
    // Controls whether the timer module creates a Hwi. Default is true
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.prescale = UInt8 1;
    // Prescale factor. Default is 1 (0 is not recommended)
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
 
config Timer.Params.arg  // instance
index URL

Argument for tick function

Configuration settings
var params = new Timer.Params;
  ...
params.arg = UArg null;
 
DETAILS
Default is null.
C SYNOPSIS
Timer_Params.arg
 
config Timer.Params.createHwi  // instance
index URL

Controls whether the timer module creates a Hwi. Default is true

Configuration settings
var params = new Timer.Params;
  ...
params.createHwi = Bool true;
 
DETAILS
If an application needs to create a Hwi for the timer, it is possible to indicate to the timer module to not create a Hwi by setting this param to false. This feature may be useful if the application needs to create a Hwi using the family specific Hwi module or on certain ARM targets create a Hwi of FIQ type to minimize latency.
If the application creates its own Hwi, it needs to select an interrupt number corresponding to the timer Id (see Timer Mapping Tables).
Here's an example for the Cortex-R4 target that creates a custom Hwi of FIQ type and sets "Timer.createHwi" param to false when creating a Timer object, in order to prevent the Timer module from creating a Hwi.
  *.cfg:
  xdc.useModule('ti.sysbios.timers.rti.Timer');
  xdc.useModule('ti.sysbios.family.arm.v7r.vim.Hwi');

  *.c:
  #include <xdc/std.h>
  #include <xdc/runtime/Error.h>

  #include <ti/sysbios/timers/rti/Timer.h>
  #include <ti/sysbios/family/arm/v7r/vim/Hwi.h>
  ...

  Timer_Struct timer0;
  Timer_Handle handle0;

  interrupt Void myIsr()
  {
      // Timer needs to be stopped only if run mode is One shot.
      // For periodic run mode, this function needs to only ack
      // the timer interrupt.
      Timer_stop(handle0);
      Timer_ackInterrupt(handle0);
      ...
  }

  Int main(Int argc, char* argv[])
  {
      Timer_Params timerParams;
      Hwi_Params hwiParams;
      Error_Block eb;

      Error_init(&eb);

      // The interrupt number corresponding to a given Timer Id
      // can be determined from the Timer Mapping table. A link
      // to the table can be found in this document.
      Hwi_Params_init(&hwiParams);
      hwiParams.type = Hwi_Type_FIQ;
      Hwi_create(2, (Hwi_FuncPtr)(&myIsr), &hwiParams, &eb);

      Timer_Params_init(&timerParams);
      timerParams.period = 60000;
      timerParams.runMode = Timer_RunMode_ONESHOT;
      timerParams.periodType = Timer_PeriodType_MICROSECS;
      timerParams.createHwi = FALSE;
      Timer_construct(&timer0, 0, NULL, &timerParams, &eb);

      handle0 = Timer_handle(&timer0);
      ...

      BIOS_start();
      return(0);
  }
C SYNOPSIS
Timer_Params.createHwi
 
config Timer.Params.extFreq  // instance
index URL

Timer frequency

Configuration settings
var params = new Timer.Params;
  ...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
 
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
Timer_Params.extFreq
 
config Timer.Params.hwiParams  // instance
index URL

Hwi Params for Hwi Object. Default is null

Configuration settings
var params = new Timer.Params;
  ...
params.hwiParams = Hwi.Params* null;
 
C SYNOPSIS
Timer_Params.hwiParams
 
config Timer.Params.period  // instance
index URL

Period of a tick

Configuration settings
var params = new Timer.Params;
  ...
params.period = UInt32 0;
 
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
Timer_Params.period
 
config Timer.Params.periodType  // instance
index URL

Period type

Configuration settings
var params = new Timer.Params;
  ...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
 
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
Timer_Params.periodType
 
config Timer.Params.prescale  // instance
index URL

Prescale factor. Default is 1 (0 is not recommended)

Configuration settings
var params = new Timer.Params;
  ...
params.prescale = UInt8 1;
 
DETAILS
The Prescale factor can be used to achieve longer timer periods. With a prescale factor specified, the actual timer period is period * (prescale + 1).
C SYNOPSIS
Timer_Params.prescale
 
config Timer.Params.runMode  // instance
index URL

Timer run mode

Configuration settings
var params = new Timer.Params;
  ...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
 
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
Timer_Params.runMode
 
config Timer.Params.startMode  // instance
index URL

Timer start mode

Configuration settings
var params = new Timer.Params;
  ...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
 
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
Timer_Params.startMode
Static Instance Creation
index URL

Configuration settings
var params = new Timer.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
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
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Thu, 23 May 2019 00:22:20 GMT