c-user: Split up initialization manager

This makes it easier to automatically generate parts of the module
documentation in the future.

Update #3993.

6 files changed, 120 insertions, 99 deletions

diff --git a/c-user/index.rst b/c-user/index.rst
index 2f8109a..0a05c75 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -29,7 +29,7 @@ RTEMS Classic API Guide (|version|).
 	key_concepts
 	rtems_data_types
 	scheduling-concepts/index
-	initialization
+	initialization/index
 	task/index
 	interrupt/index
 	clock/index
diff --git a/c-user/initialization/background.rst b/c-user/initialization/background.rst
new file mode 100644
index 0000000..36d8ebd
--- /dev/null
+++ b/c-user/initialization/background.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: initialization tasks
+
+Initialization Tasks
+--------------------
+
+Initialization task(s) are the mechanism by which RTEMS transfers initial
+control to the user's application.  Initialization tasks differ from other
+application tasks in that they are defined in the User Initialization Tasks
+Table and automatically created and started by RTEMS as part of its
+initialization sequence.  Since the initialization tasks are scheduled using
+the same algorithm as all other RTEMS tasks, they must be configured at a
+priority and mode which will ensure that they will complete execution before
+other application tasks execute.  Although there is no upper limit on the
+number of initialization tasks, an application is required to define at least
+one.
+
+A typical initialization task will create and start the static set of
+application tasks.  It may also create any other objects used by the
+application.  Initialization tasks which only perform initialization should
+delete themselves upon completion to free resources for other tasks.
+Initialization tasks may transform themselves into a "normal" application task.
+This transformation typically involves changing priority and execution mode.
+RTEMS does not automatically delete the initialization tasks.
+
+The Idle Task
+-------------
+
+The Idle Task is the lowest priority task in a system and executes only when no
+other task is ready to execute.  The default implementation of this task
+consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
+a CPU specific implementation, a BSP specific implementation or an application
+specific implementation.
+
+The Idle Task is preemptible and *WILL* be preempted when any other task is
+made ready to execute.  This characteristic is critical to the overall behavior
+of any application.
+
+Initialization Manager Failure
+------------------------------
+
+System initialization errors are fatal.  See :ref:`internal_errors`.
diff --git a/c-user/initialization/directives.rst b/c-user/initialization/directives.rst
new file mode 100644
index 0000000..97dea46
--- /dev/null
+++ b/c-user/initialization/directives.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the Initialization Manager's directives.  A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. raw:: latex
+
+   \clearpage
+
+.. index:: initialize RTEMS
+.. index:: start multitasking
+.. index:: rtems_initialize_executive
+
+.. _rtems_initialize_executive:
+
+INITIALIZE_EXECUTIVE - Initialize RTEMS
+---------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_initialize_executive(void);
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    Iterates through the system initialization linker set and invokes the
+    registered handlers.  The final step is to start multitasking.
+
+NOTES:
+    This directive should be called by :c:func:`boot_card()` only.
+
+    This directive *does not return* to the caller.  Errors in the
+    initialization sequence are usually fatal and lead to a system termination.
diff --git a/c-user/initialization/index.rst b/c-user/initialization/index.rst
new file mode 100644
index 0000000..b41fcdd
--- /dev/null
+++ b/c-user/initialization/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. _RTEMSAPIClassicInit:
+
+Initialization Manager
+**********************
+
+.. toctree::
+
+    introduction
+    background
+    operations
+    directives
diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst
new file mode 100644
index 0000000..ae14fb0
--- /dev/null
+++ b/c-user/initialization/introduction.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The Initialization Manager is responsible for initializing the Board Support
+Package, RTEMS, device drivers, the root filesystem and the application.  The
+:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
+shutdown.
+
+The Initialization Manager provides only one directive:
+
+- :ref:`rtems_initialize_executive`
diff --git a/c-user/initialization.rst b/c-user/initialization/operations.rst
index fa7afb5..db5c94b 100644
--- a/c-user/initialization.rst
+++ b/c-user/initialization/operations.rst
@@ -2,66 +2,6 @@
 
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
-Initialization Manager
-**********************
-
-Introduction
-============
-
-The Initialization Manager is responsible for initializing the Board Support
-Package, RTEMS, device drivers, the root filesystem and the application.  The
-:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
-shutdown.
-
-The Initialization Manager provides only one directive:
-
-- rtems_initialize_executive_ - Initialize RTEMS
-
-Background
-==========
-
-.. index:: initialization tasks
-
-Initialization Tasks
---------------------
-
-Initialization task(s) are the mechanism by which RTEMS transfers initial
-control to the user's application.  Initialization tasks differ from other
-application tasks in that they are defined in the User Initialization Tasks
-Table and automatically created and started by RTEMS as part of its
-initialization sequence.  Since the initialization tasks are scheduled using
-the same algorithm as all other RTEMS tasks, they must be configured at a
-priority and mode which will ensure that they will complete execution before
-other application tasks execute.  Although there is no upper limit on the
-number of initialization tasks, an application is required to define at least
-one.
-
-A typical initialization task will create and start the static set of
-application tasks.  It may also create any other objects used by the
-application.  Initialization tasks which only perform initialization should
-delete themselves upon completion to free resources for other tasks.
-Initialization tasks may transform themselves into a "normal" application task.
-This transformation typically involves changing priority and execution mode.
-RTEMS does not automatically delete the initialization tasks.
-
-The Idle Task
--------------
-
-The Idle Task is the lowest priority task in a system and executes only when no
-other task is ready to execute.  The default implementation of this task
-consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
-a CPU specific implementation, a BSP specific implementation or an application
-specific implementation.
-
-The Idle Task is preemptible and *WILL* be preempted when any other task is
-made ready to execute.  This characteristic is critical to the overall behavior
-of any application.
-
-Initialization Manager Failure
-------------------------------
-
-System initialization errors are fatal.  See :ref:`internal_errors`.
-
 Operations
 ==========
 
@@ -418,41 +358,3 @@ should output:
     c()
     b()
     A:A()
-
-Directives
-==========
-
-This section details the Initialization Manager's directives.  A subsection is
-dedicated to each of this manager's directives and describes the calling
-sequence, related constants, usage, and status codes.
-
-.. raw:: latex
-
-   \clearpage
-
-.. index:: initialize RTEMS
-.. index:: start multitasking
-.. index:: rtems_initialize_executive
-
-.. _rtems_initialize_executive:
-
-INITIALIZE_EXECUTIVE - Initialize RTEMS
----------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        void rtems_initialize_executive(void);
-
-DIRECTIVE STATUS CODES:
-    NONE - This function will not return to the caller.
-
-DESCRIPTION:
-    Iterates through the system initialization linker set and invokes the
-    registered handlers.  The final step is to start multitasking.
-
-NOTES:
-    This directive should be called by :c:func:`boot_card()` only.
-
-    This directive *does not return* to the caller.  Errors in the
-    initialization sequence are usually fatal and lead to a system termination.