From 90a688d9fdf3d9a6723281aed090859661682388 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 20 Nov 2020 14:45:05 +0100 Subject: spec: Review object services API --- config.yml | 3 ++ spec/rtems/object/if/api-class-information.yml | 27 +++++++++------- spec/rtems/object/if/api-maximum-class.yml | 17 +++++++--- spec/rtems/object/if/api-minimum-class.yml | 19 +++++++---- spec/rtems/object/if/build-id.yml | 23 +++++++++---- spec/rtems/object/if/build-name.yml | 34 ++++++++++++------- spec/rtems/object/if/get-api-class-name.yml | 26 +++++++++++---- spec/rtems/object/if/get-api-name.yml | 19 ++++++++--- spec/rtems/object/if/get-class-information.yml | 28 ++++++++++++---- spec/rtems/object/if/get-classic-name.yml | 33 +++++++++++++++---- spec/rtems/object/if/get-local-node.yml | 9 ++++-- spec/rtems/object/if/get-name.yml | 44 +++++++++++++++++++------ spec/rtems/object/if/group.yml | 34 +++++++++++++++++++ spec/rtems/object/if/header.yml | 3 +- spec/rtems/object/if/id-api-maximum-class.yml | 32 ------------------ spec/rtems/object/if/id-api-maximum.yml | 12 +++++-- spec/rtems/object/if/id-api-minimum.yml | 12 +++++-- spec/rtems/object/if/id-final-index.yml | 4 ++- spec/rtems/object/if/id-final.yml | 3 +- spec/rtems/object/if/id-get-api.yml | 17 +++++++--- spec/rtems/object/if/id-get-class.yml | 17 +++++++--- spec/rtems/object/if/id-get-index.yml | 17 +++++++--- spec/rtems/object/if/id-get-node.yml | 17 +++++++--- spec/rtems/object/if/id-initial-index.yml | 4 ++- spec/rtems/object/if/id-initial.yml | 20 ++++++++---- spec/rtems/object/if/search-all-nodes.yml | 4 ++- spec/rtems/object/if/search-local-node.yml | 4 ++- spec/rtems/object/if/search-other-nodes.yml | 4 ++- spec/rtems/object/if/set-name.yml | 45 ++++++++++++++++++++++---- spec/rtems/object/if/who-am-i.yml | 4 ++- 30 files changed, 385 insertions(+), 150 deletions(-) delete mode 100644 spec/rtems/object/if/id-api-maximum-class.yml diff --git a/config.yml b/config.yml index b9257dd6..77eb7be6 100644 --- a/config.yml +++ b/config.yml @@ -112,6 +112,9 @@ interface-documentation: - directives-target: modules/rtems-docs/c-user/partition/directives.rst group: /rtems/part/if/group introduction-target: modules/rtems-docs/c-user/partition/introduction.rst +- directives-target: modules/rtems-docs/c-user/object-services/directives.rst + group: /rtems/object/if/group + introduction-target: modules/rtems-docs/c-user/object-services/introduction.rst spec-verification: root-type: /spec/root spec-documentation: diff --git a/spec/rtems/object/if/api-class-information.yml b/spec/rtems/object/if/api-class-information.yml index ae969bd2..17da71e3 100644 --- a/spec/rtems/object/if/api-class-information.yml +++ b/spec/rtems/object/if/api-class-information.yml @@ -1,46 +1,51 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This structure is used to return information to the application about the + objects configured for a specific API/Class combination. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: - default: brief: | - This member is + This member contains the minimum valid object identifier for this class. definition: ${../../type/if/id:/name} ${.:name} - description: '%' + description: null kind: member name: minimum_id variants: [] - default: brief: | - This member is + This member contains the maximum valid object identifier for this class. definition: ${../../type/if/id:/name} ${.:name} - description: '%' + description: null kind: member name: maximum_id variants: [] - default: brief: | - This member is + This member contains the maximum number of active objects configured + for this class. definition: ${/c/if/uint32_t:/name} ${.:name} - description: '%' + description: null kind: member name: maximum variants: [] - default: brief: | - This member is + This member is true, if this class is configured for automatic object + extension, otherwise it is false. definition: ${/c/if/bool:/name} ${.:name} - description: '%' + description: null kind: member name: auto_extend variants: [] - default: brief: | - This member is + This member contains the number of currently inactive objects of this + class. definition: ${/c/if/uint32_t:/name} ${.:name} - description: '%' + description: null kind: member name: unallocated variants: [] diff --git a/spec/rtems/object/if/api-maximum-class.yml b/spec/rtems/object/if/api-maximum-class.yml index f583fdc7..ca8069f8 100644 --- a/spec/rtems/object/if/api-maximum-class.yml +++ b/spec/rtems/object/if/api-maximum-class.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the highest valid class value of the object API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -21,12 +22,18 @@ links: - role: interface-ingroup uid: group name: rtems_object_api_maximum_class -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the object API to get the highest valid class value. dir: null name: api return: - return: null - return-values: [] + return: | + Returns the highest valid class value of the object API. + return-values: + - description: | + The object API was invalid. + value: 0 type: interface diff --git a/spec/rtems/object/if/api-minimum-class.yml b/spec/rtems/object/if/api-minimum-class.yml index 66b67b30..1877cda2 100644 --- a/spec/rtems/object/if/api-minimum-class.yml +++ b/spec/rtems/object/if/api-minimum-class.yml @@ -1,8 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the lowest valid class value of the object API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +- Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) definition: default: attributes: null @@ -21,12 +22,18 @@ links: - role: interface-ingroup uid: group name: rtems_object_api_minimum_class -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the object API to get the lowest valid class value. dir: null name: api return: - return: null - return-values: [] + return: | + Returns the lowest valid class value of the object API. + return-values: + - description: | + The object API was invalid. + value: -1 type: interface diff --git a/spec/rtems/object/if/build-id.yml b/spec/rtems/object/if/build-id.yml index daff0341..0b65c5a3 100644 --- a/spec/rtems/object/if/build-id.yml +++ b/spec/rtems/object/if/build-id.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Builds the object identifier from the API, class, MPCI node, and index + components. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -17,21 +19,28 @@ links: - role: interface-ingroup uid: group name: rtems_build_id -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the API of the object identifier to build. dir: null name: _api -- description: '%' +- description: | + is the class of the object identifier to build. dir: null name: _class -- description: '%' +- description: | + is the MPCI node of the object identifier to build. dir: null name: _node -- description: '%' +- description: | + is the index of the object identifier to build. dir: null name: _index return: - return: null + return: | + Returns the object identifier built from the API, class, MPCI node, and + index components. return-values: [] type: interface diff --git a/spec/rtems/object/if/build-name.yml b/spec/rtems/object/if/build-name.yml index 2fb730c5..7a28b24a 100644 --- a/spec/rtems/object/if/build-name.yml +++ b/spec/rtems/object/if/build-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Builds the object name composed of the four characters. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -7,7 +8,10 @@ definition: default: | ${/score/object/if/build-name:/name}( ${.:/params[0]/name}, ${.:/params[1]/name}, ${.:/params[2]/name}, ${.:/params[3]/name} ) variants: [] -description: null +description: | + This directive takes the four characters provided as arguments and composes a + 32-bit object name with ``${.:params[0]/name}`` in the most significant + 8-bits and ``${.:params[3]/name}`` in the least significant 8-bits. enabled-by: true index-entries: [] interface-type: macro @@ -17,21 +21,27 @@ links: - role: interface-ingroup uid: group name: rtems_build_name -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the first character of the name. dir: null - name: _C1 -- description: '%' + name: _c1 +- description: | + is the second character of the name. dir: null - name: _C2 -- description: '%' + name: _c2 +- description: | + is the third character of the name. dir: null - name: _C3 -- description: '%' + name: _c3 +- description: | + is the fourth character of the name. dir: null - name: _C4 + name: _c4 return: - return: null + return: | + Returns the object name composed of the four characters. return-values: [] type: interface diff --git a/spec/rtems/object/if/get-api-class-name.yml b/spec/rtems/object/if/get-api-class-name.yml index 68115299..25dfdda2 100644 --- a/spec/rtems/object/if/get-api-class-name.yml +++ b/spec/rtems/object/if/get-api-class-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets a descriptive name of the object class of the object API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -22,15 +23,28 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_api_class_name -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + The string returned is from constant space. Do not modify or free it. params: -- description: '%' +- description: | + is the object API of the object class. dir: null name: the_api -- description: '%' +- description: | + is the object class of the object API to get the name. dir: null name: the_class return: - return: null - return-values: [] + return: | + Returns a descriptive name of the class of the API, if the class of the API + and the API were valid. + return-values: + - description: | + The API was invalid. + value: '"BAD API"' + - description: | + The class of the API was invalid. + value: '"BAD CLASS"' type: interface diff --git a/spec/rtems/object/if/get-api-name.yml b/spec/rtems/object/if/get-api-name.yml index c3725c62..88c0cf84 100644 --- a/spec/rtems/object/if/get-api-name.yml +++ b/spec/rtems/object/if/get-api-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets a descriptive name of the object API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -21,12 +22,20 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_api_name -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + The string returned is from constant space. Do not modify or free it. params: -- description: '%' +- description: | + is the object API to get the name. dir: null name: api return: - return: null - return-values: [] + return: | + Returns a descriptive name of the API, if the API was valid. + return-values: + - description: | + The API was invalid. + value: '"BAD API"' type: interface diff --git a/spec/rtems/object/if/get-class-information.yml b/spec/rtems/object/if/get-class-information.yml index ae81ab33..8467e96b 100644 --- a/spec/rtems/object/if/get-class-information.yml +++ b/spec/rtems/object/if/get-class-information.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the object class information of the object class of the object API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -23,18 +24,33 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_class_information -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the object API of the object class. dir: null name: the_api -- description: '%' +- description: | + is the object class of the object API to get the class information. dir: null name: the_class -- description: '%' +- description: | + is the pointer to an object class information variable. The object class + information of the class of the API will be stored in this variable, in + case of a successful operation. dir: null name: info return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The class of the API or the API was invalid. + value: ${../../status/if/invalid-number:/name} type: interface diff --git a/spec/rtems/object/if/get-classic-name.yml b/spec/rtems/object/if/get-classic-name.yml index ba72c20a..67fef062 100644 --- a/spec/rtems/object/if/get-classic-name.yml +++ b/spec/rtems/object/if/get-classic-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the object name associated with the object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -22,15 +23,35 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_classic_name -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the object identifier to get the name. dir: null name: id -- description: '%' - dir: null +- description: | + is the pointer to an object name variable. The object name associated with + the object identifier will be stored in this variable, in case of a + successful operation. + dir: out name: name return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no object information available for the object identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + The object name associated with the object identifier was a string. + value: ${../../status/if/invalid-id:/name} + - description: | + There was no object associated with the object identifier. + value: ${../../status/if/invalid-id:/name} type: interface diff --git a/spec/rtems/object/if/get-local-node.yml b/spec/rtems/object/if/get-local-node.yml index 8b32e3d2..b738c7e2 100644 --- a/spec/rtems/object/if/get-local-node.yml +++ b/spec/rtems/object/if/get-local-node.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the local MPCI node number. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) @@ -21,9 +22,11 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_local_node -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: [] return: - return: null + return: | + Returns the local MPCI node number. return-values: [] type: interface diff --git a/spec/rtems/object/if/get-name.yml b/spec/rtems/object/if/get-name.yml index 024227bb..de9592bc 100644 --- a/spec/rtems/object/if/get-name.yml +++ b/spec/rtems/object/if/get-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the object name associated with the object identifier as a string. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -13,7 +14,13 @@ definition: - char *${.:/params[2]/name} return: char * variants: [] -description: null +description: | + The object name is stored in the name buffer. If the name buffer length is + greater than zero, then the stored object name will be ``NUL`` terminated. + The stored object name may be truncated to fit the length. There is no + indication if a truncation occurred. Every attempt is made to return name as + a printable string even if the object has the Classic API 32-bit integer + style name. enabled-by: true index-entries: [] interface-type: function @@ -23,18 +30,37 @@ links: - role: interface-ingroup uid: group name: rtems_object_get_name -notes: null +notes: + This directive may cause the calling task to be preempted due to an obtain + and release of the object allocator mutex. params: -- description: '%' +- description: | + is the object identifier to get the name. dir: null name: id -- description: '%' +- description: | + is the buffer length in bytes. dir: null name: length -- description: '%' - dir: null +- description: | + is the pointer to a buffer of the specified length. + dir: out name: name return: - return: null - return-values: [] + return: | + Returns the ``${.:/params[2]/name}`` parameter value, if there is an object + name associated with the object identifier. + return-values: + - description: | + The ${.:/params[1]/name} parameter was 0. + value: ${/c/if/null:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${/c/if/null:/name} + - description: | + There was no object information available for the object identifier. + value: ${/c/if/null:/name} + - description: | + There was no object associated with the object identifier. + value: ${/c/if/null:/name} type: interface diff --git a/spec/rtems/object/if/group.yml b/spec/rtems/object/if/group.yml index aa235400..7ee11c06 100644 --- a/spec/rtems/object/if/group.yml +++ b/spec/rtems/object/if/group.yml @@ -17,6 +17,40 @@ links: uid: header - role: interface-ingroup uid: ../../if/group +- role: placement-order + uid: build-id +- role: placement-order + uid: build-name +- role: placement-order + uid: get-classic-name +- role: placement-order + uid: get-name +- role: placement-order + uid: set-name +- role: placement-order + uid: id-get-api +- role: placement-order + uid: id-get-class +- role: placement-order + uid: id-get-node +- role: placement-order + uid: id-get-index +- role: placement-order + uid: id-api-minimum +- role: placement-order + uid: id-api-maximum +- role: placement-order + uid: api-minimum-class +- role: placement-order + uid: api-maximum-class +- role: placement-order + uid: get-api-name +- role: placement-order + uid: get-api-class-name +- role: placement-order + uid: get-class-information +- role: placement-order + uid: get-local-node name: Object Services text: | The Classic API shall provide an interface to the Object Services. diff --git a/spec/rtems/object/if/header.yml b/spec/rtems/object/if/header.yml index 6bc71569..aa759dfa 100644 --- a/spec/rtems/object/if/header.yml +++ b/spec/rtems/object/if/header.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: This header file defines the Object Manager API. +brief: | + This header file provides the Object Services API. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) enabled-by: true diff --git a/spec/rtems/object/if/id-api-maximum-class.yml b/spec/rtems/object/if/id-api-maximum-class.yml deleted file mode 100644 index 5519118c..00000000 --- a/spec/rtems/object/if/id-api-maximum-class.yml +++ /dev/null @@ -1,32 +0,0 @@ -SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' -copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -definition: - default: - attributes: null - body: null - params: - - int ${.:/params[0]/name} - return: int - variants: [] -description: null -enabled-by: true -index-entries: [] -interface-type: function -links: -- role: interface-placement - uid: header -- role: interface-ingroup - uid: group -name: rtems_object_id_api_maximum_class -notes: null -params: -- description: '%' - dir: null - name: api -return: - return: null - return-values: [] -type: interface diff --git a/spec/rtems/object/if/id-api-maximum.yml b/spec/rtems/object/if/id-api-maximum.yml index 45c8238c..f09c0bf5 100644 --- a/spec/rtems/object/if/id-api-maximum.yml +++ b/spec/rtems/object/if/id-api-maximum.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the highest valid value for the API component of an object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,9 +17,14 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_api_maximum -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + A body is also provided. params: [] return: - return: null + return: | + Returns the highest valid value for the API component of an object + identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-api-minimum.yml b/spec/rtems/object/if/id-api-minimum.yml index cc4f8840..7d989469 100644 --- a/spec/rtems/object/if/id-api-minimum.yml +++ b/spec/rtems/object/if/id-api-minimum.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the lowest valid value for the API component of an object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,9 +17,14 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_api_minimum -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + A body is also provided. params: [] return: - return: null + return: | + Returns the lowest valid value for the API component of an object + identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-final-index.yml b/spec/rtems/object/if/id-final-index.yml index aa9c1cc0..15963a16 100644 --- a/spec/rtems/object/if/id-final-index.yml +++ b/spec/rtems/object/if/id-final-index.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant represents the highest value for the index component of an + object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/id-final.yml b/spec/rtems/object/if/id-final.yml index b771c33c..8229256d 100644 --- a/spec/rtems/object/if/id-final.yml +++ b/spec/rtems/object/if/id-final.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant represents the highest object identifier value. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/id-get-api.yml b/spec/rtems/object/if/id-get-api.yml index 75f68fb2..6c545803 100644 --- a/spec/rtems/object/if/id-get-api.yml +++ b/spec/rtems/object/if/id-get-api.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the API component of the object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,12 +17,20 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_get_api -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + This directive does not validate the object identifier provided in + ``${.:/params[0]/name}``. + + A body is also provided. params: -- description: '%' +- description: | + is the object identifier with the API component to get. dir: null name: _id return: - return: null + return: | + Returns the API component of the object identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-get-class.yml b/spec/rtems/object/if/id-get-class.yml index ab3fae2a..3b091ac8 100644 --- a/spec/rtems/object/if/id-get-class.yml +++ b/spec/rtems/object/if/id-get-class.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the class component of the object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,12 +17,20 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_get_class -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + This directive does not validate the object identifier provided in + ``${.:/params[0]/name}``. + + A body is also provided. params: -- description: '%' +- description: | + is the object identifier with the class component to get. dir: null name: _id return: - return: null + return: | + Returns the class component of the object identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-get-index.yml b/spec/rtems/object/if/id-get-index.yml index 703c95ff..7de2d018 100644 --- a/spec/rtems/object/if/id-get-index.yml +++ b/spec/rtems/object/if/id-get-index.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the index component of the object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,12 +17,20 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_get_index -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + This directive does not validate the object identifier provided in + ``${.:/params[0]/name}``. + + A body is also provided. params: -- description: '%' +- description: | + is the object identifier with the index component to get. dir: null name: _id return: - return: null + return: | + Returns the index component of the object identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-get-node.yml b/spec/rtems/object/if/id-get-node.yml index d0c261e5..4cd0d318 100644 --- a/spec/rtems/object/if/id-get-node.yml +++ b/spec/rtems/object/if/id-get-node.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the MPCI node component of the object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -16,12 +17,20 @@ links: - role: interface-ingroup uid: group name: rtems_object_id_get_node -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. + + This directive does not validate the object identifier provided in + ``${.:/params[0]/name}``. + + A body is also provided. params: -- description: '%' +- description: | + is the object identifier with the MPCI node component to get. dir: null name: _id return: - return: null + return: | + Returns the MPCI node component of the object identifier. return-values: [] type: interface diff --git a/spec/rtems/object/if/id-initial-index.yml b/spec/rtems/object/if/id-initial-index.yml index e5df066d..5af3890a 100644 --- a/spec/rtems/object/if/id-initial-index.yml +++ b/spec/rtems/object/if/id-initial-index.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant represents the lowest value for the index component of an + object identifier. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/id-initial.yml b/spec/rtems/object/if/id-initial.yml index 4e4549fa..33185b12 100644 --- a/spec/rtems/object/if/id-initial.yml +++ b/spec/rtems/object/if/id-initial.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Builds the object identifier with the lowest index from the API, class, and + MPCI node components. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -17,18 +19,24 @@ links: - role: interface-ingroup uid: group name: RTEMS_OBJECT_ID_INITIAL -notes: null +notes: | + This directive is strictly local and does not impact task scheduling. params: -- description: '%' +- description: | + is the API of the object identifier to build. dir: null name: _api -- description: '%' +- description: | + is the class of the object identifier to build. dir: null name: _class -- description: '%' +- description: | + is the MPCI node of the object identifier to build. dir: null name: _node return: - return: null + return: | + Returns the object identifier with the lowest index built from the API, + class, and MPCI node components. return-values: [] type: interface diff --git a/spec/rtems/object/if/search-all-nodes.yml b/spec/rtems/object/if/search-all-nodes.yml index 5698d32d..abaa0bd7 100644 --- a/spec/rtems/object/if/search-all-nodes.yml +++ b/spec/rtems/object/if/search-all-nodes.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant indicates that an object name to identifier search should + search through all MPCI nodes of the system. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/search-local-node.yml b/spec/rtems/object/if/search-local-node.yml index dcdbe150..66725e35 100644 --- a/spec/rtems/object/if/search-local-node.yml +++ b/spec/rtems/object/if/search-local-node.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant indicates that an object name to identifier search should + search only the local MPCI node of the system. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/search-other-nodes.yml b/spec/rtems/object/if/search-other-nodes.yml index 2a47ad2e..1c11f759 100644 --- a/spec/rtems/object/if/search-other-nodes.yml +++ b/spec/rtems/object/if/search-other-nodes.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant indicates that an object name to identifier search should + search through all MPCI nodes of the system except the local node. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/object/if/set-name.yml b/spec/rtems/object/if/set-name.yml index 45583b7c..3c5c2a42 100644 --- a/spec/rtems/object/if/set-name.yml +++ b/spec/rtems/object/if/set-name.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sets the object name of the object associated with the object identifier. 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,8 @@ definition: - const char *${.:/params[1]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive will set the object name based upon the user string. enabled-by: true index-entries: [] interface-type: function @@ -22,15 +24,46 @@ links: - role: interface-ingroup uid: group name: rtems_object_set_name -notes: null +notes: | + This directive may cause the calling task to be preempted due to an obtain + and release of the object allocator mutex. + + This directive can be used to set the name of objects which do not have a + naming scheme per their API. + + If the object specified by ``${.:/params[0]/name}`` is of a class that has a + string name, this directive will free the existing name to the RTEMS Workspace + and allocate enough memory from the RTEMS Workspace to make a copy of the + string located at ``${.:/params[1]/name}``. + + If the object specified by ``${.:/params[0]/name}`` is of a class that has a + 32-bit integer style name, then the first four characters in + ``${.:/params[1]/name}`` will be used to construct the name. params: -- description: '%' +- description: | + is the object identifier of the object to set the name. dir: null name: id -- description: '%' +- description: | + is the object name to set. dir: null name: name return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[1]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no object information available for the object identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + There was no object associated with the object identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + There was no memory available to duplicate the name. + value: ${../../status/if/no-memory:/name} type: interface diff --git a/spec/rtems/object/if/who-am-i.yml b/spec/rtems/object/if/who-am-i.yml index 58115c14..0357229e 100644 --- a/spec/rtems/object/if/who-am-i.yml +++ b/spec/rtems/object/if/who-am-i.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant indicates that an object name to identifier search is being + asked for the identifier of the currently executing task. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -- cgit v1.2.3