From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- .../RTOS2/html/group__CMSIS__RTOS__EventFlags.html | 656 +++++++++++++++++++++ 1 file changed, 656 insertions(+) create mode 100644 docs/RTOS2/html/group__CMSIS__RTOS__EventFlags.html (limited to 'docs/RTOS2/html/group__CMSIS__RTOS__EventFlags.html') diff --git a/docs/RTOS2/html/group__CMSIS__RTOS__EventFlags.html b/docs/RTOS2/html/group__CMSIS__RTOS__EventFlags.html new file mode 100644 index 0000000..9d7271b --- /dev/null +++ b/docs/RTOS2/html/group__CMSIS__RTOS__EventFlags.html @@ -0,0 +1,656 @@ + + + + + +Event Flags +CMSIS-RTOS2: Event Flags + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS2 +  Version 2.1.3 +
+
Real-Time Operating System: API and RTX Reference Implementation
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Data Structures | +Typedefs | +Functions
+
+
Event Flags
CMSIS-RTOS API v2
+
+
+ +

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. More...
 
uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags)
 Set the specified Event Flags. More...
 
uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags)
 Clear the specified Event Flags. More...
 
uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)
 Get the current Event Flags. More...
 
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. More...
 
osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 Delete an Event Flags object. More...
 
const char * osEventFlagsGetName (osEventFlagsId_t ef_id)
 Get name of an Event Flags object. More...
 
+

Description

+

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

+
    +
  • can wait for event flags to be set (using osEventFlagsWait). Using this function, it enters the BLOCKED state.
    • +
  • may set one or more flags in any other given thread (using osEventFlagsSet).
    • +
  • may clear its own signals or the signals of other threads (using osEventFlagsClear).
    • +
+

When a thread wakes up and resumes execution, its signal flags are automatically cleared (unless event flags option osFlagsNoClear is specified).

+
Note
The functions osEventFlagsSet, osEventFlagsClear, osEventFlagsGet, and osEventFlagsWait can be called from Interrupt Service Routines.
+
+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 event flags:

+
    +
  1. In the thread that is supposed to send a event with id sig1_id, call the set function:
    osDelay (1000); // wait for 1 second
    +
    osEventFlagsSet (sig1_id, 0x0001U); // set the flag 0x0001U for event sig1_id
    +
    2. +
  2. In another thread (or threads) that are supposed to wait for the event, call the wait function:
    osEventFlagsWait (sig1_id, 0x0001U, NULL, osWaitForever); // wait forever for any flag
    +
    3. +
+

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) {
+
; // do something
+
}
+
tid_Thread_EventReceiver = osThreadNew (Thread_EventReceiver, NULL, NULL);
+
if (tid_Thread_EventReceiver == NULL) {
+
; // do something
+
}
+
; // do something
+
}
+
+
void Thread_EventSender (void *argument)
+
{
+
evt_id = osEventFlagsNew(NULL);
+
while (1) {
+
osEventFlagsSet(evt_id, FLAGS_MSK1);
+
osDelay (1000); // 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
+
+

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 string with a human readable name of the event object.
+Default: NULL.

+
+uint32_t +attr_bits +attribute bits

Reserved for future use (set to '0').
+Default: 0.

+
+void * +cb_mem +memory for control block

Pointer to a memory location for the event control block object. This can optionally be used for custom memory management systems.
+Default: NULL (uses 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 control block object or larger.

+
+ +
+
+

Typedef Documentation

+ +
+
+ + + + +
osEventFlagsId_t
+
+

Event Flags ID identifies the event flags.

+

Returned by:

+ + +
+
+

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.
+

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.

+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os2.h" // CMSIS RTOS header file
+
+
osEventFlagsId_t evt_id; // message queue id
+
+
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
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
uint32_t osEventFlagsSet (osEventFlagsId_t ef_id,
uint32_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 highest bit set.
+

The function osEventFlagsSet sets the event flags specified by the parameter flags in an event flags object specified by parameter ef_id. All threads waiting for the flag set will be notified to resume from BLOCKED state. The function returns the event flags after setting or an error code (highest bit is set, refer to Flags Functions Error Codes).

+

Possible Flags Functions Error Codes return values:

+
    +
  • osFlagsErrorUnknown: Unspecified error.
    • +
  • osFlagsErrorResource: Event flags object specified by parameter ef_id is not ready to be used.
    • +
  • osFlagsErrorParameter: Parameter ef_id does not identify a valid event flags object or flags has highest bit set.
    • +
+
Note
This function may be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os2.h" // CMSIS RTOS header file
+
+
osEventFlagsId_t evt_id; // message queue id
+
+
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
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
uint32_t osEventFlagsClear (osEventFlagsId_t ef_id,
uint32_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 highest bit set.
+

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:

+
    +
  • osFlagsErrorUnknown: Unspecified error.
    • +
  • osFlagsErrorResource: Event flags object specified by parameter ef_id is not ready to be used.
    • +
  • osFlagsErrorParameter: Parameter ef_id does not identify a valid event flags object or flags has highest bit set.
    • +
+
Note
This function may be called from Interrupt Service Routines.
+ +
+
+ +
+
+ + + + + + + + +
uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)
+
+
Parameters
+ + +
[in]ef_idevent flags ID obtained by osEventFlagsNew.
+
+
+
Returns
current event flags.
+

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.

+
Note
This function may be called from Interrupt Service Routines.
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
uint32_t osEventFlagsWait (osEventFlagsId_t ef_id,
uint32_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 highest bit set.
+

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:

+
    +
  • when timeout is 0, the function returns instantly (i.e. try semantics).
    • +
  • when timeout is set to osWaitForever the function will wait for an infinite time until the event flags become available (i.e. wait semantics).
    • +
  • all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
    • +
+

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:

+
    +
  • osFlagsErrorUnknown: Unspecified error.
    • +
  • osFlagsErrorTimeout: The awaited flags has not been set during given timeout.
    • +
  • osFlagsErrorResource: Event flags object specified by parameter ef_id is not ready to be used.
    • +
  • osFlagsErrorParameter: Parameter ef_id does not identify a valid event flags object or flags has highest bit set.
    • +
+
Note
May be called from Interrupt Service Routines if the parameter timeout is set to 0.
+

Code Example

+
#include "cmsis_os2.h" // CMSIS RTOS header file
+
+
osEventFlagsId_t evt_id; // message queue id
+
+
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
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
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.
+

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:

+
    +
  • osOK: the specified event flags object has been deleted.
    • +
  • osErrorISR: osEventFlagsDelete cannot be called from interrupt service routines.
    • +
  • osErrorParameter: the value of the parameter ef_id is incorrect.
    • +
  • osErrorResource: parameter ef_id is NULL or wrong.
    • +
+
Note
This function cannot be called from Interrupt Service Routines.
+ +
+
+ +
+
+ + + + + + + + +
const char * osEventFlagsGetName (osEventFlagsId_t ef_id)
+
+
Parameters
+ + +
[in]ef_idevent flags ID obtained by osEventFlagsNew.
+
+
+
Returns
name as null-terminated string.
+

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.

+
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
void EvtFlagsGetName_example (void) {
+
char id; // id of the event flags object
+
+
id = osEventFlagsGetName ();
+
if (id == NULL) {
+
// Failed to get the event flags object name
+
}
+
}
+
+
+
+
+
+ + + + -- cgit