Article Directory
1. Introduction to event flag group
1. Event bit (event flag)
The event bit is used to indicate whether an event occurs, and the event bit is usually used as an event flag, such as the following examples:
● When a message is received and the message is processed, a certain bit (flag) can be set to 1, and when there is no message to be processed in the queue, this bit (flag) can be set to 0.
● After the messages in the queue are sent out through the network, a certain bit (flag) can be set to 1, and when there is no data to be sent out from the network, this bit (flag) can be set to 0.
● Now it is necessary to send a heartbeat message to the network and set a certain bit (flag) to 1. Now there is no need to send heartbeat information to the network, this bit (flag) is set to 0.
2. Event group
An event group is a group of event bits, and the event bits in the event group are accessed through bit numbers. Similarly, take the three examples listed above as examples: ● Bit0 of the event flag group
indicates the message in the queue Whether to dispose of.
● Bit1 of the event flag group indicates whether there is a message to be sent from the network.
● Bit 2 of the event flag group indicates whether to send heartbeat information to the network now.
3. Data type of event flag group and event bit
The data type of the event flag group is EventGroupHandle_t. When configUSE_16_BIT_TICKS is 1, the event flag group can store 8 event bits. When configUSE_16_BIT_TICKS is 0, the event flag group can store 24 event bits. .
All event bits in the event flag group are stored in an unsigned variable of type EventBits_t, and EventBits_t is defined in event_groups.h as follows:
typedef TickType_t EventBits_t;
The data type TickType_t is defined in the file portmacro.h as follows:
#if( configUSE_16_BIT_TICKS == 1 )
typedef uint16_t TickType_t;
#define portMAX_DELAY ( TickType_t ) 0xffff
#else
typedef uint32_t TickType_t;
#define portMAX_DELAY ( TickType_t ) 0xffffffffUL
#define portTICK_TYPE_IS_ATOMIC 1
#endif
It can be seen that when configUSE_16_BIT_TICKS is 0, TickType_t is a 32-bit data type, so EventBits_t is also a 32-bit data type. A variable of type EventBits_t can store 24 event bits, and the other high 8 bits are used for other purposes. Event bit 0 is stored in bit0 of this variable, bit1 of the variable is event bit 1, and so on. For STM32, an event flag group can store up to 24 event bits, as shown in the following figure:
2. Create an event flag group
FreeRTOS provides two functions for creating event flag groups, as shown in the following table:
1. Function xEventGroupCreate()
This function is used to create an event flag group, and the required memory is allocated through the dynamic memory management method. Due to internal processing, the number of available bits for the event flag group depends on configUSE_16_BIT_TICKS. When configUSE_16_BIT_TICKS1 is 1, there are 8 available bits (bit0~bit7) for the event flag group. When configUSE_16_BIT_TICKS is 0, there are 24 available bits for the event flag group. bit (bit0~bit23). The variable of type EventBits_t is used to store each event bit in the event flag group, and the function prototype is as follows:
EventGroupHandle_t xEventGroupCreate( void )
Parameters:
None.
Return value:
NULL: Failed to create event flag group.
Other values: Created successfully event flag group handle.
2. Function xEventGroupCreateStatic()
This function is used to create an event flag group timer. The required memory needs to be allocated by the user. The prototype of this function is as follows:
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer )
Parameters:
pxEventGroupBuffer: The parameter points to a variable of type StaticEventGroup_t, which is used to save the event flag group structure.
Return value:
NULL: Failed to create event flag group.
Other values: Created successfully event flag group handle.
3. Set the event bit
FreeRTOS provides 4 functions to set the event bit (flag) in the event flag group. The setting of the event bit (flag) includes two operations of clearing and setting. These 4 functions are shown in the following table:
1. Function xEventGroupClearBits()
Clear the specified event bit in the event flag group, this function can only be used in the task, not in the interrupt service function!
The interrupt service function has other API functions. The function prototype is as follows:
EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToClear );
Parameters:
xEventGroup: The handle of the event flag group to be operated.
uxBitsToClear: The event bit to be cleared, for example, set it to 0X08 if bit3 is to be cleared. Multiple bits can be cleared at the same time. For example, if it is set to 0X09, bit3 and bit0 will be cleared at the same time.
Return Value:
Any Value: The event group value before clearing the specified event bit.
2. Function xEventGroupClearBitsFromISR()
This function is the interrupt-level version of the function xEventGroupClearBits(), and also clears the specified event bit (flag). This function is used in the interrupt service function, and the prototype of this function is as follows:
BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet );
Parameters:
xEventGroup: The handle of the event flag group to be operated.
uxBitsToClear: The event bit to be cleared, for example, set it to 0X08 if bit3 is to be cleared. Multiple bits can be cleared at the same time. For example, if it is set to 0X09, bit3 and bit0 will be cleared at the same time.
Return value:
pdPASS: event bit is cleared successfully.
pdFALSE: Event bit clearing failed.
3. Function xEventGroupSetBits()
Set the specified event bit to 1. This function can only be used in tasks, not interrupt service functions. The prototype of this function is as follows:
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet );
Parameters:
xEventGroup: The handle of the event flag group to be operated.
uxBitsToClear: Specify the event bit to be set to 1, for example, to set bit3 to 1, set it to 0X08. Multiple bits can be set to 1 at the same time. For example, if it is set to 0X09, bit3 and bit0 are set to 1 at the same time.
Return Value:
Any Value: The event group value after setting the specified event bit.
4. Function xEventGroupSetBitsFromISR()
This function is also used to set the specified event bit to 1. This function is the interrupt version of xEventGroupSetBits(), which is used in the interrupt service function. The function prototype is as follows:
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
BaseType_t * pxHigherPriorityTaskWoken );
Parameters:
xEventGroup: The handle of the event flag group to be operated.
uxBitsToClear: Specify the event bit to be set to 1, for example, to set bit3 to 1, set it to 0X08. Multiple bits can be set to 1 at the same time. For example, if it is set to 0X09, bit3 and bit0 are set to 1 at the same time.
pxHigherPriorityTaskWoken: Mark whether to switch tasks after exiting this function. The value function of this variable will be automatically set. The user does not need to set it. The user only needs to provide a variable to save this value. When this value is pdTRUE, a task switch must be performed before exiting the interrupt service function.
Return value:
pdPASS: Event position 1 successful.
pdFALSE: Event location 1 failed.
4. Get the event flag group value
We can query the event standard group value through the API function provided by FreeRTOS. FreeRTOS provides a total of two such API functions, as shown in the following table:
1. Function xEventGroupGetBits()
This function is used to get the value of the current event flag group, that is, the value of each event bit. This function is used in a task and cannot be used in an interrupt service function. This function is a macro, and what is actually executed is the function xEventGroupClearBits(). The function prototype is as follows:
EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup )
Parameters:
xEventGroup: The handle of the event flag group to be obtained.
Return Value:
Any Value: The value of the current event flag group.
2. Function xEventGroupGetBitsFromISR()
Get the value of the current event flag group, this function is the interrupt version of xEventGroupGetBits(), the function prototype is as follows:
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )
Parameters:
xEventGroup: The handle of the event flag group to be obtained.
Return Value:
Any Value: The value of the current event flag group.
5. Wait for the specified event bit
A certain task may need to synchronize with multiple events, then this task needs to wait and judge multiple event bits (flags), and use the function xEventGroupWaitBits() to complete this function. After calling the function, if the event bit to be waited for by the task is not ready (set to 1 or cleared), the task will enter the blocking state until the blocking time arrives or the event bit to be waited for is ready. The function prototype is as follows:
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToWaitFor,
const BaseType_t xClearOnExit,
const BaseType_t xWaitForAllBits,
const TickType_t xTicksToWait );
Parameters:
xEventGroup: Specifies the event flag group to wait for.
uxBitsToWaitFord: Specifies the event bit to wait for. For example, when waiting for bit0 and (or) bit2, this parameter is 0X05; if waiting for bit0 and (or) bit1 and (or) bit2, this parameter is 0X07, and so on.
xClearOnExit: If this parameter is pdTRUE, the event bits set by the parameter uxBitsToWaitFor will be cleared before exiting this function. These event bits are not changed if bit pdFALSE is set.
xWaitForAllBits: If this parameter is set to pdTRUE, the function xEventGroupWaitBits() will return when the event bits set by uxBitsToWaitFor are all set to 1, or the specified blocking time is up. When this function is pdFALSE, as long as any one of these event bits set by uxBitsToWaitFor is set to 1, or the specified blocking time is up, the function xEventGroupWaitBits() will return.
xTicksToWait: Set the blocking time, the unit is the number of beats.
Return value:
any value: return the value of the event flag group after the event bit being waited for is set to 1, or the blocking time is up. According to this value, we know which event bits are 1. If the function returns because the blocking time is up, then this return value does not mean anything.