xQueueCreate() function in FreeRTOS

Introduction

The xQueueCreate() function is used to make a new queue in FreeRTOS. A queue helps tasks send and receive data safely.

When you want two tasks to share information without mixing it up.

When you need to send commands or data from an interrupt to a task.

When you want to hold multiple messages or data items in order.

When you want to control access to a shared resource between tasks.

Syntax

FreeRTOS

QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength, UBaseType_t uxItemSize);

uxQueueLength is how many items the queue can hold.

uxItemSize is the size in bytes of each item stored in the queue.

Examples

This creates a queue that can hold 5 integers.

FreeRTOS

QueueHandle_t myQueue = xQueueCreate(5, sizeof(int));

Creating a queue with length 0 will fail and return NULL.

FreeRTOS

QueueHandle_t emptyQueue = xQueueCreate(0, sizeof(int));

This queue holds only one character at a time.

FreeRTOS

QueueHandle_t singleItemQueue = xQueueCreate(1, sizeof(char));

This queue holds 10 items of type struct Data.

FreeRTOS

QueueHandle_t largeQueue = xQueueCreate(10, sizeof(struct Data));

Sample Program

This program creates a queue that can hold 3 Data items. It sends one item and then receives it back, printing messages to show success.

FreeRTOS

#include "FreeRTOS.h"
#include "queue.h"
#include "task.h"
#include <stdio.h>

// Simple struct to send via queue
typedef struct {
    int id;
    char message[20];
} Data;

int main(void) {
    // Create a queue to hold 3 Data items
    QueueHandle_t dataQueue = xQueueCreate(3, sizeof(Data));

    if (dataQueue == NULL) {
        printf("Queue creation failed!\n");
        return 1;
    } else {
        printf("Queue created successfully.\n");
    }

    // Prepare a data item
    Data newData = {1, "Hello"};

    // Send data to the queue
    if (xQueueSend(dataQueue, &newData, 0) == pdPASS) {
        printf("Data sent to queue: id=%d, message=%s\n", newData.id, newData.message);
    } else {
        printf("Failed to send data to queue.\n");
    }

    // Receive data from the queue
    Data receivedData;
    if (xQueueReceive(dataQueue, &receivedData, 0) == pdPASS) {
        printf("Data received from queue: id=%d, message=%s\n", receivedData.id, receivedData.message);
    } else {
        printf("Failed to receive data from queue.\n");
    }

    return 0;
}

Important Notes

Time complexity of xQueueCreate() is generally O(1) because it just allocates memory and sets up the queue structure.

Space complexity depends on the queue length and item size: total memory = queue length x item size + overhead.

A common mistake is to create a queue with zero length or zero item size, which causes failure (returns NULL).

Use xQueueCreate() when you need a fixed-size queue for inter-task communication. For dynamic or more complex needs, consider other FreeRTOS mechanisms.

Summary

xQueueCreate() makes a new queue to hold data items safely between tasks.

You must specify how many items and the size of each item.

Check if the returned queue handle is NULL to know if creation succeeded.

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