.. 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.