module ti.sysbios.family.c28.Timer

index URL

Timer peripherals manager for the c28 family

C synopsis
Individual elements
XDCscript usage
Individual elements

28x Timers

[ more ... ]

C synopsis target-domain sourced in ti/sysbios/family/c28/Timer.xdc

#include <ti/sysbios/family/c28/Timer.h>

Functions
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);
UInt16	Timer_getPrescale// Get timer prescale value(Timer_Handle handle);
UInt16	Timer_getPrescaleCount// Reads timer prescale counter(Timer_Handle handle);
Void	Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void	Timer_setPrescale// Set timer prescale value(Timer_Handle handle, UInt16 preScalar);
Functions common to all ITimer modules
UInt32	Timer_getCount// Returns the number of counts that have passed(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
#define	Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)3
Typedefs
typedef struct	Timer_EmulationMode// Timer Emulation Mode ...
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_invalidHwiMask// Assert raised in Timer_create when Hwi Params does not mask 'self';
extern const Assert_Id	Timer_A_invalidRunMode// Assert raised in Timer_create if an invalid RunMode is requested;
extern const Assert_Id	Timer_A_invalidTimer// Assert raised in Timer_create when timer id specified is not supported;
extern const Assert_Id	Timer_E_cannotSupport// Assert raised when period requested is not supported;
extern const Error_Id	Timer_E_notAvailable// Error raised in Timer_create when timer requested is in use;

DETAILS

28x Timers

The 28x has three 32-bit timers.
The 28x timer counts downward from 'period' to 0; however, Timer_getCount will count upward.
The 28x timer supports an optional 16-bit prescalar. The prescalar effectively sets the period of the timer tick; the prescalar counts down from the prescale factor to 0, then a timer tick occurs. So, with a prescale set, the actual timer period is (prescale * period).

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
getPrescale	Y	Y	Y	Y	N
getPrescaleCount	Y	Y	Y	Y	N
setPeriod	Y	Y	Y	Y	N
setPeriodMicroSecs	Y	Y	Y	Y	N
setPrescale	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

const Timer_NUM_TIMER_DEVICES

index URL

Number of timer peripherals on chip

C synopsis target-domain

#define Timer_NUM_TIMER_DEVICES (Int)3

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.

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);

struct Timer_EmulationMode

index URL

Timer Emulation Mode

C synopsis target-domain

typedef struct Timer_EmulationMode {

UInt free;

// At sw breakpoint, stop or free-run the timer

UInt soft;

// At sw breakpoint, hard stop or run down timer

} Timer_EmulationMode;

config Timer_A_invalidHwiMask // module-wide

index URL

Assert raised in Timer_create when Hwi Params does not mask 'self'

C synopsis target-domain

extern const Assert_Id Timer_A_invalidHwiMask;

DETAILS

This is not allowed because the timers on this platform do not inherently support one-shot mode. Instead, a stub is used to stop the timer, so it is important that the timer interrupt not occur again before the stub has stopped the timer.

config Timer_A_invalidRunMode // module-wide

index URL

Assert raised in Timer_create if an invalid RunMode is requested

C synopsis target-domain

extern const Assert_Id Timer_A_invalidRunMode;

config Timer_A_invalidTimer // module-wide

index URL

Assert raised in Timer_create 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

Assert raised when period requested is not supported

C synopsis target-domain

extern const Assert_Id Timer_E_cannotSupport;

config Timer_E_notAvailable // module-wide

index URL

Error raised in Timer_create 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;

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

Timer_EmulationMode emulationModeInit;

// Initial timer emulation mode. Default hard stop

Types_FreqHz extFreq;

// Timer frequency

Hwi_Params *hwiParams;

// Parameters for the Hwi object created for the Timer ISR

UInt32 period;

// Period of a tick

ITimer_PeriodType periodType;

// Period type

UInt16 prescale;

// Prescale factor

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_arg // instance

index URL

Argument for tick function

C synopsis target-domain

struct Timer_Params {

...

UArg arg;

DETAILS

Default is null.

config Timer_emulationModeInit // instance

index URL

Initial timer emulation mode. Default hard stop

C synopsis target-domain

struct Timer_Params {

...

Timer_EmulationMode emulationModeInit;

DETAILS

Determines timer state at a software breakpoint. If 'free' is 1, the timer will continue to run, and the value of 'soft' doesn't matter. When 'free' is 0 and 'soft' is 1, the timer runs down to 0 then stops. When 'free' is 0 and 'soft' is 0, the timer halts.

  FREE   SOFT    
  0      0      Stop after next timer decrement. (Hard stop)
  0      1      Stop after timer runs down to 0. (Soft stop)
  1      x      Continue running the timer.

config Timer_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_hwiParams // instance

index URL

Parameters for the Hwi object created for the Timer ISR

C synopsis target-domain

struct Timer_Params {

...

Hwi_Params *hwiParams;

DETAILS

The mask setting for the Hwi object should include SELF to prevent nested timer interrupts.

config Timer_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_periodType // instance

index URL

Period type

C synopsis target-domain

struct Timer_Params {

...

ITimer_PeriodType periodType;

DETAILS

Default is PeriodType_MICROSECS

config Timer_prescale // instance

index URL

Prescale factor

C synopsis target-domain

struct Timer_Params {

...

UInt16 prescale;

DETAILS

The prescale factor determines the length of a timer tick. If a prescale of 10 is specified, a timer tick will occur every 11 cycles.

If the timer is used as a counter, the prescale factor determines the period between counts. Otherwise, the prescale factor can be used to achieve longer timer periods: with a prescale specified, the actual period is (period * prescale+1).

config Timer_runMode // instance

index URL

Timer run mode

C synopsis target-domain

struct Timer_Params {

...

ITimer_RunMode runMode;

DETAILS

Default is RunMode_CONTINUOUS.

config Timer_startMode // instance

index URL

Timer start mode

C synopsis target-domain

struct Timer_Params {

...

ITimer_StartMode startMode;

DETAILS

Default is StartMode_AUTO.

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_getCount() // instance

index URL

Returns the number of counts that have passed

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 counts, counting upward from 0

DETAILS

The 28x timer counts downward from the period to 0, but getCount subtracts the timer counter value from the period so that getCount counts upward instead of downward.

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_getPrescale() // instance

index URL

Get timer prescale value

C synopsis target-domain

UInt16 Timer_getPrescale(Timer_Handle handle);

ARGUMENTS

handle — handle of a previously-created Timer instance object

RETURNS

prescale value

DETAILS

This is not the prescale count, but the period of the prescalar.

Timer_getPrescaleCount() // instance

index URL

Reads timer prescale counter

C synopsis target-domain

UInt16 Timer_getPrescaleCount(Timer_Handle handle);

ARGUMENTS

handle — handle of a previously-created Timer instance object

RETURNS

prescale counter, counting upward from 0

DETAILS

The prescale counter counts down from prescale to 0, but getPrescaleCount subtracts the counter value from the period so that this function counts upward instead of downward.

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_setPrescale() // instance

index URL

Set timer prescale value

C synopsis target-domain

Void Timer_setPrescale(Timer_Handle handle, UInt16 preScalar);

ARGUMENTS

handle — handle of a previously-created Timer instance object

preScalar — The value to set the prescale period to.

DETAILS

This function sets the value of the prescalar, and will also reload the timer counter and prescale registers.

The prescalar decrements with each timer clock source cycle until it reaches zero, then the timer's count is decremented by one. The prescalar has the effect of setting the rate of the timer tick.

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

  // 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

XDCscript usage meta-domain sourced in ti/sysbios/family/c28/Timer.xdc

var Timer = xdc.useModule('ti.sysbios.family.c28.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;

const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 3;

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.EmulationMode// Timer Emulation Mode;

obj.free// At sw breakpoint, stop or free-run the timer = UInt ...

obj.soft// At sw breakpoint, hard stop or run down timer = UInt ...

module-wide config parameters

Timer.A_invalidHwiMask// Assert raised in Timer_create when Hwi Params does not mask 'self' = Assert.Desc {

msg: "A_InvalidMask: Mask in hwiParams cannot enable self"

};

Timer.A_invalidRunMode// Assert raised in Timer_create if an invalid RunMode is requested = Assert.Desc {

msg: "A_invalidRunMode: Invalid RunMode"

};

Timer.A_invalidTimer// Assert raised in Timer_create when timer id specified is not supported = Assert.Desc {

msg: "A_invalidTimer: Timer id must be 0-2"

};

Timer.E_cannotSupport// Assert raised when period requested is not supported = Assert.Desc {

msg: "E_cannotSupport: Timer cannot support requested period"

};

Timer.E_notAvailable// Error raised in Timer_create 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 0x7;

Timer.common$// Common module configuration parameters = Types.Common$ undefined;

per-instance config parameters

var params = new Timer.Params// Instance config-params object;

params.arg// Argument for tick function = UArg null;

params.emulationModeInit// Initial timer emulation mode. Default hard stop = Timer.EmulationMode {

free: 0,

soft: 0

};

params.extFreq// Timer frequency = Types.FreqHz {

lo: 0,

hi: 0

};

params.hwiParams// Parameters for the Hwi object created for the Timer ISR = Hwi.Params* null;

params.period// Period of a tick = UInt32 0;

params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;

params.prescale// Prescale factor = UInt16 0;

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

XDCscript usage meta-domain

const Timer.ANY = ~0;

C SYNOPSIS

Timer_ANY

const Timer.MAX_PERIOD

index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain

const Timer.MAX_PERIOD = 0xffffffff;

C SYNOPSIS

Timer_MAX_PERIOD

const Timer.NUM_TIMER_DEVICES

index URL

Number of timer peripherals on chip

XDCscript usage meta-domain

const Timer.NUM_TIMER_DEVICES = 3;

C SYNOPSIS

Timer_NUM_TIMER_DEVICES

enum Timer.PeriodType

index URL

Timer period units

XDCscript usage meta-domain

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

XDCscript usage meta-domain

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.

C SYNOPSIS

Timer_RunMode

enum Timer.StartMode

index URL

Timer Start Modes

XDCscript usage meta-domain

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

XDCscript usage meta-domain

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

struct Timer.EmulationMode

index URL

Timer Emulation Mode

XDCscript usage meta-domain

var obj = new Timer.EmulationMode;

obj.free = UInt ...

// At sw breakpoint, stop or free-run the timer

obj.soft = UInt ...

// At sw breakpoint, hard stop or run down timer

C SYNOPSIS

Timer_EmulationMode

config Timer.A_invalidHwiMask // module-wide

index URL

Assert raised in Timer_create when Hwi Params does not mask 'self'

XDCscript usage meta-domain

Timer.A_invalidHwiMask = Assert.Desc {

msg: "A_InvalidMask: Mask in hwiParams cannot enable self"

};

DETAILS

C SYNOPSIS

Timer_A_invalidHwiMask

config Timer.A_invalidRunMode // module-wide

index URL

Assert raised in Timer_create if an invalid RunMode is requested

XDCscript usage meta-domain

Timer.A_invalidRunMode = Assert.Desc {

msg: "A_invalidRunMode: Invalid RunMode"

};

C SYNOPSIS

Timer_A_invalidRunMode

config Timer.A_invalidTimer // module-wide

index URL

Assert raised in Timer_create when timer id specified is not supported

XDCscript usage meta-domain

Timer.A_invalidTimer = Assert.Desc {

msg: "A_invalidTimer: Timer id must be 0-2"

};

C SYNOPSIS

Timer_A_invalidTimer

config Timer.E_cannotSupport // module-wide

index URL

Assert raised when period requested is not supported

XDCscript usage meta-domain

Timer.E_cannotSupport = Assert.Desc {

msg: "E_cannotSupport: Timer cannot support requested period"

};

C SYNOPSIS

Timer_E_cannotSupport

config Timer.E_notAvailable // module-wide

index URL

Error raised in Timer_create when timer requested is in use

XDCscript usage meta-domain

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

XDCscript usage meta-domain

Timer.anyMask = UInt 0x7;

C SYNOPSIS

Timer_anyMask

metaonly config Timer.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

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.

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new Timer.Params;

// Instance config-params object

params.arg = UArg null;

// Argument for tick function

params.emulationModeInit = Timer.EmulationMode {

// Initial timer emulation mode. Default hard stop

free: 0,

soft: 0

};

params.extFreq = Types.FreqHz {

// Timer frequency

lo: 0,

hi: 0

};

params.hwiParams = Hwi.Params* null;

// Parameters for the Hwi object created for the Timer ISR

params.period = UInt32 0;

// Period of a tick

params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;

// Period type

params.prescale = UInt16 0;

// Prescale factor

params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;

// Timer run mode

params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;

// Timer start mode

config Timer.arg // instance

index URL

Argument for tick function

XDCscript usage meta-domain

var params = new Timer.Params;

...

params.arg = UArg null;

DETAILS

Default is null.

C SYNOPSIS

null

config Timer.emulationModeInit // instance

index URL

Initial timer emulation mode. Default hard stop

XDCscript usage meta-domain

var params = new Timer.Params;

...

params.emulationModeInit = Timer.EmulationMode {

free: 0,

soft: 0

};

DETAILS

  FREE   SOFT    
  0      0      Stop after next timer decrement. (Hard stop)
  0      1      Stop after timer runs down to 0. (Soft stop)
  1      x      Continue running the timer.

C SYNOPSIS

null

config Timer.extFreq // instance

index URL

Timer frequency

XDCscript usage meta-domain

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

null

config Timer.hwiParams // instance

index URL

Parameters for the Hwi object created for the Timer ISR

XDCscript usage meta-domain

var params = new Timer.Params;

...

params.hwiParams = Hwi.Params* null;

DETAILS

The mask setting for the Hwi object should include SELF to prevent nested timer interrupts.