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.

1 files changed, 89 insertions, 216 deletions

diff --git a/doc/user/init.t b/doc/user/init.t
index 4fe4926bfd..c5ebc0d8c8 100644
--- a/doc/user/init.t
+++ b/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.
+
+@table @dfn
+
+@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
 
-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.
-
-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.
+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.