[PATCH] c-user: Generate Object Services documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Nov 24 12:43:54 UTC 2020
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
+ 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
More information about the devel
mailing list