From 25461290ea1c0d339bcc89df4440cfdfb8897a07 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 24 Jun 2020 16:20:32 +0200 Subject: spec: Document name to id directives --- spec/if/rtems/barrier/ident.yml | 40 ++++++++++++++++++++----- spec/if/rtems/dpmem/ident.yml | 39 ++++++++++++++++++++----- spec/if/rtems/message/ident.yml | 64 +++++++++++++++++++++++++++++++++++----- spec/if/rtems/part/ident.yml | 64 +++++++++++++++++++++++++++++++++++----- spec/if/rtems/ratemon/ident.yml | 40 ++++++++++++++++++++----- spec/if/rtems/region/ident.yml | 39 ++++++++++++++++++++----- spec/if/rtems/sem/ident.yml | 64 +++++++++++++++++++++++++++++++++++----- spec/if/rtems/tasks/ident.yml | 65 +++++++++++++++++++++++++++++++++++------ spec/if/rtems/timer/ident.yml | 39 ++++++++++++++++++++----- spec/if/rtems/userext/ident.yml | 40 ++++++++++++++++++++----- 10 files changed, 419 insertions(+), 75 deletions(-) (limited to 'spec') diff --git a/spec/if/rtems/barrier/ident.yml b/spec/if/rtems/barrier/ident.yml index b761f199..60760c48 100644 --- a/spec/if/rtems/barrier/ident.yml +++ b/spec/if/rtems/barrier/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a barrier object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the barrier identifier associated with the barrier + name specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,38 @@ links: - role: interface-ingroup uid: /groups/api/classic/barrier name: rtems_barrier_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface diff --git a/spec/if/rtems/dpmem/ident.yml b/spec/if/rtems/dpmem/ident.yml index c65135ad..d2c61253 100644 --- a/spec/if/rtems/dpmem/ident.yml +++ b/spec/if/rtems/dpmem/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a port object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the port identifier associated with the port name + specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,37 @@ links: - role: interface-ingroup uid: /groups/api/classic/dpmem name: rtems_port_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface diff --git a/spec/if/rtems/message/ident.yml b/spec/if/rtems/message/ident.yml index 56c6d917..3fd6a4bc 100644 --- a/spec/if/rtems/message/ident.yml +++ b/spec/if/rtems/message/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a message queue object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,7 +13,21 @@ definition: - ${../types/id:/name} *${.:/params[2]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the 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 + + * a valid node number, + + * the constant ${../object/search-all-nodes:/name} to search in all nodes, + + * the constant ${../object/search-local-node:/name} to search in the local + node only, or + + * the constant ${../object/search-other-nodes:/name} to search in all nodes + except the local node. enabled-by: true interface-type: function links: @@ -21,18 +36,51 @@ links: - role: interface-ingroup uid: /groups/api/classic/message name: rtems_message_queue_ident -notes: null +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. + + If node is ${../object/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. + + 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. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' +- description: is the node or node set to search for a matching object. dir: null name: node -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the specified nodes. + value: ${../status/invalid-name:/name} + - description: | + In multiprocessing configurations, the specified node was invalid. + value: ${../status/invalid-node:/name} type: interface diff --git a/spec/if/rtems/part/ident.yml b/spec/if/rtems/part/ident.yml index 25f3db2d..676ca6d6 100644 --- a/spec/if/rtems/part/ident.yml +++ b/spec/if/rtems/part/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a partition object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,7 +13,21 @@ definition: - ${../types/id:/name} *${.:/params[2]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the partition identifier associated with the partition + name specified in ``${.:/params[0]/name}``. + + The node to search is specified in ``${.:/params[1]/name}``. It shall be + + * a valid node number, + + * the constant ${../object/search-all-nodes:/name} to search in all nodes, + + * the constant ${../object/search-local-node:/name} to search in the local + node only, or + + * the constant ${../object/search-other-nodes:/name} to search in all nodes + except the local node. enabled-by: true interface-type: function links: @@ -21,18 +36,51 @@ links: - role: interface-ingroup uid: /groups/api/classic/part name: rtems_partition_ident -notes: null +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. + + If node is ${../object/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. + + 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. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' +- description: is the node or node set to search for a matching object. dir: null name: node -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the specified nodes. + value: ${../status/invalid-name:/name} + - description: | + In multiprocessing configurations, the specified node was invalid. + value: ${../status/invalid-node:/name} type: interface diff --git a/spec/if/rtems/ratemon/ident.yml b/spec/if/rtems/ratemon/ident.yml index ce67b9f6..2564dc7a 100644 --- a/spec/if/rtems/ratemon/ident.yml +++ b/spec/if/rtems/ratemon/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a period object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the period identifier associated with the period name + specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,38 @@ links: - role: interface-ingroup uid: /groups/api/classic/ratemon name: rtems_rate_monotonic_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface diff --git a/spec/if/rtems/region/ident.yml b/spec/if/rtems/region/ident.yml index 40238e6b..ca0bf9b6 100644 --- a/spec/if/rtems/region/ident.yml +++ b/spec/if/rtems/region/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a region object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the region identifier associated with the region name + specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,37 @@ links: - role: interface-ingroup uid: /groups/api/classic/region name: rtems_region_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface diff --git a/spec/if/rtems/sem/ident.yml b/spec/if/rtems/sem/ident.yml index 5c17a399..30f5c37d 100644 --- a/spec/if/rtems/sem/ident.yml +++ b/spec/if/rtems/sem/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a semaphore object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,7 +13,21 @@ definition: - ${../types/id:/name} *${.:/params[2]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the 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 + + * a valid node number, + + * the constant ${../object/search-all-nodes:/name} to search in all nodes, + + * the constant ${../object/search-local-node:/name} to search in the local + node only, or + + * the constant ${../object/search-other-nodes:/name} to search in all nodes + except the local node. enabled-by: true interface-type: function links: @@ -21,18 +36,51 @@ links: - role: interface-ingroup uid: /groups/api/classic/sem name: rtems_semaphore_ident -notes: null +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. + + If node is ${../object/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. + + 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. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' +- description: is the node or node set to search for a matching object. dir: null name: node -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the specified nodes. + value: ${../status/invalid-name:/name} + - description: | + In multiprocessing configurations, the specified node was invalid. + value: ${../status/invalid-node:/name} type: interface diff --git a/spec/if/rtems/tasks/ident.yml b/spec/if/rtems/tasks/ident.yml index 9405b54e..f7f22743 100644 --- a/spec/if/rtems/tasks/ident.yml +++ b/spec/if/rtems/tasks/ident.yml @@ -1,8 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a task object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -- Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) +- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: body: null @@ -12,7 +13,24 @@ definition: - ${../types/id:/name} *${.:/params[2]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the 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 + the name. + + The node to search is specified in ``${.:/params[1]/name}``. It shall be + + * a valid node number, + + * the constant ${../object/search-all-nodes:/name} to search in all nodes, + + * the constant ${../object/search-local-node:/name} to search in the local + node only, or + + * the constant ${../object/search-other-nodes:/name} to search in all nodes + except the local node. enabled-by: true interface-type: function links: @@ -21,18 +39,47 @@ links: - role: interface-ingroup uid: /groups/api/classic/tasks name: rtems_task_ident -notes: null +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. + + If node is ${../object/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. + + 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. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' +- description: is the node or node set to search for a matching object. dir: null name: node -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + There was no object with the specified name on the specified nodes. + value: ${../status/invalid-name:/name} + - description: | + In multiprocessing configurations, the specified node was invalid. + value: ${../status/invalid-node:/name} type: interface diff --git a/spec/if/rtems/timer/ident.yml b/spec/if/rtems/timer/ident.yml index 9d70bee2..dca12696 100644 --- a/spec/if/rtems/timer/ident.yml +++ b/spec/if/rtems/timer/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies a timer object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the timer identifier associated with the timer name + specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,37 @@ links: - role: interface-ingroup uid: /groups/api/classic/timer name: rtems_timer_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface diff --git a/spec/if/rtems/userext/ident.yml b/spec/if/rtems/userext/ident.yml index b7184e92..016ccce2 100644 --- a/spec/if/rtems/userext/ident.yml +++ b/spec/if/rtems/userext/ident.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Identifies an extension set object by the specified object name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,9 @@ definition: - ${../types/id:/name} *${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive obtains the extension set identifier associated with the + extension set name specified in ``${.:/params[0]/name}``. enabled-by: true interface-type: function links: @@ -20,15 +23,38 @@ links: - role: interface-ingroup uid: /groups/api/classic/userext name: rtems_extension_ident -notes: null +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. + + The objects are searched from lowest to the highest index. Only the local + node is searched. params: -- description: '%' +- description: is the object name to look up. dir: null name: name -- description: '%' - dir: null +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/if/c/null:/name}. + value: ${../status/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../status/invalid-name:/name} + - description: | + There was no object with the specified name on the local node. + value: ${../status/invalid-name:/name} type: interface -- cgit v1.2.3