CMSIS-RTOS2  Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Event Flags

Create events using flags. More...

Data Structures

struct  osEventFlagsAttr_t
 Attributes structure for event flags. More...
 

Typedefs

typedef void * osEventFlagsId_t
 

Functions

osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)
 Create and Initialize an Event Flags object. More...
 
int32_t osEventFlagsSet (osEventFlagsId_t ef_id, int32_t flags)
 Set the specified Event Flags. More...
 
int32_t osEventFlagsClear (osEventFlagsId_t ef_id, int32_t flags)
 Clear the specified Event Flags. More...
 
int32_t osEventFlagsGet (osEventFlagsId_t ef_id)
 Get the current Event Flags. More...
 
int32_t osEventFlagsWait (osEventFlagsId_t ef_id, int32_t flags, uint32_t options, uint32_t timeout)
 Wait for one or more Event Flags to become signaled. More...
 
osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 Delete an Event Flags object. More...
 

Description

Events are used to trigger execution states between threads. The event flag management functions in CMSIS-RTOS allow you to control or wait for event flags. Each signal has up to 31 event flags (int32_t flags provides 31 bits).

A thread

When a thread wakes up and resumes execution, its signal flags are automatically cleared.

Note
Refer to Event Flags Configuration for RTX5 configuration options.

Working with Events

Here is a simple example that shows how two thread can communicate with each others using event flags:

simple_signal.png
Simple event communication

The following steps are required to use signals:

  1. In the thread that is supposed to send a event with id sig1_id, call the wait function:
    osEventFlagsSet (sig1_id, 0x0001); //
  2. In another thread (or threads) that are supposed wait for the event:
    osEventFlagsGet (sig1_id, 0x0001, NULL, osWaitForever); // set the signal 0x0001 for thread tid_thread1
    osDelay (1000); // wait for 1 second

The following complete example code can be directly used with the "CMSIS-RTOS2 main template" and is also provided as a stand-alone template for RTX5:

Code Example

void Thread_EventSender (void *argument); // thread function 1
void Thread_EventReceiver (void *argument); // thread function 2
osThreadId_t tid_Thread_EventSender; // thread id 1
osThreadId_t tid_Thread_EventReceiver; // thread id 2
osEventFlagsId_t evt_id; // message queue id
#define FLAGS_MSK1 0x00000001ul
void app_main (void)
{
tid_Thread_EventSender = osThreadNew (Thread_EventSender, NULL, NULL);
if (tid_Thread_EventSender == NULL) {
return(-1);
}
tid_Thread_EventReceiver = osThreadNew (Thread_EventReceiver, NULL, NULL);
if (tid_Thread_EventReceiver == NULL) {
return(-1);
}
return(0);
}
void Thread_EventSender (void *argument)
{
evt_id = osEventFlagsNew(NULL);
while (1) {
osEventFlagsSet(evt_id, FLAGS_MSK1);
osThreadYield (); // suspend thread
}
}
void Thread_EventReceiver (void *argument)
{
uint32_t flags;
while (1) {
flags = osEventFlagsWait (evt_id,FLAGS_MSK1,osFlagsWaitAny, osWaitForever);
//handle event
}
}

Data Structure Documentation

struct osEventFlagsAttr_t
Data Fields
const char * name name of the event flags

String with a human readable name of the event object.

uint32_t attr_bits attribute bits

No attributes available.

void * cb_mem memory for control block

Pointer to a memory location for the event object. This can optionally be used for custom memory management systems. Specify NULL to use the kernel memory management.

uint32_t cb_size size of provided memory for control block

The size of the memory block passed with cb_mem. Must be the size of an event object or larger.

Typedef Documentation

Event Flags ID identifies the event flags.

Function Documentation

osEventFlagsId_t osEventFlagsNew ( const osEventFlagsAttr_t attr)
Parameters
[in]attrevent flags attributes; NULL: default values.
Returns
event flags ID for reference by other functions or NULL in case of error.

Create and initialize a Event Flag object that is used to send events across threads.

Code Example

#include "cmsis_os2.h"
osEventId_tId_t event_id;
void CreateEvent (void) {
event_id = osEventFlagsNew(NULL);
if (event_id != NULL) {
// Event object created
}
}
int32_t osEventFlagsSet ( osEventFlagsId_t  ef_id,
int32_t  flags 
)
Parameters
[in]ef_idevent flags ID obtained by osEventFlagsNew.
[in]flagsspecifies the flags that shall be set.
Returns
event flags after setting or error code if negative.

Set the event flags in an event flags object. This function may be used also within interrupt service routines. All threads waiting for the flag set will be notified to resume from BLOCKED state.

Note
Interrupt Service Routines can call this function.

Code Example

void Thread_2 (void *arg);
static void EX_Signal_1 (void) {
int32_t signals;
osThreadId_t thread_id;
thread_id = osThreadNew (Thread_2, NULL, NULL);
signals = osEventFlagsSet (event_id, 0x00000005); // Send signals to the created thread
}
int32_t osEventFlagsClear ( osEventFlagsId_t  ef_id,
int32_t  flags 
)
Parameters
[in]ef_idevent flags ID obtained by osEventFlagsNew.
[in]flagsspecifies the flags that shall be cleared.
Returns
event flags before clearing or error code if negative.

Clear the event flags of an event flags object.

int32_t osEventFlagsGet ( osEventFlagsId_t  ef_id)
Parameters
[in]ef_idevent flags ID obtained by osEventFlagsNew.
Returns
current event flags.

Return the event flags currently set in an event flags object.

int32_t osEventFlagsWait ( osEventFlagsId_t  ef_id,
int32_t  flags,
uint32_t  options,
uint32_t  timeout 
)
Parameters
[in]ef_idevent flags ID obtained by osEventFlagsNew.
[in]flagsspecifies the flags to wait for.
[in]optionsspecifies flags options (osFlagsXxxx).
[in]timeoutTimeout Value or 0 in case of no time-out.
Returns
event flags before clearing or error code if negative.

Suspend the execution of the current RUNNING thread until any or all specified event flags with the parameter flags are set. The options parameter specifies the wait condition.

Option
osFlagsWaitAny Wait for any flag (default).
osFlagsWaitAll Wait for all flags.
osFlagsNoClear Do not clear flags which have been specified to wait for.

If osFlagsNoClear is set in the options osEventFlagsClear can be used to clear flags manually.

When these event flags are already set, the function returns instantly. Otherwise the thread is put into the state BLOCKED.

osStatus_t osEventFlagsDelete ( osEventFlagsId_t  ef_id)
Parameters
[in]ef_idevent flags ID obtained by osEventFlagsNew.
Returns
status code that indicates the execution status of the function.

Delete an event flag object. The function releases internal memory obtained for event flags handling. After this call the ef_id is no longer valid and cannot be used. The ef_id may be created again using the function osEventFlagsNew. This can cause starvation of threads that are waiting for flags of this event object.