Significant additions.

1 files changed, 156 insertions, 45 deletions

diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t
index e18d70d6e6..8d3ecf0505 100644
--- a/doc/bsp_howto/target.t
+++ b/doc/bsp_howto/target.t
@@ -6,87 +6,198 @@
 @c  $Id$
 @c
 
-@chapter CPU and Board Dependent Files
+@chapter Target Dependent Files
 
-RTEMS divides board dependencies into two parts:
+RTEMS has a multi-layered approach to portability.  This is done to
+maximize the amount of software that can be reused.  Much of the
+RTEMS source code can be reused on all RTEMS platforms.  Other parts
+of the executive are specific to hardware in some sense.
+RTEMS classifies target dependent code based upon its dependencies
+into one of the following categories.
 
 @itemize @bullet
+@item CPU dependent
+@item Board dependent
+@item Peripheral dependent
+@end itemize
 
-@item the CPU dependant code : it provides basics calls to the kernel,
-just as the context switch or the interrupt subroutine implementations.
-Sources for the supported families of processors can be found in
-$RTEMS_ROOT/c/src/exec/score/cpu. A good starti ng point for a new family
-of processors is the no_cpu directory, which holds both prototypes and
-descriptions of each needed CPU dependant function. 
+@subheading CPU Dependent
 
-@item the board dependant code : it includes support for a given board,
-such as the board initialization code and drivers for the various devices:
+This class of code includes the foundation
+routines for the executive proper such as as the context switch and
+the interrupt subroutine implementations.  Sources for the supported
+processor families can be found in @code{$RTEMS_ROOT/c/src/exec/score/cpu}.
+A good starting point for a new family of processors is the
+@code{no_cpu} directory, which holds both prototypes and
+descriptions of each needed CPU dependent function. 
 
-@end itemize
+CPU dependent code is further subcategorized if the implementation is
+dependent on a particular CPU model.  For example, the MC68000 and MC68020
+processors are both members of the m68k CPU family but there are significant
+differents between these CPU models which RTEMS must take into account.
+
+@subheading Board Dependent
+
+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.
+
+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
+and the peripherals actually placed on the board.
+
+@subheading Peripheral Dependent
+
+This class of code provides a reusable library of peripheral device
+drivers which can be tailored easily to a particular board.  This
+reusable library provides software objects which correspond to standard
+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.
+
+@section Questions to Ask
 
-Porting RTEMS on a new board should raise two questions:
+Porting RTEMS on a new board should raise some questions:
 
 @itemize @bullet
 
-@item is the main board CPU supported ?
+@item Does a BSP for this board exist?
 
-@item does a BSP for a similar board exists ?
+@item Does a BSP for a similar board exists?
+
+@item Is the board's CPU supported?
 
 @end itemize
 
-If the main board CPU is supported, you will only have do write the Board
-Support Package. Otherwise you'll have to write both CPU dependant code
-and the BSP. One should always start writing a BSP from a similar one. 
+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 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.
+
+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.
+
+Otherwise you'll have to write both CPU dependent code and the BSP.
+
+Regardless of the amount of development required, OAR Corporation
+offers custom development services to help you use RTEMS.
+@ifset use-html
+For more information, contact OAR Corporation
+at @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.
+@end ifclear
+
 
 @section CPU Dependent Executive Files
 
-XXX
+The CPU dependent files in the RTEMS executive source code are found
+in the following directory:
+
+@example
+c/src/exec/score/cpu/CPU
+@end example
+
+where CPU is replcaed 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
+supported CPU models within that family.
 
 @section CPU Dependent Support Files
 
-XXX
+The CPU dependent support files contain routines which aid in the development
+of applications using that CPU family.  For example, the support routines
+may contain standard trap handlers for alignment or floating point exceptions
+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
+@end example
+
+CPU model dependent support code is found in the following directory:
+
+@example
+c/src/lib/libcpu/CPU/CPU_MODEL
+@end example
 
 @section Board Support Package Structure
 
-The BSPs are kept in the $RTEMS_ROOT/c/src/lib/libbsp directory. They
-are filed under the processor family (m68k, powerpc, etc.). A given BSP
-consists in the following directories: 
+The BSPs are all under the c/src/lib/libbsp directory.  Below this
+directory, there is a subdirectory for each CPU family.  Each BSP
+is found under the subdirectory for the appropriate processor
+family (m68k, powerpc, etc.).  In addition, there is source code
+available which may be shared across all BSPs regardless of
+the CPU family or just across BSPs within a single CPU family.  This
+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
+@end example
+
+Under each BSP specific directory, you will find 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.
 
 @itemize @bullet
 
-@item @b{clock} - 
-support for the realtime clock, which provides a regular
-time basis to the kernel,
+@item @b{console}:
+is technically the serial driver for the BSP rather
+than just a console driver, it deals with the board
+UARTs (i.e. serial devices).
 
-@item @b{console} - 
-rather the serial driver than only a console driver, it
-deals with the board UARTs (i.e. serial devices),
+@item @b{clock}:
+support for the clock tick -- a regular time basis to the kernel.
 
-@item @b{include} - 
-the include files,
+@item @b{timer}:
+support of timer devices.
 
-@item @b{startup} - 
-the board initialization code,
+@item @b{rtc}:
+support for the hardware real-time clock.
 
-@item @b{timer} - 
-support of timer devices,
+@item @b{nvmem}:
+support for non-volatile memory such as EEPROM or Flash.
 
-@item @b{shmsupp} - 
-support of shared memory in a multiprocessor system,
+@item @b{network}:
+the Ethernet driver.
 
-@item @b{network} - 
-the Ethernet driver. 
+@item @b{shmsupp}:
+support of shared memory driver MPCI layer in a multiprocessor system,
 
-@item @b{rtc} - 
-the real-time clock driver. 
+@item @b{include}:
+include files for this BSP.
 
-@item @b{wrapup} - XXX
+@item @b{wrapup}:
+bundles all the components necessary to construct the BSP library.
 
 @end itemize
 
-Another important element are the makefiles, which have to be provided by
-the user. 
-
+The build order of the BSP is determined by the Makefile structure.
+This structure is discussed in more detail in the @ref{Makefiles}
+chapter.
+RTEMS uses the @b{GNU autoconf} automatic configuration package.  This
+tool specializes the @code{Makefile.in} files at the time that RTEMS
+is configured for a specific development host and target.  Makefiles
+are automatically generated from the @code{Makefile.in} files.  It is
+necessary for the BSP developer to provide these files.  Most of the
+time, it is possible to copy the @code{Makefile.in} from another
+similar directory and edit it.
 
 @b{NOTE:} This manual refers to the gen68340 BSP for numerous concrete
 examples.  You should have a copy of the gen68340 BSP available while
@@ -94,7 +205,7 @@ reading this piece of documentation.   This BSP is located in the
 following directory:
 
 @example
-$RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340
+c/src/lib/libbsp/m68k/gen68340
 @end example
 
 Later in this document, the $BSP340_ROOT label will be used