[rtems-central commit] spec: Document new task delete behaviour

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    9cc8ca131b4ab351b76bcf2a546790522102894d
Changeset: http://git.rtems.org/rtems-central/commit/?id=9cc8ca131b4ab351b76bcf2a546790522102894d

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Jul 28 07:45:33 2022 +0200

spec: Document new task delete behaviour

---

 spec/rtems/task/if/delete.yml | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/spec/rtems/task/if/delete.yml b/spec/rtems/task/if/delete.yml
index eb635a09..fae924b2 100644
--- a/spec/rtems/task/if/delete.yml
+++ b/spec/rtems/task/if/delete.yml
@@ -38,11 +38,20 @@ links:
   uid: /constraint/obj-unlimited-free
 name: rtems_task_delete
 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
-  ${../../attr/if/floating-point:/name}, 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.  The task termination procedure involves the
+  destruction of POSIX key values and running the task termination user
+  extensions.  Once complete 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 ${/glossary/tcb:/term},
+  and, if the task is ${../../attr/if/floating-point:/name}, 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
@@ -52,10 +61,13 @@ notes: |
   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 (${self-define:/name}) will force RTEMS to
+  Deletion of the calling task (${self-define:/name}) will force RTEMS to
   select another task to execute.
 
-  The ${/glossary/tcb:/term} for the deleted task is reclaimed by RTEMS.
+  When a task deletes another task, the calling task waits until the task
+  termination procedure of the task being deleted has completed.  The
+  terminating task inherits the ${/glossary/priority-eligible:/plural} 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
@@ -82,6 +94,10 @@ return:
   - description: |
       The directive was called from within interrupt context.
     value: ${../../status/if/called-from-isr:/name}
+  - description: |
+      The task termination procedure was started, however, waiting for the
+      terminating task would have resulted in a deadlock.
+    value: ${../../status/if/incorrect-state:/name}
   - description: |
       The task resided on a remote node.
     value: ${../../status/if/illegal-on-remote-object:/name}