module ti.sysbios.knl.Event

Event Manager

C synopsis
Individual elements
DETAILS
CAVEAT
Configuration settings
Individual elements

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. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/knl/Event.xdc

#include <ti/sysbios/knl/Event.h>

Functions
Void	Event_construct// Initialize a new instance object inside the provided structure(Event_Struct structP, const Event_Params params);
Event_Handle	Event_create// Allocate and initialize a new instance object and return its handle(const Event_Params params, Error_Block eb);
Void	Event_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Event_Handle *handleP);
Void	Event_destruct// Finalize the instance object inside the provided structure(Event_Struct *structP);
UInt	Event_getPostedEvents// 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!(Event_Handle handle);
Void	Event_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Event_Params *params);
UInt	Event_pend// Wait for events defined in 'and' OR 'or' masks(Event_Handle handle, UInt andMask, UInt orMask, UInt32 timeout);
Void	Event_post// Post event(s) to an event object(Event_Handle handle, UInt eventMask);
Functions common to all target instances
	Event_handle// Convert this instance structure pointer into an instance handle, Event_Handle_label// The label associated with this instance object, Event_Handle_name// The name of this instance object, Event_Object_count// The number of statically-created instance objects, Event_Object_first// The handle of the first dynamically-created instance object, or NULL, Event_Object_get// The handle of the i-th statically-created instance object (array == NULL), Event_Object_heap// The heap used to allocate dynamically-created instance objects, Event_Object_next// The handle of the next dynamically-created instance object, or NULL, Event_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	Event_Module_getMask// Returns the diagnostics mask for this module, Event_Module_hasMask// Test whether this module has a diagnostics mask, Event_Module_heap// The heap from which this module allocates memory, Event_Module_id// Get this module's unique id, Event_Module_setMask// Set the diagnostics mask for this module, Event_Module_startupDone// Test if this module has completed startup
Defines
#define	Event_Id_00// Pre-defined Event Ids (UInt)0x1
#define	Event_Id_01// (UInt)0x2
#define	Event_Id_02// (UInt)0x4
#define	Event_Id_03// (UInt)0x8
#define	Event_Id_04// (UInt)0x10
#define	Event_Id_05// (UInt)0x20
#define	Event_Id_06// (UInt)0x40
#define	Event_Id_07// (UInt)0x80
#define	Event_Id_08// (UInt)0x100
#define	Event_Id_09// (UInt)0x200
#define	Event_Id_10// (UInt)0x400
#define	Event_Id_11// (UInt)0x800
#define	Event_Id_12// (UInt)0x1000
#define	Event_Id_13// (UInt)0x2000
#define	Event_Id_14// (UInt)0x4000
#define	Event_Id_15// (UInt)0x8000
#define	Event_Id_16// (UInt)0x10000
#define	Event_Id_17// (UInt)0x20000
#define	Event_Id_18// (UInt)0x40000
#define	Event_Id_19// (UInt)0x80000
#define	Event_Id_20// (UInt)0x100000
#define	Event_Id_21// (UInt)0x200000
#define	Event_Id_22// (UInt)0x400000
#define	Event_Id_23// (UInt)0x800000
#define	Event_Id_24// (UInt)0x1000000
#define	Event_Id_25// (UInt)0x2000000
#define	Event_Id_26// (UInt)0x4000000
#define	Event_Id_27// (UInt)0x8000000
#define	Event_Id_28// (UInt)0x10000000
#define	Event_Id_29// (UInt)0x20000000
#define	Event_Id_30// (UInt)0x40000000
#define	Event_Id_31// (UInt)0x80000000
#define	Event_Id_NONE// (UInt)0
Typedefs
typedef Event_Object *	Event_Handle// Client reference to an instance object;
typedef struct	Event_Object// Opaque internal representation of an instance object Event_Object;
typedef struct	Event_Params// Instance config-params structure ...
typedef struct	Event_Struct// Opaque client structure large enough to hold an instance object Event_Struct;
Constants
extern const Assert_Id	Event_A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context;
extern const Assert_Id	Event_A_eventInUse// Asserted when pend is called by multiple tasks on the same Event object;
extern const Assert_Id	Event_A_nullEventId// Asserted when post is called with eventId == 0;
extern const Assert_Id	Event_A_nullEventMasks// Asserted when pend is called with andMask and orMask == 0;
extern const Assert_Id	Event_A_pendTaskDisabled// Asserted in Event_pend();
extern const Log_Event	Event_LM_pend// Logged on calls to Event_pend();
extern const Log_Event	Event_LM_post// Logged on calls to Event_post();

DETAILS

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.

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.

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.

CAVEAT

When Events are implicitly posted while used in conjunction with Semaphore or Mailbox objects, then following the call to Event_pend() which consumes the matching Event_IDs pended on, the Event object will be updated by the intervening Semaphore_pend() or Mailbox_pend/post() call so that it reflects the current state of availability of the corresponding Semaphore or Mailbox object.

pend returns immediately if the andMask OR orMask conditions are true upon entry.

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 the maximum number of eventIds is 16.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
create	N	N	Y	Y	N
Params_init	Y	Y	Y	Y	Y
construct	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getPostedEvents	Y	Y	Y	Y	Y
pend	N*	N*	Y	N*	N
post	Y	Y	Y	Y	N
Definitions: (N* means OK to call iff the timeout parameter is set to '0'.) Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. Event_Module_startupDone() returns TRUE). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. Event_Module_startupDone() returns FALSE).

const Event_Id_00