BSP430  20141115
Board Support Package for MSP430 microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Macros | Typedefs | Functions
Alarm-related Timer Functionality

bsp430/periph/timer.h data structures and functions supporting alarms More...

Data Structures

struct  sBSP430timerAlarm
struct  sBSP430timerMuxSharedAlarm
struct  sBSP430timerMuxAlarm


#define BSP430_TIMER_ALARM_FLAG_SET   0x01
#define BSP430_TIMER_ALARM_SET_NOW   1


typedef const struct sBSP430timerAlarmhBSP430timerAlarm
typedef int(* iBSP430timerAlarmCallback_ni) (hBSP430timerAlarm alarm)
typedef struct sBSP430timerAlarm sBSP430timerAlarm
typedef int(* iBSP430timerMuxAlarmCallback_ni) (struct sBSP430timerMuxSharedAlarm *shared, struct sBSP430timerMuxAlarm *alarm)
typedef struct sBSP430timerMuxSharedAlarm sBSP430timerMuxSharedAlarm
typedef sBSP430timerMuxSharedAlarmhBSP430timerMuxSharedAlarm
typedef struct sBSP430timerMuxAlarm sBSP430timerMuxAlarm
typedef sBSP430timerMuxAlarmhBSP430timerMuxAlarm


hBSP430timerAlarm hBSP430timerAlarmInitialize (sBSP430timerAlarm *alarm, tBSP430periphHandle periph, int ccidx, iBSP430timerAlarmCallback_ni callback)
int iBSP430timerAlarmSetEnabled_ni (hBSP430timerAlarm alarm, int enablep)
static BSP430_CORE_INLINE int iBSP430timerAlarmEnable (hBSP430timerAlarm alarm)
static BSP430_CORE_INLINE int iBSP430timerAlarmDisable (hBSP430timerAlarm alarm)
int iBSP430timerAlarmSet_ni (hBSP430timerAlarm alarm, unsigned long setting_tck)
static BSP430_CORE_INLINE int iBSP430timerAlarmSet (hBSP430timerAlarm alarm, unsigned long setting_tck)
int iBSP430timerAlarmCancel_ni (hBSP430timerAlarm alarm)
static BSP430_CORE_INLINE int iBSP430timerAlarmCancel (hBSP430timerAlarm alarm)
hBSP430timerMuxSharedAlarm hBSP430timerMuxAlarmStartup (sBSP430timerMuxSharedAlarm *shared, tBSP430periphHandle periph, int ccidx)
int iBSP430timerMuxAlarmShutdown (sBSP430timerMuxSharedAlarm *shared)
int iBSP430timerMuxAlarmAdd_ni (hBSP430timerMuxSharedAlarm shared, hBSP430timerMuxAlarm alarm)
int iBSP430timerMuxAlarmRemove_ni (hBSP430timerMuxSharedAlarm shared, hBSP430timerMuxAlarm alarm)

Detailed Description

bsp430/periph/timer.h data structures and functions supporting alarms

BSP430 provides infrastructure that uses the capture/compare interrupt callbacks of the timer peripheral to support two types of configurable alarm system:

Dedicated Alarm Infrastructure

Each dedicated alarm is configured to reference a specific capture/compare register within a specific timer peripheral. The HAL infrastructure for that peripheral must also have been requested. The number of capture/compare registers supported by a particular peripheral may be obtained at runtime using iBSP430timerSupportedCCs(). If capture/compare register zero is to be used for alarms, the corresponding CC0 ISR infrastructure must also be enabled. The table below indicates the options that should be enabled for various timers:

Underlying Timer HAL Request CC0 ISR Request
BSP430_PERIPH_TA3 configBSP430_HAL_TA3 configBSP430_HAL_TA3_CC0_ISR
It is the responsibility of the application to configure the underlying timer to continuous mode with the appropriate clock source, any desired dividers, and enabling the interrupt that maintains the 32-bit overflow counter timer HAL infrastructure. If you are using BSP430_UPTIME_TIMER_PERIPH_HANDLE the timer is already configured this way. For other timers, use something like:
alarmHAL_ = hBSP430timerLookup(ALARM_TIMER_PERIPH_HANDLE);
if (alarmHAL_) {
alarmHAL_->hpl->ctl = 0;
alarmHAL_->hpl->ctl = APP_TASSEL | MC_2 | TACLR | TAIE;

Alarms depend on a persistent object that describes their current state and holds the callback structures necessary to connect them to the peripheral interrupt infrastructure. These objects must be initialized once using hBSP430timerAlarmInitialize(). After that point, the objects are not directly referenced; operations on the alarm are performed using a handle.

Alarms are enabled and disabled as needed. The act of enabling an alarm links its callbacks into the timer interrupt system. Because these callbacks introduce overhead even when the alarm is not set, alarms should only be enabled when they are likely to be used.

Alarms are set with iBSP430timerAlarmSet() using the absolute time of the underlying 32-bit timer, which can be obtained through ulBSP430timerCounter(). Because timers run asynchronously to the code, even when interrupts are disabled, the set function return value should be examined to ensure that the alarm was, in fact, set. Alarms may not be set if the duration is too short to reliably implement them, or if the time specified appears to be in the past. The infrastructure detects times that are past the 16-bit overflow of the underlying timer and uses the overflow interrupt to enable the capture/compare register interrupt in the correct cycle.

Alarms that are set may be reliably cancelled using iBSP430timerAlarmCancel_ni(). This should always be done with interrupts disabled, to ensure that the alarm is not firing while the cancellation occurs. The return value will indicate if the alarm cancellation failed, e.g. due to it having already gone off.

When the alarm fires, the callback registered in sBSP430timerAlarm::callback_ni is invoked. The callback may invoke iBSP430timerAlarmSet_ni() to reschedule a periodic alarm, but complex processing should not be done. The callback should instead set a volatile global variable and return a value such as BSP430_HAL_ISR_CALLBACK_EXIT_LPM. See iBSP430timerAlarmCallback_ni.

The Peripherals: Alarms example program provides an environment where the behavior of alarms can be interactively probed.


Macro Definition Documentation


Bit set in sBSP430timerAlarm::flags if the alarm is enabled.

#define BSP430_TIMER_ALARM_FLAG_SET   0x01

Bit set in sBSP430timerAlarm::flags if the alarm is currently set.


Time limit for future alarms.

If the requested time is less than this many ticks in the future, iBSP430timerAlarmSet_ni() will not schedule the alarm and will returned BSP430_TIMER_ALARM_SET_NOW. Events at least this many ticks in the future will be scheduled.

The value here is superseded by previously encountered definitions.

Value returned by iBSP430timerAlarmSet_ni() when the alarm was already scheduled.

#define BSP430_TIMER_ALARM_SET_NOW   1

Value returned by iBSP430timerAlarmSet_ni() when the requested time is too near for the scheduling to be reliable. See BSP430_TIMER_ALARM_FUTURE_LIMIT.


Value returned by iBSP430timerAlarmSet_ni() when the requested time appears to be in the past.

Typedef Documentation

typedef const struct sBSP430timerAlarm* hBSP430timerAlarm

A handle to an alarm structure.

The reference is to a const sBSP430timerAlarm because user code should never manipulate the alarm configuration directly.

Handle for an individual multiplixed alarm.

Handle for the underlying shared alarm for multiplixed alarms.

typedef int(* iBSP430timerAlarmCallback_ni) (hBSP430timerAlarm alarm)

Callback for alarm events.

This function will be invoked by the timer infrastructure in an interrupt context when the alarm goes off. The implementation is permitted to invoke iBSP430timerAlarmSet_ni() to schedule a new alarm. If this is not done, the alarm will automatically be disabled when the callback returns.

Because cfg is a pointer to the underlying sBSP430timerAlarm structure, the techniques of Providing Extended Information to the Callback may be used to provide additional parameters for use by the callback function.
cfgThe structure describing the alarm configuration.
As with iBSP430halISRCallbackVoid_ni().
typedef int(* iBSP430timerMuxAlarmCallback_ni) (struct sBSP430timerMuxSharedAlarm *shared, struct sBSP430timerMuxAlarm *alarm)

Callback used for multiplexed timers.

This is invoked by the shared alarm when the time specified by alarm->setting_tck has been reached. When this is invoked alarm has been removed from the list of alarms associated with shared.

It is permitted to invoke iBSP430timerMuxAlarmSet_ni() from this callback to re-associate alarm with shared. Prior to doing this the alarm->setting_tck value should be updated.

A structure holding information related to timer-based alarms.

The contents of this structure must not be manipulated by user code at any time. The primary reason the internals are exposed is so that alarm structures can be statically allocated. Fields may be inspected, though only sBSP430timerAlarm::flags and sBSP430timerAlarm::setting_tck are likely to be of great interest.

Structure holding data for an individual multiplexed alarm. Instances of the structure are adopted by a shared alarm when added using iBSP430timerMuxAlarmAdd_ni(), and must not be mutated until the corresponding callback is invoked or the alarm is cancelled.

Structure holding multiplexed alarm shared data.

Function Documentation

hBSP430timerAlarm hBSP430timerAlarmInitialize ( sBSP430timerAlarm alarm,
tBSP430periphHandle  periph,
int  ccidx,
iBSP430timerAlarmCallback_ni  callback 

Initialize an alarm structure.

This routine configures the alarm structure so it is prepared to operate using capture/compare register ccidx of the timer peripheral identified by periph. This involves setting various fields inside the alarm structure; those settings should never be manipulated by user code.

Note that this simply initializes the structure; it does not set any alarms, nor does it enable the alarm. ccidx for periph may be reused for another purpose, or re-initialized for a new alarm role, as long as the alarm has first been disabled.

alarma pointer to the structure holding alarm configuration data.
periphthe handle identifier, such as BSP430_UPTIME_TIMER_PERIPH_HANDLE.
ccidxthe capture/compare index within the timer. It is the user's responsibility to ensure that the selected timer supports the selected capture/compare register.
If configBSP430_TIMER_VALID_COUNTER_READ is enabled attempts to configure an alarm on BSP430_TIMER_VALID_COUNTER_READ_CCIDX will be rejected.
callbackthe callback function to be invoked when the alarm goes off. This may be a null pointer, in which case the infrastructure will behave as though a registered callback did nothing but return BSP430_HAL_ISR_CALLBACK_EXIT_LPM.
A non-null handle for the alarm. A null handle will be returned if initialization failed, e.g. because periph could not be identified as a timer with a HAL supporting an alarm.
periph/timer/alarm/main.c, utility/cli/main.c, and utility/u8glib/main.c.
hBSP430timerMuxSharedAlarm hBSP430timerMuxAlarmStartup ( sBSP430timerMuxSharedAlarm shared,
tBSP430periphHandle  periph,
int  ccidx 

Configure for a multiplexed alarm.

hBSP430timerAlarmInitialize() is used to initialize the dedicated timer capture/compare interrupt associated with periph and ccidx, and the resulting alarm is enabled. The list of shared alarms is initialized to be empty.

See also
shareda pointer to a structure that holds the underlying dedicated alarm data along with a list of active alarms.
periphthe timer peripheral used to control the alarm.
ccidxthe capture/compare index within periph that is to be used for the shared alarms.
a handle for the shared alarm, or a null pointer if an error is detected.
static BSP430_CORE_INLINE int iBSP430timerAlarmCancel ( hBSP430timerAlarm  alarm)

Wrapper to invoke iBSP430timerAlarmCancel_ni() when interrupts are enabled.

int iBSP430timerAlarmCancel_ni ( hBSP430timerAlarm  alarm)

Cancel a scheduled alarm event.

This disconnects the scheduled alarm and inhibits any pending alarm from being executed. It may be executed from user code or from within an alarm callback or other interrupt handler.

alarma pointer to an alarm structure initialized using iBSP430timerAlarmInitialize().
A non-negative value if the cancellation was effective disabled. The value is 1 if the alarm had been set, and zero if it had not been set (e.g., the alarm had already fired). A negative value indicates an error such as an invalid alarm value, or the alarm not being enabled.
static BSP430_CORE_INLINE int iBSP430timerAlarmDisable ( hBSP430timerAlarm  alarm)

Disable an enabled alarm.

A wrapper around iBSP430timerAlarmSetEnabled_ni() suitable for use when interrupts are enabled.

This removes the alarm's callbacks from the timer infrastructure. Any scheduled alarm will be canceled prior to disabling it.

static BSP430_CORE_INLINE int iBSP430timerAlarmEnable ( hBSP430timerAlarm  alarm)

Enable an initialized alarm.

A wrapper around iBSP430timerAlarmSetEnabled_ni() suitable for use when interrupts are enabled.

This hooks the alarm's callbacks into the timer infrastructure. It does not set the alarm. Alarms must be enabled before they can be set, and initialized before they can be enabled.

static BSP430_CORE_INLINE int iBSP430timerAlarmSet ( hBSP430timerAlarm  alarm,
unsigned long  setting_tck 

Wrapper to invoke iBSP430timerAlarmSet_ni() when interrupts are enabled.

int iBSP430timerAlarmSet_ni ( hBSP430timerAlarm  alarm,
unsigned long  setting_tck 

Set the alarm to go off at the specified time.

This function may be invoked in normal user code, or within an alarm callback or other interrupt handler to reschedule the alarm.

The alarm is set only if the return value is zero.
alarma pointer to an alarm structure initialized using iBSP430timerAlarmInitialize().
setting_tckthe time at which the alarm should go off. The value should be no more than 2^31 ticks ahead of the current time or it will be assumed to specify a past time.
  • Zero to indicate the alarm was successfully scheduled;
  • The positive value BSP430_TIMER_ALARM_SET_NOW if setting_tck is in the future but too near for the alarm infrastructure to guarantee delivery of the alarm event;
  • The positive value BSP430_TIMER_ALARM_SET_PAST if setting_tck appears to be in the past;
  • The negative value BSP430_TIMER_ALARM_SET_ALREADY if the alarm was already scheduled;
  • other negative values indicating specific or generic errors.
periph/timer/alarm/main.c, utility/cli/main.c, and utility/u8glib/main.c.
int iBSP430timerAlarmSetEnabled_ni ( hBSP430timerAlarm  alarm,
int  enablep 

Enable or disable an alarm.

The effect of this is to hook the alarm into the necessary interrupt callbacks. Enabling the alarm does not cause it to be set; disabling does cause a set alarm to be cancelled.

During the times an alarm is enabled its callbacks are linked into the relevant interrupt callback chains. This can introduce overhead, so alarms should be explicitly disabled during periods when they are not active.

Do not enable or disable alarms from inside interrupt handlers or alarm callbacks.
alarmthe alarm that is being configured
enablepnonzero if the alarm is to be enabled; zero if it is to be disabled.
0 if setting was successful; -1 if an error occurs.
periph/timer/alarm/main.c, utility/cli/main.c, and utility/u8glib/main.c.
int iBSP430timerMuxAlarmAdd_ni ( hBSP430timerMuxSharedAlarm  shared,
hBSP430timerMuxAlarm  alarm 

Link a new alarm into the list managed by shared

The user must have already initialized the alarm structure including its callback and setting. alarm is linked into the list of alarms managed by shared, and the underlying timer is configured to wake when the first alarm is due.

The underlying dedicated alarm sets its wakeup using iBSP430timerAlarmSetForced_ni() so that delays resulting from slow processing will still result in the alarm being set even if it is overdue.

sharedthe shared alarm that manages multiplexed alarms.
alarminformation on the alarm to be set. The structure must not already be in an alarm list. The contents pointed to by this handle must not be manipulated by the user until the alarm fires or is cancelled via iBSP430timerMuxAlarmRemove_ni().
Normally the return value from iBSP430timerAlarmSetForced_ni() when setting for the first multiplexed alarm. If a negative value appears, the multiplexed alarm structure is in an undefined state.
int iBSP430timerMuxAlarmRemove_ni ( hBSP430timerMuxSharedAlarm  shared,
hBSP430timerMuxAlarm  alarm 

Remove an alarm from a shared list.

The alarm is removed from the list. If any alarms remain, shared is updated to fire when the next alarm is due. It is guaranteed that the removed alarm will not fire after this function has been invoked.

sharedthe shared alarm that manages multiplexed alarms.
alarmthe alarm to be removed.
Normally the return value from iBSP430timerAlarmSetForced_ni() when setting for the next scheduled multiplexed alarm. Zero is returned if no alarms remain. If a negative value appears, the multiplexed alarm structure is in an undefined state.
int iBSP430timerMuxAlarmShutdown ( sBSP430timerMuxSharedAlarm shared)

Disable multiplexed alarms.

The underlying shared alarm is cancelled and disabled. User code may inspect and manipulate the remaining alarms to process any unexpired timers.

shareda pointer to the structure used for multiplexed alarms
as with iBSP430timerAlarmDisable_ni()