[PATCH 1/8] c-user: Split up initialization manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Apr 21 13:49:59 UTC 2021
This makes it easier to automatically generate parts of the module
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/initialization/background.rst | 48 +++++++++
c-user/initialization/directives.rst | 41 ++++++++
c-user/initialization/index.rst | 15 +++
c-user/initialization/introduction.rst | 15 +++
.../operations.rst} | 98 -------------------
6 files changed, 120 insertions(+), 99 deletions(-)
create mode 100644 c-user/initialization/background.rst
create mode 100644 c-user/initialization/directives.rst
create mode 100644 c-user/initialization/index.rst
create mode 100644 c-user/initialization/introduction.rst
rename c-user/{initialization.rst => initialization/operations.rst} (80%)
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
similarity index 80%
rename from c-user/initialization.rst
rename to 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.
--
2.26.2
More information about the devel
mailing list