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.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
