[rtems-central commit] spec: Review object services API
Sebastian Huber
sebh at rtems.org
Fri Nov 27 08:55:54 UTC 2020
Module: rtems-central
Branch: master
Commit: 90a688d9fdf3d9a6723281aed090859661682388
Changeset: http://git.rtems.org/rtems-central/commit/?id=90a688d9fdf3d9a6723281aed090859661682388
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Nov 20 14:45:05 2020 +0100
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(-)
diff --git a/config.yml b/config.yml
index b9257dd..77eb7be 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 ae969bd..17da71e 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 f583fdc..ca8069f 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 66b67b3..1877cda 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 daff034..0b65c5a 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 2fb730c..7a28b24 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 6811529..25dfdda 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 c3725c6..88c0cf8 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 ae81ab3..8467e96 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 ba72c20..67fef06 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 8b32e3d..b738c7e 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 024227b..de9592b 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 aa23540..7ee11c0 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 6bc7156..aa759df 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 5519118..0000000
--- 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 45c8238..f09c0bf 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 cc4f884..7d98946 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 aa9c1cc..15963a1 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 b771c33..8229256 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 75f68fb..6c54580 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 ab3fae2..3b091ac 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 703c95f..7de2d01 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 d0c261e..4cd0d31 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 e5df066..5af3890 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 4e4549f..33185b1 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 5698d32..abaa0bd 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 dcdbe15..66725e3 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 2a47ad2..1c11f75 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 45583b7..3c5c2a4 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 58115c1..0357229 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)
More information about the vc
mailing list