c-user: Split up object services

This makes it easier to automatically generate parts of the module
documentation in the future.

Update #3993.

1 files changed, 643 insertions, 0 deletions

diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst
new file mode 100644
index 0000000..87f0f5a
--- /dev/null
+++ b/c-user/object-services/directives.rst
@@ -0,0 +1,643 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: build object name
+.. index:: rtems_build_name
+
+.. _rtems_build_name:
+
+BUILD_NAME - Build object name from characters
+----------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_name rtems_build_name(
+            uint8_t c1,
+            uint8_t c2,
+            uint8_t c3,
+            uint8_t c4
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns a name constructed from the four characters.
+
+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.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: get name from id
+.. index:: obtain name from id
+.. index:: rtems_object_get_classic_name
+
+.. _rtems_object_get_classic_name:
+
+OBJECT_GET_CLASSIC_NAME - Lookup name from id
+---------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_object_get_classic_name(
+            rtems_id      id,
+            rtems_name   *name
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - name looked up successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - invalid name pointer
+     * - ``RTEMS_INVALID_ID``
+       - invalid object id
+
+DESCRIPTION:
+    This service looks up the name for the object ``id`` specified and, if
+    found, places the result in ``*name``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: get object name as string
+.. index:: obtain object name as string
+.. index:: rtems_object_get_name
+
+.. _rtems_object_get_name:
+
+OBJECT_GET_NAME - Obtain object name as string
+----------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        char* rtems_object_get_name(
+            rtems_id       id,
+            size_t         length,
+            char          *name
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns a pointer to the name if successful or ``NULL`` otherwise.
+
+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.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: set object name
+.. index:: rtems_object_set_name
+
+.. _rtems_object_set_name:
+
+OBJECT_SET_NAME - Set object name
+---------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_object_set_name(
+            rtems_id       id,
+            const char    *name
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - name looked up successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - invalid name pointer
+     * - ``RTEMS_INVALID_ID``
+       - invalid object id
+
+DESCRIPTION:
+    This service sets the name of ``id`` to that specified by 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 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``.
+
+    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
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain API from id
+.. index:: rtems_object_id_get_api
+
+.. _rtems_object_id_get_api:
+
+OBJECT_ID_GET_API - Obtain API from Id
+--------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_id_get_api(
+            rtems_id id
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns the API portion of the object Id.
+
+DESCRIPTION:
+    This directive returns the API portion of the provided object ``id``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+    This directive does NOT validate the ``id`` provided.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain class from object id
+.. index:: rtems_object_id_get_class
+
+.. _rtems_object_id_get_class:
+
+OBJECT_ID_GET_CLASS - Obtain Class from Id
+------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_object_id_get_class(
+                 rtems_id id
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns the class portion of the object Id.
+
+DESCRIPTION:
+    This directive returns the class portion of the provided object ``id``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+    This directive does NOT validate the ``id`` provided.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain node from object id
+.. index:: rtems_object_id_get_node
+
+.. _rtems_object_id_get_node:
+
+OBJECT_ID_GET_NODE - Obtain Node from Id
+----------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_object_id_get_node(
+                 rtems_id id
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns the node portion of the object Id.
+
+DESCRIPTION:
+    This directive returns the node portion of the provided object ``id``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+    This directive does NOT validate the ``id`` provided.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain index from object id
+.. index:: rtems_object_id_get_index
+
+.. _rtems_object_id_get_index:
+
+OBJECT_ID_GET_INDEX - Obtain Index from Id
+------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint16_t rtems_object_id_get_index(
+                 rtems_id id
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns the index portion of the object Id.
+
+DESCRIPTION:
+    This directive returns the index portion of the provided object ``id``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+    This directive does NOT validate the ``id`` provided.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: build object id from components
+.. index:: rtems_build_id
+
+.. _rtems_build_id:
+
+BUILD_ID - Build Object Id From Components
+------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_id rtems_build_id(
+            int the_api,
+            int the_class,
+            int the_node,
+            int the_index
+        );
+
+DIRECTIVE STATUS CODES:
+    Returns an object Id constructed from the provided arguments.
+
+DESCRIPTION:
+    This service constructs an object Id from the provided ``the_api``,
+    ``the_class``, ``the_node``, and ``the_index``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+    This directive does NOT validate the arguments provided or the Object id
+    returned.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain minimum API value
+.. index:: rtems_object_id_api_minimum
+
+.. _rtems_object_id_api_minimum:
+
+OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
+------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_id_api_minimum(void);
+
+DIRECTIVE STATUS CODES:
+    Returns the minimum valid for the API portion of an object Id.
+
+DESCRIPTION:
+    This service returns the minimum valid for the API portion of an object Id.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain maximum API value
+.. index:: rtems_object_id_api_maximum
+
+.. _rtems_object_id_api_maximum:
+
+OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
+------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_id_api_maximum(void);
+
+DIRECTIVE STATUS CODES:
+    Returns the maximum valid for the API portion of an object Id.
+
+DESCRIPTION:
+    This service returns the maximum valid for the API portion of an object Id.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain minimum class value
+.. index:: rtems_object_api_minimum_class
+
+.. _rtems_object_api_minimum_class:
+
+OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
+-----------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_api_minimum_class(
+            int api
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``api`` is not valid, -1 is returned.
+
+    If successful, this service returns the minimum valid for the class portion
+    of an object Id for the specified ``api``.
+
+DESCRIPTION:
+    This service returns the minimum valid for the class portion of an object
+    Id for the specified ``api``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain maximum class value
+.. index:: rtems_object_api_maximum_class
+
+.. _rtems_object_api_maximum_class:
+
+OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
+-----------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_api_maximum_class(
+            int api
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``api`` is not valid, -1 is returned.
+
+    If successful, this service returns the maximum valid for the class portion
+    of an object Id for the specified ``api``.
+
+DESCRIPTION:
+    This service returns the maximum valid for the class portion of an object
+    Id for the specified ``api``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain minimum class value for an API
+.. index:: rtems_object_id_api_minimum_class
+
+.. _rtems_object_id_api_minimum_class:
+
+OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API
+-------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_get_id_api_minimum_class(
+            int api
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``api`` is not valid, -1 is returned.
+
+    If successful, this service returns the index corresponding to the first
+    object class of the specified ``api``.
+
+DESCRIPTION:
+    This service returns the index for the first object class associated with
+    the specified ``api``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain maximum class value for an API
+.. index:: rtems_object_id_api_maximum_class
+
+.. _rtems_object_id_api_maximum_class:
+
+OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API
+-------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_object_get_api_maximum_class(
+            int api
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``api`` is not valid, -1 is returned.
+
+    If successful, this service returns the index corresponding to the last
+    object class of the specified ``api``.
+
+DESCRIPTION:
+    This service returns the index for the last object class associated with
+    the specified ``api``.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain API name
+.. index:: rtems_object_get_api_name
+
+.. _rtems_object_get_api_name:
+
+OBJECT_GET_API_NAME - Obtain API Name
+-------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        const char* rtems_object_get_api_name(
+            int api
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``api`` is not valid, the string ``"BAD API"`` is returned.
+
+    If successful, this service returns a pointer to a string containing the
+    name of the specified ``api``.
+
+DESCRIPTION:
+    This service returns the name of the specified ``api``.
+
+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.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain class name
+.. index:: rtems_object_get_api_class_name
+
+.. _rtems_object_get_api_class_name:
+
+OBJECT_GET_API_CLASS_NAME - Obtain Class Name
+---------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        const char *rtems_object_get_api_class_name(
+            int the_api,
+            int the_class
+        );
+
+DIRECTIVE STATUS CODES:
+    If ``the_api`` is not valid, the string ``"BAD API"`` is returned.
+
+    If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned.
+
+    If successful, this service returns a pointer to a string containing the
+    name of the specified ``the_api`` / ``the_class`` pair.
+
+DESCRIPTION:
+    This service returns the name of the object class indicated by the
+    specified ``the_api`` and ``the_class``.
+
+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.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain class information
+.. index:: rtems_object_get_class_information
+
+.. _rtems_object_get_class_information:
+
+OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
+-------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_object_get_class_information(
+            int                                 the_api,
+            int                                 the_class,
+            rtems_object_api_class_information *info
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - information obtained successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``info`` is NULL
+     * - ``RTEMS_INVALID_NUMBER``
+       - invalid ``api`` or ``the_class``
+
+    If successful, the structure located at ``info`` will be filled in with
+    information about the specified ``api`` / ``the_class`` pairing.
+
+DESCRIPTION:
+    This service returns information about the object class indicated by the
+    specified ``api`` and ``the_class``. This structure is defined as follows:
+
+    .. code-block:: c
+
+        typedef struct {
+            rtems_id  minimum_id;
+            rtems_id  maximum_id;
+            int       maximum;
+            bool      auto_extend;
+            int       unallocated;
+        } rtems_object_api_class_information;
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: obtain local node
+.. index:: rtems_object_get_local_node
+
+.. _rtems_object_get_local_node:
+
+OBJECT_GET_LOCAL_NODE - Obtain Local Node
+-----------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint16_t rtems_object_get_local_node( void );
+
+DIRECTIVE STATUS CODES:
+    NONE
+
+DESCRIPTION:
+    This service returns the local MPCI node.
+
+NOTES:
+    This directive is strictly local and does not impact task scheduling.