[PATCH] c-user: Clarify object services

Tue Feb 2 15:37:39 UTC 2021

On Tue, Feb 2, 2021 at 6:44 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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.
>

I may have missed the discussion, but this note is being removed without
being added elsewhere.

Is it implied that all functions are local and do not impact task
scheduling, unless otherwise constrained?

> +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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210202/c7fe94ba/attachment.html>