c-user: Clarify object services

Add a "Constraints" paragraph to the documentation.  Use function
prototypes for the directives.

Update #3993.

2 files changed, 151 insertions, 55 deletions

diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst
index 75a0516..19d4d82 100644
--- a/c-user/object-services/directives.rst
+++ b/c-user/object-services/directives.rst
@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR)
 
 .. This file is part of the RTEMS quality process and was automatically
@@ -47,14 +47,19 @@ components.
 
 .. code-block:: c
 
-    #define rtems_build_id( api, class, node, index )
+    rtems_id rtems_build_id(
+      uint32_t api,
+      uint32_t the_class,
+      uint32_t node,
+      uint32_t index
+    );
 
 .. rubric:: PARAMETERS:
 
 ``api``
     This parameter is the API of the object identifier to build.
 
-``class``
+``the_class``
     This parameter is the class of the object identifier to build.
 
 ``node``
@@ -68,9 +73,15 @@ components.
 Returns the object identifier built from the API, class, MPCI node, and index
 components.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
 
-This directive is strictly local and does not impact task scheduling.
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/build-name
 
@@ -91,7 +102,7 @@ Builds the object name composed of the four characters.
 
 .. code-block:: c
 
-    #define rtems_build_name( c1, c2, c3, c4 )
+    rtems_name rtems_build_name( char c1, char c2, char c3, char c4 );
 
 .. rubric:: PARAMETERS:
 
@@ -117,9 +128,15 @@ least significant 8-bits.
 
 Returns the object name composed of the four characters.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
 
-This directive is strictly local and does not impact task scheduling.
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/get-classic-name
 
@@ -173,9 +190,13 @@ Gets the object name associated with the object identifier.
 :c:macro:`RTEMS_INVALID_ID`
     There was no object associated with the object identifier.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
 
-This directive is strictly local and does not impact task scheduling.
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/get-name
 
@@ -235,10 +256,13 @@ string even if the object has the Classic API 32-bit integer style name.
 Returns the ``name`` parameter value, if there is an object name associated
 with the object identifier.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
 
-This directive may cause the calling task to be preempted due to an obtain and
-release of the object allocator mutex.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/set-name
 
@@ -293,9 +317,6 @@ This directive will set the object name based upon the user string.
 
 .. rubric:: 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.
 
@@ -308,6 +329,17 @@ If the object specified by ``id`` is of a class that has a 32-bit integer style
 name, then the first four characters in ``name`` will be used to construct the
 name.
 
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex.  This may
+  cause the calling task to be preempted.
+
 .. Generated from spec:/rtems/object/if/id-get-api
 
 .. raw:: latex
@@ -327,7 +359,7 @@ Gets the API component of the object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_get_api( id )
+    int rtems_object_id_get_api( rtems_id id );
 
 .. rubric:: PARAMETERS:
 
@@ -340,11 +372,17 @@ Returns the API component of the object identifier.
 
 .. rubric:: NOTES:
 
-This directive is strictly local and does not impact task scheduling.
-
 This directive does not validate the object identifier provided in ``id``.
 
-A body is also provided.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-get-class
 
@@ -365,7 +403,7 @@ Gets the class component of the object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_get_class( id )
+    int rtems_object_id_get_class( rtems_id id );
 
 .. rubric:: PARAMETERS:
 
@@ -378,11 +416,17 @@ Returns the class component of the object identifier.
 
 .. rubric:: NOTES:
 
-This directive is strictly local and does not impact task scheduling.
-
 This directive does not validate the object identifier provided in ``id``.
 
-A body is also provided.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-get-node
 
@@ -403,7 +447,7 @@ Gets the MPCI node component of the object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_get_node( id )
+    int rtems_object_id_get_node( rtems_id id );
 
 .. rubric:: PARAMETERS:
 
@@ -417,11 +461,17 @@ Returns the MPCI node component of the object identifier.
 
 .. rubric:: NOTES:
 
-This directive is strictly local and does not impact task scheduling.
-
 This directive does not validate the object identifier provided in ``id``.
 
-A body is also provided.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-get-index
 
@@ -442,7 +492,7 @@ Gets the index component of the object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_get_index( id )
+    int rtems_object_id_get_index( rtems_id id );
 
 .. rubric:: PARAMETERS:
 
@@ -455,11 +505,17 @@ Returns the index component of the object identifier.
 
 .. rubric:: NOTES:
 
-This directive is strictly local and does not impact task scheduling.
-
 This directive does not validate the object identifier provided in ``id``.
 
-A body is also provided.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-api-minimum
 
@@ -480,17 +536,21 @@ Gets the lowest valid value for the API component of an object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_api_minimum()
+    int rtems_object_id_api_minimum( void );
 
 .. rubric:: RETURN VALUES:
 
 Returns the lowest valid value for the API component of an object identifier.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
 
-This directive is strictly local and does not impact task scheduling.
+The following constraints apply to this directive:
 
-A body is also provided.
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-api-maximum
 
@@ -511,17 +571,21 @@ Gets the highest valid value for the API component of an object identifier.
 
 .. code-block:: c
 
-    #define rtems_object_id_api_maximum()
+    int rtems_object_id_api_maximum( void );
 
 .. rubric:: RETURN VALUES:
 
 Returns the highest valid value for the API component of an object identifier.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
 
-This directive is strictly local and does not impact task scheduling.
+The following constraints apply to this directive:
 
-A body is also provided.
+* The directive is implemented by a macro and may be called from within C/C++
+  constant expressions.  In addition, a function implementation of the
+  directive exists for bindings to other programming languages.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/api-minimum-class
 
@@ -556,9 +620,13 @@ Gets the lowest valid class value of the object API.
 
 Returns the lowest valid class value of the object API.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
 
-This directive is strictly local and does not impact task scheduling.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/api-maximum-class
 
@@ -593,9 +661,13 @@ Gets the highest valid class value of the object API.
 
 Returns the highest valid class value of the object API.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
 
-This directive is strictly local and does not impact task scheduling.
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/get-api-name
 
@@ -632,10 +704,16 @@ Returns a descriptive name of the API, if the API was valid.
 
 .. rubric:: 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.
 
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
 .. Generated from spec:/rtems/object/if/get-api-class-name
 
 .. raw:: latex
@@ -678,10 +756,16 @@ the API were valid.
 
 .. rubric:: 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.
 
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
 .. Generated from spec:/rtems/object/if/get-class-information
 
 .. raw:: latex
@@ -733,9 +817,13 @@ Gets the object class information of the object class of the object API.
 :c:macro:`RTEMS_INVALID_NUMBER`
     The class of the API or the API was invalid.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
 
-This directive is strictly local and does not impact task scheduling.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/get-local-node
 
@@ -762,9 +850,13 @@ Gets the local MPCI node number.
 
 Returns the local MPCI node number.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
 
-This directive is strictly local and does not impact task scheduling.
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
 
 .. Generated from spec:/rtems/object/if/id-initial
 
@@ -804,6 +896,10 @@ MPCI node components.
 Returns the object identifier with the lowest index built from the API, class,
 and MPCI node components.
 
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
 
-This directive is strictly local and does not impact task scheduling.
+* The directive will not cause the calling task to be preempted.
diff --git a/c-user/object-services/introduction.rst b/c-user/object-services/introduction.rst
index 6d02c9a..d5a33a4 100644
--- a/c-user/object-services/introduction.rst
+++ b/c-user/object-services/introduction.rst
@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR)
 
 .. This file is part of the RTEMS quality process and was automatically