spec: Document all delete directives

10 files changed, 338 insertions, 74 deletions

diff --git a/spec/rtems/barrier/if/delete.yml b/spec/rtems/barrier/if/delete.yml
index fd22d0f3..1fc73962 100644
--- a/spec/rtems/barrier/if/delete.yml
+++ b/spec/rtems/barrier/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the barrier.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,45 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the barrier specified by ${.:/params[0]/name}.  All
+  tasks blocked waiting for the barrier to be released will be readied and
+  returned a status code which indicates that the barrier was deleted.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a barrier
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_barrier_delete
-notes: null
+notes: |
+  The ${/glossary/bcb:/term} for the deleted barrier is reclaimed by RTEMS.
 params:
-- description: '%'
+- description: |
+    is the barrier identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no barrier associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface
diff --git a/spec/rtems/dpmem/if/delete.yml b/spec/rtems/dpmem/if/delete.yml
index b7567b84..1b3f0183 100644
--- a/spec/rtems/dpmem/if/delete.yml
+++ b/spec/rtems/dpmem/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the port.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,43 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the port specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a port
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_port_delete
-notes: null
+notes: |
+  The ${/glossary/dpcb:/term} for the deleted port is reclaimed by RTEMS.
 params:
-- description: '%'
+- description: |
+    is the port identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no port associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface
diff --git a/spec/rtems/message/if/delete.yml b/spec/rtems/message/if/delete.yml
index c7c12375..72afc6ca 100644
--- a/spec/rtems/message/if/delete.yml
+++ b/spec/rtems/message/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the message queue.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,64 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the message queue specified by ${.:/params[0]/name}.
+  As a result of this directive, all tasks blocked waiting to receive a message
+  from this queue will be readied and returned a status code which indicates
+  that the message queue was deleted.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a message queue
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_message_queue_delete
-notes: null
+notes: |
+  When the message queue is deleted, any messages in the queue are returned to
+  the free message buffer pool.  Any information stored in those messages is
+  lost.  The message buffers allocated for the message queue are reclaimed.
+
+  The ${/glossary/qcb:/term} for the deleted message queue is reclaimed by
+  RTEMS.
+
+  When a global message queue is deleted, the message queue identifier must be
+  transmitted to every node in the system for deletion from the local copy of
+  the global object table.
+
+  The message queue must reside on the local node, even if the message queue
+  was created with the ${../../attr/if/global:/name} attribute.
+
+  Proxies, used to represent remote tasks, are reclaimed when the message queue
+  is deleted.
 params:
-- description: '%'
+- description: |
+    is the message queue identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no message queue associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The semaphore resided on a remote node.
+    value: ${../../status/if/illegal-on-remote-object:/name}
 type: interface
diff --git a/spec/rtems/part/if/delete.yml b/spec/rtems/part/if/delete.yml
index 5dad046b..7d2976cb 100644
--- a/spec/rtems/part/if/delete.yml
+++ b/spec/rtems/part/if/delete.yml
@@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
   Deletes the partition.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,9 +13,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive deletes the partition specified by the ${.:/params[0]/name}
-  parameter.  The partition cannot be deleted if any of its buffers are still
-  allocated.
+  This directive deletes the partition specified by ${.:/params[0]/name}.
 enabled-by: true
 index-entries:
 - delete a partition
@@ -25,16 +23,22 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_partition_delete
 notes: |
-  This directive may cause the calling task to be preempted due to an obtain
-  and release of the object allocator mutex.
+  The partition cannot be deleted if any of its buffers are still allocated.
 
   The ${/glossary/ptcb:/term} for the deleted partition is reclaimed by RTEMS.
 
-  The calling task does not have to be the task that created the partition.
-  Any local task that knows the partition identifier can delete the partition.
-
   When a global partition is deleted, the partition identifier must be
   transmitted to every node in the system for deletion from the local copy of
   the global object table.
@@ -42,7 +46,8 @@ notes: |
   The partition must reside on the local node, even if the partition was
   created with the ${../../attr/if/global:/name} attribute.
 params:
-- description: is the partition identifier.
+- description: |
+    is the partition identifier.
   dir: null
   name: id
 return:
diff --git a/spec/rtems/ratemon/if/delete.yml b/spec/rtems/ratemon/if/delete.yml
index 7764ac8e..19097a06 100644
--- a/spec/rtems/ratemon/if/delete.yml
+++ b/spec/rtems/ratemon/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the period.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,44 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the period specified by ${.:/params[0]/name}.  If the
+  period is running, it is automatically canceled.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a period
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_rate_monotonic_delete
-notes: null
+notes: |
+  The ${/glossary/pcb:/term} for the deleted period is reclaimed by RTEMS.
 params:
-- description: '%'
+- description: |
+    is the period identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no period associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface
diff --git a/spec/rtems/region/if/delete.yml b/spec/rtems/region/if/delete.yml
index 8d73049e..d6fd991d 100644
--- a/spec/rtems/region/if/delete.yml
+++ b/spec/rtems/region/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the region.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,48 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the region specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a region
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_region_delete
-notes: null
+notes: |
+  The region cannot be deleted if any of its segments are still allocated.
+
+  The ${/glossary/rncb:/term} for the deleted region is reclaimed by RTEMS.
 params:
-- description: '%'
+- description: |
+    is the region identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no region associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      There were segments of the region still in use.
+    value: ${../../status/if/resource-in-use:/name}
 type: interface
diff --git a/spec/rtems/sem/if/delete.yml b/spec/rtems/sem/if/delete.yml
index 103f9998..6b22b603 100644
--- a/spec/rtems/sem/if/delete.yml
+++ b/spec/rtems/sem/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the semaphore.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,65 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the semaphore specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a semaphore
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_semaphore_delete
-notes: null
+notes: |
+  Binary semaphores with an owner cannot be deleted.
+  
+  When a semaphore is deleted, all tasks blocked waiting to obtain the
+  semaphore will be readied and returned a status code which indicates that the
+  semaphore was deleted.
+
+  The ${/glossary/smcb:/term} for the deleted semaphore is reclaimed by RTEMS.
+
+  When a global semaphore is deleted, the semaphore identifier must be
+  transmitted to every node in the system for deletion from the local copy of
+  the global object table.
+
+  The semaphore must reside on the local node, even if the semaphore was
+  created with the ${../../attr/if/global:/name} attribute.
+
+  Proxies, used to represent remote tasks, are reclaimed when the semaphore is
+  deleted.
 params:
-- description: '%'
+- description: |
+    is the semaphore identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no semaphore associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The semaphore resided on a remote node.
+    value: ${../../status/if/illegal-on-remote-object:/name}
+  - description: |
+      The binary semaphore had an owner.
+    value: ${../../status/if/resource-in-use:/name}
 type: interface
diff --git a/spec/rtems/task/if/delete.yml b/spec/rtems/task/if/delete.yml
index b0df6a99..d34ed0ec 100644
--- a/spec/rtems/task/if/delete.yml
+++ b/spec/rtems/task/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the task.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,71 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the task, either the calling task or another task, as
+  specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete a task
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_task_delete
-notes: null
+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.
+
+  A task is responsible for releasing its resources back to RTEMS before
+  deletion.  To insure proper deallocation of resources, a task should not be
+  deleted unless it is unable to execute or does not hold any RTEMS resources.
+  If a task holds RTEMS resources, the task should be allowed to deallocate its
+  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 (${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 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.
+
+  The task must reside on the local node, even if the task was created with the
+  ${../../attr/if/global:/name} attribute.
 params:
-- description: '%'
+- description: |
+    is the task identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no task associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The task resided on a remote node.
+    value: ${../../status/if/illegal-on-remote-object:/name}
 type: interface
diff --git a/spec/rtems/timer/if/delete.yml b/spec/rtems/timer/if/delete.yml
index 5bc65bdc..975f6526 100644
--- a/spec/rtems/timer/if/delete.yml
+++ b/spec/rtems/timer/if/delete.yml
@@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
   Deletes the timer.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -13,8 +13,8 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive deletes the timer specified by the ${.:/params[0]/name}
-  parameter.  If the timer is running, it is automatically canceled.
+  This directive deletes the timer specified by ${.:/params[0]/name}.  If the
+  timer is running, it is automatically canceled.
 enabled-by: true
 index-entries:
 - delete a timer
@@ -24,14 +24,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
+- role: constraint
+  uid: /constraint/obj-unlimited-free
 name: rtems_timer_delete
 notes: |
-  This directive may cause the calling task to be preempted due to an obtain
-  and release of the object allocator mutex.
-
   The ${/glossary/tmcb:/term} for the deleted timer is reclaimed by RTEMS.
-
-  A timer can be deleted by a task other than the task which created the timer.
 params:
 - description: is the timer identifier.
   dir: null
diff --git a/spec/rtems/userext/if/delete.yml b/spec/rtems/userext/if/delete.yml
index b8c37b39..13fa2e2e 100644
--- a/spec/rtems/userext/if/delete.yml
+++ b/spec/rtems/userext/if/delete.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Deletes the extension set.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -11,22 +12,42 @@ definition:
     - ${../../type/if/id:/name} ${.:/params[0]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive deletes the extension set specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- delete an extension set
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../../constraint/delete-by-any-task
 name: rtems_extension_delete
-notes: null
+notes: |
+  The ${/glossary/escb:/term} for the deleted extension set is reclaimed by
+  RTEMS.
 params:
-- description: '%'
+- description: |
+    is the extension set identifier.
   dir: null
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no extension set associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface