Task Create API

In the previous article, we learn about the task. In this article, let’s understand FreeRTOS APIs to schedule a task.

The API xTaskCreate (Figure 1) is used to create a task.

The xTaskCreate is a FreeRTOS API, which dynamically creates a task in the memory. Before using any task, you first create it in the memory.

The API xTaskCreate will give rise to a task control block in the memory and associated stack space for the task. That’s why before using any task, you have to create it.

Now let’s explore various parameters of xTaskCreate API:

1. The first parameter is pvTaskCode, which is of the type TaskFunction_t. In the place of pvTaskCode, you have to mention the name of the task function, which we discussed in the previous article. Here you have to mention the task name of the function name that is going to handle the task.

2. And the second parameter is a constant string (constpcName). Here you can mention the descriptive name for the task. 

3. Next parameter is stack size (usStackDepth). Always remember that a task will have its own function and stack space. When the task is scheduled to run, the task function corresponding to that task will be executed, and the task function uses the stack space of the task to save the local variables and the context of the task during context switching.

Let’s say you have created Task1. When you create a Task1, it should have its own task handler or task function, which is a place where you write code and implement your task, and also, a task must have its own stack memory. While creating a task, you have to mention the size of the stack. All the local variables you create inside the task function of this task will be created in the associated stack. Whenever the task wants to save its context during preemption or something, all the status information, context, and registers will be stored in its corresponding stack. We will explore more about context switching later, where you will learn how the stack is used and how it is switched from one task to another task.

4. The fourth parameter is just a pointer (pvParameters), which you can pass to the task function. For example, the task function takes a void pointer as an input parameter (Figure 2). To send data to the task handler, you can use pvParameters parameter. Whatever data pointer you mention for pvParameters parameter will be passed to the task function handler.

5. The next parameter is the priority of the task (uxPriority). Using this parameter, you can mention the priority for a task.

6. After that, pxCreatedTask is the 6th parameter of the task create API, which is actually a handle to the created task control block. pxCreatedTask parameter is a pointer to the created task in the memory. That pointer we call it as a handle of a task. If you want to get that pointer, all you need to do is just pass the pointer of TaskHandle_t data type in the task create API, and then the task create function will fill up that variable with the task pointer, which will call as a task handle.

All the above-discussed parameters are not mandatory to provide, but you must mention the name of the task function, and constpcName can be mentioned as a NULL if you don’t want to mention any descriptive name. Stack depth must be mentioned. If you don’t have any data to send to a task function, then you can mention pvParameters as NULL. You should mention priority.

A handler is optional, and you can mention it as NULL.