From 05f06aa7e70bc6d8bf303b56b5744b464bae5011 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 20 Nov 2020 14:22:44 +0100 Subject: c-user: Split up object services This makes it easier to automatically generate parts of the module documentation in the future. Update #3993. --- c-user/index.rst | 2 +- c-user/object-services/background.rst | 43 ++ c-user/object-services/directives.rst | 643 +++++++++++++++++++++++++ c-user/object-services/index.rst | 15 + c-user/object-services/introduction.rst | 47 ++ c-user/object-services/operations.rst | 86 ++++ c-user/object_services.rst | 815 -------------------------------- 7 files changed, 835 insertions(+), 816 deletions(-) create mode 100644 c-user/object-services/background.rst create mode 100644 c-user/object-services/directives.rst create mode 100644 c-user/object-services/index.rst create mode 100644 c-user/object-services/introduction.rst create mode 100644 c-user/object-services/operations.rst delete mode 100644 c-user/object_services.rst diff --git a/c-user/index.rst b/c-user/index.rst index 569b60f..2f8109a 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -54,7 +54,7 @@ RTEMS Classic API Guide (|version|). pci_library stack_bounds_checker cpu_usage_statistics - object_services + object-services/index chains red_black_trees timespec_helpers diff --git a/c-user/object-services/background.rst b/c-user/object-services/background.rst new file mode 100644 index 0000000..efa9e94 --- /dev/null +++ b/c-user/object-services/background.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +APIs +---- + +RTEMS implements multiple APIs including an Internal API, the Classic API, and +the POSIX API. These APIs share the common foundation of SuperCore objects and +thus share object management code. This includes a common scheme for object Ids +and for managing object names whether those names be in the thirty-two bit form +used by the Classic API or C strings. + +The object Id contains a field indicating the API that an object instance is +associated with. This field holds a numerically small non-zero integer. + +Object Classes +-------------- + +Each API consists of a collection of managers. Each manager is responsible for +instances of a particular object class. Classic API Tasks and POSIX Mutexes +example classes. + +The object Id contains a field indicating the class that an object instance is +associated with. This field holds a numerically small non-zero integer. In +all APIs, a class value of one is reserved for tasks or threads. + +Object Names +------------ + +Every RTEMS object which has an Id may also have a name associated with it. +Depending on the API, names may be either thirty-two bit integers as in the +Classic API or strings as in the POSIX API. + +Some objects have Ids but do not have a defined way to associate a name with +them. For example, POSIX threads have Ids but per POSIX do not have names. In +RTEMS, objects not defined to have thirty-two bit names may have string names +assigned to them via the ``rtems_object_set_name`` service. The original +impetus in providing this service was so the normally anonymous POSIX threads +could have a user defined name in CPU Usage Reports. 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. diff --git a/c-user/object-services/index.rst b/c-user/object-services/index.rst new file mode 100644 index 0000000..878e47b --- /dev/null +++ b/c-user/object-services/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: object manipulation + +Object Services +*************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/object-services/introduction.rst b/c-user/object-services/introduction.rst new file mode 100644 index 0000000..3c7ff18 --- /dev/null +++ b/c-user/object-services/introduction.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +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: + +- :ref:`rtems_build_id` + +- :ref:`rtems_build_name` + +- :ref:`rtems_object_get_classic_name` + +- :ref:`rtems_object_get_name` + +- :ref:`rtems_object_set_name` + +- :ref:`rtems_object_id_get_api` + +- :ref:`rtems_object_id_get_class` + +- :ref:`rtems_object_id_get_node` + +- :ref:`rtems_object_id_get_index` + +- :ref:`rtems_build_id` + +- :ref:`rtems_object_id_api_minimum` + +- :ref:`rtems_object_id_api_maximum` + +- :ref:`rtems_object_id_api_minimum_class` + +- :ref:`rtems_object_id_api_maximum_class` + +- :ref:`rtems_object_get_api_name` + +- :ref:`rtems_object_get_api_class_name` + +- :ref:`rtems_object_get_class_information` + +- :ref:`rtems_object_get_local_node` diff --git a/c-user/object-services/operations.rst b/c-user/object-services/operations.rst new file mode 100644 index 0000000..d900835 --- /dev/null +++ b/c-user/object-services/operations.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Decomposing and Recomposing an Object Id +---------------------------------------- + +Services are provided to decompose an object Id into its subordinate +components. The following services are used to do this: + +- ``rtems_object_id_get_api`` + +- ``rtems_object_id_get_class`` + +- ``rtems_object_id_get_node`` + +- ``rtems_object_id_get_index`` + +The following C language example illustrates the decomposition of an Id and +printing the values. + +.. code-block:: c + + void printObjectId(rtems_id id) + { + printf( + "API=%d Class=%" PRIu32 " Node=%" PRIu32 " Index=%" PRIu16 "\n", + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); + } + +This prints the components of the Ids as integers. + +It is also possible to construct an arbitrary Id using the ``rtems_build_id`` +service. The following C language example illustrates how to construct the +"next Id." + +.. code-block:: c + + rtems_id nextObjectId(rtems_id id) + { + return rtems_build_id( + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + 1 + ); + } + +Note that this Id may not be valid in this +system or associated with an allocated object. + +Printing an Object Id +--------------------- + +RTEMS also provides services to associate the API and Class portions of an +Object Id with strings. This allows the application developer to provide more +information about an object in diagnostic messages. + +In the following C language example, an Id is decomposed into its constituent +parts and "pretty-printed." + +.. code-block:: c + + void prettyPrintObjectId(rtems_id id) + { + int tmpAPI; + uint32_t tmpClass; + + tmpAPI = rtems_object_id_get_api(id), + tmpClass = rtems_object_id_get_class(id), + + printf( + "API=%s Class=%s Node=%" PRIu32 " Index=%" PRIu16 "\n", + rtems_object_get_api_name(tmpAPI), + rtems_object_get_api_class_name(tmpAPI, tmpClass), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); + } diff --git a/c-user/object_services.rst b/c-user/object_services.rst deleted file mode 100644 index 860ce8c..0000000 --- a/c-user/object_services.rst +++ /dev/null @@ -1,815 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: object manipulation - -Object Services -*************** - -Introduction -============ - -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: - -- build_id - -- rtems_build_name_ - build object name from characters - -- rtems_object_get_classic_name_ - lookup name from Id - -- rtems_object_get_name_ - obtain object name as string - -- rtems_object_set_name_ - set object name - -- rtems_object_id_get_api_ - obtain API from Id - -- rtems_object_id_get_class_ - obtain class from Id - -- rtems_object_id_get_node_ - obtain node from Id - -- rtems_object_id_get_index_ - obtain index from Id - -- rtems_build_id_ - build object id from components - -- rtems_object_id_api_minimum_ - obtain minimum API value - -- rtems_object_id_api_maximum_ - obtain maximum API value - -- rtems_object_id_api_minimum_class_ - obtain minimum class value - -- rtems_object_id_api_maximum_class_ - obtain maximum class value - -- rtems_object_get_api_name_ - obtain API name - -- rtems_object_get_api_class_name_ - obtain class name - -- rtems_object_get_class_information_ - obtain class information - -- rtems_object_get_local_node_ - obtain local node - -Background -========== - -APIs ----- - -RTEMS implements multiple APIs including an Internal API, the Classic API, and -the POSIX API. These APIs share the common foundation of SuperCore objects and -thus share object management code. This includes a common scheme for object Ids -and for managing object names whether those names be in the thirty-two bit form -used by the Classic API or C strings. - -The object Id contains a field indicating the API that an object instance is -associated with. This field holds a numerically small non-zero integer. - -Object Classes --------------- - -Each API consists of a collection of managers. Each manager is responsible for -instances of a particular object class. Classic API Tasks and POSIX Mutexes -example classes. - -The object Id contains a field indicating the class that an object instance is -associated with. This field holds a numerically small non-zero integer. In -all APIs, a class value of one is reserved for tasks or threads. - -Object Names ------------- - -Every RTEMS object which has an Id may also have a name associated with it. -Depending on the API, names may be either thirty-two bit integers as in the -Classic API or strings as in the POSIX API. - -Some objects have Ids but do not have a defined way to associate a name with -them. For example, POSIX threads have Ids but per POSIX do not have names. In -RTEMS, objects not defined to have thirty-two bit names may have string names -assigned to them via the ``rtems_object_set_name`` service. The original -impetus in providing this service was so the normally anonymous POSIX threads -could have a user defined name in CPU Usage Reports. - -Operations -========== - -Decomposing and Recomposing an Object Id ----------------------------------------- - -Services are provided to decompose an object Id into its subordinate -components. The following services are used to do this: - -- ``rtems_object_id_get_api`` - -- ``rtems_object_id_get_class`` - -- ``rtems_object_id_get_node`` - -- ``rtems_object_id_get_index`` - -The following C language example illustrates the decomposition of an Id and -printing the values. - -.. code-block:: c - - void printObjectId(rtems_id id) - { - printf( - "API=%d Class=%" PRIu32 " Node=%" PRIu32 " Index=%" PRIu16 "\n", - rtems_object_id_get_api(id), - rtems_object_id_get_class(id), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) - ); - } - -This prints the components of the Ids as integers. - -It is also possible to construct an arbitrary Id using the ``rtems_build_id`` -service. The following C language example illustrates how to construct the -"next Id." - -.. code-block:: c - - rtems_id nextObjectId(rtems_id id) - { - return rtems_build_id( - rtems_object_id_get_api(id), - rtems_object_id_get_class(id), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) + 1 - ); - } - -Note that this Id may not be valid in this -system or associated with an allocated object. - -Printing an Object Id ---------------------- - -RTEMS also provides services to associate the API and Class portions of an -Object Id with strings. This allows the application developer to provide more -information about an object in diagnostic messages. - -In the following C language example, an Id is decomposed into its constituent -parts and "pretty-printed." - -.. code-block:: c - - void prettyPrintObjectId(rtems_id id) - { - int tmpAPI; - uint32_t tmpClass; - - tmpAPI = rtems_object_id_get_api(id), - tmpClass = rtems_object_id_get_class(id), - - printf( - "API=%s Class=%s Node=%" PRIu32 " Index=%" PRIu16 "\n", - rtems_object_get_api_name(tmpAPI), - rtems_object_get_api_class_name(tmpAPI, tmpClass), - rtems_object_id_get_node(id), - rtems_object_id_get_index(id) - ); - } - -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. -- cgit v1.2.3