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