mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-17 20:41:44 +08:00
285 lines
10 KiB
ReStructuredText
285 lines
10 KiB
ReStructuredText
Initialization Manager
|
||
######################
|
||
|
||
Introduction
|
||
============
|
||
|
||
The Initialization Manager is responsible for
|
||
initiating and shutting down RTEMS. Initiating RTEMS involves
|
||
creating and starting all configured initialization tasks, and
|
||
for invoking the initialization routine for each user-supplied
|
||
device driver. In a multiprocessor configuration, this manager
|
||
also initializes the interprocessor communications layer. The
|
||
directives provided by the Initialization Manager are:
|
||
|
||
- ``rtems_initialize_executive`` - Initialize RTEMS
|
||
|
||
- ``rtems_shutdown_executive`` - Shutdown RTEMS
|
||
|
||
Background
|
||
==========
|
||
|
||
Initialization Tasks
|
||
--------------------
|
||
.. index:: 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.
|
||
|
||
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 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 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
|
||
------------------------------
|
||
|
||
The ``rtems_fatal_error_occurred`` directive will
|
||
be invoked from ``rtems_initialize_executive``
|
||
for any of the following reasons:
|
||
|
||
- If either the Configuration Table or the CPU Dependent
|
||
Information Table is not provided.
|
||
|
||
- If the starting address of the RTEMS RAM Workspace,
|
||
supplied by the application in the Configuration Table, is NULL
|
||
or is not aligned on a four-byte boundary.
|
||
|
||
- If the size of the RTEMS RAM Workspace is not large
|
||
enough to initialize and configure the system.
|
||
|
||
- If the interrupt stack size specified is too small.
|
||
|
||
- If multiprocessing is configured and the node entry in
|
||
the Multiprocessor Configuration Table is not between one and
|
||
the maximum_nodes entry.
|
||
|
||
- If a multiprocessor system is being configured and no
|
||
Multiprocessor Communications Interface is specified.
|
||
|
||
- If no user initialization tasks are configured. At
|
||
least one initialization task must be configured to allow RTEMS
|
||
to pass control to the application at the end of the executive
|
||
initialization sequence.
|
||
|
||
- If any of the user initialization tasks cannot be
|
||
created or started successfully.
|
||
|
||
A discussion of RTEMS actions when a fatal error occurs
|
||
may be found `Announcing a Fatal Error`_.
|
||
|
||
Operations
|
||
==========
|
||
|
||
Initializing RTEMS
|
||
------------------
|
||
|
||
The Initialization Manager ``rtems_initialize_executive``
|
||
directives is called by the ``boot_card`` routine. The ``boot_card``
|
||
routine 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 ``rtems_initialize_executive`` directive uses a system
|
||
initialization linker set to initialize only those parts of the overall RTEMS
|
||
feature set that is necessary for a particular application. See `Linker Sets`_.
|
||
Each RTEMS feature used the application may optionally register an
|
||
initialization handler. The system initialization API is available via``#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.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS`
|
||
The work areas consisting of C Program Heap and the RTEMS Workspace are
|
||
initialized by the Board Support Package. This step is mandatory.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BSP_START`
|
||
Basic initialization step provided by the Board Support Package. This step is
|
||
mandatory.
|
||
|
||
:dfn:`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.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BSP_LIBC`
|
||
Depending on the application configuration the IO library and root filesystem
|
||
is initialized. This step is mandatory.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS`
|
||
This directive performs initialization that must occur between basis RTEMS data
|
||
structure initialization and device driver initialization. In particular, in a
|
||
multiprocessor configuration, this directive will create the MPCI Server Task.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
|
||
Initialization step performed right before device drivers are initialized
|
||
provided by the Board Support Package. This step is mandatory.
|
||
|
||
:dfn:`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.
|
||
|
||
:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS`
|
||
Initialization step performed right after device drivers are initialized
|
||
provided by the Board Support Package. This step is mandatory.
|
||
|
||
The final action of the ``rtems_initialize_executive`` directive
|
||
is to start multitasking. 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 `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
|
||
==========
|
||
|
||
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.
|
||
|
||
INITIALIZE_EXECUTIVE - Initialize RTEMS
|
||
---------------------------------------
|
||
.. index:: initialize RTEMS
|
||
.. index:: start multitasking
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. index:: rtems_initialize_executive
|
||
|
||
.. code:: c
|
||
|
||
void rtems_initialize_executive(void);
|
||
|
||
**DIRECTIVE STATUS CODES:**
|
||
|
||
NONE
|
||
|
||
**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 ``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.
|
||
|
||
SHUTDOWN_EXECUTIVE - Shutdown RTEMS
|
||
-----------------------------------
|
||
.. index:: shutdown RTEMS
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. index:: rtems_shutdown_executive
|
||
|
||
.. code:: 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.
|
||
|
||
.. COMMENT: COPYRIGHT (c) 1988-2014.
|
||
|
||
.. COMMENT: On-Line Applications Research Corporation (OAR).
|
||
|
||
.. COMMENT: All rights reserved.
|
||
|