event.h File Reference

Support for recording timestamped and fact-of events. More...

#include <bsp430/periph/timer.h>

Go to the source code of this file.

Data Structures
union	uBSP430eventAnyType
struct	sBSP430eventTagConfig
struct	sBSP430eventTagRecord
struct	sBSP430eventPeriodicConfig

Macros
#define	BSP430_EVENT_TAG_NUM_SUPPORTED   8
#define	BSP430_EVENT_RECORD_NUM_SUPPORTED   16

Typedefs
typedef union uBSP430eventAnyType	uBSP430eventAnyType
typedef struct sBSP430eventTagConfig	sBSP430eventTagConfig
typedef struct sBSP430eventTagRecord	sBSP430eventTagRecord
typedef void(*	vBSP430eventPeriodicProcess) (const sBSP430eventTagRecord *ep, struct sBSP430eventPeriodic *ap)
typedef struct sBSP430eventPeriodicConfig	sBSP430eventPeriodicConfig
typedef sBSP430eventPeriodicConfig *	hBSP430eventPeriodicConfig

Functions
int	iBSP430eventPeriodicAdd_ni (hBSP430timerMuxSharedAlarm shared, hBSP430eventPeriodicConfig cfg, unsigned long setting_tck)
int	iBSP430eventPeriodicRemove_ni (hBSP430timerMuxSharedAlarm shared, hBSP430eventPeriodicConfig cfg)
static BSP430_CORE_INLINE const sBSP430eventTagConfig *	hBSP430eventTagLookup (unsigned char tag)
unsigned char	ucBSP430eventTagAllocate (const char *id)
unsigned int	uiBSP430eventFlagAllocate ()
static BSP430_CORE_INLINE int	iBSP430eventFlagsEmpty_ni ()
static BSP430_CORE_INLINE int	iBSP430eventFlagsEmpty ()
static BSP430_CORE_INLINE unsigned int	uiBSP430eventFlagsGet_ni ()
static BSP430_CORE_INLINE unsigned int	uiBSP430eventFlagsGet ()
static BSP430_CORE_INLINE void	vBSP430eventFlagsSet_ni (unsigned int flags)
static BSP430_CORE_INLINE void	vBSP430eventFlagsSet (unsigned int flags)
const volatile sBSP430eventTagRecord *	xBSP430eventRecordEvent_ni (unsigned char tag, unsigned char flags, const uBSP430eventAnyType *up)
static BSP430_CORE_INLINE void	vBSP430eventRecordEvent (unsigned char tag, unsigned char flags, const uBSP430eventAnyType *up)
int	iBSP430eventTagGetRecords (sBSP430eventTagRecord *evts, int len)

Variables
static const unsigned char	ucBSP430eventTag_LostEventRecord = 0
static const unsigned int	uiBSP430eventFlag_EventRecord = 0x01

Detailed Description

Support for recording timestamped and fact-of events.

Many event-driven programs need ways to communicate information from interrupt handlers to the main processing loop. This module provides facilities for two types of information:

• Timestamped tagged events held in a circular buffer
• Flagged events held in a bit vector

The BSP430 infrastructure cannot know how what events are used by an application. Nor can an application know what events might be used by libraries or modules it links to. This means the identifying values for distinct events cannot be defined at compile-time or conflicts might be produced. Instead, this module provides a facility to assign event identifiers during application and component initialization.

An event "tag" is an ordinal created by ucBSP430eventTagAllocate() and used to identify the specific event held in an internal circular buffer of capacity BSP430_EVENT_RECORD_NUM_SUPPORTED. The number of permitted tags is a compile-time constant BSP430_EVENT_TAG_NUM_SUPPORTED. The tag ucBSP430eventTag_LostEventRecord is pre-allocated and is used by iBSP430eventTagGetRecords() to indicate the loss of older events due to internal buffer overrun.

An event "flag" is a bit assigned by uiBSP430eventFlagAllocate() and is used to identify occurrence or presence of an edge or level event. The number of permitted flags is the number of bits in an unsigned int. The flag uiBSP430eventFlag_EventRecord is pre-allocated and is used by xBSP430eventRecordEvent_ni() to indicate that unconsumed events need to be processed by iBSP430eventTagGetRecords().

Homepage

http://github.com/pabigot/bsp430

Copyright

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

Macro Definition Documentation

#define BSP430_EVENT_RECORD_NUM_SUPPORTED   16

The capacity of the tagged event record buffer. The value must be at least 2 and cannot exceed 255. Using a power-of-2 may produce slightly faster code. The per-record memory required is the size of sBSP430eventTagRecord.

#define BSP430_EVENT_TAG_NUM_SUPPORTED   8

The number of event tags that the application will support. The value must be at least 2, and cannot exceed 255. The per-tag memory required is the size of sBSP430eventTagConfig.

Typedef Documentation

typedef sBSP430eventPeriodicConfig* hBSP430eventPeriodicConfig

A handle for a periodic event configuration

typedef struct sBSP430eventPeriodicConfig sBSP430eventPeriodicConfig

Information used to support a periodic event.

This uses the Multiplexed Alarm Infrastructure with wrapper functions. It allows xBSP430eventRecordEvent_ni() to be invoked at a regular interval automatically. The tag and flags fields of the event may be customized. The u.p field of the event will point to this configuration structure.

Note

None of the fields in this structure may be mutated while the periodic event is registered.

typedef struct sBSP430eventTagConfig sBSP430eventTagConfig

Information about a particular allocated event tag.

See also

xBSP430eventTagLookup().

typedef struct sBSP430eventTagRecord sBSP430eventTagRecord

A tagged event record

typedef union uBSP430eventAnyType uBSP430eventAnyType

A utility union that allows event records to hold one value of any scalar type not exceeding 32 bits. The union field that is valid for a particular even tag should be documented at the point the tag is declared.

typedef void(* vBSP430eventPeriodicProcess) (const sBSP430eventTagRecord *ep, struct sBSP430eventPeriodic *ap)

A function to process a periodic event.

Parameters

ep	pointer to the event record that was generated by the mux alarm callback
ap	pointer to the record defining the periodic event

Function Documentation

static BSP430_CORE_INLINE const sBSP430eventTagConfig* hBSP430eventTagLookup ( unsigned char  tag )

static

Obtain information such as diagnostic text associated with the tag when it was allocated.

Parameters

tag	a tag as returned by ucBSP430eventTagAllocate().

Returns

the tag configuration data, or a null pointer if tag is not a valid allocated tag.

static BSP430_CORE_INLINE int iBSP430eventFlagsEmpty ( )

static

Interrupt-safe wrapper around iBSP430eventFlagsEmpty_ni()

static BSP430_CORE_INLINE int iBSP430eventFlagsEmpty_ni ( )

static

Test whether there are unhandled event flags.

Returns

0 if there are no unhandled flags, nonzero if there are unhandled flags.

int iBSP430eventPeriodicAdd_ni	(	hBSP430timerMuxSharedAlarm	shared,
		hBSP430eventPeriodicConfig	cfg,
		unsigned long	setting_tck
	)

Wrapper around iBSP430timerMuxAlarmAdd_ni to install cfg for periodic invocation.

Parameters

shared	the basis for a set of synchronized multiplexed alarms. This must already be up and running.
cfg	pointer to the structure holding the alarm state and parameters to the periodic event. See in particular sBSP430eventPeriodicConfig::interval_tck.
setting_tck	the counter value in the realm of shared at which the periodic event is first generated. A reasonable default is ulBSP430timerMuxSharedAlarmCounter().

Returns

as with iBSP430timerMuxAlarmAdd_ni().

int iBSP430eventPeriodicRemove_ni	(	hBSP430timerMuxSharedAlarm	shared,
		hBSP430eventPeriodicConfig	cfg
	)

Wrapper around iBSP430timerMuxAlarmRemove_ni to remove cfg from periodic invocation.

Parameters

shared	the basis for a set of synchronized multiplexed alarms. This must already be up and running.
cfg	pointer to the structure holding the alarm state and parameters to the periodic event. See in particular sBSP430eventPeriodicConfig::interval_tck.

Returns

as with iBSP430timerMuxAlarmRemove_ni().

int iBSP430eventTagGetRecords	(	sBSP430eventTagRecord *	evts,
		int	len
	)

Transfer tagged events from the infrastructure to the application.

This function should be invoked whenever uiBSP430eventFlag_EventRecord is set.

Parameters

evts	space into which tagged event records may be copied
len	the maximum number of tagged event records that may be copied into evts

Returns

the actual number of tagged event records that were copied into evts

unsigned char ucBSP430eventTagAllocate

(

const char *

id

)

Allocate a new tag.

Since BSP430 cannot know what events are of interest to an application, and some events may be defined internal to libraries the application uses, tags cannot be predefined as constants. This function should be invoked by initialization code for any capability that uses tags, producing a value that is constant for the remainder of the execution.

Warning

If allocation would exceed BSP430_EVENT_TAG_NUM_SUPPORTED tags this function will spin in place, allowing the developer to detect what would otherwise be a memory access error. Since tag allocation should never be data-dependent, allocation violations will be immediately visible during testing.

Parameters

id	text used by generic code to identify the tag

Returns

a unique tag

unsigned int uiBSP430eventFlagAllocate

(

)

Allocate a new flag.

As with ucBSP430eventTagAllocate(), the flags that are required by an application or its libraries cannot be compile-time constants.

Warning

If no more event flags are available this function will spin in place, allowing the developer to detect what would otherwise be a memory access error. Since flag allocation should never be data-dependent, allocation violations will be immediately visible during testing.

Returns

a unique unsigned int value with a single bit set.

static BSP430_CORE_INLINE unsigned int uiBSP430eventFlagsGet ( )

static

Interrupt-safe wrapper around uiBSP430eventFlagsGet_ni()

static BSP430_CORE_INLINE unsigned int uiBSP430eventFlagsGet_ni ( )

static

Transfer responsibility for unhandled flags to the application.

This returns the current set of unhandled flags, and clears them from the pending set. Any flags that the application cannot handle immediately may be returned to the infrastructure using vBSP430eventFlagsSet_ni().

static BSP430_CORE_INLINE void vBSP430eventFlagsSet ( unsigned int  flags )

static

Interrupt-safe wrapper around vBSP430eventFlagsSet_ni()

static BSP430_CORE_INLINE void vBSP430eventFlagsSet_ni ( unsigned int  flags )

static

Record the need to handle one or more flags

Any flags set in flags will be added to the currently pending set of flags.

Parameters

flags

flags that must be handled.

static BSP430_CORE_INLINE void vBSP430eventRecordEvent ( unsigned char  tag, unsigned char  flags, const uBSP430eventAnyType *  up  )

static

Interrupt-safe wrapper around xBSP430eventRecordEvent_ni().

const volatile sBSP430eventTagRecord* xBSP430eventRecordEvent_ni	(	unsigned char	tag,
		unsigned char	flags,
		const uBSP430eventAnyType *	up
	)

Record an event along with its metadata.

Parameters

tag	the tag identifying the type of event
flags	any tag-specific flags that provide information about the event
up	pointer to any additional tag-specific metadata. If null, the sBSP430eventTagRecord::u field is cleared.

Returns

a pointer to the completed event record, providing the event timestamp.

Variable Documentation

const unsigned char ucBSP430eventTag_LostEventRecord = 0

static

LostEventRecord is generated when extracting pending events if the ring buffer overflowed. The number of events that were lost is available in the sBSP430eventRecord::u::sz field. The sBSP430eventRecord::flags field is not used.

const unsigned int uiBSP430eventFlag_EventRecord = 0x01

static

EventRecord is flagged whenever there is at least one record in the tagged event buffer.