c-user: Split up initialization manager

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

Update #3993.

5 files changed, 479 insertions, 0 deletions

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/operations.rst b/c-user/initialization/operations.rst
new file mode 100644
index 0000000..db5c94b
--- /dev/null
+++ b/c-user/initialization/operations.rst
@@ -0,0 +1,360 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Initializing RTEMS
+------------------
+
+The Initialization Manager :c:func:`rtems_initialize_executive()` directives is
+called by the :c:func:`boot_card()` routine which is invoked by the Board
+Support Package once a basic C run-time environment is set up.  This consists
+of
+
+- a valid and accessible text section, read-only data, read-write data and
+  zero-initialized data,
+
+- an initialization stack large enough to initialize the rest of the Board
+  Support Package, RTEMS and the device drivers,
+
+- all registers and components mandated by Application Binary Interface, and
+
+- disabled interrupts.
+
+The :c:func:`rtems_initialize_executive()` directive uses a system
+initialization :ref:`linker set <linker_sets>` to initialize only those parts
+of the overall RTEMS feature set that is necessary for a particular
+application.  Each RTEMS feature used the application may optionally register
+an initialization handler.  The system initialization API is available via
+:samp:`#included <rtems/sysinit.h>`.
+
+A list of all initialization steps follows.  Some steps are optional depending
+on the requested feature set of the application.  The initialization steps are
+execute in the order presented here.
+
+RTEMS_SYSINIT_RECORD
+    Initialization of the event recording is the first initialization step.
+    This allows to record the further system initialization.  This step is
+    optional and depends on the :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`
+    configuration option.
+
+RTEMS_SYSINIT_BSP_EARLY
+    The Board Support Package may perform an early platform initialization in
+    this step.  This step is optional.
+
+RTEMS_SYSINIT_MEMORY
+    The Board Support Package should initialize everything so that calls to
+    :c:func:`_Memory_Get()` can be made after this step.  This step is optional.
+
+RTEMS_SYSINIT_DIRTY_MEMORY
+    The free memory is dirtied in this step.  This step is optional and depends
+    on the :c:macro:`BSP_DIRTY_MEMORY` BSP option.
+
+RTEMS_SYSINIT_ISR_STACK
+    The stack checker initializes the ISR stacks in this step.  This step is
+    optional and depends on the :ref:`CONFIGURE_STACK_CHECKER_ENABLED`
+    configuration option.
+
+RTEMS_SYSINIT_PER_CPU_DATA
+    The per-CPU data is initialized in this step.  This step is mandatory.
+
+RTEMS_SYSINIT_SBRK
+    The Board Support Package may initialize the :c:func:`sbrk()` support in
+    this step.  This step is optional.
+
+RTEMS_SYSINIT_WORKSPACE
+    The workspace is initialized in this step.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_MALLOC
+    The C program heap is initialized in this step.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_BSP_START
+    The Board Support Package should perform a general platform initialization
+    in this step (e.g. interrupt controller initialization).  This step is
+    mandatory.
+
+RTEMS_SYSINIT_CPU_COUNTER
+    Initialization of the CPU counter hardware and support functions.  The CPU
+    counter is initialized early to allow its use in the tracing and profiling
+    of the system initialization sequence.  This step is optional and depends
+    on the application configuration.
+
+RTEMS_SYSINIT_INITIAL_EXTENSIONS
+    Registers the initial extensions.  This step is optional and depends on the
+    application configuration.
+
+RTEMS_SYSINIT_MP_EARLY
+    In MPCI configurations, an early MPCI initialization is performed in this
+    step.  This step is mandatory in MPCI configurations.
+
+RTEMS_SYSINIT_DATA_STRUCTURES
+    This directive is called when the Board Support Package has completed its
+    basic initialization and allows RTEMS to initialize the application
+    environment based upon the information in the Configuration Table, User
+    Initialization Tasks Table, Device Driver Table, User Extension Table,
+    Multiprocessor Configuration Table, and the Multiprocessor Communications
+    Interface (MPCI) Table.
+
+RTEMS_SYSINIT_MP
+    In MPCI configurations, a general MPCI initialization is performed in this
+    step.  This step is mandatory in MPCI configurations.
+
+RTEMS_SYSINIT_USER_EXTENSIONS
+    Initialization of the User Extensions object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_TASKS
+    Initialization of the Classic Tasks object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_TASKS_MP
+    In MPCI configurations, the Classic Tasks MPCI support is initialized in
+    this step.  This step is optional and depends on the application
+    configuration.
+
+RTEMS_SYSINIT_CLASSIC_TIMER
+    Initialization of the Classic Timer object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_SIGNAL
+    Initialization of the Classic Signal support.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_SIGNAL_MP
+    In MPCI configurations, the Classic Signal MPCI support is initialized in
+    this step.  This step is optional and depends on the application
+    configuration.
+
+RTEMS_SYSINIT_CLASSIC_EVENT
+    Initialization of the Classic Event support.  This step is optional and
+    depends on the application configuration.  This step is only used on MPCI
+    configurations.
+
+RTEMS_SYSINIT_CLASSIC_EVENT_MP
+    In MPCI configurations, the Classic Event MPCI support is initialized in
+    this step.  This step is optional and depends on the application
+    configuration.
+
+RTEMS_SYSINIT_CLASSIC_MESSAGE_QUEUE
+    Initialization of the Classic Message Queue object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_SEMAPHORE
+    Initialization of the Classic Semaphore object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_SEMAPHORE_MP
+    In MPCI configurations, the Classic Semaphore MPCI support is initialized
+    in this step.  This step is optional and depends on the application
+    configuration.
+
+RTEMS_SYSINIT_CLASSIC_PARTITION
+    Initialization of the Classic Partition object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_PARTITION_MP
+    In MPCI configurations, the Classic Partition MPCI support is initialized
+    in this step.  This step is optional and depends on the application
+    configuration.
+
+RTEMS_SYSINIT_CLASSIC_REGION
+    Initialization of the Classic Region object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_DUAL_PORTED_MEMORY
+    Initialization of the Classic Dual-Ported Memory object class.  This step
+    is optional and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_RATE_MONOTONIC
+    Initialization of the Classic Rate-Monotonic object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_CLASSIC_BARRIER
+    Initialization of the Classic Barrier object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_SIGNALS
+    Initialization of the POSIX Signals support.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_THREADS
+    Initialization of the POSIX Threads object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_MESSAGE_QUEUE
+    Initialization of the POSIX Message Queue object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_SEMAPHORE
+    Initialization of the POSIX Semaphore object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_TIMER
+    Initialization of the POSIX Timer object class.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_SHM
+    Initialization of the POSIX Shared Memory object class.  This step is
+    optional and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_KEYS
+    Initialization of the POSIX Keys object class.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_CLEANUP
+    Initialization of the POSIX Cleanup support.  This step is optional and
+    depends on the application configuration.
+
+RTEMS_SYSINIT_IDLE_THREADS
+    Initialization of idle threads.  This step is mandatory.
+
+RTEMS_SYSINIT_LIBIO
+    Initialization of IO library.  This step is optional and depends on the
+    application configuration.
+
+RTEMS_SYSINIT_ROOT_FILESYSTEM
+    Initialization of the root filesystem.  This step is optional and depends
+    on the application configuration.
+
+RTEMS_SYSINIT_DRVMGR
+    Driver manager initialization.  This step is optional and depends on the
+    application configuration.  Only available if the driver manager is
+    enabled.
+
+RTEMS_SYSINIT_MP_SERVER
+    In MPCI configurations, the MPCI server is initialized in this step.  This
+    step is mandatory in MPCI configurations.
+
+RTEMS_SYSINIT_BSP_PRE_DRIVERS
+    Initialization step performed right before device drivers are initialized.
+    This step is mandatory.
+
+RTEMS_SYSINIT_DRVMGR_LEVEL_1
+    Driver manager level 1 initialization.  This step is optional and depends
+    on the application configuration.  Only available if the driver manager is
+    enabled.
+
+RTEMS_SYSINIT_DEVICE_DRIVERS
+    This step initializes all statically configured device drivers and performs
+    all RTEMS initialization which requires device drivers to be initialized.
+    This step is mandatory.  In a multiprocessor configuration, this service
+    will initialize the Multiprocessor Communications Interface (MPCI) and
+    synchronize with the other nodes in the system.
+
+RTEMS_SYSINIT_DRVMGR_LEVEL_2
+    Driver manager level 2 initialization.  This step is optional and depends
+    on the application configuration.  Only available if the driver manager is
+    enabled.
+
+RTEMS_SYSINIT_DRVMGR_LEVEL_3
+    Driver manager level 3 initialization.  This step is optional and depends
+    on the application configuration.  Only available if the driver manager is
+    enabled.
+
+RTEMS_SYSINIT_DRVMGR_LEVEL_4
+    Driver manager level 4 initialization.  This step is optional and depends
+    on the application configuration.  Only available if the driver manager is
+    enabled.
+
+RTEMS_SYSINIT_MP_FINALIZE
+    Finalize MPCI initialization.  This step is mandatory on MPCI
+    configurations.
+
+RTEMS_SYSINIT_CLASSIC_USER_TASKS
+    Creates and starts the Classic initialization tasks.  This step is optional
+    and depends on the application configuration.
+
+RTEMS_SYSINIT_POSIX_USER_THREADS
+    Creates POSIX initialization threads.  This step is optional and depends on
+    the application configuration.
+
+RTEMS_SYSINIT_STD_FILE_DESCRIPTORS
+    Open the standard input, output and error file descriptors.  This step is
+    optional and depends on the application configuration.
+
+The final action of the :c:func:`rtems_initialize_executive()` directive is to
+start multitasking and switch to the highest priority ready thread.  RTEMS does
+not return to the initialization context and the initialization stack may be
+re-used for interrupt processing.
+
+Many of RTEMS actions during initialization are based upon the contents of the
+Configuration Table.  For more information regarding the format and contents of
+this table, please refer to the chapter :ref:`Configuring a System`.
+
+Global Construction
+-------------------
+
+The global construction is carried out by the first Classic API initialization
+task (first is defined by index zero in the Classic API initialization task
+configuration table).  If no Classic API initialization task exists, then it is
+carried out by the first POSIX API initialization thread.  If no initialization
+task or thread exists, then no global construction is performed, see for
+example :ref:`Specify Idle Task Performs Application Initialization`.  The
+Classic API task or POSIX API thread which carries out global construction is
+called the main thread.
+
+Global construction runs before the entry function of the main thread.  The
+configuration of the main thread must take the global construction into
+account.  In particular, the main thread stack size, priority, attributes and
+initial modes must be set accordingly.  Thread-local objects and POSIX key
+values created during global construction are accessible by the main thread.
+If other initialization tasks are configured, and one of them has a higher
+priority than the main thread and the main thread is preemptible, this task
+executes before the global construction.  In case the main thread blocks during
+global construction, then other tasks may run.  In SMP configurations, other
+initialization tasks may run in parallel with global construction.  Tasks
+created during global construction may preempt the main thread or run in
+parallel in SMP configurations.  All RTEMS services allowed in task context are
+allowed during global construction.
+
+Global constructors are C++ global object constructors or functions with the
+constructor attribute.  For example, the following test program
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <assert.h>
+
+    class A {
+      public:
+        A()
+        {
+          puts( "A:A()" );
+        }
+    };
+
+    static A a;
+
+    static thread_local int i;
+
+    static thread_local int j;
+
+    static __attribute__(( __constructor__ )) void b( void )
+    {
+      i = 1;
+      puts( "b()" );
+    }
+
+    static __attribute__(( __constructor__( 1000 ) )) void c( void )
+    {
+      puts( "c()" );
+    }
+
+    int main( void )
+    {
+      assert( i == 1 );
+      assert( j == 0 );
+      return 0;
+    }
+
+should output:
+
+.. code-block:: shell
+
+    c()
+    b()
+    A:A()