summaryrefslogtreecommitdiffstats
path: root/c-user/object_services.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c-user/object_services.rst')
-rw-r--r--c-user/object_services.rst788
1 files changed, 788 insertions, 0 deletions
diff --git a/c-user/object_services.rst b/c-user/object_services.rst
new file mode 100644
index 0000000..f4b388a
--- /dev/null
+++ b/c-user/object_services.rst
@@ -0,0 +1,788 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+Object Services
+###############
+
+.. index:: object manipulation
+
+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
+
+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=%d Node=%d Index=%d\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, tmpClass;
+
+ tmpAPI = rtems_object_id_get_api(id),
+ tmpClass = rtems_object_id_get_class(id),
+
+ printf(
+ "API=%s Class=%s Node=%d Index=%d\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
+==========
+
+.. _rtems_build_name:
+
+BUILD_NAME - Build object name from characters
+----------------------------------------------
+.. index:: build object name
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_build_name
+
+.. 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.
+
+.. _rtems_object_get_classic_name:
+
+OBJECT_GET_CLASSIC_NAME - Lookup name from id
+---------------------------------------------
+.. index:: get name from id
+.. index:: obtain name from id
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_get_classic_name
+
+.. 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.
+
+.. _rtems_object_get_name:
+
+OBJECT_GET_NAME - Obtain object name as string
+----------------------------------------------
+.. index:: get object name as string
+.. index:: obtain object name as string
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_get_name
+
+.. 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.
+
+.. _rtems_object_set_name:
+
+OBJECT_SET_NAME - Set object name
+---------------------------------
+.. index:: set object name
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_set_name
+
+.. 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
+
+.. _rtems_object_id_get_api:
+
+OBJECT_ID_GET_API - Obtain API from Id
+--------------------------------------
+.. index:: obtain API from id
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_get_api
+
+.. 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.
+
+.. _rtems_object_id_get_class:
+
+OBJECT_ID_GET_CLASS - Obtain Class from Id
+------------------------------------------
+.. index:: obtain class from object id
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_get_class
+
+.. code-block:: c
+
+ int 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.
+
+.. _rtems_object_id_get_node:
+
+OBJECT_ID_GET_NODE - Obtain Node from Id
+----------------------------------------
+.. index:: obtain node from object id
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_get_node
+
+.. code-block:: c
+
+ int 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.
+
+.. _rtems_object_id_get_index:
+
+OBJECT_ID_GET_INDEX - Obtain Index from Id
+------------------------------------------
+.. index:: obtain index from object id
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_get_index
+
+.. code-block:: c
+
+ int 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.
+
+.. _rtems_build_id:
+
+BUILD_ID - Build Object Id From Components
+------------------------------------------
+.. index:: build object id from components
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_build_id
+
+.. 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.
+
+.. _rtems_object_id_api_minimum:
+
+OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
+------------------------------------------------
+.. index:: obtain minimum API value
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_api_minimum
+
+.. 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.
+
+.. _rtems_object_id_api_maximum:
+
+OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
+------------------------------------------------
+.. index:: obtain maximum API value
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_api_maximum
+
+.. 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.
+
+.. _rtems_object_api_minimum_class:
+
+OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
+-----------------------------------------------------
+.. index:: obtain minimum class value
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_api_minimum_class
+
+.. 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.
+
+.. _rtems_object_api_maximum_class:
+
+OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
+-----------------------------------------------------
+.. index:: obtain maximum class value
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_api_maximum_class
+
+.. 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.
+
+.. _rtems_object_id_api_minimum_class:
+
+OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API
+-------------------------------------------------------------------
+.. index:: obtain minimum class value for an API
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_api_minimum_class
+
+.. 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.
+
+.. _rtems_object_id_api_maximum_class:
+
+OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API
+-------------------------------------------------------------------
+.. index:: obtain maximum class value for an API
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_id_api_maximum_class
+
+.. 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.
+
+.. _rtems_object_get_api_name:
+
+OBJECT_GET_API_NAME - Obtain API Name
+-------------------------------------
+.. index:: obtain API name
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_get_api_name
+
+.. 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.
+
+.. _rtems_object_get_api_class_name:
+
+OBJECT_GET_API_CLASS_NAME - Obtain Class Name
+---------------------------------------------
+.. index:: obtain class name
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_get_api_class_name
+
+.. 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.
+
+.. _rtems_object_get_class_information:
+
+OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
+-------------------------------------------------------
+.. index:: obtain class information
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_object_get_class_information
+
+.. 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.
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-19 10:19:19 +0000