diff options
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 | 910 | ||||
| -rw-r--r-- | c-user/object-services/index.rst | 17 | ||||
| -rw-r--r-- | c-user/object-services/introduction.rst | 104 | ||||
| -rw-r--r-- | c-user/object-services/operations.rst | 86 |
5 files changed, 1160 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..c692168 --- /dev/null +++ b/c-user/object-services/directives.rst @@ -0,0 +1,910 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ObjectServicesDirectives: + +Directives +========== + +This section details the directives of the Object Services. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/object/if/build-id + +.. raw:: latex + + \clearpage + +.. index:: rtems_build_id() + +.. _InterfaceRtemsBuildId: + +rtems_build_id() +---------------- + +Builds the object identifier from the API, class, MPCI node, and index +components. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id rtems_build_id( + uint32_t api, + uint32_t the_class, + uint32_t node, + uint32_t index + ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the API of the object identifier to build. + +``the_class`` + This parameter is the class of the object identifier to build. + +``node`` + This parameter is the MPCI node of the object identifier to build. + +``index`` + This parameter is the index of the object identifier to build. + +.. rubric:: RETURN VALUES: + +Returns the object identifier built from the API, class, MPCI node, and index +components. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/build-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_build_name() + +.. _InterfaceRtemsBuildName: + +rtems_build_name() +------------------ + +Builds the object name composed of the four characters. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_name rtems_build_name( char c1, char c2, char c3, char c4 ); + +.. rubric:: PARAMETERS: + +``c1`` + This parameter is the first character of the name. + +``c2`` + This parameter is the second character of the name. + +``c3`` + This parameter is the third character of the name. + +``c4`` + This parameter is the fourth character of the name. + +.. rubric:: DESCRIPTION: + +This directive takes the four characters provided as arguments and composes a +32-bit object name with ``c1`` in the most significant 8-bits and ``c4`` in the +least significant 8-bits. + +.. rubric:: RETURN VALUES: + +Returns the object name composed of the four characters. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-classic-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_classic_name() + +.. _InterfaceRtemsObjectGetClassicName: + +rtems_object_get_classic_name() +------------------------------- + +Gets the object name associated with the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_object_get_classic_name( + rtems_id id, + rtems_name *name + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier to get the name. + +``name`` + This parameter is the pointer to an :ref:`InterfaceRtemsName` object. When + the directive call is successful, the object name associated with the + object identifier will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. + +:c:macro:`RTEMS_INVALID_ID` + The object name associated with the object identifier was a string. + +:c:macro:`RTEMS_INVALID_ID` + There was no object associated with the object identifier. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_name() + +.. _InterfaceRtemsObjectGetName: + +rtems_object_get_name() +----------------------- + +Gets the object name associated with the object identifier as a string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + char *rtems_object_get_name( rtems_id id, size_t length, char *name ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier to get the name. + +``length`` + This parameter is the buffer length in bytes. + +``name`` + This parameter is the pointer to a buffer of the specified length. + +.. rubric:: DESCRIPTION: + +The object name is stored in the name buffer. If the name buffer length is +greater than zero, then the stored object name will be ``NUL`` terminated. The +stored object name may be truncated to fit the length. There is no indication +if a truncation occurred. Every attempt is made to return name as a printable +string even if the object has the Classic API 32-bit integer style name. + +.. rubric:: RETURN VALUES: + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``length`` parameter was 0. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object information available for the object identifier. + +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object associated with the object identifier. + +Returns the ``name`` parameter value, if there is an object name associated +with the object identifier. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/set-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_set_name() + +.. _InterfaceRtemsObjectSetName: + +rtems_object_set_name() +----------------------- + +Sets the object name of the object associated with the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier of the object to set the name. + +``name`` + This parameter is the object name to set. + +.. rubric:: DESCRIPTION: + +This directive will set the object name based upon the user string. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. + +:c:macro:`RTEMS_INVALID_ID` + There was no object associated with the object identifier. + +:c:macro:`RTEMS_NO_MEMORY` + There was no memory available to duplicate the name. + +.. rubric:: NOTES: + +This directive can be used to set the name of objects which do not have a +naming scheme per their API. + +If the object specified by ``id`` is of a class that has a string name, this +directive 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 32-bit integer style +name, then the first four characters in ``name`` will be used to construct the +name. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-get-api + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_api() + +.. _InterfaceRtemsObjectIdGetApi: + +rtems_object_id_get_api() +------------------------- + +Gets the API component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_api( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the API component to get. + +.. rubric:: RETURN VALUES: + +Returns the API component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-get-class + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_class() + +.. _InterfaceRtemsObjectIdGetClass: + +rtems_object_id_get_class() +--------------------------- + +Gets the class component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_class( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the class component to get. + +.. rubric:: RETURN VALUES: + +Returns the class component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-get-node + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_node() + +.. _InterfaceRtemsObjectIdGetNode: + +rtems_object_id_get_node() +-------------------------- + +Gets the MPCI node component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_node( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the MPCI node component to + get. + +.. rubric:: RETURN VALUES: + +Returns the MPCI node component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-get-index + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_get_index() + +.. _InterfaceRtemsObjectIdGetIndex: + +rtems_object_id_get_index() +--------------------------- + +Gets the index component of the object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_get_index( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the object identifier with the index component to get. + +.. rubric:: RETURN VALUES: + +Returns the index component of the object identifier. + +.. rubric:: NOTES: + +This directive does not validate the object identifier provided in ``id``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-api-minimum + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_api_minimum() + +.. _InterfaceRtemsObjectIdApiMinimum: + +rtems_object_id_api_minimum() +----------------------------- + +Gets the lowest valid value for the API component of an object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_api_minimum( void ); + +.. rubric:: RETURN VALUES: + +Returns the lowest valid value for the API component of an object identifier. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-api-maximum + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_id_api_maximum() + +.. _InterfaceRtemsObjectIdApiMaximum: + +rtems_object_id_api_maximum() +----------------------------- + +Gets the highest valid value for the API component of an object identifier. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_id_api_maximum( void ); + +.. rubric:: RETURN VALUES: + +Returns the highest valid value for the API component of an object identifier. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/api-minimum-class + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_api_minimum_class() + +.. _InterfaceRtemsObjectApiMinimumClass: + +rtems_object_api_minimum_class() +-------------------------------- + +Gets the lowest valid class value of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_api_minimum_class( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the lowest valid class value. + +.. rubric:: RETURN VALUES: + +``-1`` + The object API was invalid. + +Returns the lowest valid class value of the object API. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/api-maximum-class + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_api_maximum_class() + +.. _InterfaceRtemsObjectApiMaximumClass: + +rtems_object_api_maximum_class() +-------------------------------- + +Gets the highest valid class value of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int rtems_object_api_maximum_class( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the highest valid class value. + +.. rubric:: RETURN VALUES: + +``0`` + The object API was invalid. + +Returns the highest valid class value of the object API. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-api-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_api_name() + +.. _InterfaceRtemsObjectGetApiName: + +rtems_object_get_api_name() +--------------------------- + +Gets a descriptive name of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_object_get_api_name( int api ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the object API to get the name. + +.. rubric:: RETURN VALUES: + +"BAD API" + The API was invalid. + +Returns a descriptive name of the API, if the API was valid. + +.. rubric:: NOTES: + +The string returned is from constant space. Do not modify or free it. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-api-class-name + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_api_class_name() + +.. _InterfaceRtemsObjectGetApiClassName: + +rtems_object_get_api_class_name() +--------------------------------- + +Gets a descriptive name of the object class of the object API. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_object_get_api_class_name( int the_api, int the_class ); + +.. rubric:: PARAMETERS: + +``the_api`` + This parameter is the object API of the object class. + +``the_class`` + This parameter is the object class of the object API to get the name. + +.. rubric:: RETURN VALUES: + +"BAD API" + The API was invalid. + +"BAD CLASS" + The class of the API was invalid. + +Returns a descriptive name of the class of the API, if the class of the API and +the API were valid. + +.. rubric:: NOTES: + +The string returned is from constant space. Do not modify or free it. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-class-information + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_class_information() + +.. _InterfaceRtemsObjectGetClassInformation: + +rtems_object_get_class_information() +------------------------------------ + +Gets the object class information of the object class of the object API. + +.. rubric:: 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 + ); + +.. rubric:: PARAMETERS: + +``the_api`` + This parameter is the object API of the object class. + +``the_class`` + This parameter is the object class of the object API to get the class + information. + +``info`` + This parameter is the pointer to an + :ref:`InterfaceRtemsObjectApiClassInformation` object. When the directive + call is successful, the object class information of the class of the API + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NUMBER` + The class of the API or the API was invalid. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/get-local-node + +.. raw:: latex + + \clearpage + +.. index:: rtems_object_get_local_node() + +.. _InterfaceRtemsObjectGetLocalNode: + +rtems_object_get_local_node() +----------------------------- + +Gets the local MPCI node number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint16_t rtems_object_get_local_node( void ); + +.. rubric:: RETURN VALUES: + +Returns the local MPCI node number. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/object/if/id-initial + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_OBJECT_ID_INITIAL() + +.. _InterfaceRTEMSOBJECTIDINITIAL: + +RTEMS_OBJECT_ID_INITIAL() +------------------------- + +Builds the object identifier with the lowest index from the API, class, and +MPCI node components. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id RTEMS_OBJECT_ID_INITIAL( + uint32_t api, + uint32_t class, + uint32_t node + ); + +.. rubric:: PARAMETERS: + +``api`` + This parameter is the API of the object identifier to build. + +``class`` + This parameter is the class of the object identifier to build. + +``node`` + This parameter is the MPCI node of the object identifier to build. + +.. rubric:: RETURN VALUES: + +Returns the object identifier with the lowest index built from the API, class, +and MPCI node components. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/object-services/index.rst b/c-user/object-services/index.rst new file mode 100644 index 0000000..3218551 --- /dev/null +++ b/c-user/object-services/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: object manipulation + +.. _RTEMSAPIClassicObject: + +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..adff786 --- /dev/null +++ b/c-user/object-services/introduction.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/object/if/group + +.. _ObjectServicesIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/object/if/build-id +.. spec:/rtems/object/if/build-name +.. spec:/rtems/object/if/get-classic-name +.. spec:/rtems/object/if/get-name +.. spec:/rtems/object/if/set-name +.. spec:/rtems/object/if/id-get-api +.. spec:/rtems/object/if/id-get-class +.. spec:/rtems/object/if/id-get-node +.. spec:/rtems/object/if/id-get-index +.. spec:/rtems/object/if/id-api-minimum +.. spec:/rtems/object/if/id-api-maximum +.. spec:/rtems/object/if/api-minimum-class +.. spec:/rtems/object/if/api-maximum-class +.. spec:/rtems/object/if/get-api-name +.. spec:/rtems/object/if/get-api-class-name +.. spec:/rtems/object/if/get-class-information +.. spec:/rtems/object/if/get-local-node +.. spec:/rtems/object/if/id-initial + +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 directives provided by the Object Services are: + +* :ref:`InterfaceRtemsBuildId` - Builds the object identifier from the API, + class, MPCI node, and index components. + +* :ref:`InterfaceRtemsBuildName` - Builds the object name composed of the four + characters. + +* :ref:`InterfaceRtemsObjectGetClassicName` - Gets the object name associated + with the object identifier. + +* :ref:`InterfaceRtemsObjectGetName` - Gets the object name associated with the + object identifier as a string. + +* :ref:`InterfaceRtemsObjectSetName` - Sets the object name of the object + associated with the object identifier. + +* :ref:`InterfaceRtemsObjectIdGetApi` - Gets the API component of the object + identifier. + +* :ref:`InterfaceRtemsObjectIdGetClass` - Gets the class component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdGetNode` - Gets the MPCI node component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdGetIndex` - Gets the index component of the + object identifier. + +* :ref:`InterfaceRtemsObjectIdApiMinimum` - Gets the lowest valid value for the + API component of an object identifier. + +* :ref:`InterfaceRtemsObjectIdApiMaximum` - Gets the highest valid value for + the API component of an object identifier. + +* :ref:`InterfaceRtemsObjectApiMinimumClass` - Gets the lowest valid class + value of the object API. + +* :ref:`InterfaceRtemsObjectApiMaximumClass` - Gets the highest valid class + value of the object API. + +* :ref:`InterfaceRtemsObjectGetApiName` - Gets a descriptive name of the object + API. + +* :ref:`InterfaceRtemsObjectGetApiClassName` - Gets a descriptive name of the + object class of the object API. + +* :ref:`InterfaceRtemsObjectGetClassInformation` - Gets the object class + information of the object class of the object API. + +* :ref:`InterfaceRtemsObjectGetLocalNode` - Gets the local MPCI node number. + +* :ref:`InterfaceRTEMSOBJECTIDINITIAL` - Builds the object identifier with the + lowest index from the API, class, and MPCI node components. 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) + ); + } |