FreeRTOS event flag groups
Event Flag Group Profile
1. event bit (event flag)
Event bit is used to indicate whether an event occurs, the event bit is normally used as event flags, such as the following few examples:
When a message is received and disposed of after this message can be a bit (flag) is set, when the message queue is not in need of treatment, when this bit can be (flag) is set to zero.
When the transmission output message queue by the network can be a bit (flag) is set, when no data needs to be sent out from the network, then will the bit (flag) is set to zero.
Now you need to send a heartbeat message to the network, will be a bit (flag) is set. Now item does not need to send heartbeat information network, the bit (flag) is set to zero.
2. Event group
An event group is a group of bits of the event, event group event bit by bit number to access the same, with three examples listed above as an example:
Bit0 event flag groups represented in the message queue if disposed of.
Bit1 event flag indicating whether there are slim group needs to be sent out from the network.
Bit2 event flag indicating whether the group now needs to send a heartbeat message to the network.
3. Event flag set and event-bit data types
Data type for the event flag group EventBits_t, when configUSE_16_BIT_TICKS is to 1, the event flag set may store 8-bit event, when configUSE_16_BIT_TICKS is 0 when the event flag bit group memory 24 event.
Event flag group, all events are stored in a bit unsigned EventBits_t types of variables, EventBits_t defined as follows in event_groups.h in:
typedef TickType_t EventBits_t;
TickType_t following data types defined in the file in portmacro.h:
#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 /* 32-bit tick type on a 32-bit architecture, so reads of the tick count do not need to be guarded with a critical section. */ #define portTICK_TYPE_IS_ATOMIC 1 #endif
As can be seen, when configUSE_16_BIT_TICKS is 0, TickType_t is a 32-bit data types, EventBits_t also a 32-bit data types. EventBits_t types of variables can store 24-bit event, in addition to that high eight other use. Event Bit 0 is stored in the variable bit0, bit1 variable is the event bit 1, and so on. For STM32, one event flag groups can store up to 24 event bits, as shown below:
Create an event flag groups
FreeRTOS provides two functions for creating event flag groups:
| function | description |
| xEventGroupCreate() | Create an event flag group uses a dynamic approach |
| xEventGroupCreateStatic() | Create an event flag groups use the static method |
1. Function xEventGroupCreate ()
This function creates a time stamp set, lock needs to allocate memory through dynamic memory management method. Due to internal processing, the bit number depends on the set of available event flag configUSE_16_BIT_TICKS, when configUSE_16_BIT_TICKS 1, the event flag group has 8 bits available (bit0 ~ bit7), when configUSE_16_BIT_TICKS is 0, the time stamp group 24 available bits (bit0 ~ bit23). EventBits_t variable for each event type event flag bit storage group, the following function prototype:
EventGroupHandle_t xEventGroupCreate( void )
parameter:
no.
return value:
NULL: Failed to create event flag groups.
Other values: to create a successful event flag groups handle.
2. Functions xEventGroupCreateStatic ()
This function creates an event flag group, the required memory required for discretionary, the function prototype is as follows:
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer )
parameter:
pxEventGroupBuffer: StaticEventGroup_t parameter points to a type that saves the time group structure.
return value:
NULL: Failed to create event flag groups.
Other values: to create a successful event flag groups handle.
Set event bits
FreeRTOS provides four functions for setting the event flag bits set events (flag) set the event bit is set and cleared comprises two kinds of operation 1:
| function | description |
| xEventGroupClearBits() | The specified event bit is cleared, used in the task. |
| xEventGroupClearBitsFromISR() | The specified event bit is cleared by the interrupt service function. |
| xEventGroupSetBits() | The specified event location 1, used in the task. |
| xEventGroupSetBitsFromISR() | The specified event location 1, with the interrupt service function. |
1. Function xEventGroupClearBits ()
The event flag groups specified event bit is cleared, this function can only be used in the task, can not be used in an interrupt service routine, the interrupt service routine in other API functions. Function prototype is as follows:
EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToClear )
parameter:
Handle event flag groups to operate: xEventGroup.
uxBitsToClear: To clear the event site, such as if you want to clear bit3 is set to 0x08. Can clear multiple simultaneous bit, as set 0x09, then that is also clear bit3 and bit0.
return value:
Any value: the value of the specified event group prior to the event bit is cleared.
2. Functions xEventGroupClearBitsFromISR ()
This function is xEventGroupClearBits () interrupt level version is specified event bit (flag) is cleared. This function is used in the interrupt service function, the function prototype is as follows:
BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet )
parameter:
Handle event flag groups to operate: xEventGroup.
uxBitsToClear: To clear the event site, such as if you want to clear bit3 is set to 0x08. Can clear multiple simultaneous bit, as set 0x09, then that is also clear bit3 and bit0.
return value:
pdPASS: Event bit is cleared successfully.
pdFALSE: Event bit is cleared to fail.
3. function xEventGroupSetBits ()
Set the specified event bit is 1, this function can only be used in the task, it can not be used to interrupt service function. The function prototype is as follows:
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet )
parameter:
Event Flag Group handles to operate: xEventGroup.
uxBitsToSet: Specify the set bit 1 of the event, such as if you want to set bit3 1 is set to 0x08. You can simultaneously set a plurality of bit 1, as it is set to 0x09 and while bit3 bit0 set.
return value:
Any value: designated event location in the event of a set of values.
3. function xEventGroupSetBitsFromISR ()
This function is also used to specify the event location 1, this function is xEventGroupSetBits () interrupt version 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)
parameter:
Handle event flag groups to operate: xEventGroup.
uxBitsToClear: Specify the set bit 1 of the event, such as if you want to set bit3 1 is set 0x08. You can simultaneously set a plurality of bit 1, as it is set to 0x09 and while bit3 bit0 set.
pxHigherPriorityTaskWoken: mark whether task switching later to exit this function. The value of the variable, the function is automatically set, the user need not set, users only need to provide a variable to hold the value on the line. When this value is pdTRUE must be to conduct a task switching before exiting the interrupt service routine.
return value:
pdPASS: 1 successful event location.
pdFALSE: 1 failed event location.
Get event flag set of values
We can query the event flag set of values provided by the API function FreeRTOS. FreeRTOS provided a total of two such API functions.
| function | description |
| xEventGroupGetBits() | Gets the value of the current event flag groups (each event bit value), with the task |
| xEventGroupGetBitsFromISR() | Gets the value of the current event flag groups, with the interrupt service function. |
1. Function xEventGroupGetBits ()
This function is used to get the value of the current event flag groups, that is, the value of each bit of the event. This function is used in the task, it can not be used in the interrupt service function. This function is a macro function xEventGroupClearBits real thing execute (), the function prototype is as follows:
EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup )
parameter:
Handle event flag set to be acquired: xEventGroup.
return value:
Any value: the value of the current time stamp group.
2. Functions xEventGroupGetBitsFromISR ()
Gets the value of the current event flag groups, this function is xEventGroupGetBits () interrupt version, the function prototype is as follows:
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )
parameter:
Handle event flag set to be acquired: xEventGroup.
return value:
Any value: the value of the current event flag groups.
Wait for the specified event bits
A task may need to be synchronized with multiple events, then this task will have to wait and judge multiple events bit (flag), use the function xEventGroupWaitBits () can perform this function. After calling the function if the event bit to wait for the task was not ready (set or cleared), then the task will enter the blocking state until the obstruction or the time to reach the waiting position ready for the event. Function prototype is as follows:
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToWaitFor,
const BaseType_t xClearOnExit,
const BaseType_t xWaitForAllBits,
TickType_t xTicksToWait )
parameter:
Specified event flag groups to wait: xEventGroup.
uxBitsToWaitFor: Specifies the position to wait for the event, such as to wait bit0 and (or) bit2 when this parameter is 0x05, if you want to wait bit0 and (or) bit1 and (or) bit2 when this function is 0x07, and so on .
xClearOnExit: If this parameter pdTRUE, then this function before exiting these events by parameter uxBitsToWaitFor bit set will be cleared. If set to pdFALSE bits, then these events will not change.
xWaitForAllBits: If this parameter is set to pdTRUE, so that when these events are set uxBitsToWaitFor bit is set to 1, or the specified blocking time to time function xEventGroupWaitBits () will return. When this parameter is pdFALSE, so long as any of these events wherein bits uxBitsToWaitFor provided a set, or to a specified time, then the blocking function xEventGroupWaitBits () returns.
xTicksToWait: Set blocking time in number of beats.
return value:
Any value: Returns the value of the event flag set when the event location after waiting 1 or obstruct the time. This value is based on what we know of the event location 1. If the function because the blocking time to return, then the return value does not represent any meaning.
Event flags set of experiments
Creating event flags group, the corresponding event bit, waiting for the operation of the corresponding event location 1.
Experimental set three tasks: start_task, eventsetbit_task, eventgroup_task.
start_task: to create two other tasks, create time stamp group.
eventsetbit_task: different key value, the corresponding event in the event flag set to 1.
eventgroup_task: waiting for an event flag bit event group, when these events bits are set, performs a corresponding process.
EventGroupHandler: event flag groups created handle. Use event bit event flag groups: bit0 bit1 bit2
Task Assignment:
// task priority #define START_TASK_PRIO. 1 // task stack size #define START_STK_SIZE 128 // task handle TaskHandle_t StartTask_Handler; // task function void start_task ( void * pvParameters); // task priority #define EVENTSETBIT_TASK_PRIO 2 // task stack size #define EVENTSETBIT_STK_SIZE 50 // task handle TaskHandle_t EventSetbitTask_Handler; // task function void eventsetbit_task ( void * pvParameters); //Task Priority #define EVENTGROUP_TASK_PRIO 3 // task stack size #define EVENTGROUP_STK_SIZE 50 @ task handle TaskHandle_t EventGroupTask_Handler; // task function void eventgroup_task ( void * pvParameters); EventGroupHandle_t EventGroupHandle; // event handler sets mark // define event bit # DEFINE Bit_0 (<<. 1 0) #define bit_1 (<<. 1. 1) #define bit_2 (<<. 1 2)
main () function:
int main ( void ) { NVIC_PriorityGroupConfig (NVIC_PriorityGroup_4); // set the system interrupt priority packets. 4 delay_init (); // delay function initializes uart_init ( 115200 ); // initialize the serial port LED_Init (); // initialize the LED KEY_Init () ; // initialize button // create a task start xTaskCreate ((TaskFunction_t) start_task, // task function ( const char *) " start_task ", // task name (uint16_t) START_STK_SIZE, // task stack size ( void *) NULL, // parameters passed to the function task (UBaseType_t) START_TASK_PRIO, // task priority (TaskHandle_t *) & StartTask_Handler); // task handle vTaskStartScheduler (); // open task scheduling }
Task function:
// start the task task function void start_task ( void * pvParameters) { taskENTER_CRITICAL (); // enter critical region EventGroupHandle = xEventGroupCreate (); // create an event flag group IF (EventGroupHandle == NULL) { printf ( " EventGroup the Create Failed! \ r \ the n- " ); } // create eventsetbit task xTaskCreate ((TaskFunction_t) eventsetbit_task, ( const char *) " eventsetbit_task " , (uint16_t )EVENTSETBIT_STK_SIZE, (void* )NULL, (UBaseType_t )EVENTSETBIT_TASK_PRIO, (TaskHandle_t* )&EventSetbitTask_Handler); //创建eventgroup任务 xTaskCreate((TaskFunction_t )eventgroup_task, (const char* )"eventgroup_task", (uint16_t )EVENTGROUP_STK_SIZE, (void* )NULL, (UBaseType_t )EVENTGROUP_TASK_PRIO, (TaskHandle_t * )&EventGroupTask_Handler); vTaskDelete (StartTask_Handler); // Delete start task taskEXIT_CRITICAL (); // exit the critical section } // eventsetbit_task task function void eventsetbit_task ( void * pvParameters) { U8 Key = 0 ; the while ( 1 ) { Key = KEY_Scan ( 0 ); Switch (Key) { Case KEY1_PRES: IF (! EventGroupHandle = NULL) { xEventGroupSetBits (EventGroupHandle, Bit_0); // set event flag is set Bit_0 group. 1 } BREAK ; Case KEY2_PRES: IF (! EventGroupHandle = NULL) { xEventGroupSetBits (EventGroupHandle, bit_1); // set event flag is set Bit_0 group. 1 } BREAK ; } vTaskDelay ( 10 ); } } // eventgroup_task task function void eventgroup_task ( void * pvParameters) { EventBits_t EventBitsVal = 0 ; the while ( 1 ) { IF (! EventGroupHandle = NULL) { EventBitsVal = xEventGroupWaitBits ( EventGroupHandle, // to wait for the event flag groups (Bit_0 | bit_1), // wait event bits pdTRUE, // clear zero pdFALSE, // as long as the events get one bit exit portMAX_DELAY); // dead et printf ( " EventBitsVal the X-# =% \ r \ the n- " , EventBitsVal); } the else { vTaskDelay ( 10 ); } } }
operation result:
Press KEY1, output EventBitsVal = 0x1
Press KEY2, output EventBitsVal = 0x2