[PATCH] c-user: Clarify object services
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Feb 2 13:44:10 UTC 2021
Add a "Constraints" paragraph to the documentation. Use function
prototypes for the directives.
Update #3993.
---
c-user/object-services/directives.rst | 97 +++++++++++++++++--------
c-user/object-services/introduction.rst | 2 +-
2 files changed, 66 insertions(+), 33 deletions(-)
diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst
index 75a0516..364c7ac 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,13 @@ components.
Returns the object identifier built from the API, class, MPCI node, and index
components.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
-This directive is strictly local and does not impact task scheduling.
+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.
.. Generated from spec:/rtems/object/if/build-name
@@ -91,7 +100,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 +126,13 @@ least significant 8-bits.
Returns the object name composed of the four characters.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
-This directive is strictly local and does not impact task scheduling.
+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.
.. Generated from spec:/rtems/object/if/get-classic-name
@@ -327,7 +340,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 +353,15 @@ 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.
.. Generated from spec:/rtems/object/if/id-get-class
@@ -365,7 +382,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 +395,15 @@ 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.
.. Generated from spec:/rtems/object/if/id-get-node
@@ -403,7 +424,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 +438,15 @@ 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.
.. Generated from spec:/rtems/object/if/id-get-index
@@ -442,7 +467,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 +480,15 @@ 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.
.. Generated from spec:/rtems/object/if/id-api-minimum
@@ -480,17 +509,19 @@ 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.
.. Generated from spec:/rtems/object/if/id-api-maximum
@@ -511,17 +542,19 @@ 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.
.. Generated from spec:/rtems/object/if/api-minimum-class
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
--
2.26.2
More information about the devel
mailing list