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

Data Structures
struct	sBSP430timerAlarm

struct	sBSP430timerMuxSharedAlarm

struct	sBSP430timerMuxAlarm

Macros
#define	BSP430_TIMER_ALARM_FLAG_SET 0x01

#define	BSP430_TIMER_ALARM_FLAG_ENABLED 0x02

#define	BSP430_TIMER_ALARM_FUTURE_LIMIT 3UL

#define	BSP430_TIMER_ALARM_SET_NOW 1

#define	BSP430_TIMER_ALARM_SET_PAST 2

#define	BSP430_TIMER_ALARM_SET_ALREADY -2

Typedefs
typedef const struct sBSP430timerAlarm *	hBSP430timerAlarm

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 sBSP430timerMuxSharedAlarm *	hBSP430timerMuxSharedAlarm

typedef struct sBSP430timerMuxAlarm	sBSP430timerMuxAlarm

typedef sBSP430timerMuxAlarm *	hBSP430timerMuxAlarm

Functions
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 supports one deadline+callback associated with specific capture/compare register
Multiplexed Alarm Infrastructure supports an arbitrary number of independent deadline+callbacks that share a single dedicated alarm

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
BSP430_UPTIME_TIMER_PERIPH_HANDLE	automatic	configBSP430_UPTIME_TIMER_HAL_CC0_ISR
BSP430_TIMER_CCACLK_PERIPH_HANDLE	configBSP430_TIMER_CCACLK_HAL	configBSP430_TIMER_CCACLK_HAL_CC0_ISR

Note: 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;

vBSP430timerResetCounter_ni(alarmHAL_);

alarmHAL_->hpl->ctl = APP_TASSEL | MC_2 | TACLR | TAIE;

vBSP430timerInferHints_ni(alarmHAL_);

}

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.

Homepage: http://github.com/pabigot/bsp430

Copyright: Copyright 2012-2014, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSP430_TIMER_ALARM_FLAG_ENABLED 0x02

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

Examples:: periph/timer/alarm/main.c.

#define BSP430_TIMER_ALARM_FLAG_SET 0x01

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

Examples:: periph/timer/alarm/main.c.

#define BSP430_TIMER_ALARM_FUTURE_LIMIT 3UL

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.

Defaulted:: The value here is superseded by previously encountered definitions.

#define BSP430_TIMER_ALARM_SET_ALREADY -2

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.

#define BSP430_TIMER_ALARM_SET_PAST 2

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.

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

typedef sBSP430timerMuxAlarm* hBSP430timerMuxAlarm

Handle for an individual multiplixed alarm.

typedef sBSP430timerMuxSharedAlarm* hBSP430timerMuxSharedAlarm

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.

Note: 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.

Parameters

cfg	The structure describing the alarm configuration.

Returns: 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.

typedef struct sBSP430timerAlarm sBSP430timerAlarm

A structure holding information related to timer-based alarms.

Warning: 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.

typedef struct sBSP430timerMuxAlarm sBSP430timerMuxAlarm

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.

typedef struct sBSP430timerMuxSharedAlarm sBSP430timerMuxSharedAlarm

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.

Parameters

alarm	a pointer to the structure holding alarm configuration data.
periph	the handle identifier, such as BSP430_UPTIME_TIMER_PERIPH_HANDLE.
ccidx	the capture/compare index within the timer. It is the user's responsibility to ensure that the selected timer supports the selected capture/compare register.

Warning: If configBSP430_TIMER_VALID_COUNTER_READ is enabled attempts to configure an alarm on BSP430_TIMER_VALID_COUNTER_READ_CCIDX will be rejected.

Parameters

callback the 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.

Returns: 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.

Examples:: 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: iBSP430timerMuxAlarmShutdown()

Parameters

shared	a pointer to a structure that holds the underlying dedicated alarm data along with a list of active alarms.
periph	the timer peripheral used to control the alarm.
ccidx	the capture/compare index within `periph` that is to be used for the shared alarms.

Returns: a handle for the shared alarm, or a null pointer if an error is detected.

static BSP430_CORE_INLINE int iBSP430timerAlarmCancel ( hBSP430timerAlarm alarm )

static

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.

Parameters

alarm a pointer to an alarm structure initialized using iBSP430timerAlarmInitialize().

Returns: 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.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE int iBSP430timerAlarmDisable ( hBSP430timerAlarm alarm )

static

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.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE int iBSP430timerAlarmEnable ( hBSP430timerAlarm alarm )

static

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.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE int iBSP430timerAlarmSet	(	hBSP430timerAlarm	alarm,
		unsigned long	setting_tck
	)

static

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.

Note: The alarm is set only if the return value is zero.

Parameters

alarm	a pointer to an alarm structure initialized using iBSP430timerAlarmInitialize().
setting_tck	the 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.

Returns

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.

Examples:: 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.

Warning: Do not enable or disable alarms from inside interrupt handlers or alarm callbacks.

Parameters

alarm	the alarm that is being configured
enablep	nonzero if the alarm is to be enabled; zero if it is to be disabled.

Returns: 0 if setting was successful; -1 if an error occurs.

Examples:: 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.

Parameters

shared	the shared alarm that manages multiplexed alarms.
alarm	information 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().

Returns: 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.

Parameters

shared	the shared alarm that manages multiplexed alarms.
alarm	the alarm to be removed.

Returns: 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.

Parameters

shared a pointer to the structure used for multiplexed alarms

Returns: as with iBSP430timerAlarmDisable_ni()

Data Structures

Macros

Typedefs

Functions

Detailed Description

Dedicated Alarm Infrastructure

Macro Definition Documentation

Typedef Documentation

Function Documentation