[PATCH] c-user: Document new rtems_task_delete() behaviour

[Chris Johns]

On 26/7/2022 8:07 pm, Sebastian Huber wrote:
> Update #4679.
> ---
>  c-user/task/directives.rst | 29 +++++++++++++++++++++++------
>  1 file changed, 23 insertions(+), 6 deletions(-)
> 
> diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
> index 64b591d..9f9ea45 100644
> --- a/c-user/task/directives.rst
> +++ b/c-user/task/directives.rst
> @@ -805,16 +805,28 @@ specified by ``id``.
>  :c:macro:`RTEMS_CALLED_FROM_ISR`
>      The directive was called from within interrupt context.
>  
> +:c:macro:`RTEMS_INCORRECT_STATE`
> +    The task termination procedure was started, however, waiting for the
> +    terminating task would have resulted in a deadlock.

The process is synchronous if the task is not deleting itself?

> +
>  :c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
>      The task resided on a remote node.
>  
>  .. rubric:: NOTES:
>  
> -RTEMS stops the execution of the task and reclaims the stack memory, any
> -allocated delay or timeout timers, the TCB, and, if the task is
> -:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS
> -explicitly does not reclaim the following resources: region segments, partition
> -buffers, semaphores, timers, or rate monotonic periods.
> +The task deletion is done in several steps.  Firstly, the task is marked as
> +terminating.  While the task life of the terminating task is protected, it
> +executes normally until it disables the task life protection or it deletes
> +itself. 

I do not understand this last sentence. How does a task executing normally
disable it's task life protection?

What is task life protection?

> A terminating task will eventually stop its normal execution and start
> +its termination procedure.

Is the context when the task is not deleting itself?

> The procedure executes in the context of the
> +terminating task.

I assume from above this is synchronous? When is the deleting task dispatched to
run?

> It involves the destruction of POSIX key values and running
> the task termination user extensions.

It? What about:

 "The task termination procedure involves the destruction of POSIX
  key values and running the task termination user extensions."

?

> Once the task termination procedure is 

"Once complete the execution of the task is stopped and ..."

Chris

> +done, the execution of the task is stopped and task-specific resources are
> +reclaimed by the system, such as the stack memory, any allocated delay or
> +timeout timers, the TCB, and, if the task is :c:macro:`RTEMS_FLOATING_POINT`,
> +its floating point context area. RTEMS explicitly does not reclaim the
> +following resources: region segments, partition buffers, semaphores, timers, or
> +rate monotonic periods.
>  
>  A task is responsible for releasing its resources back to RTEMS before
>  deletion.  To insure proper deallocation of resources, a task should not be
> @@ -824,11 +836,16 @@ resources before deletion.  A task can be directed to release its resources and
>  delete itself by restarting it with a special argument or by sending it a
>  message, an event, or a signal.
>  
> -Deletion of the current task (:c:macro:`RTEMS_SELF`) will force RTEMS to select
> +Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select
>  another task to execute.

What about SMP? If the calling task is deleting a task running on another core?

The language is hard here. I am not sure what works.

>  
>  The :term:`TCB` for the deleted task is reclaimed by RTEMS.
>  
> +When a task other than the calling task is deleted, the calling task waits

"When a task is deleting another task the task calling delete waits ..."?

> +until the task termination procedure of the other task is done.  The

"until the task termination procedure of the task being delete has completed."?

> +terminating task inherits the :term:`eligible priorities <eligible priority>`
> +of the calling task.

Inherits when terminating?

So it is synchronous. Maybe this could be mentioned before now.

Chris