spec: Clarify object identification

11 files changed, 154 insertions, 68 deletions

diff --git a/spec/rtems/barrier/if/ident.yml b/spec/rtems/barrier/if/ident.yml
index d99a65d2..f7cc00bb 100644
--- a/spec/rtems/barrier/if/ident.yml
+++ b/spec/rtems/barrier/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a barrier object by the specified object name.
+  Identifies a barrier by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the barrier identifier associated with the barrier
+  This directive obtains a barrier identifier associated with the barrier
   name specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
@@ -24,18 +24,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_barrier_ident
 notes: |
   If the barrier name is not unique, then the barrier identifier will match the
   first barrier with that name in the search order.  However, this barrier
-  identifier is not guaranteed to correspond to the desired barrier.  The
-  barrier identifier is used with other barrier related directives to access
-  the barrier.
+  identifier is not guaranteed to correspond to the desired barrier.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+
+  The barrier identifier is used with other barrier related directives to
+  access the barrier.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/dpmem/if/ident.yml b/spec/rtems/dpmem/if/ident.yml
index 7946c28e..404e4f90 100644
--- a/spec/rtems/dpmem/if/ident.yml
+++ b/spec/rtems/dpmem/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a port object by the specified object name.
+  Identifies a port by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the port identifier associated with the port name
+  This directive obtains a port identifier associated with the port name
   specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
@@ -24,17 +24,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_port_ident
 notes: |
   If the port name is not unique, then the port identifier will match the first
   port with that name in the search order.  However, this port identifier is
-  not guaranteed to correspond to the desired port.  The port identifier is
-  used with other dual-ported memory related directives to access the port.
+  not guaranteed to correspond to the desired port.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+  
+  The port identifier is used with other dual-ported memory related directives
+  to access the port.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/message/if/ident.yml b/spec/rtems/message/if/ident.yml
index 3680adc3..1c57744b 100644
--- a/spec/rtems/message/if/ident.yml
+++ b/spec/rtems/message/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a message queue object by the specified object name.
+  Identifies a message queue by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,7 +15,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the message queue identifier associated with the
+  This directive obtains a message queue identifier associated with the
   message queue name specified in ${.:/params[0]/name}.
 
   The node to search is specified in ${.:/params[1]/name}.  It shall be
@@ -37,28 +37,37 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_message_queue_ident
 notes: |
   If the message queue name is not unique, then the message queue identifier
   will match the first message queue with that name in the search order.
   However, this message queue identifier is not guaranteed to correspond to the
-  desired message queue.  The message queue identifier is used with other
-  message related directives to access the message queue.
+  desired message queue.
 
-  If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with
-  the local node being searched first.  All other nodes are searched with the
-  lowest numbered node searched first.
+  The objects are searched from lowest to the highest index.  If
+  ${.:/params[1]/name} is ${../../object/if/search-all-nodes:/name}, all nodes
+  are searched with the local node being searched first.  All other nodes are
+  searched from lowest to the highest node number.
 
   If node is a valid node number which does not represent the local node, then
   only the message queues exported by the designated node are searched.
 
   This directive does not generate activity on remote nodes.  It accesses only
   the local copy of the global object table.
+
+  The message queue identifier is used with other message related directives to
+  access the message queue.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
-- description: is the node or node set to search for a matching object.
+- description: |
+    is the node or node set to search for a matching object.
   dir: null
   name: node
 - description: |
diff --git a/spec/rtems/part/if/ident.yml b/spec/rtems/part/if/ident.yml
index 9ac8d174..ca89d14d 100644
--- a/spec/rtems/part/if/ident.yml
+++ b/spec/rtems/part/if/ident.yml
@@ -39,28 +39,37 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_partition_ident
 notes: |
   If the partition name is not unique, then the partition identifier will match
   the first partition with that name in the search order.  However, this
   partition identifier is not guaranteed to correspond to the desired
-  partition.  The partition identifier is used with other partition related
-  directives to access the partition.
+  partition.
 
-  If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with
-  the local node being searched first.  All other nodes are searched with the
-  lowest numbered node searched first.
+  The objects are searched from lowest to the highest index.  If
+  ${.:/params[1]/name} is ${../../object/if/search-all-nodes:/name}, all nodes
+  are searched with the local node being searched first.  All other nodes are
+  searched from lowest to the highest node number.
 
   If node is a valid node number which does not represent the local node, then
   only the partitions exported by the designated node are searched.
 
   This directive does not generate activity on remote nodes.  It accesses only
   the local copy of the global object table.
+
+  The partition identifier is used with other partition related directives to
+  access the partition.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
-- description: is the node or node set to search for a matching object.
+- description: |
+    is the node or node set to search for a matching object.
   dir: null
   name: node
 - description: |
diff --git a/spec/rtems/ratemon/if/ident.yml b/spec/rtems/ratemon/if/ident.yml
index 5350f1bf..ae066fec 100644
--- a/spec/rtems/ratemon/if/ident.yml
+++ b/spec/rtems/ratemon/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a period object by the specified object name.
+  Identifies a period by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the period identifier associated with the period name
+  This directive obtains a period identifier associated with the period name
   specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
@@ -24,18 +24,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_rate_monotonic_ident
 notes: |
   If the period name is not unique, then the period identifier will match the
   first period with that name in the search order.  However, this period
-  identifier is not guaranteed to correspond to the desired period.  The period
-  identifier is used with other rate monotonic related directives to access the
-  period.
+  identifier is not guaranteed to correspond to the desired period.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+
+  The period identifier is used with other rate monotonic related directives to
+  access the period.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/region/if/ident.yml b/spec/rtems/region/if/ident.yml
index f67af7d2..4710f880 100644
--- a/spec/rtems/region/if/ident.yml
+++ b/spec/rtems/region/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a region object by the specified object name.
+  Identifies a region by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the region identifier associated with the region name
+  This directive obtains a region identifier associated with the region name
   specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
@@ -24,17 +24,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_region_ident
 notes: |
   If the region name is not unique, then the region identifier will match the
   first region with that name in the search order.  However, this region
-  identifier is not guaranteed to correspond to the desired region.  The region
-  identifier is used with other region related directives to access the region.
+  identifier is not guaranteed to correspond to the desired region.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+
+  The region identifier is used with other region related directives to access
+  the region.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/scheduler/if/ident.yml b/spec/rtems/scheduler/if/ident.yml
index f0816b18..520a7f86 100644
--- a/spec/rtems/scheduler/if/ident.yml
+++ b/spec/rtems/scheduler/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a scheduler instance by its name.
+  Identifies a scheduler by the object name.
 copyrights:
 - Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
@@ -12,7 +12,9 @@ definition:
     - ${../../type/if/id:/name} *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive obtains a scheduler identifier associated with the scheduler
+  name specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
 interface-type: function
@@ -21,11 +23,19 @@ links:
   uid: ../../task/if/header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_scheduler_ident
 notes: |
   The scheduler name is determined by the scheduler configuration.
+
+  The scheduler identifier is used with other scheduler related directives to
+  access the scheduler.
 params:
-- description: is the scheduler name.
+- description: |
+    is the scheduler name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/sem/if/ident.yml b/spec/rtems/sem/if/ident.yml
index 30466cae..5b223830 100644
--- a/spec/rtems/sem/if/ident.yml
+++ b/spec/rtems/sem/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a semaphore object by the specified object name.
+  Identifies a semaphore by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,7 +15,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the semaphore identifier associated with the semaphore
+  This directive obtains a semaphore identifier associated with the semaphore
   name specified in ${.:/params[0]/name}.
 
   The node to search is specified in ${.:/params[1]/name}.  It shall be
@@ -37,28 +37,37 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_semaphore_ident
 notes: |
   If the semaphore name is not unique, then the semaphore identifier will match
   the first semaphore with that name in the search order.  However, this
   semaphore identifier is not guaranteed to correspond to the desired
-  semaphore.  The semaphore identifier is used with other semaphore related
-  directives to access the semaphore.
+  semaphore.
 
-  If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with
-  the local node being searched first.  All other nodes are searched with the
-  lowest numbered node searched first.
+  The objects are searched from lowest to the highest index.  If
+  ${.:/params[1]/name} is ${../../object/if/search-all-nodes:/name}, all nodes
+  are searched with the local node being searched first.  All other nodes are
+  searched from lowest to the highest node number.
 
   If node is a valid node number which does not represent the local node, then
   only the semaphores exported by the designated node are searched.
 
   This directive does not generate activity on remote nodes.  It accesses only
   the local copy of the global object table.
+
+  The semaphore identifier is used with other semaphore related directives to
+  access the semaphore.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
-- description: is the node or node set to search for a matching object.
+- description: |
+    is the node or node set to search for a matching object.
   dir: null
   name: node
 - description: |
diff --git a/spec/rtems/task/if/ident.yml b/spec/rtems/task/if/ident.yml
index 12523dbc..bfdfb115 100644
--- a/spec/rtems/task/if/ident.yml
+++ b/spec/rtems/task/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies a task object by the specified object name.
+  Identifies a task by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,7 +15,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the task identifier associated with the task name
+  This directive obtains a task identifier associated with the task name
   specified in ${.:/params[0]/name}.
 
   A task may obtain its own identifier by specifying ${self-define:/name} for
@@ -40,27 +40,36 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_task_ident
 notes: |
   If the task name is not unique, then the task identifier will match the first
   task with that name in the search order.  However, this task identifier is
-  not guaranteed to correspond to the desired task.  The task identifier is
-  used with other task related directives to access the task.
+  not guaranteed to correspond to the desired task.
 
-  If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with
-  the local node being searched first.  All other nodes are searched with the
-  lowest numbered node searched first.
+  The objects are searched from lowest to the highest index.  If
+  ${.:/params[1]/name} is ${../../object/if/search-all-nodes:/name}, all nodes
+  are searched with the local node being searched first.  All other nodes are
+  searched from lowest to the highest node number.
 
   If node is a valid node number which does not represent the local node, then
   only the tasks exported by the designated node are searched.
 
   This directive does not generate activity on remote nodes.  It accesses only
   the local copy of the global object table.
+
+  The task identifier is used with other task related directives to access the
+  task.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
-- description: is the node or node set to search for a matching object.
+- description: |
+    is the node or node set to search for a matching object.
   dir: null
   name: node
 - description: |
diff --git a/spec/rtems/timer/if/ident.yml b/spec/rtems/timer/if/ident.yml
index 4218efa1..c99b4981 100644
--- a/spec/rtems/timer/if/ident.yml
+++ b/spec/rtems/timer/if/ident.yml
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the timer identifier associated with the timer name
+  This directive obtains a timer identifier associated with the timer name
   specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries:
@@ -25,17 +25,24 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_timer_ident
 notes: |
   If the timer name is not unique, then the timer identifier will match the
   first timer with that name in the search order.  However, this timer
-  identifier is not guaranteed to correspond to the desired timer.  The timer
-  identifier is used with other timer related directives to access the timer.
+  identifier is not guaranteed to correspond to the desired timer.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+
+  The timer identifier is used with other timer related directives to access
+  the timer.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |
diff --git a/spec/rtems/userext/if/ident.yml b/spec/rtems/userext/if/ident.yml
index 731dfbfd..162e565d 100644
--- a/spec/rtems/userext/if/ident.yml
+++ b/spec/rtems/userext/if/ident.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Identifies an extension set object by the specified object name.
+  Identifies an extension set by the object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,7 +14,7 @@ definition:
     return: ${../../status/if/code:/name}
   variants: []
 description: |
-  This directive obtains the extension set identifier associated with the
+  This directive obtains an extension set identifier associated with the
   extension set name specified in ${.:/params[0]/name}.
 enabled-by: true
 index-entries: []
@@ -24,18 +24,25 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_extension_ident
 notes: |
   If the extension set name is not unique, then the extension set identifier
   will match the first extension set with that name in the search order.
   However, this extension set identifier is not guaranteed to correspond to the
-  desired extension set.  The extension set identifier is used with other
-  extension related directives to access the extension set.
+  desired extension set.
 
   The objects are searched from lowest to the highest index.  Only the local
   node is searched.
+
+  The extension set identifier is used with other extension related directives
+  to access the extension set.
 params:
-- description: is the object name to look up.
+- description: |
+    is the object name to look up.
   dir: null
   name: name
 - description: |