Synchronize threads using event 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. | |
uint32_t | osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags) |
Set the specified Event Flags. | |
uint32_t | osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags) |
Clear the specified Event Flags. | |
uint32_t | osEventFlagsGet (osEventFlagsId_t ef_id) |
Get the current Event Flags. | |
uint32_t | osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout) |
Wait for one or more Event Flags to become signaled. | |
osStatus_t | osEventFlagsDelete (osEventFlagsId_t ef_id) |
Delete an Event Flags object. | |
const char * | osEventFlagsGetName (osEventFlagsId_t ef_id) |
Get name of an Event Flags object. | |
Synchronize threads using event flags.
The event flags management functions in CMSIS-RTOS allow you to control or wait for event flags. Each signal has up to 31 event flags.
A thread
When a thread wakes up and resumes execution, its signal flags are automatically cleared (unless event flags option osFlagsNoClear is specified).
Here is a simple example that shows how two thread can communicate with each others using event flags:
The following steps are required to use event flags:
Code Example
struct osEventFlagsAttr_t |
Attributes structure for event flags.
Attributes to configure an event flag set.
Refer to Memory Management for details about usage of
Data Fields | ||
---|---|---|
const char * | name |
name of the event flags Pointer to a constant string with a human readable name (displayed during debugging) of the event flag object. Default: NULL no name specified. |
uint32_t | attr_bits |
attribute bits Reserved for future use (must be set to '0' for future compatibility). |
void * | cb_mem |
memory for control block Pointer to a memory for the event flag control block object. Refer to Manual User-defined Allocation for more information. Default: NULL to use Automatic Dynamic Allocation for the event flag control block. |
uint32_t | cb_size |
size of provided memory for control block The size (in bytes) of memory block passed with cb_mem. Required value depends on the underlying kernel implementation. Default: 0 as the default is no memory provided with cb_mem. |
osEventFlagsId_t osEventFlagsNew | ( | const osEventFlagsAttr_t * | attr | ) |
Create and Initialize an Event Flags object.
[in] | attr | event flags attributes; NULL: default values. |
The function osEventFlagsNew creates a new event flags object that is used to send events across threads and returns the pointer to the event flags object identifier or NULL in case of an error. It can be safely called before the RTOS is started (call to osKernelStart), but not before it is initialized (call to osKernelInitialize).
The parameter attr sets the event flags attributes (refer to osEventFlagsAttr_t). Default attributes will be used if set to NULL, i.e. kernel memory allocation is used for the event control block.
Code Example
uint32_t osEventFlagsSet | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags | ||
) |
Set the specified Event Flags.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
[in] | flags | specifies the flags that shall be set. |
The function osEventFlagsSet sets the event flags specified by the parameter flags in an event flags object specified by parameter ef_id.
The threads with highest priority waiting for the flag(s) set will be notified to resume from BLOCKED state. The function returns the event flags stored in the event control block or an error code (highest bit is set, refer to Flags Functions Error Codes). Further threads may be wakened in priority order when the option osFlagsNoClear is given to the osEventFlagsWait call.
Possible Flags Functions Error Codes return values:
Code Example
uint32_t osEventFlagsClear | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags | ||
) |
Clear the specified Event Flags.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
[in] | flags | specifies the flags that shall be cleared. |
The function osEventFlagsClear clears the event flags specified by the parameter flags in an event flags object specified by parameter ef_id. The function returns the event flags before clearing or an error code (highest bit is set, refer to Flags Functions Error Codes).
Possible Flags Functions Error Codes return values:
uint32_t osEventFlagsGet | ( | osEventFlagsId_t | ef_id | ) |
Get the current Event Flags.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
The function osEventFlagsGet returns the event flags currently set in an event flags object specified by parameter ef_id or 0 in case of an error.
uint32_t osEventFlagsWait | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags, | ||
uint32_t | options, | ||
uint32_t | timeout | ||
) |
Wait for one or more Event Flags to become signaled.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
[in] | flags | specifies the flags to wait for. |
[in] | options | specifies flags options (osFlagsXxxx). |
[in] | timeout | Timeout Values or 0 in case of no time-out. |
The function osEventFlagsWait suspends the execution of the currently RUNNING thread until any or all event flags specified by the parameter flags in the event object specified by parameter ef_id are set. When these event flags are already set, the function returns instantly. Otherwise, the thread is put into the state BLOCKED.
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.
The parameter timeout specifies how long the system waits for event flags. While the system waits, the thread that is calling this function is put into the BLOCKED state. The parameter timeout can have the following values:
The function returns the event flags before clearing or an error code (highest bit is set, refer to Flags Functions Error Codes).
Possible Flags Functions Error Codes return values:
Code Example
osStatus_t osEventFlagsDelete | ( | osEventFlagsId_t | ef_id | ) |
Delete an Event Flags object.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
The function osEventFlagsDelete deletes the event flags object specified by parameter ef_id and releases the internal memory obtained for the event flags handling. After this call, the ef_id is no longer valid and cannot be used. This can cause starvation of threads that are waiting for flags of this event object. The ef_id may be created again using the function osEventFlagsNew.
Possible osStatus_t return values:
const char * osEventFlagsGetName | ( | osEventFlagsId_t | ef_id | ) |
Get name of an Event Flags object.
[in] | ef_id | event flags ID obtained by osEventFlagsNew. |
The function osEventFlagsGetName returns the pointer to the name string of the event flags object identified by parameter ef_id or NULL in case of an error.
Code Example