2008-08-22 Joel Sherrill <joel.sherrill@oarcorp.com>

	* bsp_howto/Makefile.am, bsp_howto/init.t, bsp_howto/intro.t,
	bsp_howto/makefiles.t, bsp_howto/support.t: Update initialization
	sequence. Add another figure.
	* bsp_howto/BSPInitFlowchart-49.eps, bsp_howto/BSPInitFlowchart-49.png: New files.

1 files changed, 161 insertions, 59 deletions

diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t
index 421c638056..6f9c902d0a 100644
--- a/doc/bsp_howto/init.t
+++ b/doc/bsp_howto/init.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2008.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -18,62 +18,97 @@ commonly found in the BSP related to initialization.  The remainder of
 this chapter covers special issues which require attention such
 as interrupt vector table and chip select initialization.
 
-Most of the examples in this chapter will be based on the gen68340 BSP
-initialization code.  Like most BSPs, the initialization for this 
-BSP is divided into two subdirectories under the BSP source directory.
-The gen68340 BSP source code is in the following directory:
+Most of the examples in this chapter will be based on the SPARC/ERC32 and
+m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization
+for these BSP is divided into two subdirectories under the BSP source
+directory.  The BSP source code for these BSPs is in the following
+directories:
 
 @example
 c/src/lib/libbsp/m68k/gen68340
+c/src/lib/libbsp/sparc/erc32
 @end example
 
-The following source code files are in this subdirectory.
-
-@itemize @bullet
-
-@item @code{start340}: assembly language code which contains early
-initialization routines
+Both BSPs contain startup code written in assembly language and C.
+The gen68340 BSP has its early initialization start code in the
+@code{start340} subdirectory and its C startup code in the @code{startup}
+directory.  In the @code{start340} directory are two source files.
+The file @code{startfor340only.s} is the simpler of these files as it only
+has initialization code for a MC68340 board.  The file @code{start340.s}
+contains initialization for a 68349 based board as well.
 
-@item @code{startup}: C code with higher level routines (RTEMS
-initialization related) 
+Similarly, the ERC32 BSP has startup code written in assembly language
+and C.  However, this BSP shares this code with other SPARC BSPs.
+Thus the @code{Makefile.am} explicitly references the following files
+for this functionality.
 
-@end itemize
+@example
+../../sparc/shared/start.S
+../../sparc/shared/bspclean.c
+@end example
 
-@b{NOTE:} The directory @code{start340} is simply named @code{start} or 
-start followed by a BSP designation.
-
-In the @code{start340} directory are two source files.  The file
-@code{startfor340only.s} is the simpler of these files as it only has 
-initialization code for a MC68340 board.  The file @code{start340.s}
-contains initialization for a 68349 based board as well.
+@b{NOTE:} In most BSPs, the directory named @code{start340} in the
+gen68340 BSP would be simply named @code{start} or start followed by a
+BSP designation.
 
 @section Required Global Variables
 
 Although not strictly part of initialization, there are a few global
-variables assumed to exist by many support components.  These 
-global variables are normally not defined by the BSP since the RTEMS
-Project strives to avoid duplication as much as possible.
-The following is a list of these global variables:
+variables assumed to exist by reusable device drivers.  These global
+variables should only defined by the BSP when using one of these device
+drivers.
 
-@itemize @bullet
-@item @code{Configuration} is the RTEMS Configuration Table generated
-by @code{<rtems/confdefs.h>}.
+The BSP author probably should be aware of the @code{Configuration}
+Table structure generated by @code{<rtems/confdefs.h>} during debug but
+should not explicitly reference it in the source code.  There are helper
+routines provided by RTEMS to access individual fields.
 
-@end itemize
+In older RTEMS versions, the BSP included a number of required global
+variables.  We have made every attempt to eliminate these in the interest
+of simplicity.
 
 @section Board Initialization
 
 This section describes the steps an application goes through from the
 time the first BSP code is executed until the first application task
-executes.  The routines invoked during this will be discussed and
-their location in the RTEMS source tree pointed out.
+executes.  The following figure illustrates the program flow during
+this sequence:
+
+@ifset use-ascii
+IMAGE NOT AVAILABLE IN ASCII VERSION
+@end ifset
+
+@ifset use-tex
+@image{BSPInitFlowchart-49,6in,,Initialization Sequence,.png}
+@c      @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
+@end ifset
+
+@ifset use-html
+@html
+<center>
+<IMG SRC="BSPInitFlowchart-49.png" WIDTH=800 ALT="Initialization Sequence">
+</center>
+@end html
+@end ifset
+
+The above figure illustrates the flow from assembly language start code
+to the shared @code{bootcard.c} framework then through the C Library,
+RTEMS, device driver initialization phases, and the context switch
+to the first application task.  After this, the application executes
+until it calls @code{exit}, @code{rtems_shutdown_executive}, or some
+other normal termination initiating routine and control is returned
+to @code{bootcard.c} which allows the BSP to perform some clanup in C
+(@code{bsp_cleanup}) and then @code{boot_card} returns to the assembly
+language which initially invoked it.
+
+The routines invoked during this will be discussed and their location
+in the RTEMS source tree pointed out as we discuss each.
 
 @subsection Start Code - Assembly Language Initialization
 
-The assembly language code in the directory @code{start} is
-the first part of the application to execute.  It is 
-responsible for initializing the processor and board enough to execute
-the rest of the BSP.  This includes:
+The assembly language code in the directory @code{start} is the first part
+of the application to execute.  It is responsible for initializing the
+processor and board enough to execute the rest of the BSP.  This includes:
 
 @itemize @bullet
 @item initializing the stack
@@ -82,26 +117,28 @@ the rest of the BSP.  This includes:
 @item copy the initialized data from ROM to RAM
 @end itemize
 
-The general rule of thumb is that the
-start code in assembly should do the minimum necessary to allow C code
-to execute to complete the initialization sequence.  
+The general rule of thumb is that the start code in assembly should
+do the minimum necessary to allow C code to execute to complete the
+initialization sequence.
 
 The initial assembly language start code completes its execution by
 invoking the shared routine @code{boot_card()}.
 
 The label (symbolic name) associated with the starting address of the
-program is typically called @code{start}.  The start object file
-is the first object file linked into the program image so it is insured
-that the start code is at offset 0 in the @code{.text} section.  It is
-the responsibility of the linker script in conjunction with the 
-compiler specifications file to put the start code in the correct location
-in the application image.
+program is typically called @code{start}.  The start object file is the
+first object file linked into the program image so it is ensured that
+the start code is at offset 0 in the @code{.text} section.  It is the
+responsibility of the linker script in conjunction with the compiler
+specifications file to put the start code in the correct location in
+the application image.
 
 @subsection boot_card() - Boot the Card
 
-The @code{boot_card()} is the first C code invoked.  Most of the BSPs
-use the same shared version of @code{boot_card()} which is located in
-the following file:
+The @code{boot_card()} is the first C code invoked.  This file is the
+core component in the RTEMS BSP Initialization Framework and provides
+the proper sequencing of initialization steps for the BSP, RTEMS and
+device drivers. All BSPs use the same shared version of @code{boot_card()}
+which is located in the following file:
 
 @example
 c/src/lib/libbsp/shared/bootcard.c
@@ -111,23 +148,88 @@ The @code{boot_card()} routine performs the following functions:
 
 @itemize @bullet
 
-@item invokes the BSP specific routine @code{bsp_start()},
+@item It disables processor interrupts.
+
+@item It sets the global program name and command line argument variables
+for later use by the application.
+
+@item If the macro is BSP_BOOTCARD_HANDLES_RAM_ALLOCATION is defined, it
+will invoke the BSP specific @code{bsp_get_work_area} function to obtain
+information on the amount and location of BSP RAM that is available to
+be allocated to the C Program Heap and RTEMS Workspace.  If the amount
+of memory available for the RTEMS Workspace is less than that required
+by the application (e.g. @code{rtems_configuration_get_work_space_size()},
+then a message is printed using @code{printk}, @code{bsp_cleanup} is
+invoked, and -1 is return to the assembly language start code.  BSPs which
+use this memory allocation functionality in @code{bootcard.c}
+must invoke the RTEMS specific autoconf macro
+@code{RTEMS_BSP_BOOTCARD_HANDLES_RAM_ALLOCATION} in the BSP's
+@code{configure.ac} file.
+
+@item It invokes the BSP specific routine @code{bsp_start()} which is
+written in C and thus able to perform more advanced initialization.
+Often MMU and bus initialization occurs here.
+
+@item It invokes the RTEMS directive
+@code{rtems_initialize_data_structures()} to initialize the RTEMS
+executive to a state where objects can be created but tasking is not
+enabled.
+
+@item If the macro is BSP_BOOTCARD_HANDLES_RAM_ALLOCATION is defined,
+it will calculate the memory available for the C Program Heap and invoke
+the initialization routine for the C Library with this information.
+
+@item It invokes the BSP specific routine @code{bsp_pretasking_hook}. On
+most BSPs which utilize the framework, this routine does nothing.
+
+@item If @code{RTEMS_DEBUG} is enabled, then the RTEMS debug mask level
+is inialized appropriately.
+
+@item It invokes the RTEMS directive
+@code{rtems_initialize_before_drivers()} to initialize the MPCI Server
+thread in a multiprocessor configuration and execute API specific
+extensions.
+
+@item It invokes the BSP specific routine @code{bsp_predriver_hook}. For
+most BSPs, the implementation of this routine does nothing.  However,
+on some BSPs, required subsystems which utilize the C Library
+(e.g. @code{malloc} in particular) may be initialized at this point.
+
+@item It invokes the RTEMS directive
+@code{rtems_initialize_device_drivers()} to initialize the statically
+configured set of device drivers in the order they were specified in
+the Configuration Table.
+
+@item It invokes the BSP specific routine @code{bsp_postdriver_hook}. For
+most BSPs, the implementation of this routine does nothing.  However, some
+BSPs use this hook and perform some initialization which must be done at
+this point in the initialization sequence.  This is the last opportunity
+for the BSP to insert BSP specific code into the initialization sequence.
+
+@item It invokes the RTEMS directive
+@code{rtems_initialize_start_multitasking()} which starts multitasking and context switches to the first task.  @code{boot_card()} will not return until the application is shutdown.  As part of this sequence the following actions occur:
 
-@item invokes the RTEMS directive @code{rtems_initialize_executive_early()}
-to initialize the executive, C Library, and all device drivers but
-return without initiating multitasking or enabling interrupts,
+@itemize @bullet
 
-@item invokes the shared @code{main()} in the same file as
-@code{boot_card()} which does not return until the
-@code{rtems_shutdown_executive} directive is called, and
+@item RTEMS will context switch to the first application task.  As a
+side-effect of this context switch, processor interrupts will be enabled.
+This is often the source of a fatal error during BSP development because
+the BSP did not clear and/or disable all interrupt sources and a spurious
+interrupt will occur .
+
+@item When in the context of the first task but before its body has been
+entered, any C++ Global Constructors will be invoked.
+
+@end itemize
 
-@item invokes the BSP specific routine @code{bsp_cleanup()} to perform
-any necessary board specific shutdown actions.
+@item Finally after the application shutsdown RTEMS and control is
+return to @code{boot_card()} from RTEMS, it invokes the BSP specific
+routine @code{bsp_cleanup()} to perform any necessary board specific
+shutdown actions.
 
 @end itemize
 
-It is important to note that the executive and much of the
-support environment must be initialized before invoking @code{main()}.
+That's it.  We just went through the entire sequence. 
 
 @subsection bsp_start() - BSP Specific Initialization
 
@@ -180,7 +282,7 @@ support library and, most importantly, invokes the C++ global
 constructors.  
 
 The precise placement of when @code{main()} is invoked in the 
-RTEMS initialization sequence insures that C Library and non-blocking
+RTEMS initialization sequence ensures that C Library and non-blocking
 calls can be made in global C++ constructors.
 
 The shared implementation of this routine is located in the following file: