From 95e2f933cb59f8ff5da34a006daae28c82af40c2 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 2 Feb 2021 14:42:21 +0100 Subject: 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(-) (limited to 'c-user') 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 -- cgit v1.2.3