Corrections from Jennifer and Jeff plus additions to the initialization

chapter.

5 files changed, 285 insertions, 87 deletions

diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile
index 1110252d3b..f61d8b5739 100644
--- a/doc/bsp_howto/Makefile
+++ b/doc/bsp_howto/Makefile
@@ -43,8 +43,8 @@ $(PROJECT).ps: $(PROJECT).dvi
 
 # run texi2dvi twice to generate the xref's properly.
 $(PROJECT).dvi: $(FILES)
-	$(TEXI2DVI) -v $(PROJECT).texi
-	texi2dvi -v $(PROJECT).texi
+	$(TEXI2DVI) $(PROJECT).texi
+	$(TEXI2DVI) $(PROJECT).texi
 
 html: dirs $(FILES)
 	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t
index 50137ad754..669d5f9d3b 100644
--- a/doc/bsp_howto/init.t
+++ b/doc/bsp_howto/init.t
@@ -11,27 +11,225 @@
 @section Introduction
 
 The initialization code is the first piece of code executed when there's a
-reset/reboot. It aims at initializing the main functions of the board. As
-an introduction I advise you to give a look to the gen68340 BSP
-initialization code, which is split onto t wo directories: 
+reset/reboot. Its purpose is to initialize the board for the application.
+This chapter contains a narrative description of the initialization
+process followed by a description of each of the files and routines
+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 in the following directory:
+
+@example
+c/src/lib/libbsp/m68k/gen68340: 
+@end example
 
 @itemize @bullet
 
-@item $BSP340_ROOT/start340/: assembly language code which contains early
-initialization routines,
+@item @code{start340}: assembly language code which contains early
+initialization routines
 
-@item $BSP340_ROOT/startup/: C code with higher level routines (RTEMS
-initialization related). 
+@item @code{startup}: C code with higher level routines (RTEMS
+initialization related) 
 
 @end itemize
 
+@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.
+
 @section Board Initialization
 
-You'll find two files under the $BSP340_ROOT/start340/ directory, open
-rtemsfor340only.s which holds initialization code for a MC68340 board only
-and is simpler. 
+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.
+
+@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:
+
+@itemize @bullet
+@item initializing the stack
+@item zeroing out the uninitialized data section @code{.bss}
+@item disabling external interrupts
+@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 initial assembly language start code completes its execution by
+invoking the shared routine @code{boot_card()}.
+
+@subsection boot_card() - Boot the Card
+
+The @code{boot_card()} is the first C code invoked.  Most of the BSPs
+use the sams shared version of @code{boot_card()} which is located in
+the following file:
+
+@example
+c/src/lib/libbsp/shared/main.c
+@end example
+
+The @code{boot_card()} routine performs the following functions:
+
+@itemize @bullet
+
+@item initializes the shared fields of the CPU Configuration Table
+(variable name @code{Cpu_table}) to a default state,
+
+@item copies the application's RTEMS Configuration Table
+(variable name @code{Configuration}) to the BSP's Configuration
+Table (variable name @code{BSP_Configuration}) so it can be modified
+as necessary without copying the original table,
+
+@item invokes the BSP specific routine @code{bsp_start()},
+
+@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,
+
+@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 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()}.
+
+@subsection bsp_start() - BSP Specific Initialization
+
+This is the first BSP specific C routine to execute during system
+initialization.  This routine often performs required fundamental
+hardware initialization such as setting bus controller registers
+that do not have a direct impact on whether or not C code can execute.
+The source code for this routine is usually found in the following
+file:
+
+@example
+c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
+@end example
+
+This routine is also responsible for overriding the default settings
+in the CPU Configuration Table and setting port specific entries
+in this table.  This routine will typically install routines
+for one or more of the following initialization hooks:
+
+@itemize @bullet
+@item BSP Pretasking Hook
+@item BSP Predriver Hook
+@item BSP Postdriver Hook
+@end itemize
+
+One of the most important functions performed by this routine
+is determining where the RTEMS Executive Work Space is to be
+located in memory.  All RTEMS objects and task stacks will be
+allocated from this Workspace.  The RTEMS Workspace is distinct
+from the application heap used for @code{malloc()}.
+
+Many BSPs place this area at the end of RAM although this is
+certainly not a requirement.
+
+After completing execution, this routine returns to the
+@code{boot_card()} routine.
+
+@subsection main() - C Main
+
+This routine is the C main entry point.  This is a special routine 
+and the GNU Compiler Suite treats it as such.  The GNU C Compiler
+recognizes @code{main()} and automatically inserts a call to the
+compiler run-time support routine @code{__main()} as the first
+code executed in @code{main()}.
+
+The routine @code{__main()} initializes the compiler's basic run-time
+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
+calls can be made in global C++ constructors.
+
+The shared implementation of this routine is located in the following file:
+
+@example
+c/src/lib/libbsp/shared/main.c
+@end example
+
+In addition to the implicit invocation of @code{__main}, this 
+routine performs some explitit initialization.  This routine 
+sets the variable @code{rtems_progname} and initiates 
+multitasking via a call to the RTEMS directive
+@code{rtems_initialize_executive_late}.  It is important to note
+that the executive does not return to this routine until the
+RTEMS directive @code{rtems_shutdown_executive} is invoked.
+
+@subsection RTEMS Pretasking Callback
+
+The @code{pretasking_hook} entry in the RTEMS CPU Configuration
+Table may be the address of a user provided routine that is
+invoked once RTEMS initialization is complete but before interrupts
+and tasking are enabled.  No tasks -- not even the IDLE task -- have
+been created when this hook is invoked.  The pretasking hook is optional.
+
+Although optional, most of the RTEMS BSPs provide a pretasking hook
+callback.  This routine is usually called @code{bsp_pretasking_hook}
+and is found in the file:
+
+@example
+c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
+@end example
+
+The @code{bsp_pretasking_hook()} routine is the appropriate place to
+initialize any support components which depend on the RTEMS APIs.
+Most BSPs initialize the RTEMS C Library support in their
+implementation of @code{bsp_pretasking_hook()}.  This initialization
+includes the application heap as well as the reentrancy support
+for the C Library.
+
+@subsection RTEMS Predriver Callback
+
+XXX is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+
+@subsection Device Driver Initialization
+
+At this point in the initialization sequence, the initialization 
+routines for all of the device drivers specified in the Device
+Driver Table are invoked.
+
+@subsection RTEMS Postdriver Callback
+
+XXX is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+
+
+@section The Interrupts Vector Table
+
 
-@subsection The Interrupts Vector Table
 
 After the entry label starts a code section in which some room is
 allocated for the table of interrupts vectors. They are assigned to the
@@ -44,7 +242,7 @@ $BSP_ROOT/startup/dumpanic.c - that pri nts which address caused the
 interrupt and the contents of the registers, stack...), but this should
 not return. 
 
-@subsection Chip Select Initialization
+@section Chip Select Initialization
 
 When the microprocessor accesses a memory area, address decoding is
 handled by an address decoder (!), so that the microprocessor knows which
@@ -57,13 +255,13 @@ the linkcmds settings. In this BSP ROM and RAM addresses can be found in
 both the linkcmds and initialization code, but this is not a great way to
 do, better use some shared variables . 
 
-@subsection Integrated processor registers initialization
+@section Integrated processor registers initialization
 
 There are always some specific integrated processor registers
 initialization to do. Integrated processors' user manuals often detail
 them. 
 
-@subsection Data section recopy
+@section Data section recopy
 
 The next initialization part can be found in
 $BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is
@@ -85,7 +283,7 @@ Then control is passed to the RTEMS-specific initialization code.
 
 @section RTEMS-Specific Initialization
 
-@subsection The RTEMS configuration table
+@section The RTEMS configuration table
 
 The RTEMS configuration table contains the maximum number of objects RTEMS
 can handle during the application (e.g. maximum number of tasks,
@@ -101,7 +299,7 @@ The BSP_Configuration label points on this table.
 For more information on the RTEMS configuration table, refer to C user's
 guide, chapter 23 <insert a link here>. 
 
-@subsection RTEMS initialization procedure
+@section RTEMS initialization procedure
 
 The RTEMS initialization procedure is described in the 3rd chapter of the
 C user's manual <insert a link here>. Please read it carefully. 
@@ -125,19 +323,6 @@ It starts libc support (needed to allocate some memory using C primitive
 malloc for example). Heap size must be passed in argument, this is the one
 which is defined in the linkcmds (cf. 5.) 
 
-@end table
-
-@item bspstart.c
-
-@table @b
-@item bsp_start
-
-Here the user and application specific configuration table has been
-"loaded" so that BSP_Configuration is up to date. 
-
-You can make last modifications here, for instance reserve more room for
-the RTEMS Work Space, or adjust the heap size (you can for example use the
-memory left for the lone heap). 
 
 @end table
 
@@ -153,7 +338,7 @@ Return control to the monitor.
 
 @end table
 
-@subsection Drivers initialization
+@section Drivers initialization
 
 The Driver Address Table is part of the RTEMS configuration table. It
 defines RTEMS drivers entry points (initialization, open, close, read,
diff --git a/doc/bsp_howto/linkcmds.t b/doc/bsp_howto/linkcmds.t
index 6b92ed1326..3bfb28b4be 100644
--- a/doc/bsp_howto/linkcmds.t
+++ b/doc/bsp_howto/linkcmds.t
@@ -13,7 +13,7 @@
 The @code{linkcmds} file is a script which is passed to the linker at linking
 time.  This file describes the memory configuration of the board as needed
 to link the program.  Specifically it specifies where the code and data
-for your application will reside in memory.
+for the application will reside in memory.
 
 @section Program Sections
 
@@ -37,7 +37,8 @@ one generally doesn't care about them.  In a personal computer,
 a program is nearly always stored on disk and executed in RAM.  Things
 are a bit different for embedded targets: the target will execute the
 program each time it is rebooted or switched on.   The application
-program is stored in ROM. On the other hand, data processing occurs in RAM. 
+program is stored in non-volatile memory such as ROM, PROM, EEPROM,
+or Flash. On the other hand, data processing occurs in RAM. 
 
 This leads us to the structure of an embedded program.  In rough terms,
 an embedded program is made of sections.  It is the responsibility of
@@ -69,7 +70,7 @@ to zero at program start.  This is not required by the ISO/ANSI C Standard
 but is such a common requirement that most BSPs do this.
 
 That brings us up to the notion of the image of an executable: it consists
-in the set of the program sections. 
+of the set of the sections that together constitute the application. 
 
 @section Image of an Executable
 
@@ -83,8 +84,7 @@ some of his sections going into the ROM.
 
 The connection between a section and where that section is loaded into
 memory is made at link time.  One has to let the linker know where
-the different sections location are to be placed once they are in
-memory. 
+the different sections are to be placed once they are in memory. 
 
 The following example shows a simple layout of program sections.  With
 some object formats, there are many more sections but the basic 
@@ -131,7 +131,7 @@ RamSize = DEFINED(RamSize) ? RamSize : 4M;
  *  Set the amount of RAM to be used for the application heap.  Objects
  *  allocated using malloc() come from this area.  Having a tight heap size
  *  is somewhat difficult and multiple attempts to squeeze it may be needed
- *  if you want to save the memory usage.  If you allocate all objects from
+ *  reducing memory usage is important.  If all objects are allocated from
  *  the heap at system initialization time, this eases the sizing of the
  *  application heap.  
  *
@@ -357,7 +357,7 @@ SECTIONS @{
 @section Initialized Data
 
 Now there's a problem with the initialized data: the @code{.data} section
-has to be in RAM as these data may be modified during the program execution.
+has to be in RAM as this data may be modified during the program execution.
 But how will the values be initialized at boot time?
 
 One approach is to place the entire program image in RAM and reload 
@@ -369,8 +369,8 @@ environment, it is cumbersome.
 The solution is to place a copy of the initialized data in a separate 
 area of memory and copy it into the proper location each time the
 program is started.  It is common practice to place a copy of the initialized
-@code{.data} section the end of the code (@code{.text} section
-(i.e. in ROM) when building a PROM image. The GNU tool @code{objcopy}
+@code{.data} section at the end of the code (@code{.text}) section
+in ROM when building a PROM image. The GNU tool @code{objcopy}
 can be used for this purpose. 
 
 The following figure illustrates the steps a linked program goes through
@@ -410,9 +410,9 @@ $(basename $@@).exe \
 $(basename $@@).exe
 @end example
 
-NOTE: The address at which the copy of the @code{.data} section is
-specified by extracting the address of the end of the @code{.text}
-section (i.e. in ROM) with an @code{awk} script.  The details of how
+NOTE: The address of the "copy of @code{.data} section" is
+created by extracting the last address in the @code{.text}
+section with an @code{awk} script.  The details of how
 this is done are not relevant.
 
 Step 3 shows the final executable image as it logically appears in
diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t
index c79ea01674..cf815f10a1 100644
--- a/doc/bsp_howto/makefiles.t
+++ b/doc/bsp_howto/makefiles.t
@@ -62,16 +62,17 @@ user configured networking.
 
 There is a @code{Makefile.in} in most of the directories in a BSP. This
 class of Makefile lists the files to be built as part of the driver.
-Do not forget to add the reference to a new file in the @code{Makefile.in}
-it is created! 
+When adding new files to an existing directory, Do not forget to add
+the new files to the list of files to be built in the @code{Makefile.in}.
 
 @b{NOTE:} The @code{Makefile.in} files are ONLY processed during the configure
-process of a RTEMS build. It means that, when you're working on the design
-of your BSP, and that you're adding a file to a folder and to the
-corresponding makefile.in, it will not be taken into account! You have to
-run configure again or modify the @code{Makefile} (the result of the 
-configure process) by hand.  This file will be in a directory such as 
-the following:
+process of a RTEMS build. Therefore, when developing 
+a BSP and adding a new file to a @code{Makefile.in}, the 
+already generated @code{Makefile} will not include the new references.
+This results in the new file not being be taken into account! 
+The @code{configure} script must be run again or the @code{Makefile}
+(the result of the configure process) modified by hand.  This file will
+be in a directory such as the following:
 
 @example
 MY_BUILD_DIR/c/src/lib/libbsp/CPU/BSP/DRIVER
@@ -125,8 +126,8 @@ It is strongly advised to use these template Makefiles since they
 encapsulate a number of build rules along with the compile and link
 time options necessary to execute on the target board.
 
-There are template Makefiles provided for each of the classes of RTEMS
-Makefiles.  This include Makefiles to:
+There is a template Makefile provided for each of class of RTEMS
+Makefiles.  The purpose of each class of RTEMS Makefile is to:
 
 @itemize @bullet
 @item call recursively the makefiles in the directories beneath
@@ -190,7 +191,7 @@ endif
 @subsection Creating a New BSP Make Customization File
 
 The basic steps for creating a @code{make/custom} file for a new BSP
-is as follows:
+are as follows:
 
 @itemize @bullet
 
@@ -201,7 +202,7 @@ RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.
 
 @end itemize
 
-It is generally easier to copy a @code{make/custom} file which is for a
-BSP close to your own.
+It is generally easier to copy a @code{make/custom} file from a
+BSP similar to the one being developed.
 
 
diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t
index 0ca96d02d7..a14f7d6a49 100644
--- a/doc/bsp_howto/target.t
+++ b/doc/bsp_howto/target.t
@@ -24,7 +24,7 @@ into one of the following categories.
 @section CPU Dependent
 
 This class of code includes the foundation
-routines for the executive proper such as as the context switch and
+routines for the executive proper such as the context switch and
 the interrupt subroutine implementations.  Sources for the supported
 processor families can be found in @code{c/src/exec/score/cpu}.
 A good starting point for a new family of processors is the
@@ -40,12 +40,15 @@ differents between these CPU models which RTEMS must take into account.
 
 This class of code provides the most specific glue between RTEMS and
 a particular board.  This code is represented by the Board Support Packages
-and associated Device Drivers.
+and associated Device Drivers.  Sources for the BSPs included in the
+RTEMS distribution are located in the directory @code{c/src/lib/libbsp}.
+The BSP source directory is further subdivided based on the CPU family
+and BSP.
 
 Some BSPs may support multiple board models within a single board family.
-This is necessary when the board's vendor supports build variants on a 
-single base base.  For example, the Motorola MVME162 board family has a
-a fairly large number of variations based upon the particular CPU model
+This is necessary when the board supports multiple variants on a 
+single base board.  For example, the Motorola MVME162 board family has a
+fairly large number of variations based upon the particular CPU model
 and the peripherals actually placed on the board.
 
 @section Peripheral Dependent
@@ -57,9 +60,16 @@ controllers.  Just as the hardware engineer choose a standard controller
 when designing a board, the goal of this library is to let the software
 engineer do the same thing.
 
+The source code for the reusable peripheral driver library may be found
+in the directory @code{c/src/lib/libchip}.  The source code is further
+divided based upon the class of hardware.  Example classes include serial
+communications controllers, real-time clocks, non-volatile memory, and
+network controllers.
+
 @section Questions to Ask
 
-Porting RTEMS on a new board should raise some questions:
+When evaluating what is required to support RTEMS applications on
+a particular target board, the following questions should be asked:
 
 @itemize @bullet
 
@@ -71,33 +81,35 @@ Porting RTEMS on a new board should raise some questions:
 
 @end itemize
 
-If there is already a BSP for your board, then you may already be ready
-to start developing application software.  You should verify that the
-existing BSP provides device drivers for all the peripherals on the board
-that your application will be using.  For example, the board may have
-an Ethernet controller which is not supported by the existing BSP.
+If there is already a BSP for the board, then things may already be ready
+to start developing application software.  All that remains is to verify
+that the existing BSP provides device drivers for all the peripherals
+on the board that the application will be using.  For example, the application
+in question may require that the board's Ethernet controller be used and
+the existing BSP may not support this.
 
 If the BSP does not exist and the board's CPU model is supported, then
-you should look at existing BSPs for a close match.  This will help
-reduce the effort required.  It is often possible to reuse device drivers
-from BSPs from different CPU families.
+examine the reusable chip library and existing BSPs for a close match.  
+This will help reduce the development effort required.  It is often
+possible to copy existing components in the reusable chip library or
+device drivers from BSPs from different CPU families as the starting
+point for a new device driver. 
 
 If the board's CPU family is supported but the particular CPU model on
 that board is not, then the RTEMS port to that CPU family will have to
-be augmented.  After this is done, then you can proceed to developing
-the new BSP.
+be augmented.  After this is done, development of the new BSP can proceed.
 
-Otherwise you'll have to write both CPU dependent code and the BSP.
+Otherwise both CPU dependent code and the BSP will have to be written.
 
 Regardless of the amount of development required, OAR Corporation
-offers custom development services to help you use RTEMS.
+offers custom development services to assist RTEMS users.
+For more information on custom development, training courses, and
+support, contact OAR Corporation at
 @ifset use-html
-For more information, contact OAR Corporation
-at @href{http://www.oarcorp.com,,,http://www.oarcorp.com}.
+@href{http://www.oarcorp.com,,,http://www.oarcorp.com}.
 @end ifset
 @ifclear use-html
-For more information, contact OAR Corporation
-at http://www.oarcorp.com.
+http://www.oarcorp.com.
 @end ifclear
 
 
@@ -107,13 +119,13 @@ The CPU dependent files in the RTEMS executive source code are found
 in the following directory:
 
 @example
-c/src/exec/score/cpu/CPU
+c/src/exec/score/cpu/@i{CPU}
 @end example
 
-where CPU is replaced with the CPU family name.
+where @i{CPU} is replaced with the CPU family name.
 
 Within each CPU dependent directory inside the executive proper is a 
-file named @code{CPU.h} which contains information about each of the
+file named @code{@i{CPU}.h} which contains information about each of the
 supported CPU models within that family.
 
 @section CPU Dependent Support Files
@@ -125,13 +137,13 @@ or device drivers for peripheral controllers found on the CPU itself.
 This class of code may be found in the following directory:
 
 @example
-c/src/lib/libcpu/CPU
+c/src/lib/libcpu/@i{CPU}
 @end example
 
 CPU model dependent support code is found in the following directory:
 
 @example
-c/src/lib/libcpu/CPU/CPU_MODEL
+c/src/lib/libcpu/@i{CPU}/@i{CPU_MODEL}
 @end example
 
 @section Board Support Package Structure
@@ -146,11 +158,11 @@ results in a BSP using the following directories:
 
 @example
 c/src/lib/libbsp/shared
-c/src/lib/libbsp/CPU/shared
-c/src/lib/libbsp/CPU/BSP
+c/src/lib/libbsp/@i{CPU}/shared
+c/src/lib/libbsp/@i{CPU}/@i{BSP}
 @end example
 
-Under each BSP specific directory, you will find a collection of
+Under each BSP specific directory, there is a collection of
 subdirectories.  For commonly provided functionality, the BSPs
 follow a convention on subdirectory naming.  The following list
 describes the commonly found subdirectories under each BSP.