diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-11-20 14:22:44 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-11-20 14:25:59 +0100 |
commit | 05f06aa7e70bc6d8bf303b56b5744b464bae5011 (patch) | |
tree | 74c4924598b028bec960edfd56d6a22b93bbb364 /c-user/object-services | |
parent | user/bsps: Fix list in bsps-arm (diff) | |
download | rtems-docs-05f06aa7e70bc6d8bf303b56b5744b464bae5011.tar.bz2 |
c-user: Split up object services
This makes it easier to automatically generate parts of the module
documentation in the future.
Update #3993.
Diffstat (limited to 'c-user/object-services')
-rw-r--r-- | c-user/object-services/background.rst | 43 | ||||
-rw-r--r-- | c-user/object-services/directives.rst | 643 | ||||
-rw-r--r-- | c-user/object-services/index.rst | 15 | ||||
-rw-r--r-- | c-user/object-services/introduction.rst | 47 | ||||
-rw-r--r-- | c-user/object-services/operations.rst | 86 |
5 files changed, 834 insertions, 0 deletions
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) + ); + } |