xEventGroupCreate() function in FreeRTOS - Step-by-Step Execution

Concept Flow - xEventGroupCreate() function

Call xEventGroupCreate()

↓

Allocate memory for Event Group

↓

Initialize Event Group bits to 0

↓

Return handle to Event Group

↓

Use handle to set/wait bits

This flow shows how calling xEventGroupCreate() allocates and initializes an event group, then returns a handle for later use.

Execution Sample

FreeRTOS

EventGroupHandle_t eg = xEventGroupCreate();
if (eg != NULL) {
    xEventGroupSetBits(eg, BIT_0);
}

Create an event group, check if creation succeeded, then set a bit in the event group.

Execution Table

Step	Action	Internal State	Result
1	Call xEventGroupCreate()	No event group allocated	Start allocation
2	Allocate memory for event group	Memory allocated, bits = 0	Memory ready
3	Initialize bits to 0	Bits = 0 (all cleared)	Event group initialized
4	Return handle	Handle points to event group	eg != NULL
5	Check if eg != NULL	eg valid	Proceed to set bits
6	Call xEventGroupSetBits(eg, BIT_0)	Set BIT_0 in bits	Bits = 0x01
7	End	Bits = 0x01	Event group ready with BIT_0 set

💡 Event group created and BIT_0 set successfully

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 6	Final
eg (handle)	NULL	Memory allocated	Initialized	Valid handle	Valid handle
bits	N/A	N/A	0x00	0x01	0x01

Key Moments - 2 Insights

Why do we check if the handle returned by xEventGroupCreate() is NULL?

Because if memory allocation fails, xEventGroupCreate() returns NULL. Checking ensures we only use a valid event group handle (see execution_table step 5).

What does the bits variable represent inside the event group?

It represents the current state of all event bits. Initially all bits are cleared (0), then bits are set or cleared by API calls (see execution_table steps 3 and 6).

Visual Quiz - 3 Questions

Look at the execution table, what is the value of bits after step 3?

A NULL (no bits)

B 0x01 (BIT_0 set)

C 0x00 (all bits cleared)

D Undefined

💡 Hint

Check the Internal State column at step 3 in the execution_table

At which step does the event group handle become valid (not NULL)?

A Step 4

B Step 6

C Step 1

D Step 2

💡 Hint

Look at the Result column in execution_table for when eg != NULL

If memory allocation fails inside xEventGroupCreate(), what will the handle value be?

A Valid pointer

B NULL

C Random value

D Zero bits

💡 Hint

Refer to key_moments about why we check for NULL handle

Concept Snapshot

xEventGroupCreate() allocates and initializes an event group.
Returns a handle to use with event group APIs.
Check if handle is NULL to ensure success.
Bits start cleared (0).
Use handle to set, clear, or wait on bits.
Essential for task synchronization in FreeRTOS.

Full Transcript

The xEventGroupCreate() function in FreeRTOS is used to create a new event group. When called, it allocates memory for the event group and initializes all event bits to zero, meaning no events are set initially. It then returns a handle to this event group. This handle is used in other API calls to set or wait for event bits. It is important to check if the returned handle is NULL, which indicates that memory allocation failed and the event group was not created. In the example, after creating the event group, we check the handle and then set BIT_0. The bits variable inside the event group tracks which events are set. Initially, bits are zero, and after setting BIT_0, bits become 0x01. This process helps tasks synchronize by waiting for or signaling events safely.

Practice

1. What does the xEventGroupCreate() function do in FreeRTOS?

easy

A. Creates a new event group and returns its handle

B. Deletes an existing event group

C. Sends an event to a task

D. Creates a new task

Solution

1. Step 1: Understand the purpose of xEventGroupCreate()

   This function is designed to create a new event group in FreeRTOS, which is used for task communication.

2. Step 2: Identify the return value

   The function returns a handle to the newly created event group, which is used to interact with it later.

3. Final Answer:

   Creates a new event group and returns its handle -> Option A

4. Quick Check:

   xEventGroupCreate() creates event group = A [OK]

Hint: Remember: create means new event group and get handle [OK]

Common Mistakes:

• Confusing creation with deletion
• Thinking it sends events instead of creating groups
• Assuming it creates tasks

2. Which of the following is the correct way to declare and create an event group using xEventGroupCreate()?

easy

A. xEventGroupHandle_t xEventGroup = xEventGroupCreate();

B. EventGroupHandle_t xEventGroup = CreateEventGroup();

C. EventGroupHandle_t xEventGroup = xCreateEventGroup();

D. EventGroupHandle_t xEventGroup = xEventGroupCreate();

Solution

1. Step 1: Check the correct type name

   The correct type for event group handles is EventGroupHandle_t.

2. Step 2: Verify the function name

   The function to create an event group is exactly xEventGroupCreate().

3. Final Answer:

   EventGroupHandle_t xEventGroup = xEventGroupCreate(); -> Option D

4. Quick Check:

   Correct type and function name = C [OK]

Hint: Match exact type and function name spelling [OK]

Common Mistakes:

• Using wrong type name like xEventGroupHandle_t
• Using incorrect function names
• Missing the semicolon

3. What will be the output of the following code snippet?

EventGroupHandle_t xGroup;
xGroup = xEventGroupCreate();
if (xGroup == NULL) {
    printf("Failed to create event group\n");
} else {
    printf("Event group created successfully\n");
}

medium

A. Event group created successfully

B. No output

C. Compilation error

D. Failed to create event group

Solution

1. Step 1: Understand xEventGroupCreate() return value

   This function returns a valid handle if creation succeeds, otherwise NULL.

2. Step 2: Analyze the if condition

   The code checks if the handle is NULL. If not NULL, it prints success message.

3. Final Answer:

   Event group created successfully -> Option A

4. Quick Check:

   Handle != NULL means success = D [OK]

Hint: Check if handle is NULL to confirm creation success [OK]

Common Mistakes:

• Assuming NULL means success
• Confusing printf output strings
• Ignoring the if condition logic

4. Identify the error in the following code snippet that uses xEventGroupCreate():

EventGroupHandle_t xGroup;
xGroup = xEventGroupCreate;
if (xGroup == NULL) {
    // handle error
}

medium

A. Incorrect variable type for xGroup

B. Missing parentheses when calling xEventGroupCreate

C. No check for NULL handle

D. Using wrong function name

Solution

1. Step 1: Check function call syntax

   The code assigns xEventGroupCreate without parentheses, so it assigns the function pointer, not the result.

2. Step 2: Understand correct usage

   To call the function and get the handle, parentheses are required: xEventGroupCreate().

3. Final Answer:

   Missing parentheses when calling xEventGroupCreate -> Option B

4. Quick Check:

   Function call needs () = B [OK]

Hint: Always use () to call functions, not just name [OK]

Common Mistakes:

• Forgetting parentheses on function calls
• Confusing function pointer with return value
• Not checking for NULL after creation

5. You want to create an event group and ensure your program handles failure gracefully. Which code snippet correctly creates the event group and checks for failure?

hard

A. EventGroupHandle_t xGroup = xEventGroupCreate(); if (xGroup == NULL) { /* proceed */ } else { /* handle error */ }

B. EventGroupHandle_t xGroup; xGroup = xEventGroupCreate; if (xGroup == NULL) { /* handle error */ }

C. EventGroupHandle_t xGroup = xEventGroupCreate(); if (xGroup != NULL) { /* proceed */ } else { /* handle error */ }

D. EventGroupHandle_t xGroup = CreateEventGroup(); if (xGroup == NULL) { /* handle error */ }

Solution

1. Step 1: Verify correct function call and assignment

   EventGroupHandle_t xGroup = xEventGroupCreate(); if (xGroup != NULL) { /* proceed */ } else { /* handle error */ } correctly calls xEventGroupCreate() with parentheses and assigns the handle.

2. Step 2: Check the logic for failure handling

   It checks if the handle is not NULL to proceed, else handles error. This is the correct logic.

3. Final Answer:

   EventGroupHandle_t xGroup = xEventGroupCreate(); if (xGroup != NULL) { /* proceed */ } else { /* handle error */ } -> Option C

4. Quick Check:

   Correct call and NULL check = A [OK]

Hint: Call with () and check if handle is NULL to handle errors [OK]

Common Mistakes:

• Not using parentheses on function call
• Reversing NULL check logic
• Using wrong function name