The whole truth about the RTOS. Article # 12. Task Services

We continue to consider RTOS services that provide additional information about tasks and operations with them.

Additional API calls related to tasks include calls to get the task ID, check the stack size, reset the task, get information about the task and determine the number of tasks in the system. Nucleus RTOS and Nucleus SE provide 4 basic API calls for these operations, which I will discuss in this article.
')
Previous articles in the series:
Article # 11. Tasks: configuration and introduction to the API
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.

Getting the ID of the current task

This service call returns the ID of the task being called. For Nucleus, RTOS is a pointer to the control unit of the current task. For Nucleus SE, the index (0-15) of the current task.

Call the current task in the Nucleus RTOS
Service Call Prototype:
NU_TASK * NU_Current_Task_Pointer (VOID);

Options:
None.

Return value:
A pointer to the control unit of the current task;
NU_NULL - no task in progress .

Calling the current task in the Nucleus SE
This API call supports the core functionality of the Nucleus RTOS API.

Service Call Prototype:
NUSE_TASK NUSE_Task_Current (void);

Options:
None.

Return value:
The index of the current (called) task.

Perform the current task in the Nucleus SE
The implementation of the API call in this case is quite simple: the value of the global variable NUSE_Task_Active is returned .

Check available stack size

This service call returns the available stack size (in bytes) for the current task. This is only appropriate for planners, where each task has its own stack; those. not suitable for the Run To Completion (RTC) scheduler in the Nucleus SE.

Calling up stack volume information in Nucleus RTOS
Service Call Prototype:
UNSIGNED NU_Task_Check_Stack (VOID);

Options:
None.

Return value:
The size of the available stack size for the current task in bytes.

Calling up stack size information in Nucleus SE
This API call supports Nucleus RTOS core API functionality. However, the Nucleus SE requires a formal (dummy) parameter to make it easier to get the value of the pointer to the stack used.

Service Call Prototype:
U16 NUSE_Task_Check_Stack (U8 dummy);

Options:
dummy is any value because it is not actually used.

Return value:
The size of the available stack size for the current task in bytes.

Implementation
For such a call, the code must be portable:



If the RTC scheduler is used, the return value is 0 because it is not possible (using portable code) to determine the available stack space for the task.

In other cases, the value of the stack pointer is determined by finding the address of the dummy parameter, which will be almost at the beginning of the stack. Strictly speaking, this method depends on the development tools / compiler, but will always be working. The return value is the difference between this value and the initial value of the stack space, translated into bytes.

Task reset

An API call, in this case, returns the task to its original unused state. Such an API function is different from the normal API reset functions for other kernel objects, if only because it is a reset, and not just setting a task to its initial state (for Nucleus SE, this is either NUSE_READY or the NUSE_Task_Initial_State [] entry (see Data structures in next article)); the task is placed in a suspended state ( NUSE_PURE_SUSPEND ) and must be resumed in order to be scheduled again. Such logic is similar to the functionality of the corresponding API call in the Nucleus RTOS.

Call reset task in the Nucleus RTOS
Service Call Prototype:
STATUS NU_Reset_Task (NU_TASK * task, UNSIGNED argc, VOID * argv);

Options:
task - a pointer to the task management block;
argc is a data element that can be used to transfer information to a task;
argv is a pointer that can be used to pass information to a task.

Return value:
NU_SUCCESS - the call was completed successfully;
NU_INVALID_TASK - incorrect pointer to the task;
NU_NOT_TERMINATED - the described task is not in a state of complete suspension (terminated) or completion (finished); only tasks in suspended or terminated state can be reset.

Call reset task in the Nucleus SE
This API call supports the core functionality of the Nucleus RTOS API.

Service Call Prototype:
STATUS NUSE_Task_Reset (NUSE_TASK task);

Options:
task - an index (ID) of the task to be reset.

Return value:
NUSE_SUCCESS - the call was completed successfully;
NUSE_INVALID_TASK - incorrect task index.

Implementing a reset task in the Nucleus SE
The main purpose of the NUSE_Task_Reset () function API after checking a parameter is to re-initialize all the data structures of the task:



If a task is blocked when calling an API to wait for access to a kernel object, the first thing to do is configure the counter of blocked tasks corresponding to the object. This is done by the switch statement.

Then the data structures of the task are initialized (mainly with zeros, except for its context block) by calling the initialization function NUSE_Init_Task () . Its implementation will be discussed in more detail in the next article with a description of the system initialization. Finally, the task status is set to NUSE_PURE_SUSPEND .

Obtaining information about the task

This service call allows you to get partial information about the task. The implementation of the Nucleus SE differs from the Nucleus PLUS, in which less information is returned, since the assignment of names to objects, the displacement of a lower priority task and the time slice are not supported, and the priority is not returned, being redundant information.

Calling for information about a task in Nucleus RTOS
Service Call Prototype:
STATUS NU_Task_Information (NU_TASK * task, CHAR * name, DATA_ELEMENT * task_status, UNSIGNED * scheduled_count, OPTION * priority, OPTION * preempt, UNSIGNED * time_slice, VOID ** stack_base, UNSIGNED * stack_size, UNSIGNED

Options:
task - a pointer to the task, information about which is requested;
name - pointer to the 8-character string for the task name; includes area for null characters;
task_status - pointer to a variable that receives the current status of the task;
scheduled_count - pointer to the variable that receives the counter value, how many times the task was added to the scheduler;
priority - a pointer to a variable to get the priority of the task;
preempt - a pointer to a variable for displacing options for a lower priority task; NU_PREEMPT indicates that the task can be preempted, and NU_NO_PREEMPT indicates that the task cannot be preempted;
time_slice - pointer to the variable to get the value of the time slice of the task; a value of 0 indicates that time slicing is not possible for this task;
stack_base - a pointer to a variable to get the address of the task stack;
stack_size - a pointer to a variable to get the size of the task stack;
minimum_stack - a pointer to a variable to get the minimum number of bytes remaining on the stack.

Return value:
NU_SUCCESS - the call was completed successfully;
NU_INVALID_TASK - incorrect pointer to the task.

Calling for information about a task in Nucleus SE
This call supports the core functionality of the Nucleus PLUS API.

Service Call Prototype:
STATUS NUSE_Task_Information (NUSE_TASK task, U8 * task_status, U16 * scheduled_count, ADDR * stack_base, U16 * stack_size);

Options:
task - index of the task for which information is requested;
task_status - pointer to the U8 variable, which receives the current status of the task (if the waiting state of the task is not available, nothing is returned);
scheduled_count - pointer to U16 variable, which receives the value of the counter for the number of tasks added to the scheduler (if the scheduled tasks counter is disabled, then nothing is returned);
stack_base - a pointer to the ADDR variable that receives the address of the task stack (if the RTC scheduler is used, nothing is returned);
stack_size is a pointer to a U16 variable that receives the size of the task stack (if the RTC scheduler is used, nothing is returned).

Return value:
NUSE_SUCCESS - the call was completed successfully;
NUSE_INVALID_TASK - incorrect task index;
NUSE_INVALID_POINTER - pointer parameters (one or more) are incorrect.

Implementing task information in Nucleus SE
The implementation of this API call is quite simple:



The function returns the status of the task, taking into account the various possibilities of configurations.

Getting the number of tasks

This service call returns information about the number of tasks configured in the application. While in Nucleus RTOS this number may change, and the return value will represent the current number of tasks at the moment, in Nucleus SE, the return value is set during assembly and no longer changes.

The challenge of getting the number of tasks in the Nucleus RTOS
Service Call Prototype:
UNSIGNED NU_Established_Tasks (VOID);

Options:
Absent

Return value:
The number of installed (created and not deleted) tasks in the application.

The challenge of getting the number of tasks in the Nucleus SE
This API call supports the Nucleus PLUS core API functionality.

Service Call Prototype:
U8 NUSE_Task_Count (void);

Options:
Absent

Return value:
The number of tasks configured in the application.

Implementation
The implementation of this API call is quite simple: the value of the #define NUSE_TASK_NUMBER directive is returned .

The next article will look at the data structures in Nucleus SE associated with tasks and some standard API calls that are not supported by 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.