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

[Sebastian Huber]

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.
+
 :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.  A terminating task will eventually stop its normal execution and start
+its termination procedure.  The procedure executes in the context of the
+terminating task.  It involves the destruction of POSIX key values and running
+the task termination user extensions.  Once the task termination procedure is
+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.
 
 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
+until the task termination procedure of the other task is done.  The
+terminating task inherits the :term:`eligible priorities <eligible priority>`
+of the calling task.
+
 When a global task is deleted, the task identifier must be transmitted to every
 node in the system for deletion from the local copy of the global object table.
 
-- 
2.35.3