[PATCH v2] c-user: Generate Object Services documentation

Gedare Bloom gedare at rtems.org
Wed Dec 2 17:16:28 UTC 2020


It looks ok to me. I still don't know what "A body is also provided." means
though.

On Wed, Dec 2, 2020 at 1:22 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.  The documentation source
> files were generated from the items by a script.
>
> Update #3993.
> ---
>
> The generated documentation is available here:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
> v2:
>
> Remove leading '_' from parameter names.
>
>  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..ce7a894 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
> +    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.
> +
> +.. 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.
> +
> +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.
>
> -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.
>
> -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/20201202/4d6339eb/attachment-0001.html>


More information about the devel mailing list