The whole truth about RTOS. Article # 11. Tasks: configuration and introduction to the API
- Transfer
The concept of the task was introduced in previous articles. In essence, a task is simply a set of values that can be loaded into the processor registers (for the task being performed) or can be stored in a state ready for a context switch to the task in the future. Most often, the task has its own stack.
Of course, when using the Run to Completion (RTC) scheduler, context switching is not used, and a task can be considered simply a program counter value (the entry point to the code).
The task definition does not include the code itself. The task must execute the code, but it does not belong to it. Tasks may have common functions. Moreover, the entire code of several tasks may be common. General code should almost always be written according to reentrancy requirements. Most compilers can easily cope with this code, but care is needed with library functions, as they may not be designed for multi-tasking applications.
This definition dictates certain rules that should be followed when developing the data structures of the tasks and API functions described in this article. I will review the configuration of tasks in Nucleus SE and begin a detailed overview of the service calls (API calls) that are related to tasks in both Nucleus SE and Nucleus RTOS.
Previous articles in the series:
Article # 10. Scheduler: Additional Features and Saving Context
Article # 9. Scheduler: Implementation
Article # 8. Nucleus SE: Internal Design and Deployment
Article # 7. Nucleus SE: Introduction
Article # 6. Other RTOS services
Article # 5. Interaction between tasks and synchronization
Article # 4. Tasks, Context Switching and Interrupts
Article # 3. Tasks and planning
Article # 2. RTOS: Structure and Real-time Mode
Article # 1. RTOS: introduction.
Configuring Tasks
Number of tasks
In Nucleus SE, task configuration is mainly controlled by #define directives in nuse_config.h . The key parameter NUSE_TASK_NUMBER determines the number of tasks that can be configured in the application. The default value is 1 (i.e., one task during execution), and the maximum parameter value is 16. An incorrect value will result in a compilation error, which will be generated by checking in nuse_config_chech.h (it is included in nuse_config.c , which means compiled with this module), the #error directive will work . This parameter is used when defining data structures, their size depends on its value.
In Nucleus SE, except when using the RTC scheduler, it is necessary that at least one task is always ready for execution. When using the Priority scheduler, you need to make sure that the task with the lowest priority will never be in a suspended state; such a task should be considered a “background task”.
Unlike some other real-time kernels, Nucleus SE does not use "system tasks", which means that all 16 tasks are available to the user application code or Middleware.
API parameters
Each API function (service call) in the Nucleus SE is activated by the #define directive in nuse_config.h . For tasks such parameters are:
- NUSE_TASK_SUSPEND
- NUSE_TASK_RESUME
- NUSE_TASK_SLEEP
- NUSE_TASK_RELINQUISH
- NUSE_TASK_CURRENT
- NUSE_TASK_CHECK_STACK
- NUSE_TASK_RESET
- NUSE_TASK_INFORMATION
- NUSE_TASK_COUNT
By default, all of the above parameters are FALSE , thus deactivating every service call and preventing the inclusion of any code that implements them. To configure tasks for an application, you need to select the necessary API calls and set the corresponding characters to TRUE .
The following is a fragment of the default nuse_config.h file .
If your code uses an API call that has not been activated, an error will appear when linking, because the implementation code was not included in the application.
Functional Parameters
In Nucleus SE, you can add some task functionality. Again, the necessary parameters are in the nuse_config.h file :
NUSE_SUSPEND_ENABLE allows you to suspend tasks. If this option is not selected, all tasks are constantly waiting for planning. Activation of this parameter is required when using the Priority scheduler.
NUSE_BLOCKING_ENABLE allows you to pause tasks for multiple function API calls. If this option is activated, NUSE_SUSPEND_ENABLE must also be activated.
NUSE_INITIAL_TASK_STATE_SUPPORT allows you to set the initial state of the task. If this option is not selected, all tasks will be added to the scheduler immediately after creation.
Task calls
Nucleus RTOS supports 16 task calls (APIs) for working with tasks that provide the following functionality:
| Description of the functional | Nucleus RTOS | Nucleus SE |
|---|---|---|
| Suspending a Task | NU_Suspend_Task () | NUSE_Task_Suspend () |
| Resume Task | NU_Resume_Task () | NUSE_Task_Resume () |
| Suspending a task for a specific period | NU_Sleep () | NUSE_Task_Sleep () |
| Process Control Release | NU_Relinquish () | NUSE_Task_Relinquish () |
| Getting the ID of the current task | NU_Current_Task_Pointer () | NUSE_Task_Current () |
| Check available stack size | NU_Check_Stack () | NUSE_Task_Check_Stack () |
| Returning a task to an unused state (reset) | NU_Reset_Task () | NUSE_Task_Reset () |
| Providing information about a specific task | NU_Task_Information () | NUSE_Task_Information () |
| Getting the counter of configured tasks (for now) in the application | NU_Established_Tasks () | NUSE_Task_Count () |
| Adding a new task to the application (creating) | NU_Create_Task () | Not implemented. |
| Delete task from application | NU_Delete_Task () | Not implemented. |
| Return pointers to all tasks in the application | NU_Task_Pointers () | Not implemented. |
| Changing the crowding algorithm | NU_Change_Preemption () | Not implemented. |
| Change task priority | NU_Change_Priority () | Not implemented. |
| Changing the time quantum of the task | NU_Change_Time_Slice () | Not implemented. |
| Completing the task | NU_Terminate_Task () | Not implemented. |
The implementation of each of the above service calls is discussed in detail below, as well as in the following RTOS articles.
Task Management Services
Basic operations with tasks: suspending a task for an indefinite time, resuming, suspending a task for a specific time, releasing the processor. Nucleus RTOS and Nucleus SE provide four basic API calls for performing these operations, which I will describe below.
Suspending a Task
Nucleus PLUS provides a simple API call that allows you to suspend a specific task indefinitely. Nucleus SE has a service call with similar functionality.
Call Suspending Task in Nucleus RTOS
Service Call Prototype:
STATUS NU_Suspend_Task (NU_TASK * task);
Parameters:
task - a pointer to the control block of the task to be suspended (which can be current, and its ID can be obtained using NU_Current_Task_Pointer () , more details in the next article).
Return value:
NU_SUCCESS - the call was successfully completed;
NU_INVALID_TASK - incorrect pointer to the task;
NU_INVALID_SUSPEND - the specified task has the statusNU_FINISHED or NU_TERMINATED .
Call Suspending Task in Nucleus SE
This API call supports the core functionality of the Nucleus PLUS API.
Service call prototype:
STATUS NUSE_Task_Suspend (NUSE_TASK task);
Parameters:
task - the index (ID) of the task to be suspended (which can be current, and its ID can be obtained using NUSE_Task_Current () - more details in the next article).
Return value:
NUSE_SUCCESS - the call was successfully completed;
NUSE_INVALID_TASK - incorrect task index.
Implementing Suspending a Task in the Nucleus SE
The main functionality of the API function is quite simple:
In essence, in this implementation, the NUSE_Suspend_Task () scheduler function is called with the “unconditional stop” parameter ( NUSE_PURE_SUSPEND ). This function calls the scheduler if the suspended task is the current one.
Resume Task
Nucleus RTOS provides a simple API call that allows you to resume a task that was previously suspended for an indefinite period of time. Nucleus SE has a service call with similar functionality.
Call Resume Task in Nucleus RTOS
Service Call Prototype:
STATUS NU_Resume_Task (NU_TASK * task);
Parameters:
task - a pointer to the control unit of the renewable task.
Return value:
NUSE_SUCCESS - the call was successfully completed;
NUSE_INVALID_TASK - incorrect pointer to the task;
NUSE_INVALID_RESUME - the task was not unconditionally suspended.
Call Resume Task in Nucleus SE
This API call supports the basic Nucleus RTOS API.
Service call prototype:
STATUS NUSE_Task_Resume (NUSE_TASK task);
Parameters:
task - the index (ID) of the task to be resumed.
Return value:
NUSE_SUCCESS - the call was successfully completed;
NUSE_INVALID_TASK - incorrect task index;
NUSE_INVALID_RESUME - the task was not unconditionally suspended.
Implementing the resumption of the task in the Nucleus SE
The core functionality of the API function is quite simple:
In fact, the NUSE_Wake_Task () scheduler function is called in this implementation.. This function calls the scheduler if the Priority scheduler is used, and the renewable task has a higher priority than the current task.
Suspending a task for a specific time period
Nucleus RTOS provides a simple API call to pause the current task for a specific period of time. Nucleus SE has a service call with similar functionality.
Call Suspend Task for a Specific Time Period Nucleus RTOS
Service Call Prototype:
VOID NU_Sleep (UNSIGNED ticks);
Parameters:
ticks - time period for which the task should be suspended (in tacts of the real-time clock).
Return value:
None.
Call Suspending a Task for a Specific Period of Time Nucleus SE
This API call supports the core functionality of the Nucleus RTOS API.
Service call prototype:
void NUSE_Task_Sleep (U16 ticks);
Parameters:
ticks- the period of time for which the task must be suspended (in tacts of the real-time clock).
Return value:
None.
Implementing suspending a task for a certain period of time in Nucleus SE
The main functionality of the API function is quite simple:
This code loads the delay value into the parameter of the current task in NUSE_Task_Timeout_Counter [] . After that, the task is suspended using NUSE_Suspend_Task () with indication of the time period of suspension ( NUSE_SLEEP_SUSPEND ).
The timeout value is used by the real-time clock interrupt handler. The code is shown below and will be discussed in more detail in a future article.
Processor release
Nucleus PLUS provides a simple API call to provide the ability to transfer control of the processor to any of the ready-for-execution tasks with the same priority based on the Round Robin algorithm. Nucleus SE has a service call with very similar functionality. However, it cannot be used with the Priority scheduler, since several tasks with one priority are not supported. Attempting to use this API call with the Priority Scheduler will result in an error. The service call works with the Round Robin and Time Slice schedulers, with the Run To Completion scheduler this API call is inefficient.
Nucleus RTOS processor release call
This API call supports the core functionality of the Nucleus PLUS API.
Service Call Prototype:
VOID NU_Relinquish (VOID);
Options:
None.
Return value:
None.
Nucleus SE processor release
call This API call supports key Nucleus PLUS API functionality.
Service Call Prototype:
void NUSE_Task_Relinquish (void);
Parameters:
None.
Return value:
None.
Implementing Nucleus SE processor release
The main functionality of the API function:
In essence, this implementation calls the NUSE_Reschedule () scheduler function . This function simply tells the scheduler to perform the next task.
The next two articles will continue to review task-related RTOS service calls, using the examples of Nucleus RTOS and Nucleus SE.
About the author: Colin Walls has been working in the electronics industry for more than thirty years, spending a significant amount of time on embedded software. He is now an embedded software engineer in Mentor Embedded (a division of Mentor Graphics). Colin Walls often speaks at conferences and seminars, author of numerous technical articles and two books on embedded software. Lives in the UK. Colin's professional blog , e-mail: colin_walls@mentor.com.
About translation: this cycle of articles seemed interesting because, despite the sometimes outdated described approaches, the author introduces a little-prepared reader with real-time OS features in a very clear language. I myself belong to the team of creators of the Russian RTOS , which wewe intend to make it free , and I hope that the cycle will be useful for novice developers.