diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-06-24 16:20:32 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-07-03 10:22:46 +0200 |
commit | 25461290ea1c0d339bcc89df4440cfdfb8897a07 (patch) | |
tree | 9207c5968ec9a89d27b9cf387157c7e9cbadf292 /spec/if/rtems/message | |
parent | d8603500df20e434623512eee086c31bfaf6e298 (diff) |
spec: Document name to id directives
Diffstat (limited to 'spec/if/rtems/message')
-rw-r--r-- | spec/if/rtems/message/ident.yml | 64 |
1 files changed, 56 insertions, 8 deletions
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 |