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

	* bsp_howto/init.t: Complete update.

2 files changed, 56 insertions, 118 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 39f60f9867..491fbe5844 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,9 @@
 2008-08-22	Joel Sherrill <joel.sherrill@oarcorp.com>
 
+	* bsp_howto/init.t: Complete update.
+
+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.
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t
index 6f9c902d0a..be35b03e38 100644
--- a/doc/bsp_howto/init.t
+++ b/doc/bsp_howto/init.t
@@ -244,107 +244,52 @@ file:
 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 may include increasing the maximum number
-of some types of RTEMS system objects to reflect the needs of 
-the BSP and the base set of device drivers. This routine will
-typically also 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 Workspace 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 the RTEMS Workspace 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 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:
-
-@example
-c/src/lib/libbsp/shared/main.c
-@end example
-
-In addition to the implicit invocation of @code{__main}, this 
-routine performs some explicit 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.
-
-The RTEMS initialization procedure is described in the @b{Initialization
-Manager} chapter of the @b{RTEMS Application C User's Guide}.
-Please refer to that manual for more information.
+On older BSPs not using @code{boot_card()}'s support for allocating memory
+to the C Program Heap and RTEMS Workspace, one of the most important
+functions performed by this routine is determining where the RTEMS
+Workspace 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
+the RTEMS Workspace 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 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
+The method @code{bsp_pretasking_hook()} is the BSP specific routine
 invoked once RTEMS API 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
+been created when this hook is invoked.  The pretasking hook is optional
+and the user may use the shared version.
 
 The @code{bsp_pretasking_hook()} routine is the appropriate place to
 initialize any support components which depend on the RTEMS APIs.
-Most BSPs set the debug level for the system and initialize the
-RTEMS C Library support in their
-implementation of @code{bsp_pretasking_hook()}.  This initialization
-includes the application heap used by the @code{malloc} family
-of routines as well as the reentrancy support for the C Library.
+Older BSPs that do not take full advantage of @code{boot_card()}
+may initialize the RTEMS C Library in their implementation of
+@code{bsp_pretasking_hook()}.  This initialization includes the
+application heap used by the @code{malloc} family of routines as well
+as the reentrancy support for the C Library.
 
 The routine @code{bsp_libc_init} routine invoked from the
-@code{bsp_pretasking_hook()} routine is passed the starting
-address, length, and growth amount passed to @code{sbrk}.  
-This "sbrk amount" is only used if the heap runs out of
-memory.  In this case, the RTEMS malloc implementation will
-invoked @code{sbrk} to obtain more memory.  See
-@ref{Miscellaneous Support Files sbrk() Implementation} for more details.
+either @code{boot_card()} or (less preferable) the BSP specific
+@code{bsp_pretasking_hook()} routine is passed the starting address,
+length, and growth amount passed to @code{sbrk}.  This "sbrk amount"
+is only used if the heap runs out of memory.  In this case, the RTEMS
+malloc implementation will invoked @code{sbrk} to obtain more memory.
+See @ref{Miscellaneous Support Files sbrk() Implementation} for more
+details.
 
 @subsection RTEMS Predriver Callback
 
-The @code{predriver_hook} entry in the RTEMS CPU Configuration
-Table may be the address of a user provided routine that is
-is invoked immediately before the the device drivers and MPCI
-are initialized. RTEMS
-initialization is complete but interrupts and tasking are disabled.
-This field may be NULL to indicate that the hook is not utilized.
+The @code{bsp_predriver_hook()} method is the BSP specific routine that
+is is invoked immediately before the the device drivers and MPCI are
+initialized. RTEMS initialization is complete but interrupts and tasking
+are disabled.
 
-Most BSPs do not use this callback.
+The BSP may use the shared version of this routine which is empty.
+Most BSPs do not provide a specific implementation of this callback.
 
 @subsection Device Driver Initialization
 
@@ -378,26 +323,16 @@ channels in the UART).
 
 @subsection RTEMS Postdriver Callback
 
-The @code{postdriver_hook} entry in the RTEMS CPU Configuration
-Table may be the address of a user provided routine that is
-invoked immediately after the the device drivers and MPCI are initialized.
-Interrupts and tasking are disabled.  The postdriver hook is optional.
+The @code{bsp_postdriver_hook()} BSP specific routine is invoked
+immediately after the the device drivers and MPCI are initialized.
+Interrupts and tasking are disabled.
 
-Although optional, most of the RTEMS BSPs provide a postdriver hook
-callback.  This routine is usually called @code{bsp_postdriver_hook}
-and is found in the file:
+Most BSPs use the shared implementation of this routine which is responsible for opening the device @code{/dev/console} for standard input, output and error if the application has configured the Console Device Driver.  This file is located at:
 
 @example
-c/src/lib/libbsp/CPU/BSP/startup/bsppost.c
+c/src/lib/libbsp/shared/bsppost.c
 @end example
 
-The @code{bsp_postdriver_hook()} routine is the appropriate place to
-perform initialization that must be performed before the first task 
-executes but requires that a device driver be initialized.  The 
-shared implementation of the postdriver hook opens the default 
-standard in, out, and error files and associates them with 
-@code{/dev/console}.
-
 @section The Interrupt Vector Table
 
 The Interrupt Vector Table is called different things on different
@@ -500,22 +435,21 @@ semaphores, etc.). It's used to allocate the size for the RTEMS inner data
 structures. 
 
 The RTEMS configuration table is application dependent, which means that
-one has to provide one per application. It is usually defined
-by defining macros and including the header file @code{<rtems/confdefs.h>}.
-In simple applications such as the tests provided with RTEMS, it is
-commonly found in the main module of the application.  For more complex
-applications, it may be in a file by itself.
-
-The header file @code{<rtems/confdefs.h>} defines a constant table named
-@code{Configuration}.  With RTEMS 4.8 and older, it was
-accepted practice for the BSP to copy this table into a modifiable
-copy named @code{BSP_Configuration}.  This copy of the table was modified
-to define the base address of the RTEMS Executive Workspace as well as
-to reflect any BSP and device driver requirements not automatically
-handled by the application.  In 4.9 and newer, we have eliminated
-the BSP copies of the configuration tables and are making efforts
-to make the configuration information generated by @code{<rtems/confdefs.h>}
-constant and read only.
+one has to provide one per application. It is usually defined by defining
+macros and including the header file @code{<rtems/confdefs.h>}.  In simple
+applications such as the tests provided with RTEMS, it is commonly found
+in the main module of the application.  For more complex applications,
+it may be in a file by itself.
+
+The header file @code{<rtems/confdefs.h>} defines a constant table
+named @code{Configuration}.  With RTEMS 4.8 and older, it was accepted
+practice for the BSP to copy this table into a modifiable copy named
+@code{BSP_Configuration}.  This copy of the table was modified to define
+the base address of the RTEMS Executive Workspace as well as to reflect
+any BSP and device driver requirements not automatically handled by the
+application.  In 4.9 and newer, we have eliminated the BSP copies of the
+configuration tables and are making efforts to make the configuration
+information generated by @code{<rtems/confdefs.h>} constant and read only.
 
 For more information on the RTEMS Configuration Table, refer to the
 @b{RTEMS Application C User's Guide}.