diff options
Diffstat (limited to 'c-user/object-services/directives.rst')
| -rw-r--r-- | c-user/object-services/directives.rst | 978 |
1 files changed, 570 insertions, 408 deletions
diff --git a/c-user/object-services/directives.rst b/c-user/object-services/directives.rst index 87f0f5a..ce7a894 100644 --- a/c-user/object-services/directives.rst +++ b/c-user/object-services/directives.rst @@ -1,643 +1,805 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. 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://docs.rtems.org/branches/master/user/support/bugs.html +.. +.. For information on updating and regenerating please refer to: +.. +.. https://docs.rtems.org/branches/master/eng/req/howto.html + +.. _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 + \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 + + #define rtems_build_id( api, class, node, index ) -.. index:: build object name -.. index:: rtems_build_name +.. rubric:: PARAMETERS: -.. _rtems_build_name: +``api`` + This parameter is the API of the object identifier to build. -BUILD_NAME - Build object name from characters ----------------------------------------------- +``class`` + This parameter is the class of the object identifier to build. -CALLING SEQUENCE: - .. code-block:: c +``node`` + This parameter is the MPCI node of the object identifier to build. - rtems_name rtems_build_name( - uint8_t c1, - uint8_t c2, - uint8_t c3, - uint8_t c4 - ); +``index`` + This parameter is the index of the object identifier to build. -DIRECTIVE STATUS CODES: - Returns a name constructed from the four characters. +.. rubric:: RETURN VALUES: -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. +Returns the object identifier built from the API, class, MPCI node, and index +components. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +.. Generated from spec:/rtems/object/if/build-name .. raw:: latex - \clearpage + \clearpage -.. index:: get name from id -.. index:: obtain name from id -.. index:: rtems_object_get_classic_name +.. index:: rtems_build_name() -.. _rtems_object_get_classic_name: +.. _InterfaceRtemsBuildName: -OBJECT_GET_CLASSIC_NAME - Lookup name from id ---------------------------------------------- +rtems_build_name() +------------------ -CALLING SEQUENCE: - .. code-block:: c +Builds the object name composed of the four characters. - rtems_status_code rtems_object_get_classic_name( - rtems_id id, - rtems_name *name - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - name looked up successfully - * - ``RTEMS_INVALID_ADDRESS`` - - invalid name pointer - * - ``RTEMS_INVALID_ID`` - - invalid object id + #define rtems_build_name( c1, c2, c3, c4 ) -DESCRIPTION: - This service looks up the name for the object ``id`` specified and, if - found, places the result in ``*name``. +.. rubric:: PARAMETERS: -NOTES: - This directive is strictly local and does not impact task scheduling. +``c1`` + This parameter is the first character of the name. -.. raw:: latex +``c2`` + This parameter is the second character of the name. - \clearpage +``c3`` + This parameter is the third character of the name. -.. index:: get object name as string -.. index:: obtain object name as string -.. index:: rtems_object_get_name +``c4`` + This parameter is the fourth character of the name. -.. _rtems_object_get_name: +.. rubric:: DESCRIPTION: -OBJECT_GET_NAME - Obtain object name as string ----------------------------------------------- +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. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: RETURN VALUES: - char* rtems_object_get_name( - rtems_id id, - size_t length, - char *name - ); +Returns the object name composed of the four characters. -DIRECTIVE STATUS CODES: - Returns a pointer to the name if successful or ``NULL`` otherwise. +.. rubric:: NOTES: -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. +This directive is strictly local and does not impact task scheduling. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. Generated from spec:/rtems/object/if/get-classic-name .. raw:: latex - \clearpage + \clearpage -.. index:: set object name -.. index:: rtems_object_set_name +.. index:: rtems_object_get_classic_name() -.. _rtems_object_set_name: +.. _InterfaceRtemsObjectGetClassicName: -OBJECT_SET_NAME - Set object name ---------------------------------- +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 + ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_object_set_name( - rtems_id id, - const char *name - ); +``id`` + This parameter is the object identifier to get the name. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``name`` + This parameter is the pointer to an object name variable. The object name + associated with the object identifier will be stored in this variable, in + case of a successful operation. - * - ``RTEMS_SUCCESSFUL`` - - name looked up successfully - * - ``RTEMS_INVALID_ADDRESS`` - - invalid name pointer - * - ``RTEMS_INVALID_ID`` - - invalid object id +.. rubric:: RETURN VALUES: -DESCRIPTION: - This service sets the name of ``id`` to that specified by the string - located at ``name``. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -NOTES: - This directive is strictly local and does not impact task scheduling. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - 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``. +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. - 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 +: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:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +.. Generated from spec:/rtems/object/if/get-name .. raw:: latex - \clearpage + \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: -.. index:: obtain API from id -.. index:: rtems_object_id_get_api +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. -.. _rtems_object_id_get_api: +.. rubric:: RETURN VALUES: -OBJECT_ID_GET_API - Obtain API from Id --------------------------------------- +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``length`` parameter was 0. -CALLING SEQUENCE: - .. code-block:: c +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + The ``name`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - int rtems_object_id_get_api( - rtems_id id - ); +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object information available for the object identifier. -DIRECTIVE STATUS CODES: - Returns the API portion of the object Id. +`NULL <https://en.cppreference.com/w/c/types/NULL>`_ + There was no object associated with the object identifier. -DESCRIPTION: - This directive returns the API portion of the provided object ``id``. +Returns the ``name`` parameter value, if there is an object name associated +with the object identifier. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: NOTES: - This directive does NOT validate the ``id`` provided. +This directive may cause the calling task to be preempted due to an obtain and +release of the object allocator mutex. + +.. Generated from spec:/rtems/object/if/set-name .. raw:: latex - \clearpage + \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>`_. -.. index:: obtain class from object id -.. index:: rtems_object_id_get_class +:c:macro:`RTEMS_INVALID_ID` + There was no object information available for the object identifier. -.. _rtems_object_id_get_class: +:c:macro:`RTEMS_INVALID_ID` + There was no object associated with the object identifier. -OBJECT_ID_GET_CLASS - Obtain Class from Id ------------------------------------------- +:c:macro:`RTEMS_NO_MEMORY` + There was no memory available to duplicate the name. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - uint32_t rtems_object_id_get_class( - rtems_id id - ); +This directive may cause the calling task to be preempted due to an obtain and +release of the object allocator mutex. -DIRECTIVE STATUS CODES: - Returns the class portion of the object Id. +This directive can be used to set the name of objects which do not have a +naming scheme per their API. -DESCRIPTION: - This directive returns the class portion of the provided object ``id``. +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``. -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 32-bit integer style +name, then the first four characters in ``name`` will be used to construct the +name. - This directive does NOT validate the ``id`` provided. +.. Generated from spec:/rtems/object/if/id-get-api .. raw:: latex - \clearpage + \clearpage -.. index:: obtain node from object id -.. index:: rtems_object_id_get_node +.. index:: rtems_object_id_get_api() -.. _rtems_object_id_get_node: +.. _InterfaceRtemsObjectIdGetApi: -OBJECT_ID_GET_NODE - Obtain Node from Id ----------------------------------------- +rtems_object_id_get_api() +------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets the API component of the object identifier. - uint32_t rtems_object_id_get_node( - rtems_id id - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - Returns the node portion of the object Id. +.. code-block:: c -DESCRIPTION: - This directive returns the node portion of the provided object ``id``. + #define rtems_object_id_get_api( id ) -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: PARAMETERS: - This directive does NOT validate the ``id`` provided. +``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 is strictly local and does not impact task scheduling. + +This directive does not validate the object identifier provided in ``id``. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/id-get-class .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_id_get_class() -.. index:: obtain index from object id -.. index:: rtems_object_id_get_index +.. _InterfaceRtemsObjectIdGetClass: -.. _rtems_object_id_get_index: +rtems_object_id_get_class() +--------------------------- -OBJECT_ID_GET_INDEX - Obtain Index from Id ------------------------------------------- +Gets the class component of the object identifier. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CALLING SEQUENCE: - uint16_t rtems_object_id_get_index( - rtems_id id - ); +.. code-block:: c -DIRECTIVE STATUS CODES: - Returns the index portion of the object Id. + #define rtems_object_id_get_class( id ) -DESCRIPTION: - This directive returns the index portion of the provided object ``id``. +.. rubric:: PARAMETERS: -NOTES: - This directive is strictly local and does not impact task scheduling. +``id`` + This parameter is the object identifier with the class component to get. - This directive does NOT validate the ``id`` provided. +.. rubric:: RETURN VALUES: + +Returns the class component of the object identifier. + +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +This directive does not validate the object identifier provided in ``id``. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/id-get-node .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_id_get_node() + +.. _InterfaceRtemsObjectIdGetNode: -.. index:: build object id from components -.. index:: rtems_build_id +rtems_object_id_get_node() +-------------------------- -.. _rtems_build_id: +Gets the MPCI node component of the object identifier. -BUILD_ID - Build Object Id From Components ------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - rtems_id rtems_build_id( - int the_api, - int the_class, - int the_node, - int the_index - ); + #define rtems_object_id_get_node( id ) -DIRECTIVE STATUS CODES: - Returns an object Id constructed from the provided arguments. +.. rubric:: PARAMETERS: -DESCRIPTION: - This service constructs an object Id from the provided ``the_api``, - ``the_class``, ``the_node``, and ``the_index``. +``id`` + This parameter is the object identifier with the MPCI node component to + get. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: RETURN VALUES: - This directive does NOT validate the arguments provided or the Object id - returned. +Returns the MPCI node component of the object identifier. + +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +This directive does not validate the object identifier provided in ``id``. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/id-get-index .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_id_get_index() + +.. _InterfaceRtemsObjectIdGetIndex: + +rtems_object_id_get_index() +--------------------------- -.. index:: obtain minimum API value -.. index:: rtems_object_id_api_minimum +Gets the index component of the object identifier. -.. _rtems_object_id_api_minimum: +.. rubric:: CALLING SEQUENCE: -OBJECT_ID_API_MINIMUM - Obtain Minimum API Value ------------------------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + #define rtems_object_id_get_index( id ) - int rtems_object_id_api_minimum(void); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - Returns the minimum valid for the API portion of an object Id. +``id`` + This parameter is the object identifier with the index component to get. -DESCRIPTION: - This service returns the minimum valid for the API portion of an object Id. +.. rubric:: RETURN VALUES: -NOTES: - This directive is strictly local and does not impact task scheduling. +Returns the index component of the object identifier. + +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +This directive does not validate the object identifier provided in ``id``. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/id-api-minimum .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_id_api_minimum() + +.. _InterfaceRtemsObjectIdApiMinimum: + +rtems_object_id_api_minimum() +----------------------------- -.. index:: obtain maximum API value -.. index:: rtems_object_id_api_maximum +Gets the lowest valid value for the API component of an object identifier. -.. _rtems_object_id_api_maximum: +.. rubric:: CALLING SEQUENCE: -OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value ------------------------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + #define rtems_object_id_api_minimum() - int rtems_object_id_api_maximum(void); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - Returns the maximum valid for the API portion of an object Id. +Returns the lowest valid value for the API component of an object identifier. -DESCRIPTION: - This service returns the maximum valid for the API portion of an object Id. +.. rubric:: NOTES: -NOTES: - This directive is strictly local and does not impact task scheduling. +This directive is strictly local and does not impact task scheduling. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/id-api-maximum .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_id_api_maximum() + +.. _InterfaceRtemsObjectIdApiMaximum: -.. index:: obtain minimum class value -.. index:: rtems_object_api_minimum_class +rtems_object_id_api_maximum() +----------------------------- -.. _rtems_object_api_minimum_class: +Gets the highest valid value for the API component of an object identifier. -OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value ------------------------------------------------------ +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - int rtems_object_api_minimum_class( - int api - ); + #define rtems_object_id_api_maximum() -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. +.. rubric:: RETURN VALUES: - If successful, this service returns the minimum valid for the class portion - of an object Id for the specified ``api``. +Returns the highest valid value for the API component of an object identifier. -DESCRIPTION: - This service returns the minimum valid for the class portion of an object - Id for the specified ``api``. +.. rubric:: NOTES: -NOTES: - This directive is strictly local and does not impact task scheduling. +This directive is strictly local and does not impact task scheduling. + +A body is also provided. + +.. Generated from spec:/rtems/object/if/api-minimum-class .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_api_minimum_class() + +.. _InterfaceRtemsObjectApiMinimumClass: -.. index:: obtain maximum class value -.. index:: rtems_object_api_maximum_class +rtems_object_api_minimum_class() +-------------------------------- -.. _rtems_object_api_maximum_class: +Gets the lowest valid class value of the object API. -OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value ------------------------------------------------------ +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - int rtems_object_api_maximum_class( - int api - ); + int rtems_object_api_minimum_class( int api ); -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. +.. rubric:: PARAMETERS: - If successful, this service returns the maximum valid for the class portion - of an object Id for the specified ``api``. +``api`` + This parameter is the object API to get the lowest valid class value. -DESCRIPTION: - This service returns the maximum valid for the class portion of an object - Id for the specified ``api``. +.. rubric:: RETURN VALUES: -NOTES: - This directive is strictly local and does not impact task scheduling. +``-1`` + The object API was invalid. + +Returns the lowest valid class value of the object API. + +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +.. Generated from spec:/rtems/object/if/api-maximum-class .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_object_api_maximum_class() + +.. _InterfaceRtemsObjectApiMaximumClass: + +rtems_object_api_maximum_class() +-------------------------------- + +Gets the highest valid class value of the object API. -.. index:: obtain minimum class value for an API -.. index:: rtems_object_id_api_minimum_class +.. rubric:: CALLING SEQUENCE: -.. _rtems_object_id_api_minimum_class: +.. code-block:: c -OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API -------------------------------------------------------------------- + int rtems_object_api_maximum_class( int api ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - int rtems_object_get_id_api_minimum_class( - int api - ); +``api`` + This parameter is the object API to get the highest valid class value. -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. +.. rubric:: RETURN VALUES: - If successful, this service returns the index corresponding to the first - object class of the specified ``api``. +``0`` + The object API was invalid. -DESCRIPTION: - This service returns the index for the first object class associated with - the specified ``api``. +Returns the highest valid class value of the object API. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: NOTES: + +This directive is strictly local and does not impact task scheduling. + +.. Generated from spec:/rtems/object/if/get-api-name .. raw:: latex - \clearpage + \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 -.. index:: obtain maximum class value for an API -.. index:: rtems_object_id_api_maximum_class + const char *rtems_object_get_api_name( int api ); -.. _rtems_object_id_api_maximum_class: +.. rubric:: PARAMETERS: -OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API -------------------------------------------------------------------- +``api`` + This parameter is the object API to get the name. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: RETURN VALUES: - int rtems_object_get_api_maximum_class( - int api - ); +"BAD API" + The API was invalid. -DIRECTIVE STATUS CODES: - If ``api`` is not valid, -1 is returned. +Returns a descriptive name of the API, if the API was valid. - If successful, this service returns the index corresponding to the last - object class of the specified ``api``. +.. rubric:: NOTES: -DESCRIPTION: - This service returns the index for the last object class associated with - the specified ``api``. +This directive is strictly local and does not impact task scheduling. -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. + +.. Generated from spec:/rtems/object/if/get-api-class-name .. raw:: latex - \clearpage + \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 -.. index:: obtain API name -.. index:: rtems_object_get_api_name + const char *rtems_object_get_api_class_name( int the_api, int the_class ); -.. _rtems_object_get_api_name: +.. rubric:: PARAMETERS: -OBJECT_GET_API_NAME - Obtain API Name -------------------------------------- +``the_api`` + This parameter is the object API of the object class. -CALLING SEQUENCE: - .. code-block:: c +``the_class`` + This parameter is the object class of the object API to get the name. - const char* rtems_object_get_api_name( - int api - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - If ``api`` is not valid, the string ``"BAD API"`` is returned. +"BAD API" + The API was invalid. - If successful, this service returns a pointer to a string containing the - name of the specified ``api``. +"BAD CLASS" + The class of the API was invalid. -DESCRIPTION: - This service returns the name of the specified ``api``. +Returns a descriptive name of the class of the API, if the class of the API and +the API were valid. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: NOTES: - The string returned is from constant space. Do not modify or free it. +This directive is strictly local and does not impact task scheduling. + +The string returned is from constant space. Do not modify or free it. + +.. Generated from spec:/rtems/object/if/get-class-information .. raw:: latex - \clearpage + \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 -.. index:: obtain class name -.. index:: rtems_object_get_api_class_name + rtems_status_code rtems_object_get_class_information( + int the_api, + int the_class, + rtems_object_api_class_information *info + ); -.. _rtems_object_get_api_class_name: +.. rubric:: PARAMETERS: -OBJECT_GET_API_CLASS_NAME - Obtain Class Name ---------------------------------------------- +``the_api`` + This parameter is the object API of the object class. -CALLING SEQUENCE: - .. code-block:: c +``the_class`` + This parameter is the object class of the object API to get the class + information. - const char *rtems_object_get_api_class_name( - int the_api, - int the_class - ); +``info`` + This parameter is the pointer to an object class information variable. The + object class information of the class of the API will be stored in this + variable, in case of a successful operation. -DIRECTIVE STATUS CODES: - If ``the_api`` is not valid, the string ``"BAD API"`` is returned. +.. rubric:: RETURN VALUES: - If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - If successful, this service returns a pointer to a string containing the - name of the specified ``the_api`` / ``the_class`` pair. +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``info`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -DESCRIPTION: - This service returns the name of the object class indicated by the - specified ``the_api`` and ``the_class``. +:c:macro:`RTEMS_INVALID_NUMBER` + The class of the API or the API was invalid. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. rubric:: NOTES: - The string returned is from constant space. Do not modify or free it. +This directive is strictly local and does not impact task scheduling. + +.. Generated from spec:/rtems/object/if/get-local-node .. raw:: latex - \clearpage + \clearpage -.. index:: obtain class information -.. index:: rtems_object_get_class_information +.. index:: rtems_object_get_local_node() -.. _rtems_object_get_class_information: +.. _InterfaceRtemsObjectGetLocalNode: -OBJECT_GET_CLASS_INFORMATION - Obtain Class Information -------------------------------------------------------- +rtems_object_get_local_node() +----------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets the local MPCI node number. - rtems_status_code rtems_object_get_class_information( - int the_api, - int the_class, - rtems_object_api_class_information *info - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``RTEMS_SUCCESSFUL`` - - information obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``info`` is NULL - * - ``RTEMS_INVALID_NUMBER`` - - invalid ``api`` or ``the_class`` + uint16_t rtems_object_get_local_node( void ); - If successful, the structure located at ``info`` will be filled in with - information about the specified ``api`` / ``the_class`` pairing. +.. rubric:: RETURN VALUES: -DESCRIPTION: - This service returns information about the object class indicated by the - specified ``api`` and ``the_class``. This structure is defined as follows: +Returns the local MPCI node number. - .. code-block:: c +.. rubric:: NOTES: - typedef struct { - rtems_id minimum_id; - rtems_id maximum_id; - int maximum; - bool auto_extend; - int unallocated; - } rtems_object_api_class_information; +This directive is strictly local and does not impact task scheduling. -NOTES: - This directive is strictly local and does not impact task scheduling. +.. Generated from spec:/rtems/object/if/id-initial .. raw:: latex - \clearpage + \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 + + #define RTEMS_OBJECT_ID_INITIAL( api, class, node ) -.. index:: obtain local node -.. index:: rtems_object_get_local_node +.. rubric:: PARAMETERS: -.. _rtems_object_get_local_node: +``api`` + This parameter is the API of the object identifier to build. -OBJECT_GET_LOCAL_NODE - Obtain Local Node ------------------------------------------ +``class`` + This parameter is the class of the object identifier to build. -CALLING SEQUENCE: - .. code-block:: c +``node`` + This parameter is the MPCI node of the object identifier to build. - uint16_t rtems_object_get_local_node( void ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - NONE +Returns the object identifier with the lowest index built from the API, class, +and MPCI node components. -DESCRIPTION: - This service returns the local MPCI node. +.. rubric:: NOTES: -NOTES: - This directive is strictly local and does not impact task scheduling. +This directive is strictly local and does not impact task scheduling. |