module ti.sysbios.hal.TimerNull

Null Timer module

C synopsis target-domain sourced in ti/sysbios/hal/TimerNull.xdc
#include <ti/sysbios/hal/TimerNull.h>
Functions
Void
Void
Void
Void
Functions common to all ITimer modules
UInt32 
Void 
UInt 
UInt32 
Void 
Void 
Bool 
Void 
Void 
Functions common to all target instances
Functions common to all target modules
Defines
#define
Typedefs
typedef Void 
typedef struct
typedef struct
typedef enum
typedef enum
typedef enum
typedef enum
typedef struct
 
 
const TimerNull_ANY

Const used to specify any timer

C synopsis target-domain
#define TimerNull_ANY (UInt)~0
 
 
enum TimerNull_PeriodType

Timer period units

C synopsis target-domain
typedef enum TimerNull_PeriodType {
    TimerNull_PeriodType_MICROSECS,
    // period in microsecs
    TimerNull_PeriodType_COUNTS
    // period in counts
} TimerNull_PeriodType;
 
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
 
enum TimerNull_RunMode

Timer Run Modes

C synopsis target-domain
typedef enum TimerNull_RunMode {
    TimerNull_RunMode_CONTINUOUS,
    // periodic and continuous
    TimerNull_RunMode_ONESHOT,
    // one-shot
    TimerNull_RunMode_DYNAMIC
    // dynamically reprogrammed (available on subset of devices)
} TimerNull_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 TimerNull_StartMode

Timer Start Modes

C synopsis target-domain
typedef enum TimerNull_StartMode {
    TimerNull_StartMode_AUTO,
    // timer starts automatically
    TimerNull_StartMode_USER
    // timer will be started by user
} TimerNull_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 TimerNull_Status

Timer Status

C synopsis target-domain
typedef enum TimerNull_Status {
    TimerNull_Status_INUSE,
    // timer in use
    TimerNull_Status_FREE
    // timer is free
} TimerNull_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 TimerNull_FuncPtr

Timer tick function prototype

C synopsis target-domain
typedef Void (*TimerNull_FuncPtr)(UArg);
 
 
TimerNull_getNumTimers()  // module-wide

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt TimerNull_getNumTimers();
 
RETURNS
Number of timer peripherals.
 
TimerNull_getStatus()  // module-wide

Returns timer status (free or in use)

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

C synopsis target-domain
Types_ModuleId TimerNull_Module_id();
// Get this module's unique id
 
Bool TimerNull_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle TimerNull_Module_heap();
// The heap from which this module allocates memory
 
Bool TimerNull_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 TimerNull_Module_getMask();
// Returns the diagnostics mask for this module
 
Void TimerNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct TimerNull_Object TimerNull_Object;
// Opaque internal representation of an instance object
 
typedef TimerNull_Object *TimerNull_Handle;
// Client reference to an instance object
 
typedef struct TimerNull_Struct TimerNull_Struct;
// Opaque client structure large enough to hold an instance object
 
TimerNull_Handle TimerNull_handle(TimerNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
TimerNull_Struct *TimerNull_struct(TimerNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct TimerNull_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
    Types_FreqHz extFreq;
    // Timer frequency
    UInt32 period;
    // Period of a tick
    ITimer_PeriodType periodType;
    // Period type
    ITimer_RunMode runMode;
    // Timer run mode
    ITimer_StartMode startMode;
    // Timer start mode
} TimerNull_Params;
 
Void TimerNull_Params_init(TimerNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config TimerNull_Params.arg  // instance

Argument for tick function

C synopsis target-domain
struct TimerNull_Params {
      ...
    UArg arg;
 
DETAILS
Default is null.
 
config TimerNull_Params.extFreq  // instance

Timer frequency

C synopsis target-domain
struct TimerNull_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 TimerNull_Params.period  // instance

Period of a tick

C synopsis target-domain
struct TimerNull_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 TimerNull_Params.periodType  // instance

Period type

C synopsis target-domain
struct TimerNull_Params {
      ...
    ITimer_PeriodType periodType;
 
DETAILS
Default is PeriodType_MICROSECS
 
config TimerNull_Params.runMode  // instance

Timer run mode

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

Timer start mode

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

C synopsis target-domain
TimerNull_Handle TimerNull_create(Int id, ITimer_FuncPtr tickFxn, const TimerNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void TimerNull_construct(TimerNull_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const TimerNull_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

C synopsis target-domain
Void TimerNull_delete(TimerNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void TimerNull_destruct(TimerNull_Struct *structP);
// Finalize the instance object inside the provided structure
 
TimerNull_getCount()  // instance

Read timer counter register

C synopsis target-domain
UInt32 TimerNull_getCount(TimerNull_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
RETURNS
timer counter value
 
TimerNull_getFreq()  // instance

Return timer frequency in Hz

C synopsis target-domain
Void TimerNull_getFreq(TimerNull_Handle handle, Types_FreqHz *freq);
 
ARGUMENTS
handle — handle of a previously-created TimerNull 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).
 
TimerNull_getFunc()  // instance

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr TimerNull_getFunc(TimerNull_Handle handle, UArg *arg);
 
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
 
TimerNull_getPeriod()  // instance

Get timer period in timer counts

C synopsis target-domain
UInt32 TimerNull_getPeriod(TimerNull_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
RETURNS
period in timer counts
 
TimerNull_setFunc()  // instance

Overwrite Timer function and arg

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

Set timer period specified in timer counts

C synopsis target-domain
Void TimerNull_setPeriod(TimerNull_Handle handle, UInt32 period);
 
ARGUMENTS
handle — handle of a previously-created TimerNull 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.
 
TimerNull_setPeriodMicroSecs()  // instance

Set timer period specified in microseconds

C synopsis target-domain
Bool TimerNull_setPeriodMicroSecs(TimerNull_Handle handle, UInt32 microsecs);
 
ARGUMENTS
handle — handle of a previously-created TimerNull 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);
 
TimerNull_start()  // instance

Reload and start the timer

C synopsis target-domain
Void TimerNull_start(TimerNull_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TimerNull 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.
 
TimerNull_stop()  // instance

Stop the timer

C synopsis target-domain
Void TimerNull_stop(TimerNull_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TimerNull 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

C synopsis target-domain
ITimer_Handle TimerNull_Handle_upCast(TimerNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
TimerNull_Handle TimerNull_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int TimerNull_Object_count();
// The number of statically-created instance objects
 
TimerNull_Handle TimerNull_Object_get(TimerNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
TimerNull_Handle TimerNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
TimerNull_Handle TimerNull_Object_next(TimerNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle TimerNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *TimerNull_Handle_label(TimerNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String TimerNull_Handle_name(TimerNull_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/hal/TimerNull.xdc
var TimerNull = xdc.useModule('ti.sysbios.hal.TimerNull');
module-wide constants & types
 
 
    values of type TimerNull.RunMode// Timer Run Modes
        const TimerNull.RunMode_ONESHOT// one-shot;
 
 
    values of type TimerNull.Status// Timer Status
module-wide config parameters
per-instance config parameters
    var params = new TimerNull.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.period// Period of a tick = UInt32 0;
per-instance creation
    var inst = TimerNull.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
 
 
const TimerNull.ANY

Const used to specify any timer

Configuration settings
const TimerNull.ANY = ~0;
 
C SYNOPSIS
 
enum TimerNull.PeriodType

Timer period units

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

Timer Run Modes

Configuration settings
values of type TimerNull.RunMode
    const TimerNull.RunMode_CONTINUOUS;
    // periodic and continuous
    const TimerNull.RunMode_ONESHOT;
    // one-shot
    const TimerNull.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
 
enum TimerNull.StartMode

Timer Start Modes

Configuration settings
values of type TimerNull.StartMode
    const TimerNull.StartMode_AUTO;
    // timer starts automatically
    const TimerNull.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
 
enum TimerNull.Status

Timer Status

Configuration settings
values of type TimerNull.Status
    const TimerNull.Status_INUSE;
    // timer in use
    const TimerNull.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
 
metaonly config TimerNull.common$  // module-wide

Common module configuration parameters

Configuration settings
TimerNull.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

Configuration settings
var params = new TimerNull.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
 
config TimerNull.Params.arg  // instance

Argument for tick function

Configuration settings
var params = new TimerNull.Params;
  ...
params.arg = UArg null;
 
DETAILS
Default is null.
C SYNOPSIS
 
config TimerNull.Params.extFreq  // instance

Timer frequency

Configuration settings
var params = new TimerNull.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
 
config TimerNull.Params.period  // instance

Period of a tick

Configuration settings
var params = new TimerNull.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
 
config TimerNull.Params.periodType  // instance

Period type

Configuration settings
var params = new TimerNull.Params;
  ...
 
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
 
config TimerNull.Params.runMode  // instance

Timer run mode

Configuration settings
var params = new TimerNull.Params;
  ...
 
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
 
config TimerNull.Params.startMode  // instance

Timer start mode

Configuration settings
var params = new TimerNull.Params;
  ...
 
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new TimerNull.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = TimerNull.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 Tue, 14 Feb 2017 19:58:48 GMT