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

Concept Flow - xTaskCreate() function

Call xTaskCreate()

↓

Check parameters valid?

No→Return error

Yes↓

Allocate stack memory

↓

Create Task Control Block

↓

Add task to Ready list

↓

Return success

↓

Scheduler runs task when ready

The xTaskCreate() function checks inputs, allocates resources, creates a task control block, adds the task to the ready list, and returns success or failure.

Execution Sample

FreeRTOS

xTaskCreate(
  vTaskCode, "Task1", 1000, NULL, 1, &xHandle);

Creates a task named "Task1" with stack size 1000 words, priority 1, no parameters, and stores the handle in xHandle.

Execution Table

Step	Action	Parameter Check	Result	Output
1	Call xTaskCreate with parameters	N/A	N/A	Function starts
2	Check if vTaskCode is not NULL	vTaskCode valid	Pass	Continue
3	Check if stack size > 0	Stack size = 1000	Pass	Continue
4	Allocate stack memory	Memory available	Pass	Stack allocated
5	Create Task Control Block (TCB)	TCB created	Pass	TCB ready
6	Add task to Ready list	Task added	Pass	Task ready to run
7	Return pdPASS	Success	Pass	xTaskCreate returns pdPASS
8	Scheduler runs task when ready	Task in ready list	Pass	Task executes when scheduled

💡 Execution stops after task is created and added to ready list; function returns pdPASS.

Variable Tracker

Variable	Start	After Step 4	After Step 5	After Step 6	Final
xHandle	NULL	NULL	Points to TCB	Points to TCB	Points to TCB
Stack Memory	Not allocated	Allocated (1000 units)	Allocated	Allocated	Allocated
Task State	Not created	Not created	Created	Ready	Ready

Key Moments - 3 Insights

Why must the stack size be greater than zero?

Because the stack is where the task stores its data during execution. Step 3 in the execution_table shows the check for stack size > 0; if zero, task creation fails.

What happens if vTaskCode is NULL?

Step 2 in the execution_table checks vTaskCode. If NULL, xTaskCreate returns an error immediately and does not create the task.

When does the task actually start running?

After step 6, the task is added to the ready list. The scheduler then runs the task when it is its turn, as shown in step 8.

Visual Quiz - 3 Questions

Look at the execution_table, at which step is the task added to the ready list?

A Step 4

B Step 2

C Step 6

D Step 8

💡 Hint

Check the 'Action' column for 'Add task to Ready list' in the execution_table.

According to variable_tracker, what is the value of xHandle after step 5?

A Points to TCB

B NULL

C Points to stack memory

D Undefined

💡 Hint

Look at the 'xHandle' row and the 'After Step 5' column in variable_tracker.

If the stack size was zero, what would happen according to the execution_table?

A Task would be created anyway

B Function would return error at step 3

C Task would run immediately

D Stack memory would be allocated with zero size

💡 Hint

Step 3 checks stack size; if zero, creation fails as shown in execution_table.

Concept Snapshot

xTaskCreate() creates a FreeRTOS task.
Syntax: xTaskCreate(TaskFunction, "Name", StackSize, Params, Priority, &Handle)
Checks parameters, allocates stack, creates TCB, adds task to ready list.
Returns pdPASS on success, error otherwise.
Task runs when scheduler schedules it.

Full Transcript

The xTaskCreate() function is called with parameters including the task function, name, stack size, parameters, priority, and a handle pointer. It first checks if the task function pointer is valid and if the stack size is greater than zero. If these checks pass, it allocates stack memory and creates a Task Control Block (TCB). The task is then added to the ready list, making it ready to run. The function returns pdPASS to indicate success. The scheduler will run the task when it is its turn. Variables like the task handle and stack memory change state during these steps, as shown in the variable tracker. Common confusions include why stack size must be positive, what happens if the task function is NULL, and when the task actually starts running. The visual quiz tests understanding of these steps and variable states.

Practice

1. What is the main purpose of the xTaskCreate() function in FreeRTOS?

easy

A. To start a new task that runs concurrently with others

B. To delete an existing task

C. To pause the scheduler temporarily

D. To allocate memory for variables

Solution

1. Step 1: Understand the role of xTaskCreate()

   This function is designed to create and start a new task in FreeRTOS, allowing multitasking.

2. Step 2: Compare with other options

   Deleting tasks, pausing the scheduler, or allocating memory are handled by different functions, not xTaskCreate().

3. Final Answer:

   To start a new task that runs concurrently with others -> Option A

4. Quick Check:

   Task creation = start new task [OK]

Hint: xTaskCreate always starts a new task [OK]

Common Mistakes:

• Confusing task creation with task deletion
• Thinking it pauses the scheduler
• Assuming it allocates general memory

2. Which of the following is the correct syntax for xTaskCreate() in FreeRTOS?

easy

A. xTaskCreate(TaskFunction, "Name", StackSize, Parameters, Priority);

B. xTaskCreate(TaskFunction, Name, StackSize, Parameters, Priority, TaskHandle);

C. xTaskCreate(TaskFunction, "Name", StackSize, Parameters, Priority, TaskHandle);

D. xTaskCreate(TaskFunction, "Name", StackSize, Parameters, Priority, &TaskHandle);

Solution

1. Step 1: Recall the correct parameter list

   The correct syntax requires the task function, a string name in quotes, stack size, parameters, priority, and a pointer to the task handle.

2. Step 2: Check each option carefully

   xTaskCreate(TaskFunction, "Name", StackSize, Parameters, Priority, &TaskHandle); matches the correct syntax exactly, including quotes around the name and the address-of operator for the task handle.

3. Final Answer:

   xTaskCreate(TaskFunction, "Name", StackSize, Parameters, Priority, &TaskHandle); -> Option D

4. Quick Check:

   Correct syntax includes &TaskHandle [OK]

Hint: Task name must be a string and handle passed by address [OK]

Common Mistakes:

• Forgetting quotes around the task name
• Passing task handle without & operator
• Omitting the task handle parameter

3. Consider the following code snippet:

void vTaskCode(void * pvParameters) {
    for(;;) {
        // Task code here
    }
}

int main() {
    TaskHandle_t xHandle = NULL;
    BaseType_t result = xTaskCreate(vTaskCode, "Task1", 1000, NULL, 2, &xHandle);
    if(result == pdPASS) {
        // Task created successfully
    }
    return 0;
}

What is the value of result if the task is created successfully?

medium

A. pdPASS

B. pdFAIL

C. NULL

D. 1

Solution

1. Step 1: Understand xTaskCreate() return values

   This function returns pdPASS if the task was created successfully, otherwise pdFAIL.

2. Step 2: Analyze the code logic

   The code checks if result == pdPASS to confirm success, so result must be pdPASS on success.

3. Final Answer:

   pdPASS -> Option A

4. Quick Check:

   Success return = pdPASS [OK]

Hint: Success returns pdPASS, failure returns pdFAIL [OK]

Common Mistakes:

• Confusing pdPASS with pdFAIL
• Assuming NULL or 1 as success
• Not checking the return value

4. Identify the error in this xTaskCreate() usage:

TaskHandle_t xHandle;
BaseType_t result = xTaskCreate(vTaskCode, "Task2", 500, NULL, 1, xHandle);

medium

A. Priority must be zero

B. Task name should not be in quotes

C. Missing & before xHandle in last parameter

D. Stack size is too large

Solution

1. Step 1: Check the task handle parameter

   The last parameter must be a pointer to the task handle variable, so it requires the address operator &.

2. Step 2: Verify other parameters

   The task name is correctly a string in quotes, stack size 500 is valid, and priority 1 is allowed.

3. Final Answer:

   Missing & before xHandle in last parameter -> Option C

4. Quick Check:

   Task handle needs & operator [OK]

Hint: Always pass &TaskHandle, not TaskHandle alone [OK]

Common Mistakes:

• Passing task handle without &
• Removing quotes from task name
• Incorrect assumptions about stack size or priority

5. You want to create two tasks with different priorities using xTaskCreate(). Which code snippet correctly creates both tasks and stores their handles?

hard

A. TaskHandle_t handle1, handle2;

xTaskCreate(Task1, "Task1", 1000, NULL, 5, handle1);
xTaskCreate(Task2, "Task2", 1000, NULL, 3, handle2);

B. TaskHandle_t handle1, handle2;

xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle1);
xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle2);

C. TaskHandle_t handle1, handle2;

xTaskCreate(Task1, Task1, 1000, NULL, 3, &handle1);
xTaskCreate(Task2, Task2, 1000, NULL, 5, &handle2);

D. TaskHandle_t handle1, handle2;

xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle2);
xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle1);

Solution

1. Step 1: Verify task handle usage

   Each task handle must be passed by address using &. TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle1); xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle2); correctly does this for both handles.

2. Step 2: Check task names and priorities

   Task names are strings in quotes. Priorities differ (3 and 5) as required. TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle1); xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle2); matches this correctly.

3. Step 3: Confirm no parameter mix-ups

   TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 5, handle1); xTaskCreate(Task2, "Task2", 1000, NULL, 3, handle2); misses & operator. TaskHandle_t handle1, handle2; xTaskCreate(Task1, Task1, 1000, NULL, 3, &handle1); xTaskCreate(Task2, Task2, 1000, NULL, 5, &handle2); uses function names instead of strings for task names. TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle2); xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle1); swaps handles incorrectly.

4. Final Answer:

   TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle1); xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle2); -> Option B

5. Quick Check:

   Correct handles and priorities = TaskHandle_t handle1, handle2; xTaskCreate(Task1, "Task1", 1000, NULL, 3, &handle1); xTaskCreate(Task2, "Task2", 1000, NULL, 5, &handle2); [OK]

Hint: Pass &handle for each task, use quoted names, set priorities properly [OK]

Common Mistakes:

• Passing handles without &
• Using function names instead of string names
• Mixing up handles between tasks