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

Concept Flow - xQueueCreate() function

Call xQueueCreate(length, item_size)

↓

Allocate memory for queue structure

↓

Allocate memory for storage buffer

↓

Initialize queue variables (head, tail, count)

↓

Return handle to created queue

↓

Use queue handle

The function creates a queue by allocating memory and setting up internal variables, then returns a handle to use the queue.

Execution Sample

FreeRTOS

QueueHandle_t q = xQueueCreate(3, sizeof(int));
// Creates a queue for 3 integers
// Returns handle to queue

This code creates a queue that can hold 3 integers and returns a handle to it.

Execution Table

Step	Action	Evaluation	Result
1	Call xQueueCreate(3, sizeof(int))	length=3, item_size=4 bytes	Proceed to allocate memory
2	Allocate memory for queue structure	Memory allocated successfully	Queue structure ready
3	Allocate memory for storage buffer	Memory allocated for 3 items * 4 bytes = 12 bytes	Storage buffer ready
4	Initialize queue variables	head=0, tail=0, count=0	Queue variables initialized
5	Return queue handle	Queue handle is valid	Queue created and ready to use
6	Use queue handle	Queue can now be used for sending/receiving	Operation successful

💡 Queue created successfully with requested length and item size

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
queue_handle	NULL	Allocated	Allocated	Allocated	Returned
storage_buffer	NULL	NULL	Allocated (12 bytes)	Allocated (12 bytes)	Allocated (12 bytes)
head	N/A	N/A	N/A	0	0
tail	N/A	N/A	N/A	0	0
count	N/A	N/A	N/A	0	0

Key Moments - 3 Insights

Why do we need to specify both length and item size when creating a queue?

Because the queue needs to know how many items it can hold (length) and how big each item is (item size) to allocate the right amount of memory, as shown in steps 2 and 3 of the execution_table.

What happens if memory allocation fails during queue creation?

If memory allocation fails, xQueueCreate returns NULL instead of a valid handle, so the queue is not created. This is why checking the returned handle is important after step 5.

Why are head, tail, and count initialized to zero?

These variables track the queue state: head and tail point to positions in the buffer, and count tracks how many items are in the queue. Initializing them to zero means the queue starts empty, as shown in step 4.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'count' after step 4?

A 0

B 3

C Undefined

D 1

💡 Hint

Check variable_tracker row for 'count' after Step 4

At which step is the storage buffer memory allocated?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look at execution_table action descriptions for memory allocation

If the item size was changed to sizeof(char), how would the storage buffer allocation change?

A It would allocate 3 bytes instead of 12 bytes

B It would allocate 12 bytes instead of 3 bytes

C It would allocate 4 bytes

D No change in allocation

💡 Hint

Refer to step 3 in execution_table and variable_tracker for storage buffer size calculation

Concept Snapshot

xQueueCreate(length, item_size) creates a queue.
It allocates memory for queue structure and storage buffer.
Initializes head, tail, count to zero.
Returns a handle to the queue or NULL if failed.
Use the handle to send/receive items safely.

Full Transcript

The xQueueCreate() function in FreeRTOS creates a queue by allocating memory for the queue structure and a storage buffer sized by the number of items and their size. It initializes internal variables like head, tail, and count to zero, indicating an empty queue. After successful creation, it returns a handle to the queue which can be used for sending and receiving data. If memory allocation fails, it returns NULL. This process ensures the queue is ready for use in task communication or synchronization.

Practice

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

easy

A. Sends data to a queue

B. Creates a new queue to hold data items between tasks

C. Deletes an existing queue

D. Receives data from a queue

Solution

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

   The function is designed to create a new queue in FreeRTOS for inter-task communication.

2. Step 2: Differentiate from other queue functions

   Functions like sending or receiving data operate on existing queues, not create them.

3. Final Answer:

   Creates a new queue to hold data items between tasks -> Option B

4. Quick Check:

   xQueueCreate() = create queue [OK]

Hint: xQueueCreate() always makes a new queue [OK]

Common Mistakes:

• Confusing creation with sending or receiving data
• Thinking it deletes a queue
• Assuming it initializes queue data

2. Which of the following is the correct syntax to create a queue for 10 items, each of size sizeof(int)?

easy

A. xQueueCreate(10, sizeof(int));

B. xQueueCreate(sizeof(int), 10);

C. xQueueCreate(10);

D. xQueueCreate(sizeof(int));

Solution

1. Step 1: Recall xQueueCreate() parameters

   The first parameter is the number of items, the second is the size of each item.

2. Step 2: Match parameters to options

   xQueueCreate(10, sizeof(int)); correctly uses 10 items and sizeof(int) as size per item.

3. Final Answer:

   xQueueCreate(10, sizeof(int)); -> Option A

4. Quick Check:

   Parameters = (number, size) [OK]

Hint: First param = count, second = size [OK]

Common Mistakes:

• Swapping the order of parameters
• Providing only one parameter
• Using raw numbers instead of sizeof()

3. Consider this code snippet:

QueueHandle_t q = xQueueCreate(5, sizeof(char));
if (q == NULL) {
    printf("Queue creation failed\n");
} else {
    printf("Queue created successfully\n");
}

What will be printed if the queue is created successfully?

medium

A. Queue creation failed

B. Compilation error

C. Queue created successfully

D. No output

Solution

1. Step 1: Check the return value of xQueueCreate()

   If queue creation succeeds, it returns a non-NULL handle.

2. Step 2: Analyze the if condition

   The code prints "Queue created successfully" when q is not NULL.

3. Final Answer:

   Queue created successfully -> Option C

4. Quick Check:

   q != NULL means success [OK]

Hint: Check if queue handle is NULL for failure [OK]

Common Mistakes:

• Assuming NULL means success
• Ignoring the if condition
• Confusing print messages

4. What is wrong with this code?

QueueHandle_t q = xQueueCreate(0, sizeof(int));
if (q == NULL) {
    // handle error
}

medium

A. Queue size cannot be zero, so creation fails

B. sizeof(int) is invalid parameter

C. Missing queue deletion after creation

D. QueueHandle_t is not the correct type

Solution

1. Step 1: Understand queue length parameter

   The first parameter must be greater than zero to hold items.

2. Step 2: Consequence of zero length

   Passing zero causes xQueueCreate() to fail and return NULL.

3. Final Answer:

   Queue size cannot be zero, so creation fails -> Option A

4. Quick Check:

   Queue length > 0 required [OK]

Hint: Queue length must be > 0 [OK]

Common Mistakes:

• Using zero length queue
• Confusing size of item with queue length
• Ignoring return NULL check

5. You want to create a queue that can hold 3 structures of type SensorData. Which is the correct way to create this queue?

hard

A. xQueueCreate(1, sizeof(SensorData) * 3);

B. xQueueCreate(sizeof(SensorData), 3);

C. xQueueCreate(3, sizeof(SensorData*));

D. xQueueCreate(3, sizeof(SensorData));

Solution

1. Step 1: Identify queue length and item size

   Queue length is 3, item size is size of one SensorData structure.

2. Step 2: Match parameters to xQueueCreate()

   First parameter is number of items (3), second is size of each item (sizeof(SensorData)).

3. Final Answer:

   xQueueCreate(3, sizeof(SensorData)); -> Option D

4. Quick Check:

   Length=3, size=sizeof(struct) [OK]

Hint: Length first, size of one item second [OK]

Common Mistakes:

• Swapping length and size parameters
• Using pointer size instead of struct size
• Creating queue for one large combined item