forked from Imagelibrary/rtems
Use linker set for system initialization
Make rtems_initialize_data_structures(), rtems_initialize_before_drivers() and rtems_initialize_device_drivers() static. Rename rtems_initialize_start_multitasking() to rtems_initialize_executive() and call the registered system initialization handlers in this function. Add system initialization API available via #include <rtems/sysinit.h>. Update the documentation accordingly. This is no functional change, only the method to call the existing initialization routines changes. Instead of direct function calls a table of function pointers contained in the new RTEMS system initialization linker set is used. This table looks like this (the actual addresses depend on the target). nm *.exe | grep _Linker | sort 0201a2d0 D _Linker_set__Sysinit_begin 0201a2d0 D _Linker_set__Sysinit_bsp_work_area_initialize 0201a2d4 D _Linker_set__Sysinit_bsp_start 0201a2d8 D _Linker_set__Sysinit_rtems_initialize_data_structures 0201a2dc D _Linker_set__Sysinit_bsp_libc_init 0201a2e0 D _Linker_set__Sysinit_rtems_initialize_before_drivers 0201a2e4 D _Linker_set__Sysinit_bsp_predriver_hook 0201a2e8 D _Linker_set__Sysinit_rtems_initialize_device_drivers 0201a2ec D _Linker_set__Sysinit_bsp_postdriver_hook 0201a2f0 D _Linker_set__Sysinit_end Add test sptests/spsysinit01. Update #2408.
This commit is contained in:
Sebastian Huber
303
doc/user/init.t
303
doc/user/init.t
@@ -16,10 +16,7 @@ also initializes the interprocessor communications layer. The
|
||||
directives provided by the Initialization Manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{@value{DIRPREFIX}initialize_data_structures} - Initialize RTEMS Data Structures
|
||||
@item @code{@value{DIRPREFIX}initialize_before_drivers} - Perform Initialization Before Device Drivers
|
||||
@item @code{@value{DIRPREFIX}initialize_device_drivers} - Initialize Device Drivers
|
||||
@item @code{@value{DIRPREFIX}initialize_start_multitasking} - Complete Initialization and Start Multitasking
|
||||
@item @code{@value{DIRPREFIX}initialize_executive} - Initialize RTEMS
|
||||
@item @code{@value{DIRPREFIX}shutdown_executive} - Shutdown RTEMS
|
||||
@end itemize
|
||||
|
||||
@@ -58,12 +55,12 @@ 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 @i{initialization thread} is not
|
||||
initialization and the @i{initialization context} is not
|
||||
a task in any sense and the user should be very careful
|
||||
during initialzation.
|
||||
during initialization.
|
||||
|
||||
The BSP must ensure that the there is enough stack
|
||||
space reserved for the initialization "thread" to
|
||||
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
|
||||
@@ -125,71 +122,96 @@ may be found @ref{Fatal Error Manager Announcing a Fatal Error}.
|
||||
|
||||
@subsection Initializing RTEMS
|
||||
|
||||
The Initialization Manager directives are called by the
|
||||
Board Support Package framework as part of its initialization
|
||||
sequence. RTEMS assumes that the Board Support Package
|
||||
successfully completed its initialization activities. These
|
||||
directives initialize RTEMS by performing the following actions:
|
||||
The Initialization Manager @code{@value{DIRPREFIX}initialize_executive}
|
||||
directives is called by the @code{boot_card} routine. The @code{boot_card}
|
||||
routine is invoked by the Board Support Package once a basic C run-time
|
||||
environment is set up. This consists of
|
||||
|
||||
@itemize @bullet
|
||||
@item Initializing internal RTEMS variables;
|
||||
@item Allocating system resources;
|
||||
@item Creating and starting the Idle Task;
|
||||
@item Initialize all device drivers;
|
||||
@item Creating and starting the user initialization task(s); and
|
||||
@item Initiating multitasking.
|
||||
@item a valid and accessible text section, read-only data, read-write data and
|
||||
zero-initialized data,
|
||||
@item an initialization stack large enough to initialize the rest of the Board
|
||||
Support Package, RTEMS and the device drivers,
|
||||
@item all registers and components mandated by Application Binary Interface, and
|
||||
@item disabled interrupts.
|
||||
@end itemize
|
||||
|
||||
The initialization directives MUST be called in the proper
|
||||
sequence before any blocking directives may be used. The services
|
||||
in this manager should be invoked just once per application
|
||||
and in precisely the following order:
|
||||
The @code{@value{DIRPREFIX}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. @xref{Linker
|
||||
Sets}. Each RTEMS feature used the application may optionally register an
|
||||
initialization handler. The system initialization API is available via
|
||||
@code{#included <rtems/sysinit.h>}.
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{@value{DIRPREFIX}initialize_data_structures}
|
||||
@item @code{@value{DIRPREFIX}initialize_before_drivers}
|
||||
@item @code{@value{DIRPREFIX}initialize_device_drivers}
|
||||
@item @code{@value{DIRPREFIX}initialize_start_multitasking}
|
||||
@end itemize
|
||||
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.
|
||||
|
||||
It is recommended that the Board Support Package use the
|
||||
provided framework which will invoke these services as
|
||||
part of the executing the function @code{boot_card} in the
|
||||
file @code{c/src/lib/libbsp/shared/bootcard.c}. This
|
||||
framework will also assist in allocating memory to the
|
||||
RTEMS Workspace and C Program Heap and initializing the
|
||||
C Library.
|
||||
@table @dfn
|
||||
|
||||
The effect of calling any blocking RTEMS directives before
|
||||
@code{@value{DIRPREFIX}initialize_start_multitasking}
|
||||
is unpredictable but guaranteed to be bad. After the
|
||||
directive @code{@value{DIRPREFIX}initialize_data_structures}
|
||||
is invoked, it is permissible to allocate RTEMS objects and
|
||||
perform non-blocking operations. But the user should be
|
||||
distinctly aware that multitasking is not available yet
|
||||
and they are @b{NOT} executing in a task context.
|
||||
@item 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.
|
||||
|
||||
@item RTEMS_SYSINIT_BSP_START
|
||||
Basic initialization step provided by the Board Support Package. This step is
|
||||
mandatory.
|
||||
|
||||
@item 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.
|
||||
|
||||
@item RTEMS_SYSINIT_BSP_LIBC
|
||||
Depending on the application configuration the IO library and root filesystem
|
||||
is initialized. This step is mandatory.
|
||||
|
||||
@item 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.
|
||||
|
||||
@item RTEMS_SYSINIT_BSP_PRE_DRIVERS
|
||||
Initialization step performed right before device drivers are initialized
|
||||
provided by the Board Support Package. This step is mandatory.
|
||||
|
||||
@item 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.
|
||||
|
||||
@item RTEMS_SYSINIT_BSP_POST_DRIVERS
|
||||
Initialization step performed right after device drivers are initialized
|
||||
provided by the Board Support Package. This step is mandatory.
|
||||
|
||||
@end table
|
||||
|
||||
The final action of the @code{@value{DIRPREFIX}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 @ref{Configuring a System}.
|
||||
|
||||
The final step in the initialization sequence is the
|
||||
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 until the
|
||||
@code{@value{DIRPREFIX}shutdown_executive} directive is called.
|
||||
This directive is called as a side-effect of POSIX calls
|
||||
including @code{exit}.
|
||||
Package after multitasking is enabled. The initialization stack may be re-used
|
||||
for interrupt processing.
|
||||
|
||||
@subsection Shutting Down RTEMS
|
||||
|
||||
The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
|
||||
application to end multitasking and return control to the board
|
||||
support package. The board support package resumes execution at
|
||||
the code immediately following the invocation of the
|
||||
@code{@value{DIRPREFIX}initialize_start_multitasking} directive.
|
||||
application to end multitasking and terminate the system.
|
||||
|
||||
@section Directives
|
||||
|
||||
@@ -199,144 +221,7 @@ directives and describes the calling sequence, related
|
||||
constants, usage, and status codes.
|
||||
|
||||
@page
|
||||
@subsection INITIALIZE_DATA_STRUCTURES - Initialize RTEMS Data Structures
|
||||
|
||||
@cindex initialize RTEMS data structures
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@findex rtems_initialize_data_structures
|
||||
@example
|
||||
void rtems_initialize_data_structures(void);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
NOT SUPPORTED FROM Ada BINDING
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading DIRECTIVE STATUS CODES:
|
||||
|
||||
NONE
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
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. This directive returns
|
||||
to the caller after completing the basic RTEMS initialization.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
The Initialization Manager directives must be used in the
|
||||
proper sequence and invokved only once in the life of an application.
|
||||
|
||||
This directive must be invoked with interrupts disabled.
|
||||
Interrupts should be disabled as early as possible in
|
||||
the initialization sequence and remain disabled until
|
||||
the first context switch.
|
||||
|
||||
@page
|
||||
@subsection INITIALIZE_BEFORE_DRIVERS - Perform Initialization Before Device Drivers
|
||||
|
||||
@cindex initialize RTEMS before device drivers
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@findex rtems_initialize_before_drivers
|
||||
@example
|
||||
void rtems_initialize_before_drivers(void);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
NOT SUPPORTED FROM Ada BINDING
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading DIRECTIVE STATUS CODES:
|
||||
|
||||
NONE
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This directive is called by the Board Support Package as the
|
||||
second step in initializing RTEMS. 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. This directive returns to the caller after
|
||||
completing the basic RTEMS initialization.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
The Initialization Manager directives must be used in the
|
||||
proper sequence and invokved only once in the life of an application.
|
||||
|
||||
This directive must be invoked with interrupts disabled.
|
||||
Interrupts should be disabled as early as possible in
|
||||
the initialization sequence and remain disabled until
|
||||
the first context switch.
|
||||
|
||||
@page
|
||||
@subsection INITIALIZE_DEVICE_DRIVERS - Initialize Device Drivers
|
||||
|
||||
@cindex initialize device drivers
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@findex rtems_initialize_device_drivers
|
||||
@example
|
||||
void rtems_initialize_device_drivers(void);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
NOT SUPPORTED FROM Ada BINDING
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading DIRECTIVE STATUS CODES:
|
||||
|
||||
NONE
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This directive is called by the Board Support Package as the
|
||||
third step in initializing RTEMS. This directive initializes
|
||||
all statically configured device drivers and performs all RTEMS
|
||||
initialization which requires device drivers to be initialized.
|
||||
|
||||
In a multiprocessor configuration, this service will initialize
|
||||
the Multiprocessor Communications Interface (MPCI) and synchronize
|
||||
with the other nodes in the system.
|
||||
|
||||
After this directive is executed, control will be returned to
|
||||
the Board Support Package framework.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
The Initialization Manager directives must be used in the
|
||||
proper sequence and invokved only once in the life of an application.
|
||||
|
||||
This directive must be invoked with interrupts disabled.
|
||||
Interrupts should be disabled as early as possible in
|
||||
the initialization sequence and remain disabled until
|
||||
the first context switch.
|
||||
|
||||
@page
|
||||
@subsection INITIALIZE_START_MULTITASKING - Complete Initialization and Start Multitasking
|
||||
@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS
|
||||
|
||||
@cindex initialize RTEMS
|
||||
@cindex start multitasking
|
||||
@@ -344,9 +229,9 @@ the first context switch.
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@findex rtems_initialize_start_multitasking
|
||||
@findex rtems_initialize_executive
|
||||
@example
|
||||
void rtems_initialize_start_multitasking(void);
|
||||
void rtems_initialize_executive(void);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@@ -362,24 +247,15 @@ NONE
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This directive initiates multitasking and performs a context switch to the
|
||||
first user application task and may enable interrupts as a side-effect of
|
||||
that context switch. The context switch saves the executing context. The
|
||||
application runs now. The directive rtems_shutdown_executive() will return
|
||||
to the saved context. The exit() function will use this directive.
|
||||
|
||||
After a return to the saved context a fatal system state is reached. The
|
||||
fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
|
||||
passed to rtems_shutdown_executive().
|
||||
Iterates through the system initialization linker set and invokes the
|
||||
registered handlers. The final step is to start multitasking.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
This directive @b{DOES NOT RETURN} to the caller.
|
||||
This directive should be called by @code{boot_card} only.
|
||||
|
||||
This directive causes all nodes in the system to
|
||||
verify that certain configuration parameters are the same as
|
||||
those of the local node. If an inconsistency is detected, then
|
||||
a fatal error is generated.
|
||||
This directive @b{does not return} to the caller. Errors in the initialization
|
||||
sequence are usually fatal and lead to a system termination.
|
||||
|
||||
@page
|
||||
@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS
|
||||
@@ -411,16 +287,13 @@ NONE
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This directive is called when the application wishes
|
||||
to shutdown RTEMS and return control to the board support
|
||||
package. The board support package resumes execution at the
|
||||
code immediately following the invocation of the
|
||||
@code{@value{DIRPREFIX}initialize_executive} directive.
|
||||
This directive is called when the application wishes to shutdown RTEMS. The
|
||||
system is terminated with a fatal source of @code{RTEMS_FATAL_SOURCE_EXIT} and
|
||||
the specified @code{result} code.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
This directive MUST be the last RTEMS directive
|
||||
invoked by an application and it DOES NOT RETURN to the caller.
|
||||
This directive @b{must} be the last RTEMS directive
|
||||
invoked by an application and it @b{does not return} to the caller.
|
||||
|
||||
This directive should not be invoked until the
|
||||
executive has successfully completed initialization.
|
||||
This directive may be called any time.
|
||||
|
||||
Reference in New Issue
Block a user