[rtems-docs commit] c-user: Clarify object services
Sebastian Huber
sebh at rtems.org
Wed Feb 3 05:20:12 UTC 2021
Module: rtems-docs
Branch: master
Commit: 95e2f933cb59f8ff5da34a006daae28c82af40c2
Changeset: http://git.rtems.org/rtems-docs/commit/?id=95e2f933cb59f8ff5da34a006daae28c82af40c2
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Feb 2 14:42:21 2021 +0100
c-user: Clarify object services
Add a "Constraints" paragraph to the documentation. Use function
prototypes for the directives.
Update #3993.
---
c-user/object-services/directives.rst | 204 +++++++++++++++++++++++---------
c-user/object-services/introduction.rst | 2 +-
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
More information about the vc
mailing list