SYS/BIOS events are a means of communication between Tasks and other
threads such as Hwis, Swis, and other Tasks, or between Tasks and
other SYS/BIOS objects. Other SYS/BIOS objects include semaphores,
mailboxes,
message queues, etc. Only tasks can wait for events; whereas tasks,
Hwis, Swis, or SYS/BIOS objects can post them.
In order for a task to be notified of an event from a SYS/BIOS object an
event object must first be registered with that object. Separate APIs
are provided (in their respective modules) for each of the SYS/BIOS object
types that support this feature.
Events are synchronous in nature, meaning that a receiving task will
block or pend while waiting for the events to occur. When the desired
events are received, the pending task continues its execution, as it
would after a call to Semaphore_pend(), for example.
Tasks can also wait on events that are not linked to other SYS/BIOS objects.
These events are explicitly posted from other threads such as tasks,
Swis, or Hwis. A task does not register to receive these events; the
sending thread simply posts its event(s) to the event object the task
is pending on. This scenario is similar to having an ISR post a
semaphore.
A task can wait on events from multiple resources and/or threads; thus,
it can be waiting for a semaphore to be posted and for a message to
arrive in a message queue or an ISR thread to signal that an event has
occurred.
Unlike Semaphores, only a single task can pend on an Event object.
pend is used to wait for events. The andMask & orMask
determine which
event(s) must occur before returning from
pend. The timeout
parameter
allows the task to wait until a timeout, wait indefinitely, or not wait
at all. A return value of zero indicates that a timeout has occurred. A
non-zero return value is the set of events that were active at the time
the task was unblocked.
Events are binary. Events become available (posted) on each Event_post()
of the eventId and become non-available (consumed) on each qualifying
Event_pend() mask.
All active events present in the orMask are consumed (ie removed from
the event object) upon return from
pend. Only when all events
present in the andMask are active are they consumed on return from
pend.
post is used to signal events. If a task is waiting for the event
and all of the event conditions are met,
post unblocks the task.
If no task is waiting,
post simply registers the event with the
event object and returns.
The maximum number of eventIds supported is target specific and depends
on the number of bits in a UInt data type.
For 6x and ARM devices the maximum number of eventIds is therefore 32.
For 28x and MSP430 devices, the maximum number of eventIds is 16.
const Event_Id_00 |
|
Pre-defined Event Ids
#define Event_Id_00 (UInt)0x1
DETAILS
Event_Ids are provided to simplify the specification of
andMasks and orMasks arguments to
Event_pend().
Since each Event_Id is a bitmask composed of only a single bit,
a group of Event_Ids within an andMask or orMask can be indicated
by simply adding them together. For instance, to indicate that a task
is to be awakened only when both Event_Id_00 and Event_Id_01 have
been posted, the andMask for Event_pend() would be constructed
as below:
Event_pend(event, Event_Id_00+EventId_01, Event_Id_NONE,
BIOS_WAIT_FOREVER);
As shown above, Event_Id_NONE is to be used as an empty (NULL)
andMask or orMask.
NOTE
For targets where a UInt is 32 bits in length,
Event_Id_00 thru Event_Id_31 can be used.
For targets where a UInt is 16 bits in length,
Event_Id_00 thru Event_Id_15 can be used.
const Event_Id_01 |
|
#define Event_Id_01 (UInt)0x2
SEE
const Event_Id_02 |
|
#define Event_Id_02 (UInt)0x4
SEE
const Event_Id_03 |
|
#define Event_Id_03 (UInt)0x8
SEE
const Event_Id_04 |
|
#define Event_Id_04 (UInt)0x10
SEE
const Event_Id_05 |
|
#define Event_Id_05 (UInt)0x20
SEE
const Event_Id_06 |
|
#define Event_Id_06 (UInt)0x40
SEE
const Event_Id_07 |
|
#define Event_Id_07 (UInt)0x80
SEE
const Event_Id_08 |
|
#define Event_Id_08 (UInt)0x100
SEE
const Event_Id_09 |
|
#define Event_Id_09 (UInt)0x200
SEE
const Event_Id_10 |
|
#define Event_Id_10 (UInt)0x400
SEE
const Event_Id_11 |
|
#define Event_Id_11 (UInt)0x800
SEE
const Event_Id_12 |
|
#define Event_Id_12 (UInt)0x1000
SEE
const Event_Id_13 |
|
#define Event_Id_13 (UInt)0x2000
SEE
const Event_Id_14 |
|
#define Event_Id_14 (UInt)0x4000
SEE
const Event_Id_15 |
|
#define Event_Id_15 (UInt)0x8000
SEE
const Event_Id_16 |
|
#define Event_Id_16 (UInt)0x10000
SEE
const Event_Id_17 |
|
#define Event_Id_17 (UInt)0x20000
SEE
const Event_Id_18 |
|
#define Event_Id_18 (UInt)0x40000
SEE
const Event_Id_19 |
|
#define Event_Id_19 (UInt)0x80000
SEE
const Event_Id_20 |
|
#define Event_Id_20 (UInt)0x100000
SEE
const Event_Id_21 |
|
#define Event_Id_21 (UInt)0x200000
SEE
const Event_Id_22 |
|
#define Event_Id_22 (UInt)0x400000
SEE
const Event_Id_23 |
|
#define Event_Id_23 (UInt)0x800000
SEE
const Event_Id_24 |
|
#define Event_Id_24 (UInt)0x1000000
SEE
const Event_Id_25 |
|
#define Event_Id_25 (UInt)0x2000000
SEE
const Event_Id_26 |
|
#define Event_Id_26 (UInt)0x4000000
SEE
const Event_Id_27 |
|
#define Event_Id_27 (UInt)0x8000000
SEE
const Event_Id_28 |
|
#define Event_Id_28 (UInt)0x10000000
SEE
const Event_Id_29 |
|
#define Event_Id_29 (UInt)0x20000000
SEE
const Event_Id_30 |
|
#define Event_Id_30 (UInt)0x40000000
SEE
const Event_Id_31 |
|
#define Event_Id_31 (UInt)0x80000000
SEE
const Event_Id_NONE |
|
#define Event_Id_NONE (UInt)0
SEE
config Event_A_badContext // module-wide |
|
Asserted when pend is called with non-zero timeout from other
than a Task context
config Event_A_eventInUse // module-wide |
|
Asserted when pend is called by multiple tasks on the same
Event object
config Event_A_nullEventId // module-wide |
|
Asserted when post is called with eventId == 0
config Event_A_nullEventMasks // module-wide |
|
Asserted when pend is called with andMask and orMask == 0
extern const Assert_Id Event_A_nullEventMasks;
config Event_A_pendTaskDisabled // module-wide |
|
Asserted in Event_pend()
extern const Assert_Id Event_A_pendTaskDisabled;
DETAILS
Assert raised if Event_pend() is called with the Task or
Swi scheduler disabled.
config Event_LM_pend // module-wide |
|
Logged on calls to Event_pend()
config Event_LM_post // module-wide |
|
Logged on calls to Event_post()
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Event_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Event_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Event_Module_getMask();
// Returns the diagnostics mask for this module
Void Event_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct Event_Object Event_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Event_Struct Event_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct Event_Params {
// Instance config-params structure
// Common per-instance configs
} Event_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
Runtime Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
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
This function creates a new Event object.
Instance Deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Event_getPostedEvents() // instance |
|
Returns the set of events that have not been consumed by a task
(ie those events that have not fully satisfied any pend() conditions).
No events are consumed!
ARGUMENTS
handle
handle of a previously-created Event instance object
RETURNS
All un-consumed events posted to the event.
Event_pend() // instance |
|
Wait for events defined in 'and' OR 'or' masks
UInt Event_pend(
Event_Handle handle,
UInt andMask,
UInt orMask,
UInt32 timeout);
ARGUMENTS
handle
handle of a previously-created Event instance object
andMask
return from pend() when ALL of these
events have occurred
orMask
return from pend() when ANY of these
events have occurred
timeout
return from pend() after this many system
time units
RETURNS
All consumed events or zero if timeout.
DETAILS
pend() is used to wait for events. The andMask and orMask determine
which
event(s) must occur before returning from pend(). The timeout parameter
allows the task to wait until a timeout, wait indefinitely, or not wait
at all. A return value of zero indicates that a timeout has occurred. A
non-zero return value is the set of events that were active at the time
the task was unblocked.
The andMask defines a set of events that must
ALL occur to allow pend() to return.
The orMask defines a set of events
that will cause pend() to return if ANY of them occur.
All active events
present in the orMask are consumed (i.e. removed from the event object)
upon return from pend(). Only when all events present in the andMask
are active are they consumed on return from pend().
The pend conditions are satisfied when either ALL of the events
in the andMask occur or ANY of the events in the orMask occur.
A timeout value of
BIOS_WAIT_FOREVER causes
the task to wait indefinitely for matching events to be posted.
A timeout value of
BIOS_NO_WAIT
causes Event_pend to return immediately.
Event_post() // instance |
|
Post event(s) to an event object
ARGUMENTS
handle
handle of a previously-created Event instance object
eventMask
mask of eventIds to post (must be non-zero)
DETAILS
Event_post() is used to signal events. If a task is waiting for the
event and the event conditions are met, post() unblocks the
task. If no tasks are waiting, post() simply registers the event with
the event object and returns.
Instance Built-Ins |
|
Int Event_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
const Event.Id_00 |
|
Pre-defined Event Ids
DETAILS
Event_Ids are provided to simplify the specification of
andMasks and orMasks arguments to
Event_pend().
Since each Event_Id is a bitmask composed of only a single bit,
a group of Event_Ids within an andMask or orMask can be indicated
by simply adding them together. For instance, to indicate that a task
is to be awakened only when both Event_Id_00 and Event_Id_01 have
been posted, the andMask for Event_pend() would be constructed
as below:
Event_pend(event, Event_Id_00+EventId_01, Event_Id_NONE,
BIOS_WAIT_FOREVER);
As shown above, Event_Id_NONE is to be used as an empty (NULL)
andMask or orMask.
NOTE
For targets where a UInt is 32 bits in length,
Event_Id_00 thru Event_Id_31 can be used.
For targets where a UInt is 16 bits in length,
Event_Id_00 thru Event_Id_15 can be used.
C SYNOPSIS
const Event.Id_01 |
|
SEE
C SYNOPSIS
const Event.Id_02 |
|
SEE
C SYNOPSIS
const Event.Id_03 |
|
SEE
C SYNOPSIS
const Event.Id_04 |
|
const Event.Id_04 = 0x10;
SEE
C SYNOPSIS
const Event.Id_05 |
|
const Event.Id_05 = 0x20;
SEE
C SYNOPSIS
const Event.Id_06 |
|
const Event.Id_06 = 0x40;
SEE
C SYNOPSIS
const Event.Id_07 |
|
const Event.Id_07 = 0x80;
SEE
C SYNOPSIS
const Event.Id_08 |
|
const Event.Id_08 = 0x100;
SEE
C SYNOPSIS
const Event.Id_09 |
|
const Event.Id_09 = 0x200;
SEE
C SYNOPSIS
const Event.Id_10 |
|
const Event.Id_10 = 0x400;
SEE
C SYNOPSIS
const Event.Id_11 |
|
const Event.Id_11 = 0x800;
SEE
C SYNOPSIS
const Event.Id_12 |
|
const Event.Id_12 = 0x1000;
SEE
C SYNOPSIS
const Event.Id_13 |
|
const Event.Id_13 = 0x2000;
SEE
C SYNOPSIS
const Event.Id_14 |
|
const Event.Id_14 = 0x4000;
SEE
C SYNOPSIS
const Event.Id_15 |
|
const Event.Id_15 = 0x8000;
SEE
C SYNOPSIS
const Event.Id_16 |
|
const Event.Id_16 = 0x10000;
SEE
C SYNOPSIS
const Event.Id_17 |
|
const Event.Id_17 = 0x20000;
SEE
C SYNOPSIS
const Event.Id_18 |
|
const Event.Id_18 = 0x40000;
SEE
C SYNOPSIS
const Event.Id_19 |
|
const Event.Id_19 = 0x80000;
SEE
C SYNOPSIS
const Event.Id_20 |
|
const Event.Id_20 = 0x100000;
SEE
C SYNOPSIS
const Event.Id_21 |
|
const Event.Id_21 = 0x200000;
SEE
C SYNOPSIS
const Event.Id_22 |
|
const Event.Id_22 = 0x400000;
SEE
C SYNOPSIS
const Event.Id_23 |
|
const Event.Id_23 = 0x800000;
SEE
C SYNOPSIS
const Event.Id_24 |
|
const Event.Id_24 = 0x1000000;
SEE
C SYNOPSIS
const Event.Id_25 |
|
const Event.Id_25 = 0x2000000;
SEE
C SYNOPSIS
const Event.Id_26 |
|
const Event.Id_26 = 0x4000000;
SEE
C SYNOPSIS
const Event.Id_27 |
|
const Event.Id_27 = 0x8000000;
SEE
C SYNOPSIS
const Event.Id_28 |
|
const Event.Id_28 = 0x10000000;
SEE
C SYNOPSIS
const Event.Id_29 |
|
const Event.Id_29 = 0x20000000;
SEE
C SYNOPSIS
const Event.Id_30 |
|
const Event.Id_30 = 0x40000000;
SEE
C SYNOPSIS
const Event.Id_31 |
|
const Event.Id_31 = 0x80000000;
SEE
C SYNOPSIS
const Event.Id_NONE |
|
SEE
C SYNOPSIS
config Event.A_badContext // module-wide |
|
Asserted when pend is called with non-zero timeout from other
than a Task context
msg: "A_badContext: bad calling context. Must be called from a Task."
};
C SYNOPSIS
config Event.A_eventInUse // module-wide |
|
Asserted when pend is called by multiple tasks on the same
Event object
msg: "A_eventInUse: Event object already in use."
};
C SYNOPSIS
config Event.A_nullEventId // module-wide |
|
Asserted when post is called with eventId == 0
msg: "A_nullEventId: posted eventId is null."
};
C SYNOPSIS
config Event.A_nullEventMasks // module-wide |
|
Asserted when pend is called with andMask and orMask == 0
msg: "A_nullEventMasks: orMask and andMask are null."
};
C SYNOPSIS
config Event.A_pendTaskDisabled // module-wide |
|
Asserted in Event_pend()
msg: "A_pendTaskDisabled: Cannot call Event_pend() while the Task or Swi scheduler is disabled."
};
DETAILS
Assert raised if Event_pend() is called with the Task or
Swi scheduler disabled.
C SYNOPSIS
config Event.LM_pend // module-wide |
|
Logged on calls to Event_pend()
msg: "LM_pend: event: 0x%x, currEvents: 0x%x, andMask: 0x%x, orMask: 0x%x, timeout: %d"
};
C SYNOPSIS
config Event.LM_post // module-wide |
|
Logged on calls to Event_post()
msg: "LM_post: event: 0x%x, currEvents: 0x%x, eventId: 0x%x"
};
C SYNOPSIS
metaonly config Event.common$ // module-wide |
|
Common module configuration parameters
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 |
|
var params = new Event.Params;
// Instance config-params object
Static Instance Creation |
|
var params =
new Event.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Event.create(params);
// Create an instance-object
ARGUMENTS
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
This function creates a new Event object.