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