[PATCH] c-user: Generate Object Services documentation
Gedare Bloom
gedare at rtems.org
Wed Nov 25 17:45:40 UTC 2020
The problem with reading my email top-to-bottom... Sometimes I miss
context. (The problem of reading bottom-to-top, sometimes I miss context.)
I see this patch fixes up the rtems_object_id_api_maximum.
Since this API was never functional, I suppose it is acceptable to drop it
directly. Does a note need to be added anywhere (obsolete API)? I lean
toward no, because it is a vacuous proof problem. The API never existed
outside of Joel's head ;)
I usually like to see the generated documentation for review.
On Tue, Nov 24, 2020 at 5:44 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:
> The documentation is a consolidation of the comments in Doxygen markup
> and the documentation sources in Sphinx markup. The documentation was
> transfered to interface specification items. This header file was
> generated from the items by a script.
>
> Update #3993.
> ---
> c-user/object-services/directives.rst | 978 ++++++++++++++----------
> c-user/object-services/introduction.rst | 93 ++-
> 2 files changed, 643 insertions(+), 428 deletions(-)
>
> diff --git a/c-user/object-services/directives.rst
> b/c-user/object-services/directives.rst
> index 87f0f5a..c760559 100644
> --- a/c-user/object-services/directives.rst
> +++ b/c-user/object-services/directives.rst
> @@ -1,643 +1,805 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation
> (OAR)
> +.. Copyright (C) 2020 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
> +.. generated. If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. _ObjectServicesDirectives:
>
> Directives
> ==========
>
> +This section details the directives of the Object Services. A subsection
> is
> +dedicated to each of this manager's directives and lists the calling
> sequence,
> +parameters, description, return values, and notes of the directive.
> +
> +.. Generated from spec:/rtems/object/if/build-id
> +
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_build_id()
> +
> +.. _InterfaceRtemsBuildId:
> +
> +rtems_build_id()
> +----------------
> +
> +Builds the object identifier from the API, class, MPCI node, and index
> +components.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + #define rtems_build_id( _api, _class, _node, _index )
>
> -.. index:: build object name
> -.. index:: rtems_build_name
> +.. rubric:: PARAMETERS:
>
> -.. _rtems_build_name:
> +``_api``
> + This parameter is the API of the object identifier to build.
>
> -BUILD_NAME - Build object name from characters
> -----------------------------------------------
> +``_class``
> + This parameter is the class of the object identifier to build.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +``_node``
> + This parameter is the MPCI node of the object identifier to build.
>
> - rtems_name rtems_build_name(
> - uint8_t c1,
> - uint8_t c2,
> - uint8_t c3,
> - uint8_t c4
> - );
> +``_index``
> + This parameter is the index of the object identifier to build.
>
> -DIRECTIVE STATUS CODES:
> - Returns a name constructed from the four characters.
> +.. rubric:: RETURN VALUES:
>
> -DESCRIPTION:
> - This service takes the four characters provided as arguments and
> constructs
> - a thirty-two bit object name with ``c1`` in the most significant byte
> and
> - ``c4`` in the least significant byte.
> +Returns the object identifier built from the API, class, MPCI node, and
> index
> +components.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: NOTES:
> +
> +This directive is strictly local and does not impact task scheduling.
> +
> +.. Generated from spec:/rtems/object/if/build-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> -.. index:: get name from id
> -.. index:: obtain name from id
> -.. index:: rtems_object_get_classic_name
> +.. index:: rtems_build_name()
>
> -.. _rtems_object_get_classic_name:
> +.. _InterfaceRtemsBuildName:
>
> -OBJECT_GET_CLASSIC_NAME - Lookup name from id
> ----------------------------------------------
> +rtems_build_name()
> +------------------
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +Builds the object name composed of the four characters.
>
> - rtems_status_code rtems_object_get_classic_name(
> - rtems_id id,
> - rtems_name *name
> - );
> +.. rubric:: CALLING SEQUENCE:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +.. code-block:: c
>
> - * - ``RTEMS_SUCCESSFUL``
> - - name looked up successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - invalid name pointer
> - * - ``RTEMS_INVALID_ID``
> - - invalid object id
> + #define rtems_build_name( _c1, _c2, _c3, _c4 )
>
> -DESCRIPTION:
> - This service looks up the name for the object ``id`` specified and, if
> - found, places the result in ``*name``.
> +.. rubric:: PARAMETERS:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +``_c1``
> + This parameter is the first character of the name.
>
> -.. raw:: latex
> +``_c2``
> + This parameter is the second character of the name.
>
> - \clearpage
> +``_c3``
> + This parameter is the third character of the name.
>
> -.. index:: get object name as string
> -.. index:: obtain object name as string
> -.. index:: rtems_object_get_name
> +``_c4``
> + This parameter is the fourth character of the name.
>
> -.. _rtems_object_get_name:
> +.. rubric:: DESCRIPTION:
>
> -OBJECT_GET_NAME - Obtain object name as string
> -----------------------------------------------
> +This directive takes the four characters provided as arguments and
> composes a
> +32-bit object name with ``_c1`` in the most significant 8-bits and
> ``_c4`` in
> +the least significant 8-bits.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: RETURN VALUES:
>
> - char* rtems_object_get_name(
> - rtems_id id,
> - size_t length,
> - char *name
> - );
> +Returns the object name composed of the four characters.
>
> -DIRECTIVE STATUS CODES:
> - Returns a pointer to the name if successful or ``NULL`` otherwise.
> +.. rubric:: NOTES:
>
> -DESCRIPTION:
> - This service looks up the name of the object specified by ``id`` and
> places
> - it in the memory pointed to by ``name``. Every attempt is made to
> return
> - name as a printable string even if the object has the Classic API
> - thirty-two bit style name.
> +This directive is strictly local and does not impact task scheduling.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. Generated from spec:/rtems/object/if/get-classic-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> -.. index:: set object name
> -.. index:: rtems_object_set_name
> +.. index:: rtems_object_get_classic_name()
>
> -.. _rtems_object_set_name:
> +.. _InterfaceRtemsObjectGetClassicName:
>
> -OBJECT_SET_NAME - Set object name
> ----------------------------------
> +rtems_object_get_classic_name()
> +-------------------------------
> +
> +Gets the object name associated with the object identifier.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_object_get_classic_name(
> + rtems_id id,
> + rtems_name *name
> + );
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: PARAMETERS:
>
> - rtems_status_code rtems_object_set_name(
> - rtems_id id,
> - const char *name
> - );
> +``id``
> + This parameter is the object identifier to get the name.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +``name``
> + This parameter is the pointer to an object name variable. The object
> name
> + associated with the object identifier will be stored in this
> variable, in
>
remove comma
> + case of a successful operation.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - name looked up successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - invalid name pointer
> - * - ``RTEMS_INVALID_ID``
> - - invalid object id
> +.. rubric:: RETURN VALUES:
>
> -DESCRIPTION:
> - This service sets the name of ``id`` to that specified by the string
> - located at ``name``.
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The name parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> - If the object specified by ``id`` is of a class that has a string
> name,
> - this method will free the existing name to the RTEMS Workspace and
> allocate
> - enough memory from the RTEMS Workspace to make a copy of the string
> located
> - at ``name``.
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no object information available for the object identifier.
>
> - If the object specified by ``id`` is of a class that has a thirty-two
> bit
> - integer style name, then the first four characters in ``*name`` will
> be
> - used to construct the name. name to the RTEMS Workspace and allocate
> - enough memory from the RTEMS Workspace to make a copy of the string
> +:c:macro:`RTEMS_INVALID_ID`
> + The object name associated with the object identifier was a string.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no object associated with the object identifier.
> +
> +.. rubric:: NOTES:
> +
> +This directive is strictly local and does not impact task scheduling.
> +
> +.. Generated from spec:/rtems/object/if/get-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_get_name()
> +
> +.. _InterfaceRtemsObjectGetName:
> +
> +rtems_object_get_name()
> +-----------------------
> +
> +Gets the object name associated with the object identifier as a string.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + char *rtems_object_get_name( rtems_id id, size_t length, char *name );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> + This parameter is the object identifier to get the name.
> +
> +``length``
> + This parameter is the buffer length in bytes.
> +
> +``name``
> + This parameter is the pointer to a buffer of the specified length.
> +
> +.. rubric:: DESCRIPTION:
>
> -.. index:: obtain API from id
> -.. index:: rtems_object_id_get_api
> +The object name is stored in the name buffer. If the name buffer length
> is
> +greater than zero, then the stored object name will be ``NUL``
> terminated. The
> +stored object name may be truncated to fit the length. There is no
> indication
> +if a truncation occurred. Every attempt is made to return name as a
> printable
> +string even if the object has the Classic API 32-bit integer style name.
>
> -.. _rtems_object_id_get_api:
> +.. rubric:: RETURN VALUES:
>
> -OBJECT_ID_GET_API - Obtain API from Id
> ---------------------------------------
> +`NULL <https://en.cppreference.com/w/c/types/NULL>`_
> + The length parameter was 0.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +`NULL <https://en.cppreference.com/w/c/types/NULL>`_
> + The name parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> - int rtems_object_id_get_api(
> - rtems_id id
> - );
> +`NULL <https://en.cppreference.com/w/c/types/NULL>`_
> + There was no object information available for the object identifier.
>
> -DIRECTIVE STATUS CODES:
> - Returns the API portion of the object Id.
> +`NULL <https://en.cppreference.com/w/c/types/NULL>`_
> + There was no object associated with the object identifier.
>
> -DESCRIPTION:
> - This directive returns the API portion of the provided object ``id``.
> +Returns the ``name`` parameter value, if there is an object name
> associated
> +with the object identifier.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: NOTES:
>
> - This directive does NOT validate the ``id`` provided.
> +This directive may cause the calling task to be preempted due to an
> obtain and
> +release of the object allocator mutex.
> +
> +.. Generated from spec:/rtems/object/if/set-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_set_name()
> +
> +.. _InterfaceRtemsObjectSetName:
> +
> +rtems_object_set_name()
> +-----------------------
> +
> +Sets the object name of the object associated with the object identifier.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_object_set_name( rtems_id id, const char
> *name );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> + This parameter is the object identifier of the object to set the name.
> +
> +``name``
> + This parameter is the object name to set.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive will set the object name based upon the user string.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The name parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -.. index:: obtain class from object id
> -.. index:: rtems_object_id_get_class
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no object information available for the object identifier.
>
> -.. _rtems_object_id_get_class:
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no object associated with the object identifier.
>
> -OBJECT_ID_GET_CLASS - Obtain Class from Id
> -------------------------------------------
> +:c:macro:`RTEMS_NO_MEMORY`
> + There was no memory available to duplicate the name.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: NOTES:
>
> - uint32_t rtems_object_id_get_class(
> - rtems_id id
> - );
> +This directive may cause the calling task to be preempted due to an
> obtain and
> +release of the object allocator mutex.
>
> -DIRECTIVE STATUS CODES:
> - Returns the class portion of the object Id.
> +This directive can be used to set the name of objects which do not have a
> +naming scheme per their API.
>
> -DESCRIPTION:
> - This directive returns the class portion of the provided object
> ``id``.
> +If the object specified by ``id`` is of a class that has a string name,
> this
> +directive will free the existing name to the RTEMS Workspace and allocate
> +enough memory from the RTEMS Workspace to make a copy of the string
> located at
> +``name``.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +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.
>
> - This directive does NOT validate the ``id`` provided.
> +.. Generated from spec:/rtems/object/if/id-get-api
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> -.. index:: obtain node from object id
> -.. index:: rtems_object_id_get_node
> +.. index:: rtems_object_id_get_api()
>
> -.. _rtems_object_id_get_node:
> +.. _InterfaceRtemsObjectIdGetApi:
>
> -OBJECT_ID_GET_NODE - Obtain Node from Id
> -----------------------------------------
> +rtems_object_id_get_api()
> +-------------------------
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +Gets the API component of the object identifier.
>
> - uint32_t rtems_object_id_get_node(
> - rtems_id id
> - );
> +.. rubric:: CALLING SEQUENCE:
>
> -DIRECTIVE STATUS CODES:
> - Returns the node portion of the object Id.
> +.. code-block:: c
>
> -DESCRIPTION:
> - This directive returns the node portion of the provided object ``id``.
> + #define rtems_object_id_get_api( _id )
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: PARAMETERS:
>
> - This directive does NOT validate the ``id`` provided.
> +``_id``
> + This parameter is the object identifier with the API component to get.
> +
> +.. rubric:: RETURN VALUES:
> +
> +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.
>
I don't understand this comment?
> +
> +.. Generated from spec:/rtems/object/if/id-get-class
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_id_get_class()
>
> -.. index:: obtain index from object id
> -.. index:: rtems_object_id_get_index
> +.. _InterfaceRtemsObjectIdGetClass:
>
> -.. _rtems_object_id_get_index:
> +rtems_object_id_get_class()
> +---------------------------
>
> -OBJECT_ID_GET_INDEX - Obtain Index from Id
> -------------------------------------------
> +Gets the class component of the object identifier.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: CALLING SEQUENCE:
>
> - uint16_t rtems_object_id_get_index(
> - rtems_id id
> - );
> +.. code-block:: c
>
> -DIRECTIVE STATUS CODES:
> - Returns the index portion of the object Id.
> + #define rtems_object_id_get_class( _id )
>
> -DESCRIPTION:
> - This directive returns the index portion of the provided object
> ``id``.
> +.. rubric:: PARAMETERS:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +``_id``
> + This parameter is the object identifier with the class component to
> get.
>
> - This directive does NOT validate the ``id`` provided.
> +.. rubric:: RETURN VALUES:
> +
> +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.
> +
> +.. Generated from spec:/rtems/object/if/id-get-node
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_id_get_node()
> +
> +.. _InterfaceRtemsObjectIdGetNode:
>
> -.. index:: build object id from components
> -.. index:: rtems_build_id
> +rtems_object_id_get_node()
> +--------------------------
>
> -.. _rtems_build_id:
> +Gets the MPCI node component of the object identifier.
>
> -BUILD_ID - Build Object Id From Components
> -------------------------------------------
> +.. rubric:: CALLING SEQUENCE:
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. code-block:: c
>
> - rtems_id rtems_build_id(
> - int the_api,
> - int the_class,
> - int the_node,
> - int the_index
> - );
> + #define rtems_object_id_get_node( _id )
>
> -DIRECTIVE STATUS CODES:
> - Returns an object Id constructed from the provided arguments.
> +.. rubric:: PARAMETERS:
>
> -DESCRIPTION:
> - This service constructs an object Id from the provided ``the_api``,
> - ``the_class``, ``the_node``, and ``the_index``.
> +``_id``
> + This parameter is the object identifier with the MPCI node component
> to
> + get.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: RETURN VALUES:
>
> - This directive does NOT validate the arguments provided or the Object
> id
> - returned.
> +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.
> +
> +.. Generated from spec:/rtems/object/if/id-get-index
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_id_get_index()
> +
> +.. _InterfaceRtemsObjectIdGetIndex:
> +
> +rtems_object_id_get_index()
> +---------------------------
>
> -.. index:: obtain minimum API value
> -.. index:: rtems_object_id_api_minimum
> +Gets the index component of the object identifier.
>
> -.. _rtems_object_id_api_minimum:
> +.. rubric:: CALLING SEQUENCE:
>
> -OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
> -------------------------------------------------
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> + #define rtems_object_id_get_index( _id )
>
> - int rtems_object_id_api_minimum(void);
> +.. rubric:: PARAMETERS:
>
> -DIRECTIVE STATUS CODES:
> - Returns the minimum valid for the API portion of an object Id.
> +``_id``
> + This parameter is the object identifier with the index component to
> get.
>
> -DESCRIPTION:
> - This service returns the minimum valid for the API portion of an
> object Id.
> +.. rubric:: RETURN VALUES:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +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.
> +
> +.. Generated from spec:/rtems/object/if/id-api-minimum
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_id_api_minimum()
> +
> +.. _InterfaceRtemsObjectIdApiMinimum:
> +
> +rtems_object_id_api_minimum()
> +-----------------------------
>
> -.. index:: obtain maximum API value
> -.. index:: rtems_object_id_api_maximum
> +Gets the lowest valid value for the API component of an object identifier.
>
> -.. _rtems_object_id_api_maximum:
> +.. rubric:: CALLING SEQUENCE:
>
> -OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
> -------------------------------------------------
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> + #define rtems_object_id_api_minimum()
>
> - int rtems_object_id_api_maximum(void);
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> - Returns the maximum valid for the API portion of an object Id.
> +Returns the lowest valid value for the API component of an object
> identifier.
>
> -DESCRIPTION:
> - This service returns the maximum valid for the API portion of an
> object Id.
> +.. rubric:: NOTES:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +This directive is strictly local and does not impact task scheduling.
> +
> +A body is also provided.
> +
> +.. Generated from spec:/rtems/object/if/id-api-maximum
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_id_api_maximum()
> +
> +.. _InterfaceRtemsObjectIdApiMaximum:
>
> -.. index:: obtain minimum class value
> -.. index:: rtems_object_api_minimum_class
> +rtems_object_id_api_maximum()
> +-----------------------------
>
> -.. _rtems_object_api_minimum_class:
> +Gets the highest valid value for the API component of an object
> identifier.
>
> -OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
> ------------------------------------------------------
> +.. rubric:: CALLING SEQUENCE:
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. code-block:: c
>
> - int rtems_object_api_minimum_class(
> - int api
> - );
> + #define rtems_object_id_api_maximum()
>
> -DIRECTIVE STATUS CODES:
> - If ``api`` is not valid, -1 is returned.
> +.. rubric:: RETURN VALUES:
>
> - If successful, this service returns the minimum valid for the class
> portion
> - of an object Id for the specified ``api``.
> +Returns the highest valid value for the API component of an object
> identifier.
>
> -DESCRIPTION:
> - This service returns the minimum valid for the class portion of an
> object
> - Id for the specified ``api``.
> +.. rubric:: NOTES:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +This directive is strictly local and does not impact task scheduling.
> +
> +A body is also provided.
> +
> +.. Generated from spec:/rtems/object/if/api-minimum-class
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_api_minimum_class()
> +
> +.. _InterfaceRtemsObjectApiMinimumClass:
>
> -.. index:: obtain maximum class value
> -.. index:: rtems_object_api_maximum_class
> +rtems_object_api_minimum_class()
> +--------------------------------
>
> -.. _rtems_object_api_maximum_class:
> +Gets the lowest valid class value of the object API.
>
> -OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
> ------------------------------------------------------
> +.. rubric:: CALLING SEQUENCE:
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. code-block:: c
>
> - int rtems_object_api_maximum_class(
> - int api
> - );
> + int rtems_object_api_minimum_class( int api );
>
> -DIRECTIVE STATUS CODES:
> - If ``api`` is not valid, -1 is returned.
> +.. rubric:: PARAMETERS:
>
> - If successful, this service returns the maximum valid for the class
> portion
> - of an object Id for the specified ``api``.
> +``api``
> + This parameter is the object API to get the lowest valid class value.
>
> -DESCRIPTION:
> - This service returns the maximum valid for the class portion of an
> object
> - Id for the specified ``api``.
> +.. rubric:: RETURN VALUES:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +``-1``
> + The object API was invalid.
>
nit: "is" invalid
> +
> +Returns the lowest valid class value of the object API.
> +
> +.. rubric:: NOTES:
> +
> +This directive is strictly local and does not impact task scheduling.
> +
> +.. Generated from spec:/rtems/object/if/api-maximum-class
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_api_maximum_class()
> +
> +.. _InterfaceRtemsObjectApiMaximumClass:
> +
> +rtems_object_api_maximum_class()
> +--------------------------------
> +
> +Gets the highest valid class value of the object API.
>
> -.. index:: obtain minimum class value for an API
> -.. index:: rtems_object_id_api_minimum_class
> +.. rubric:: CALLING SEQUENCE:
>
> -.. _rtems_object_id_api_minimum_class:
> +.. code-block:: c
>
> -OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API
> --------------------------------------------------------------------
> + int rtems_object_api_maximum_class( int api );
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: PARAMETERS:
>
> - int rtems_object_get_id_api_minimum_class(
> - int api
> - );
> +``api``
> + This parameter is the object API to get the highest valid class value.
>
> -DIRECTIVE STATUS CODES:
> - If ``api`` is not valid, -1 is returned.
> +.. rubric:: RETURN VALUES:
>
> - If successful, this service returns the index corresponding to the
> first
> - object class of the specified ``api``.
> +``0``
> + The object API was invalid.
>
nit: "is" invalid
>
> -DESCRIPTION:
> - This service returns the index for the first object class associated
> with
> - the specified ``api``.
> +Returns the highest valid class value of the object API.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: NOTES:
> +
> +This directive is strictly local and does not impact task scheduling.
> +
> +.. Generated from spec:/rtems/object/if/get-api-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_get_api_name()
> +
> +.. _InterfaceRtemsObjectGetApiName:
> +
> +rtems_object_get_api_name()
> +---------------------------
> +
> +Gets a descriptive name of the object API.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -.. index:: obtain maximum class value for an API
> -.. index:: rtems_object_id_api_maximum_class
> + const char *rtems_object_get_api_name( int api );
>
> -.. _rtems_object_id_api_maximum_class:
> +.. rubric:: PARAMETERS:
>
> -OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API
> --------------------------------------------------------------------
> +``api``
> + This parameter is the object API to get the name.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: RETURN VALUES:
>
> - int rtems_object_get_api_maximum_class(
> - int api
> - );
> +"BAD API"
> + The API was invalid.
>
> -DIRECTIVE STATUS CODES:
> - If ``api`` is not valid, -1 is returned.
> +Returns a descriptive name of the API, if the API was valid.
>
> - If successful, this service returns the index corresponding to the
> last
> - object class of the specified ``api``.
> +.. rubric:: NOTES:
>
> -DESCRIPTION:
> - This service returns the index for the last object class associated
> with
> - the specified ``api``.
> +This directive is strictly local and does not impact task scheduling.
>
> -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.
> +
> +.. Generated from spec:/rtems/object/if/get-api-class-name
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_get_api_class_name()
> +
> +.. _InterfaceRtemsObjectGetApiClassName:
> +
> +rtems_object_get_api_class_name()
> +---------------------------------
> +
> +Gets a descriptive name of the object class of the object API.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -.. index:: obtain API name
> -.. index:: rtems_object_get_api_name
> + const char *rtems_object_get_api_class_name( int the_api, int
> the_class );
>
> -.. _rtems_object_get_api_name:
> +.. rubric:: PARAMETERS:
>
> -OBJECT_GET_API_NAME - Obtain API Name
> --------------------------------------
> +``the_api``
> + This parameter is the object API of the object class.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +``the_class``
> + This parameter is the object class of the object API to get the name.
>
> - const char* rtems_object_get_api_name(
> - int api
> - );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> - If ``api`` is not valid, the string ``"BAD API"`` is returned.
> +"BAD API"
> + The API was invalid.
>
> - If successful, this service returns a pointer to a string containing
> the
> - name of the specified ``api``.
> +"BAD CLASS"
> + The class of the API was invalid.
>
> -DESCRIPTION:
> - This service returns the name of the specified ``api``.
> +Returns a descriptive name of the class of the API, if the class of the
> API and
> +the API were valid.
>
"are" valid
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: NOTES:
>
> - The string returned is from constant space. Do not modify or free it.
> +This directive is strictly local and does not impact task scheduling.
> +
> +The string returned is from constant space. Do not modify or free it.
> +
> +.. Generated from spec:/rtems/object/if/get-class-information
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_object_get_class_information()
> +
> +.. _InterfaceRtemsObjectGetClassInformation:
> +
> +rtems_object_get_class_information()
> +------------------------------------
> +
> +Gets the object class information of the object class of the object API.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -.. index:: obtain class name
> -.. index:: rtems_object_get_api_class_name
> + rtems_status_code rtems_object_get_class_information(
> + int the_api,
> + int the_class,
> + rtems_object_api_class_information *info
> + );
>
> -.. _rtems_object_get_api_class_name:
> +.. rubric:: PARAMETERS:
>
> -OBJECT_GET_API_CLASS_NAME - Obtain Class Name
> ----------------------------------------------
> +``the_api``
> + This parameter is the object API of the object class.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +``the_class``
> + This parameter is the object class of the object API to get the class
> + information.
>
> - const char *rtems_object_get_api_class_name(
> - int the_api,
> - int the_class
> - );
> +``info``
> + This parameter is the pointer to an object class information
> variable. The
> + object class information of the class of the API will be stored in
> this
> + variable, in case of a successful operation.
>
> -DIRECTIVE STATUS CODES:
> - If ``the_api`` is not valid, the string ``"BAD API"`` is returned.
> +.. rubric:: RETURN VALUES:
>
> - If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned.
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> - If successful, this service returns a pointer to a string containing
> the
> - name of the specified ``the_api`` / ``the_class`` pair.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The info parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -DESCRIPTION:
> - This service returns the name of the object class indicated by the
> - specified ``the_api`` and ``the_class``.
> +:c:macro:`RTEMS_INVALID_NUMBER`
> + The class of the API or the API was invalid.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. rubric:: NOTES:
>
> - The string returned is from constant space. Do not modify or free it.
> +This directive is strictly local and does not impact task scheduling.
> +
> +.. Generated from spec:/rtems/object/if/get-local-node
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> -.. index:: obtain class information
> -.. index:: rtems_object_get_class_information
> +.. index:: rtems_object_get_local_node()
>
> -.. _rtems_object_get_class_information:
> +.. _InterfaceRtemsObjectGetLocalNode:
>
> -OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
> --------------------------------------------------------
> +rtems_object_get_local_node()
> +-----------------------------
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +Gets the local MPCI node number.
>
> - rtems_status_code rtems_object_get_class_information(
> - int the_api,
> - int the_class,
> - rtems_object_api_class_information *info
> - );
> +.. rubric:: CALLING SEQUENCE:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +.. code-block:: c
>
> - * - ``RTEMS_SUCCESSFUL``
> - - information obtained successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``info`` is NULL
> - * - ``RTEMS_INVALID_NUMBER``
> - - invalid ``api`` or ``the_class``
> + uint16_t rtems_object_get_local_node( void );
>
> - If successful, the structure located at ``info`` will be filled in
> with
> - information about the specified ``api`` / ``the_class`` pairing.
> +.. rubric:: RETURN VALUES:
>
> -DESCRIPTION:
> - This service returns information about the object class indicated by
> the
> - specified ``api`` and ``the_class``. This structure is defined as
> follows:
> +Returns the local MPCI node number.
>
> - .. code-block:: c
> +.. rubric:: NOTES:
>
> - typedef struct {
> - rtems_id minimum_id;
> - rtems_id maximum_id;
> - int maximum;
> - bool auto_extend;
> - int unallocated;
> - } rtems_object_api_class_information;
> +This directive is strictly local and does not impact task scheduling.
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +.. Generated from spec:/rtems/object/if/id-initial
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: RTEMS_OBJECT_ID_INITIAL()
> +
> +.. _InterfaceRTEMSOBJECTIDINITIAL:
> +
> +RTEMS_OBJECT_ID_INITIAL()
> +-------------------------
> +
> +Builds the object identifier with the lowest index from the API, class,
> and
> +MPCI node components.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + #define RTEMS_OBJECT_ID_INITIAL( _api, _class, _node )
>
> -.. index:: obtain local node
> -.. index:: rtems_object_get_local_node
> +.. rubric:: PARAMETERS:
>
> -.. _rtems_object_get_local_node:
> +``_api``
> + This parameter is the API of the object identifier to build.
>
> -OBJECT_GET_LOCAL_NODE - Obtain Local Node
> ------------------------------------------
> +``_class``
> + This parameter is the class of the object identifier to build.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +``_node``
> + This parameter is the MPCI node of the object identifier to build.
>
> - uint16_t rtems_object_get_local_node( void );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> - NONE
> +Returns the object identifier with the lowest index built from the API,
> class,
> +and MPCI node components.
>
> -DESCRIPTION:
> - This service returns the local MPCI node.
> +.. rubric:: NOTES:
>
> -NOTES:
> - This directive is strictly local and does not impact task scheduling.
> +This directive is strictly local and does not impact task scheduling.
> diff --git a/c-user/object-services/introduction.rst
> b/c-user/object-services/introduction.rst
> index 3c7ff18..6e7f4af 100644
> --- a/c-user/object-services/introduction.rst
> +++ b/c-user/object-services/introduction.rst
> @@ -1,47 +1,100 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation
> (OAR)
> +.. Copyright (C) 2020 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
> +.. generated. If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. Generated from spec:/rtems/object/if/group
> +
> +.. _ObjectServicesIntroduction:
>
> Introduction
> ============
>
> +.. The following list was generated from:
> +.. spec:/rtems/object/if/build-id
> +.. spec:/rtems/object/if/build-name
> +.. spec:/rtems/object/if/get-classic-name
> +.. spec:/rtems/object/if/get-name
> +.. spec:/rtems/object/if/set-name
> +.. spec:/rtems/object/if/id-get-api
> +.. spec:/rtems/object/if/id-get-class
> +.. spec:/rtems/object/if/id-get-node
> +.. spec:/rtems/object/if/id-get-index
> +.. spec:/rtems/object/if/id-api-minimum
> +.. spec:/rtems/object/if/id-api-maximum
> +.. spec:/rtems/object/if/api-minimum-class
> +.. spec:/rtems/object/if/api-maximum-class
> +.. spec:/rtems/object/if/get-api-name
> +.. spec:/rtems/object/if/get-api-class-name
> +.. spec:/rtems/object/if/get-class-information
> +.. spec:/rtems/object/if/get-local-node
> +.. spec:/rtems/object/if/id-initial
> +
> RTEMS provides a collection of services to assist in the management and
> usage
> of the objects created and utilized via other managers. These services
> assist
> in the manipulation of RTEMS objects independent of the API used to create
> -them. The object related services provided by RTEMS are:
> +them. The directives provided by the Object Services are:
>
> -- :ref:`rtems_build_id`
> +* :ref:`InterfaceRtemsBuildId` - Builds the object identifier from the
> API,
> + class, MPCI node, and index components.
>
> -- :ref:`rtems_build_name`
> +* :ref:`InterfaceRtemsBuildName` - Builds the object name composed of the
> four
> + characters.
>
> -- :ref:`rtems_object_get_classic_name`
> +* :ref:`InterfaceRtemsObjectGetClassicName` - Gets the object name
> associated
> + with the object identifier.
>
> -- :ref:`rtems_object_get_name`
> +* :ref:`InterfaceRtemsObjectGetName` - Gets the object name associated
> with the
> + object identifier as a string.
>
> -- :ref:`rtems_object_set_name`
> +* :ref:`InterfaceRtemsObjectSetName` - Sets the object name of the object
> + associated with the object identifier.
>
> -- :ref:`rtems_object_id_get_api`
> +* :ref:`InterfaceRtemsObjectIdGetApi` - Gets the API component of the
> object
> + identifier.
>
> -- :ref:`rtems_object_id_get_class`
> +* :ref:`InterfaceRtemsObjectIdGetClass` - Gets the class component of the
> + object identifier.
>
> -- :ref:`rtems_object_id_get_node`
> +* :ref:`InterfaceRtemsObjectIdGetNode` - Gets the MPCI node component of
> the
> + object identifier.
>
> -- :ref:`rtems_object_id_get_index`
> +* :ref:`InterfaceRtemsObjectIdGetIndex` - Gets the index component of the
> + object identifier.
>
> -- :ref:`rtems_build_id`
> +* :ref:`InterfaceRtemsObjectIdApiMinimum` - Gets the lowest valid value
> for the
> + API component of an object identifier.
>
> -- :ref:`rtems_object_id_api_minimum`
> +* :ref:`InterfaceRtemsObjectIdApiMaximum` - Gets the highest valid value
> for
> + the API component of an object identifier.
>
> -- :ref:`rtems_object_id_api_maximum`
> +* :ref:`InterfaceRtemsObjectApiMinimumClass` - Gets the lowest valid class
> + value of the object API.
>
> -- :ref:`rtems_object_id_api_minimum_class`
> +* :ref:`InterfaceRtemsObjectApiMaximumClass` - Gets the highest valid
> class
> + value of the object API.
>
> -- :ref:`rtems_object_id_api_maximum_class`
> +* :ref:`InterfaceRtemsObjectGetApiName` - Gets a descriptive name of the
> object
> + API.
>
> -- :ref:`rtems_object_get_api_name`
> +* :ref:`InterfaceRtemsObjectGetApiClassName` - Gets a descriptive name of
> the
> + object class of the object API.
>
> -- :ref:`rtems_object_get_api_class_name`
> +* :ref:`InterfaceRtemsObjectGetClassInformation` - Gets the object class
> + information of the object class of the object API.
>
> -- :ref:`rtems_object_get_class_information`
> +* :ref:`InterfaceRtemsObjectGetLocalNode` - Gets the local MPCI node
> number.
>
> -- :ref:`rtems_object_get_local_node`
> +* :ref:`InterfaceRTEMSOBJECTIDINITIAL` - Builds the object identifier
> with the
> + lowest index from the API, class, and MPCI node components.
> --
> 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/20201125/a457428f/attachment-0001.html>
More information about the devel
mailing list