Update Initialization Manager chapter

Update #2408.
This commit is contained in:
Sebastian Huber 2016-12-09 13:01:57 +01:00
parent 00ffe1fa6b
commit 6fa32c01ee
3 changed files with 226 additions and 100 deletions

View File

@ -4,6 +4,8 @@
.. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved. .. COMMENT: All rights reserved.
.. _fatal_error_manager:
Fatal Error Manager Fatal Error Manager
******************* *******************
@ -19,6 +21,8 @@ provided by the fatal error manager are:
- rtems_fatal_ - Invoke the fatal error handler - rtems_fatal_ - Invoke the fatal error handler
- rtems_shutdown_executive_ - Shutdown RTEMS
- rtems_exception_frame_print_ - Print the CPU exception frame - rtems_exception_frame_print_ - Print the CPU exception frame
- rtems_fatal_source_text_ - Return the fatal source text - rtems_fatal_source_text_ - Return the fatal source text
@ -468,6 +472,38 @@ NOTE:
\clearpage \clearpage
.. _rtems_shutdown_executive:
SHUTDOWN_EXECUTIVE - Shutdown RTEMS
-----------------------------------
.. index:: shutdown RTEMS
.. index:: rtems_shutdown_executive
CALLING SEQUENCE:
.. code-block:: c
void rtems_shutdown_executive(
uint32_t result
);
DIRECTIVE STATUS CODES:
NONE - This function will not return to the caller.
DESCRIPTION:
This directive is called when the application wishes to shutdown RTEMS.
The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
and the specified ``result`` code.
NOTES:
This directive *must* be the last RTEMS directive invoked by an application
and it *does not return* to the caller.
This directive may be called any time.
.. raw:: latex
\clearpage
.. _rtems_exception_frame_print: .. _rtems_exception_frame_print:
EXCEPTION_FRAME_PRINT - Prints the exception frame EXCEPTION_FRAME_PRINT - Prints the exception frame

View File

@ -10,17 +10,15 @@ Initialization Manager
Introduction Introduction
============ ============
The Initialization Manager is responsible for initiating and shutting down The Initialization Manager is responsible for initializing the Board Support
RTEMS. Initiating RTEMS involves creating and starting all configured Package, RTEMS, device drivers, the root filesystem and the application. The
initialization tasks, and for invoking the initialization routine for each :ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
user-supplied device driver. In a multiprocessor configuration, this manager shutdown.
also initializes the interprocessor communications layer. The directives
provided by the Initialization Manager are: The Initialization Manager provides only one directive:
- rtems_initialize_executive_ - Initialize RTEMS - rtems_initialize_executive_ - Initialize RTEMS
- rtems_shutdown_executive_ - Shutdown RTEMS
Background Background
========== ==========
@ -47,25 +45,11 @@ Initialization tasks may transform themselves into a "normal" application task.
This transformation typically involves changing priority and execution mode. This transformation typically involves changing priority and execution mode.
RTEMS does not automatically delete the initialization tasks. RTEMS does not automatically delete the initialization tasks.
System Initialization
---------------------
System Initialization begins with board reset and continues through RTEMS
initialization, initialization of all device drivers, and eventually a context
switch to the first user task. Remember, that interrupts are disabled during
initialization and the *initialization context* is not a task in any sense and
the user should be very careful during initialization.
The BSP must ensure that the there is enough stack space reserved for the
initialization context to successfully execute the initialization routines for
all device drivers and, in multiprocessor configurations, the Multiprocessor
Communications Interface Layer initialization routine.
The Idle Task The Idle Task
------------- -------------
The Idle Task is the lowest priority task in a system and executes only when no The Idle Task is the lowest priority task in a system and executes only when no
other task is ready to execute. This default implementation of this task 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 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 a CPU specific implementation, a BSP specific implementation or an application
specific implementation. specific implementation.
@ -85,10 +69,10 @@ Operations
Initializing RTEMS Initializing RTEMS
------------------ ------------------
The Initialization Manager ``rtems_initialize_executive`` directives is called The Initialization Manager :c:func:`rtems_initialize_executive()` directives is
by the ``boot_card`` routine. The ``boot_card`` routine is invoked by the called by the :c:ref:`boot_card()` routine which is invoked by the Board
Board Support Package once a basic C run-time environment is set up. This Support Package once a basic C run-time environment is set up. This consists
consists of of
- a valid and accessible text section, read-only data, read-write data and - a valid and accessible text section, read-only data, read-write data and
zero-initialized data, zero-initialized data,
@ -100,25 +84,33 @@ consists of
- disabled interrupts. - disabled interrupts.
The ``rtems_initialize_executive`` directive uses a system initialization The :c:func:`rtems_initialize_executive()` directive uses a system
linker set to initialize only those parts of the overall RTEMS feature set that initialization :ref:`linker set <linker_sets>` to initialize only those parts
is necessary for a particular application. See :ref:`Linker Sets`. Each RTEMS of the overall RTEMS feature set that is necessary for a particular
feature used the application may optionally register an initialization handler. application. Each RTEMS feature used the application may optionally register
The system initialization API is available via``#included <rtems/sysinit.h>``. 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 A list of all initialization steps follows. Some steps are optional depending
on the requested feature set of the application. The initialization steps are on the requested feature set of the application. The initialization steps are
execute in the order presented here. execute in the order presented here.
``RTEMS_SYSINIT_BSP_WORK_AREAS`` RTEMS_SYSINIT_BSP_WORK_AREAS
The work areas consisting of C Program Heap and the RTEMS Workspace are The work areas consisting of C Program Heap and the RTEMS Workspace are
initialized by the Board Support Package. This step is mandatory. initialized by the Board Support Package. This step is mandatory.
``RTEMS_SYSINIT_BSP_START`` RTEMS_SYSINIT_BSP_START
Basic initialization step provided by the Board Support Package. This step Basic initialization step provided by the Board Support Package. This step
is mandatory. is mandatory.
``RTEMS_SYSINIT_DATA_STRUCTURES`` RTEMS_SYSINIT_INITIAL_EXTENSIONS
Registers the initial extensions. This step is optional and depends on the
application configuration.
RTEMS_SYSINIT_MP_EARLY
Early MPCI initialization. This step is mandatory on MPCI configurations.
RTEMS_SYSINIT_DATA_STRUCTURES
This directive is called when the Board Support Package has completed its This directive is called when the Board Support Package has completed its
basic initialization and allows RTEMS to initialize the application basic initialization and allows RTEMS to initialize the application
environment based upon the information in the Configuration Table, User environment based upon the information in the Configuration Table, User
@ -126,51 +118,181 @@ execute in the order presented here.
Multiprocessor Configuration Table, and the Multiprocessor Communications Multiprocessor Configuration Table, and the Multiprocessor Communications
Interface (MPCI) Table. Interface (MPCI) Table.
``RTEMS_SYSINIT_BSP_LIBC`` RTEMS_SYSINIT_CPU_SET
Depending on the application configuration the IO library and root Initialization of system CPU set. This step is optional and depends on the
filesystem is initialized. This step is mandatory. application configuration.
``RTEMS_SYSINIT_BEFORE_DRIVERS`` RTEMS_SYSINIT_MP
This directive performs initialization that must occur between basis RTEMS MPCI initialization. This step is mandatory on MPCI configurations.
data structure initialization and device driver initialization. In
particular, in a multiprocessor configuration, this directive will create
the MPCI Server Task.
``RTEMS_SYSINIT_BSP_PRE_DRIVERS`` RTEMS_SYSINIT_USER_EXTENSIONS
Initialization step performed right before device drivers are initialized Initialization of the User Extensions object class. This step is optional
provided by the Board Support Package. This step is mandatory. and depends on the application configuration.
``RTEMS_SYSINIT_DEVICE_DRIVERS`` RTEMS_SYSINIT_CLASSIC_TASKS
Initialization of the Classic Tasks object class. 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_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_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_PARTITION
Initialization of the Classic Partition object class. 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_CONDITION_VARIABLE
Initialization of the POSIX Condition Variable object class. This step is
optional and depends on the application configuration.
RTEMS_SYSINIT_POSIX_MUTEX
Initialization of the POSIX Mutex 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_BARRIER
Initialization of the POSIX Barrier object class. This step is optional
and depends on the application configuration.
RTEMS_SYSINIT_POSIX_RWLOCK
Initialization of the POSIX Read-Write Locks 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_POSIX_KEYS
Initialization of the POSIX Keys object class. 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
MPCI server initialization. This step is mandatory on 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 This step initializes all statically configured device drivers and performs
all RTEMS initialization which requires device drivers to be initialized. all RTEMS initialization which requires device drivers to be initialized.
This step is mandatory. In a multiprocessor configuration, this service This step is mandatory. In a multiprocessor configuration, this service
will initialize the Multiprocessor Communications Interface (MPCI) and will initialize the Multiprocessor Communications Interface (MPCI) and
synchronize with the other nodes in the system. synchronize with the other nodes in the system.
``RTEMS_SYSINIT_BSP_POST_DRIVERS`` RTEMS_SYSINIT_DRVMGR_LEVEL_2
Initialization step performed right after device drivers are initialized Driver manager level 2 initialization. This step is optional and depends
provided by the Board Support Package. This step is mandatory. on the application configuration. Only available if the driver manager is
enabled.
The final action of the ``rtems_initialize_executive`` directive is to start RTEMS_SYSINIT_DRVMGR_LEVEL_3
multitasking. RTEMS does not return to the initialization context and the Driver manager level 3 initialization. This step is optional and depends
initialization stack may be re-used for interrupt processing. 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 Many of RTEMS actions during initialization are based upon the contents of the
Configuration Table. For more information regarding the format and contents of Configuration Table. For more information regarding the format and contents of
this table, please refer to the chapter :ref:`Configuring a System`. this table, please refer to the chapter :ref:`Configuring a System`.
The final action in the initialization sequence is the initiation of
multitasking. When the scheduler and dispatcher are enabled, the highest
priority, ready task will be dispatched to run. Control will not be returned
to the Board Support Package after multitasking is enabled. The initialization
stack may be re-used for interrupt processing.
Shutting Down RTEMS
-------------------
The ``rtems_shutdown_executive`` directive is invoked by the application to end
multitasking and terminate the system.
Directives Directives
========== ==========
@ -196,46 +318,14 @@ CALLING SEQUENCE:
void rtems_initialize_executive(void); void rtems_initialize_executive(void);
DIRECTIVE STATUS CODES: DIRECTIVE STATUS CODES:
NONE NONE - This function will not return to the caller.
DESCRIPTION: DESCRIPTION:
Iterates through the system initialization linker set and invokes the Iterates through the system initialization linker set and invokes the
registered handlers. The final step is to start multitasking. registered handlers. The final step is to start multitasking.
NOTES: NOTES:
This directive should be called by ``boot_card`` only. This directive should be called by :c:func:`boot_card()` only.
This directive *does not return* to the caller. Errors in the This directive *does not return* to the caller. Errors in the
initialization sequence are usually fatal and lead to a system termination. initialization sequence are usually fatal and lead to a system termination.
.. raw:: latex
\clearpage
.. _rtems_shutdown_executive:
SHUTDOWN_EXECUTIVE - Shutdown RTEMS
-----------------------------------
.. index:: shutdown RTEMS
.. index:: rtems_shutdown_executive
CALLING SEQUENCE:
.. code-block:: c
void rtems_shutdown_executive(
uint32_t result
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
This directive is called when the application wishes to shutdown RTEMS.
The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
and the specified ``result`` code.
NOTES:
This directive *must* be the last RTEMS directive invoked by an application
and it *does not return* to the caller.
This directive may be called any time.

View File

@ -4,7 +4,7 @@
.. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved. .. COMMENT: All rights reserved.
.. _Linker Sets: .. _linker_sets:
Linker Sets Linker Sets
*********** ***********