Event.h File Reference

Detailed Description

Event Manager.

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.

Event_pend is used to wait for events. The andMask & orMask determine which event(s) must occur before returning from Event_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 Event_pend to return.

The orMask defines a set of events that will cause Event_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 Event_pend. Only when all events present in the andMask are active are they consumed on return from Event_pend.

To use the Event module, the following must be added to the app.syscfg file:

const Event = scripting.addModule("/ti/sysbios/knl/Event");

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.

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

Event_post is used to signal events. If a task is waiting for the event and all of the event conditions are met, Event_post unblocks the task. If no task is waiting, Event_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 unsigned int 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
Event_create	N	N	Y	Y	N
Event_Params_init	Y	Y	Y	Y	Y
Event_construct	N	N	Y	Y	N
Event_delete	N	N	Y	Y	N
Event_destruct	N	N	Y	Y	N
Event_getPostedEvents	Y	Y	Y	Y	Y
Event_pend	N*	N*	Y	N*	N
Event_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. after Event_init() has been called). 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. before Event_init() has been called).

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Task.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for Event.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Event_PendElem
struct	Event_Params
struct	Event_Struct

Macros
#define	Event_A_nullEventMasks   "orMask and andMask are null"
	Asserted when Event_pend() is called with andMask and orMask == 0. More...
#define	Event_A_nullEventId   "posted eventId is null"
	Asserted when Event_post() is called with eventId == 0. More...
#define	Event_A_eventInUse   "event object already in use"
	Asserted when Event_pend() is called by multiple tasks on the same Event object. More...
#define	Event_A_badContext   "bad calling context - must be called from a Task"
	Asserted when Event_pend() is called with non-zero timeout from other than a Task context. More...
#define	Event_A_pendTaskDisabled   "cannot call Event_pend() while the Task or Swi scheduler is disabled"
	Assert raised if Event_pend() is called with the Task or Swi scheduler disabled. More...
#define	Event_Id_00   (0x1)
	Pre-defined Event Ids. More...
#define	Event_Id_01   (0x2)
#define	Event_Id_02   (0x4)
#define	Event_Id_03   (0x8)
#define	Event_Id_04   (0x10)
#define	Event_Id_05   (0x20)
#define	Event_Id_06   (0x40)
#define	Event_Id_07   (0x80)
#define	Event_Id_08   (0x100)
#define	Event_Id_09   (0x200)
#define	Event_Id_10   (0x400)
#define	Event_Id_11   (0x800)
#define	Event_Id_12   (0x1000)
#define	Event_Id_13   (0x2000)
#define	Event_Id_14   (0x4000)
#define	Event_Id_15   (0x8000)
#define	Event_Id_16   (0x10000)
#define	Event_Id_17   (0x20000)
#define	Event_Id_18   (0x40000)
#define	Event_Id_19   (0x80000)
#define	Event_Id_20   (0x100000)
#define	Event_Id_21   (0x200000)
#define	Event_Id_22   (0x400000)
#define	Event_Id_23   (0x800000)
#define	Event_Id_24   (0x1000000)
#define	Event_Id_25   (0x2000000)
#define	Event_Id_26   (0x4000000)
#define	Event_Id_27   (0x8000000)
#define	Event_Id_28   (0x10000000)
#define	Event_Id_29   (0x20000000)
#define	Event_Id_30   (0x40000000)
#define	Event_Id_31   (0x80000000)
#define	Event_Id_NONE   (0)

Typedefs
typedef struct Event_Params	Event_Params
typedef struct Event_Struct	Event_Object
typedef struct Event_Struct	Event_Struct
typedef struct Event_Struct *	Event_Handle

Enumerations
enum	Event_PendState {   Event_PendState_TIMEOUT = 0,   Event_PendState_POSTED = 1,   Event_PendState_CLOCK_WAIT = 2,   Event_PendState_WAIT_FOREVER = 3 }

Functions
Event_Handle	Event_create (const Event_Params *params, Error_Block *eb)
	Create an Event object. More...
Event_Handle	Event_construct (Event_Struct *obj, const Event_Params *params)
	Construct an Event object. More...
void	Event_delete (Event_Handle *event)
	Delete an Event. More...
void	Event_destruct (Event_Struct *obj)
	Destruct an Event. More...
unsigned int	Event_pend (Event_Handle event, unsigned int andMask, unsigned int orMask, uint32_t timeout)
	Wait for events defined in 'and' OR 'or' masks. More...
void	Event_post (Event_Handle event, unsigned int eventMask)
	Post event(s) to an event object. More...
unsigned int	Event_getPostedEvents (Event_Handle event)
	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! More...
void	Event_Params_init (Event_Params *prms)
	Initialize the Event_Params structure with default values. More...
Event_Handle	Event_Object_first (void)
	return handle of the first Event on Event list More...
Event_Handle	Event_Object_next (Event_Handle event)
	return handle of the next Event on Event list More...

Macro Definition Documentation

Event_A_nullEventMasks

#define Event_A_nullEventMasks   "orMask and andMask are null"

Asserted when Event_pend() is called with andMask and orMask == 0.

Event_A_nullEventId

#define Event_A_nullEventId   "posted eventId is null"

Asserted when Event_post() is called with eventId == 0.

Event_A_eventInUse

#define Event_A_eventInUse   "event object already in use"

Asserted when Event_pend() is called by multiple tasks on the same Event object.

Event_A_badContext

#define Event_A_badContext   "bad calling context - must be called from a Task"

Asserted when Event_pend() is called with non-zero timeout from other than a Task context.

Event_A_pendTaskDisabled

#define Event_A_pendTaskDisabled   "cannot call Event_pend() while the Task or Swi scheduler is disabled"

Assert raised if Event_pend() is called with the Task or Swi scheduler disabled.

Event_Id_00

#define Event_Id_00   (0x1)

Pre-defined Event Ids.

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+Event_Id_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 unsigned int is 32 bits in length, Event_Id_00 thru Event_Id_31 can be used. For targets where a unsigned int is 16 bits in length, Event_Id_00 thru Event_Id_15 can be used.

Event_Id_01

#define Event_Id_01   (0x2)

Event_Id_02

#define Event_Id_02   (0x4)

Event_Id_03

#define Event_Id_03   (0x8)

Event_Id_04

#define Event_Id_04   (0x10)

Event_Id_05

#define Event_Id_05   (0x20)

Event_Id_06

#define Event_Id_06   (0x40)

Event_Id_07

#define Event_Id_07   (0x80)

Event_Id_08

#define Event_Id_08   (0x100)

Event_Id_09

#define Event_Id_09   (0x200)

Event_Id_10

#define Event_Id_10   (0x400)

Event_Id_11

#define Event_Id_11   (0x800)

Event_Id_12

#define Event_Id_12   (0x1000)

Event_Id_13

#define Event_Id_13   (0x2000)

Event_Id_14

#define Event_Id_14   (0x4000)

Event_Id_15

#define Event_Id_15   (0x8000)

Event_Id_16

#define Event_Id_16   (0x10000)

Event_Id_17

#define Event_Id_17   (0x20000)

Event_Id_18

#define Event_Id_18   (0x40000)

Event_Id_19

#define Event_Id_19   (0x80000)

Event_Id_20

#define Event_Id_20   (0x100000)

Event_Id_21

#define Event_Id_21   (0x200000)

Event_Id_22

#define Event_Id_22   (0x400000)

Event_Id_23

#define Event_Id_23   (0x800000)

Event_Id_24

#define Event_Id_24   (0x1000000)

Event_Id_25

#define Event_Id_25   (0x2000000)

Event_Id_26

#define Event_Id_26   (0x4000000)

Event_Id_27

#define Event_Id_27   (0x8000000)

Event_Id_28

#define Event_Id_28   (0x10000000)

Event_Id_29

#define Event_Id_29   (0x20000000)

Event_Id_30

#define Event_Id_30   (0x40000000)

Event_Id_31

#define Event_Id_31   (0x80000000)

Event_Id_NONE

#define Event_Id_NONE   (0)

Typedef Documentation

Event_Params

typedef struct Event_Params Event_Params

Event_Object

typedef struct Event_Struct Event_Object

Event_Struct

typedef struct Event_Struct Event_Struct

Event_Handle

typedef struct Event_Struct* Event_Handle

Enumeration Type Documentation

Event_PendState

enum Event_PendState

Enumerator
Event_PendState_TIMEOUT
Event_PendState_POSTED
Event_PendState_CLOCK_WAIT
Event_PendState_WAIT_FOREVER

Function Documentation

Event_create()

Event_Handle Event_create	(	const Event_Params *	params,
		Error_Block *	eb
	)

Create an Event object.

This function creates a new Event object.

Event_construct()

Event_Handle Event_construct	(	Event_Struct *	obj,
		const Event_Params *	params
	)

Construct an Event object.

Event_construct is equivalent to Event_create except that the Event_Struct is pre-allocated. See Event_construct for a description of this API.

Event_delete()

void Event_delete

(

Event_Handle *

event

)

Delete an Event.

Event_delete deletes a Event object. Note that Event_delete takes a pointer to a Event_Handle which enables Event_delete to set the Event_handle to NULL.

Parameters

event

pointer to Event handle

Event_destruct()

void Event_destruct

(

Event_Struct *

obj

)

Destruct an Event.

Event_destruct destructs an Event object.

Parameters

obj	pointer to Event object

Event_pend()

unsigned int Event_pend	(	Event_Handle	event,
		unsigned int	andMask,
		unsigned int	orMask,
		uint32_t	timeout
	)

Wait for events defined in 'and' OR 'or' masks.

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.

events have occurred

events have occurred

time units

Parameters

event	Event handle
andMask	return from pend() when ALL of these
orMask	return from pend() when ANY of these
timeout	return from pend() after this many system

Return values

All	consumed events or zero if timeout.

Event_post()

void Event_post	(	Event_Handle	event,
		unsigned int	eventMask
	)

Post event(s) to an event object.

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.

Parameters

event	Event handle
eventMask	mask of eventIds to post (must be non-zero)

Event_getPostedEvents()

unsigned int Event_getPostedEvents

(

Event_Handle

event

)

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!

Parameters

event

Event handle

Return values

All	un-consumed events posted to the event.

Event_Params_init()

void Event_Params_init

(

Event_Params *

prms

)

Initialize the Event_Params structure with default values.

Event_Params_init initializes the Event_Params structure with default values. Event_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

Event_Object_first()

Event_Handle Event_Object_first

(

void

)

return handle of the first Event on Event list

Return the handle of the first Event on the create/construct list. NULL if no Events have been created or constructed.

Return values

Event

handle

Event_Object_next()

Event_Handle Event_Object_next

(

Event_Handle

event

)

return handle of the next Event on Event list

Return the handle of the next Event on the create/construct list. NULL if no more Events are on the list.

Parameters

event

Event handle

Return values

Event

handle