The whole truth about the RTOS. Article # 11. Tasks: configuration and introduction to the API

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 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 must be taken with library functions, since 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 look at 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 context preservation
Article # 9. Scheduler: implementation
Article # 8. Nucleus SE: Inside 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
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 assign TRUE values ​​to the corresponding characters.

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 during 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 scheduling. 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 service 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 specific task 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 configured tasks (at the moment) in the application	NU_Established_Tasks ()	NUSE_Task_Count ()
Adding a new task to the application (creating)	NU_Create_Task ()	Not implemented.
Deleting a task from the 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 problem	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);

Options:
task - a pointer to the control block of the suspended task (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 status NU_FINISHED or NU_TERMINATED .

Calling a task to pause in the Nucleus SE
This API call supports the core Nucleus PLUS API functionality.

Service Call Prototype:
STATUS NUSE_Task_Suspend (NUSE_TASK task);

Options:
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 Suspend Task in the Nucleus SE
The basic functionality of the API function is quite simple:



Essentially, 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);

Options:
task - a pointer to the control unit of a 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 core Nucleus RTOS API.

Service Call Prototype:
STATUS NUSE_Task_Resume (NUSE_TASK task);

Options:
task - index 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 a resume task in the Nucleus SE
The main functionality of the API function is quite simple:



In fact, in this implementation, the NUSE_Wake_Task () scheduler function is called. 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.

Calling a task to pause for a specific period of time Nucleus RTOS
Service Call Prototype:
VOID NU_Sleep (UNSIGNED ticks);

Options:
ticks - time period for which the task should be suspended (in tacts of the real-time clock).

Return value:
Not.

Calling a task to pause 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);

Options:
ticks - time period for which the task should be suspended (in tacts of the real-time clock).

Return value:
Not.

Implementing suspending a task for a specific time period 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 the indication of the suspension time period ( 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 the same 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:
Not.

Nucleus SE processor release call
This API call supports key Nucleus PLUS API functionality.

Service Call Prototype:
void NUSE_Task_Relinquish (void);

Options:
None.

Return value:
Not.

Nucleus SE processor release implementation
The main functionality of the API function:



Essentially, this implementation calls the NUSE_Reschedule () scheduler function. This function simply tells the scheduler to perform the following 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.

On translation: this cycle of articles seemed interesting because, in spite of the 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 we intend to make free , and I hope that the cycle will be useful for novice developers.