interface ti.sysbios.interfaces.ITimer
index URL

Interface for Timer Peripherals Manager

XDCspec summary sourced in ti/sysbios/interfaces/ITimer.xdc
interface ITimer {  ...
// inherits xdc.runtime.IModule
instance:  ...
XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
package ti.sysbios.interfaces;
 
interface ITimer {
module-wide constants & types
    const UInt ANY// Const used to specify any timer = ~0;
 
    enum PeriodType// PeriodType {
        PeriodType_MICROSECS// period in microsecs,
        PeriodType_COUNTS// period in counts
    };
 
    enum RunMode// Timer Run Modes {
        RunMode_CONTINUOUS// periodic and continuous,
        RunMode_ONESHOT// one-shot
    };
 
    enum StartMode// Timer Start Modes {
        StartMode_AUTO// timer starts automatically,
        StartMode_USER// timer will be started by user
    };
 
    enum Status// Timer Status {
        Status_INUSE// timer in use,
        Status_FREE// timer is free
    };
 
    typedef Void (*FuncPtr// Timer tick function prototype)(UArg);
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    UInt getNumTimers// Returns number of timer peripherals on the platform( );
    ITimer.Status getStatus// Returns timer status (free or in use)( UInt id );
 
 
instance:
per-instance config parameters
    config UArg arg// Argument for tick function. Default is null = null;
    config Types.FreqHz extFreq// Timer frequency = {
        lo: 0,
        hi: 0
    };
    config UInt32 period// Period of tick. Can be specified in timer counts or microseconds. Default is 0 = 0;
    config ITimer.PeriodType periodType// Period Type. Default is PeriodType_MICROSECS = ITimer.PeriodType_MICROSECS;
    config ITimer.RunMode runMode// Timer run mode. Default is RunMode_CONTINUOUS = ITimer.RunMode_CONTINUOUS;
    config ITimer.StartMode startMode// Start mode. Default is StartMode_AUTO = ITimer.StartMode_AUTO;
per-instance creation
    create// Create an instance-object( Int id, ITimer.FuncPtr tickFxn );
per-instance functions
    Void getFreq// Returns timer frequency in Hz( Types.FreqHz *freq );
    ITimer.FuncPtr getFunc// Get Timer function and arg( UArg *arg );
    UInt32 getPeriod// Gets timer period in timer counts( );
    Void setFunc// Overwrite Timer function and arg( ITimer.FuncPtr fxn, UArg arg );
    Void setPeriod// Sets timer period specified in timer counts( UInt32 period );
    Bool setPeriodMicroSecs// Sets timer period specified in microseconds( UInt32 microsecs );
    Void start// Reloads and starts the timer( );
    Void stop// Stop the timer( );
}
C synopsis target-domain
#include <ti/sysbios/interfaces/ITimer.h>
per-instance object types
    typedef struct ITimer_Object// Client reference to an abstract instance object *ITimer_Handle;
per-instance config parameters
    typedef struct ITimer_Params// Instance config-params structure {
        IInstance_Params *instance;
        UArg arg// Argument for tick function. Default is null;
        Types_FreqHz extFreq// Timer frequency;
        UInt32 period// Period of tick. Can be specified in timer counts or microseconds. Default is 0;
        ITimer_PeriodType periodType// Period Type. Default is PeriodType_MICROSECS;
        ITimer_RunMode runMode// Timer run mode. Default is {@link #RunMode_CONTINUOUS};
        ITimer_StartMode startMode// Start mode. Default is {@link #StartMode_AUTO};
    } ITimer_Params;
 
 
const ITimer.ANY
index URL

Const used to specify any timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
const UInt ANY = ~0;
 
 
enum ITimer.PeriodType
index URL

PeriodType

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum PeriodType {
    PeriodType_MICROSECS,
    // period in microsecs
    PeriodType_COUNTS
    // period in counts
};
 
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
 
enum ITimer.RunMode
index URL

Timer Run Modes

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum RunMode {
    RunMode_CONTINUOUS,
    // periodic and continuous
    RunMode_ONESHOT
    // one-shot
};
 
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops
 
enum ITimer.StartMode
index URL

Timer Start Modes

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum StartMode {
    StartMode_AUTO,
    // timer starts automatically
    StartMode_USER
    // timer will be started by user
};
 
VALUES
StartMode_AUTO — Statically created/consructed 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 ITimer.Status
index URL

Timer Status

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum Status {
    Status_INUSE,
    // timer in use
    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.
 
typedef ITimer.FuncPtr
index URL

Timer tick function prototype

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
typedef Void (*FuncPtr)(UArg);
 
 
metaonly config ITimer.common$  // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
metaonly config Types.Common$ common$;
 
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.
 
ITimer.getNumTimers( )  // module-wide
index URL

Returns number of timer peripherals on the platform

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
UInt getNumTimers( );
 
RETURNS
Number of timer peripherals.
 
ITimer.getStatus( )  // module-wide
index URL

Returns timer status (free or in use)

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
ITimer.Status getStatus( UInt id );
 
RETURNS
timer status
 
per-instance object types
index URL

C synopsis target-domain
typedef struct ITimer_Object *ITimer_Handle;
// Client reference to an abstract instance object
 
per-instance config parameters
index URL

XDCscript usage meta-domain
var params = new ITimer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function. Default is null
    params.extFreq = Types.FreqHz {
    // Timer frequency
    lo: 0,
    hi: 0
};
    params.period = UInt32 0;
    // Period of tick. Can be specified in timer counts or microseconds. Default is 0
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period Type. Default is PeriodType_MICROSECS
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode. Default is {@link #RunMode_CONTINUOUS}
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Start mode. Default is {@link #StartMode_AUTO}
C synopsis target-domain
typedef struct ITimer_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function. Default is null
    Types_FreqHz extFreq;
    // Timer frequency
    UInt32 period;
    // Period of tick. Can be specified in timer counts or microseconds. Default is 0
    ITimer_PeriodType periodType;
    // Period Type. Default is PeriodType_MICROSECS
    ITimer_RunMode runMode;
    // Timer run mode. Default is {@link #RunMode_CONTINUOUS}
    ITimer_StartMode startMode;
    // Start mode. Default is {@link #StartMode_AUTO}
} ITimer_Params;
 
config ITimer.arg  // per-instance
index URL

Argument for tick function. Default is null

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config UArg arg = null;
 
 
config ITimer.extFreq  // per-instance
index URL

Timer frequency

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config Types.FreqHz extFreq = {
    lo: 0,
    hi: 0
};
 
DETAILS
This parameter is meaningfull only on platforms where the timer clock can be changed. If value is left at zero, then default hookup of timer clock is assumed.
 
config ITimer.period  // per-instance
index URL

Period of tick. Can be specified in timer counts or microseconds. Default is 0

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config UInt32 period = 0;
 
DETAILS
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
 
config ITimer.periodType  // per-instance
index URL

Period Type. Default is PeriodType_MICROSECS

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.PeriodType periodType = ITimer.PeriodType_MICROSECS;
 
 
config ITimer.runMode  // per-instance
index URL

Timer run mode. Default is RunMode_CONTINUOUS

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.RunMode runMode = ITimer.RunMode_CONTINUOUS;
 
 
config ITimer.startMode  // per-instance
index URL

Start mode. Default is StartMode_AUTO

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.StartMode startMode = ITimer.StartMode_AUTO;
 
 
per-instance creation
index URL

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
create( Int id, ITimer.FuncPtr tickFxn );
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value
tickFxn — function that runs upon timer expiry.
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.
 
ITimer.getFreq( )  // per-instance
index URL

Returns timer frequency in Hz

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void getFreq( Types.FreqHz *freq );
 
ARGUMENTS
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).
 
ITimer.getFunc( )  // per-instance
index URL

Get Timer function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
ITimer.FuncPtr getFunc( UArg *arg );
 
ARGUMENTS
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
 
ITimer.getPeriod( )  // per-instance
index URL

Gets timer period in timer counts

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
UInt32 getPeriod( );
 
RETURNS
period in timer counts
 
ITimer.setFunc( )  // per-instance
index URL

Overwrite Timer function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void setFunc( ITimer.FuncPtr fxn, UArg arg );
 
ARGUMENTS
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
 
ITimer.setPeriod( )  // per-instance
index URL

Sets timer period specified in timer counts

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void setPeriod( UInt32 period );
 
ARGUMENTS
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.
 
ITimer.setPeriodMicroSecs( )  // per-instance
index URL

Sets timer period specified in microseconds

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Bool setPeriodMicroSecs( UInt32 microsecs );
 
ARGUMENTS
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, ie 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);
 
ITimer.start( )  // per-instance
index URL

Reloads and starts the timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void start( );
 
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.
 
ITimer.stop( )  // per-instance
index URL

Stop the timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void stop( );
 
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.
generated on Mon, 21 Dec 2009 19:43:38 GMT