From 2c0696f4a09ab730c2caea9ac1b82813fe27fcfb Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 2 Feb 2021 09:05:58 +0100 Subject: spec: Clarify object identification --- spec/rtems/barrier/if/ident.yml | 18 ++++++++++++------ spec/rtems/dpmem/if/ident.yml | 17 ++++++++++++----- spec/rtems/message/if/ident.yml | 27 ++++++++++++++++++--------- spec/rtems/part/if/ident.yml | 23 ++++++++++++++++------- spec/rtems/ratemon/if/ident.yml | 18 ++++++++++++------ spec/rtems/region/if/ident.yml | 17 ++++++++++++----- spec/rtems/scheduler/if/ident.yml | 16 +++++++++++++--- spec/rtems/sem/if/ident.yml | 27 ++++++++++++++++++--------- spec/rtems/task/if/ident.yml | 27 ++++++++++++++++++--------- spec/rtems/timer/if/ident.yml | 15 +++++++++++---- spec/rtems/userext/if/ident.yml | 17 ++++++++++++----- 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: | -- cgit v1.2.3