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

@@ -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

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.

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
 ==========
 

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

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`

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)
+        );
+    }