Index: doc/ChangeLog
===================================================================
--- doc/ChangeLog	(revision 9353a0d4f22eb02d1f8a7bd1b9d198c4109c725a)
+++ doc/ChangeLog	(revision c7ff10af768978e8c4c97e93bea8ba73469e85b2)
@@ -1,2 +1,9 @@
+2008-08-21	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* bsp_howto/Makefile.am, bsp_howto/linkcmds.t, bsp_howto/makefiles.t,
+	bsp_howto/target.t: Update some of this manual.
+	* bsp_howto/Developer-User-Timeline.eps,
+	bsp_howto/Developer-User-Timeline.png: New files.
+
 2008-08-21	Joel Sherrill <joel.sherrill@OARcorp.com>
 
Index: doc/bsp_howto/Makefile.am
===================================================================
--- doc/bsp_howto/Makefile.am	(revision 9353a0d4f22eb02d1f8a7bd1b9d198c4109c725a)
+++ doc/bsp_howto/Makefile.am	(revision c7ff10af768978e8c4c97e93bea8ba73469e85b2)
@@ -19,4 +19,10 @@
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
+
+PNG_FILES = Developer-User-Timeline.png
+
+if USE_HTML
+html_project_DATA += $(PNG_FILES)
+endif
 
 FILES =
@@ -125,3 +131,3 @@
 EXTRA_DIST = adaintr.t analog.t ata.t clock.t console.t discrete.t \
     ide-ctrl.t init.t intro.t linkcmds.t makefiles.t nvmem.t rtc.t shmsupp.t \
-    support.t target.t timer.t
+    support.t target.t timer.t $(PNG_FILES) $(EPS_IMAGES)
Index: doc/bsp_howto/linkcmds.t
===================================================================
--- doc/bsp_howto/linkcmds.t	(revision 9353a0d4f22eb02d1f8a7bd1b9d198c4109c725a)
+++ doc/bsp_howto/linkcmds.t	(revision c7ff10af768978e8c4c97e93bea8ba73469e85b2)
@@ -15,4 +15,11 @@
 to link the program.  Specifically it specifies where the code and data
 for the application will reside in memory.
+
+The format of the linker script is defined by the GNU Loader @code{ld}
+which is included as a component of the GNU Binary Utilities.  If you
+are using GNU/Linux, then you probably have the documentation installed
+already and are using these same tools configured for @b{native} use.
+Please visit the Binutils project @uref{http://sourceware.org/binutils/}
+if you need more information.
 
 @section Program Sections
Index: doc/bsp_howto/makefiles.t
===================================================================
--- doc/bsp_howto/makefiles.t	(revision 9353a0d4f22eb02d1f8a7bd1b9d198c4109c725a)
+++ doc/bsp_howto/makefiles.t	(revision c7ff10af768978e8c4c97e93bea8ba73469e85b2)
@@ -13,11 +13,39 @@
 This chapter will not provide detailed information about this process.
 Nonetheless, it is important to remember that the general process consists
-of three parts:
-
+of four phases as shown here:
+
+@ifset use-ascii
+@example
+@group
 @itemize @bullet
+@item bootstrap
 @item configure
 @item build
 @item install
 @end itemize
+@end group
+@end example
+@end ifset
+
+
+@ifset use-tex
+@image{Developer-User-Timeline,6in,,Developer User Timeline,.png}
+@c      @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
+
+@end ifset
+
+@ifset use-html
+@html
+<center>
+<IMG SRC="Developer-User-Timeline.png" WIDTH=800 ALT="Developer User Timeline">
+</center>
+@end html
+@end ifset
+
+
+During the bootstrap phase, you are using the @code{configure.ac} and
+@code{Makefile.am} files as input to GNU autoconf and automake to
+generate a variety of files.  This is done by running the @code{bootstrap}
+script found at the top of the RTEMS source tree.  
 
 During the configure phase, a number of files are generated.  These 
@@ -42,11 +70,23 @@
 directory of the RTEMS source tree is executed to produce the
 automatically generated files.  That script must be run from
-a directory with a @code{configure.ac} file in it.
-
-There is a file named @code{Makefile.am} in each directory of a BSP.
-This file is used by @b{automake} to produce the file 
-named @code{Makefile.in} which is also found in each directory of a BSP.
-The configure process specializes the @code{Makefile.in} files at
-the time that RTEMS
+a directory with a @code{configure.ac} file in it.  The @code{bootstrap}
+command is usually invoked in one of the following manners:
+
+@itemize @bullet
+@item @code{bootstrap} to regenerate all files that are generated by
+autoconf and automake.
+@item @code{bootstrap -c} to remove all files generated by autoconf and
+automake.
+@item @code{bootstrap -p} to regenerate @code{preinstall.am} files.
+@end itemize
+
+There is a file named @code{Makefile.am} in each directory of
+a BSP.  This file is used by @b{automake} to produce the file named
+@code{Makefile.in} which is also found in each directory of a BSP.
+When modifying a @code{Makefile.am}, you can probably find examples of
+anything you need to do in one of the BSPs.
+
+
+The configure process 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
@@ -61,85 +101,72 @@
 The BSP developer is responsible for generating @code{Makefile.am} 
 files which properly build all the files associated with their BSP.
-There are generally three types of Makefiles in a BSP source tree:
-
-
-@itemize @bullet
-@item Directory Makefiles
-@item Source Directory Makefiles
-@item Wrapup Makefile
-@end itemize
-
-@subsection Directory Makefiles
-
-The Directory class of Makefiles directs the build process through
-a set of subdirectories in a particular order.  This order is usually
-chosen to insure that build dependencies are properly processed. 
-Most BSPs only have one Directory class Makefile.  The @code{Makefile.am}
-in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
-following Makefile fragment shows how a BSP would specify the
-directories to be built and their order:
-
-@example
-SUB_DIRS=include start340 startup clock console timer \
-    network wrapup
-@end example
-
-@subsection Source Directory Makefiles
-
-There is a @code{Makefile.am} in most of the directories in a BSP. This
-class of Makefile lists the files to be built as part of the driver.
-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.am}
-and run @code{bootstrap}.
+Most BSPs will only have a single @code{Makefile.am} which details
+the set of source files to build to compose the BSP support library
+along with the set of include files that are to be installed.  
+
+This single @code{Makefile.am} at the top of the BSP tree specifies
+the set of header files to install.  This fragment from the SPARC/ERC32
+BSP results in four header files being installed.
+
+@example
+include_HEADERS = include/bsp.h
+include_HEADERS += include/tm27.h
+include_HEADERS += include/erc32.h
+include_HEADERS += include/coverhd.h
+@end example
+
+When adding new include files, you will be adding to the set of
+@code{include_HEADERS}.  When you finish editing the @code{Makefile.am}
+file, do not forget to run @code{bootstrap -p} to regenerate the
+@code{preinstall.am}.
+
+The @code{Makefile.am} also specifies which source files to build.
+By convention, logical components within the BSP each assign their
+source files to a unique variable.  These variables which define
+the source files are collected into a single variable which instructs
+the GNU autotools that we are building @code{libbsp.a}.  This fragment
+from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
+support code, and the console device driver source is managed
+in the @code{Makefile.am}.
+
+@example
+startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
+    ../../shared/bsppredriverhook.c \
+    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \
+    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
+    startup/spurious.c startup/erc32mec.c startup/boardinit.S
+clock_SOURCES = clock/ckinit.c
+...
+noinst_LIBRARIES = libbsp.a
+libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
+@end example
+
+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 corresponding
+@code{XXX_SOURCES} variable in the @code{Makefile.am} and run
+@code{bootstrap}.
+
+Some BSPs use code that is built in @code{libcpu}.  If you BSP does
+this, then you will need to make sure the objects are pulled into your
+BSP library.  The following from the SPARC/ERC32 BSP pulls in the cache,
+register window management and system call support code from the directory
+corresponding to its @code{RTEMS_CPU} model.
+
+@example
+libbsp_a_LIBADD  = ../../../libcpu/@@RTEMS_CPU@@/cache.rel \
+    ../../../libcpu/@@RTEMS_CPU@@/reg_win.rel \
+    ../../../libcpu/@@RTEMS_CPU@@/syscall.rel
+@end example
 
 @b{NOTE:} The @code{Makefile.am} files are ONLY processed by
-@code{bootstrap} and the resulting @code{Makefile.in} files are
-only processed during the configure
-process of a RTEMS build. Therefore, when developing 
-a BSP and adding a new file to a @code{Makefile.am}, the 
-already generated @code{Makefile} will not automatically
+@code{bootstrap} and the resulting @code{Makefile.in} files are only
+processed during the configure process of a RTEMS build. Therefore,
+when developing a BSP and adding a new file to a @code{Makefile.am},
+the already generated @code{Makefile} will not automatically
 include the new references unless you configured RTEMS with the
-@code{--enable-maintainer-mode} option.
-Otherwise, the new file not being be taken into account! 
-
-If adding a new directory, be sure to add it to the list of
-automatically generated files in the BSP's @code{configure.ac}
-script.
-
-@subsection Wrapup Makefile
-
-This class of Makefiles produces a library.  The BSP wrapup Makefile
-is responsible for producing the library @code{libbsp.a} which is later
-merged into the @code{librtemsall.a} library.  This Makefile specifies
-which BSP components are to be placed into the library as well as which
-components from the CPU dependent support code library.  For example,
-this component may choose to use a default exception handler from the
-CPU dependent support code or provide its own.
-
-This Makefile makes use of the @code{foreach} construct in @b{GNU make}
-to pick up the required components:
-
-@example
-BSP_PIECES=startup clock console timer
-CPU_PIECES=
-GENERIC_PIECES=
-
-# bummer; have to use $foreach since % pattern subst
-#              rules only replace 1x
-OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).o) \
- $(foreach piece, $(CPU_PIECES), \
-   ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).o) \
- $(wildcard \
-   ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \
- $(foreach piece, \
-   $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).o)
-@end example
-
-The variable @code{OBJS} is the list of "pieces" expanded to include
-path information to the appropriate object files.  The @code{wildcard}
-function is used on pieces of @code{libbsp.a} which are optional and
-may not be present based upon the configuration options.
-
-@section Makefiles Used Both During The BSP Design and its Use
+@code{--enable-maintainer-mode} option.  Otherwise, the new file not
+being be taken into account!
+
+@section Creating a New BSP Make Customization File
 
 When building a BSP or an application using that BSP, it is necessary
@@ -152,75 +179,45 @@
 
 The configuration file is taken into account when building one's
-application using the RTEMS template Makefiles (@code{make/templates}). 
-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 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
-the current one,
-
-@item build a library, or
-
-@item build an executable.
-
-@end itemize
-
-The following is a shortened and heavily commented version of the
-make customization file for the gen68340 BSP.  The original source
-for this file can be found in the @code{make/custom} directory.
-
-@example
-
+application using the RTEMS template Makefiles (@code{make/templates}).
+These application template Makefiles have been included with the
+RTEMS source distribution since the early 1990's.  However there is
+a desire in the RTEMS user community to move all provided examples to
+GNU autoconf. They are included in the 4.9 release series and used for
+all examples provided with RTEMS. There is no definite time table for
+obsoleting them.  You are free to use these but be warned they have
+fallen out of favor with many in the RTEMS community and may disappear
+in the future.
+
+The following is a slightly shortened version of the make customization
+file for the gen68340 BSP.  The original source for this file can be
+found in the @code{make/custom} directory.
+
+@example
 # The RTEMS CPU Family and Model
 RTEMS_CPU=m68k
-RTEMS_CPU_MODEL=mcpu32
+RTEMS_CPU_MODEL=m68340
 
 include $(RTEMS_ROOT)/make/custom/default.cfg
 
-# The name of the BSP directory used for the actual source code.
-# This allows for build variants of the same BSP source.
+# This is the actual bsp directory used during the build process.
 RTEMS_BSP_FAMILY=gen68340
 
-# CPU flag to pass to GCC
-CPU_CFLAGS = -mcpu32
-
-# optimization flag to pass to GCC
-CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer
-
-# The name of the start file to be linked with.  This file is the first
-# part of the BSP which executes.
-START_BASE=start340
-
-# This make-exe macro is used in template makefiles to build the
-# final executable. Any other commands to follow, just as using
-# objcopy to build a PROM image or converting the executable to binary. 
-
-define make-exe
-	$(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@@).exe $(LINK_OBJS)
-	$(NM) -g -n $(basename $@@).exe > $(basename $@@).num
-	$(SIZE) $(basename $@@).exe
-endif
-@end example
-
-@subsection Creating a New BSP Make Customization File
-
-The basic steps for creating a @code{make/custom} file for a new BSP
-are as follows:
-
-@itemize @bullet
-
-@item copy any @code{.cfg} file to @code{BSP.cfg}
-
-@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
-RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.
-
-@end itemize
+# This contains the compiler options necessary to select the CPU model
+# and (hopefully) optimize for it.
+CPU_CFLAGS = -mcpu=cpu32
+
+# optimize flag: typically -O2
+CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
+@end example
+
+The make customization files have generally grown simpler and simpler
+with each RTEMS release.  Beginning in the 4.9 release series, the rules
+for linking an RTEMS application are shared by all BSPs.  Only BSPs which
+need to perform a transformation from linked ELF file to a downloadable
+format have any additional actions for program link time. In 4.8 and
+older, every BSP specified the "make executable" or @code{make-exe}
+rule and duplicated the same actions.
 
 It is generally easier to copy a @code{make/custom} file from a
 BSP similar to the one being developed.
 
-
Index: doc/bsp_howto/target.t
===================================================================
--- doc/bsp_howto/target.t	(revision 9353a0d4f22eb02d1f8a7bd1b9d198c4109c725a)
+++ doc/bsp_howto/target.t	(revision c7ff10af768978e8c4c97e93bea8ba73469e85b2)
@@ -37,4 +37,20 @@
 differences between these CPU models which RTEMS must take into account.
 
+The source code found in the @code{cpukit/score/cpu} is required to
+only depend upon the CPU model variations that GCC distinguishes
+for the purposes of multilib'ing.  Multilib is the term the GNU
+community uses to refer to building a single library source multiple
+times with different compiler options so the binary code generated
+is compatible.  As an example, from GCC's perspective, many PowerPC
+CPU models are just a PPC603e.  Remember that GCC only cares about
+the CPU code itself and need not be aware of any peripherals.  In
+the embedded community, we are exposed to thousands of CPU models
+which are all based upon only a relative small number of CPU cores.
+
+Similarly for the SPARC/ERC32 BSP, the @code{RTEMS_CPU} is specified as
+@code{erc32} which is the name of the CPU model and BSP for this SPARC V7
+system on chip.  But the multilib variant used is actually @code{v7}
+which indicates the ERC32 CPU core is a SPARC V7.
+
 @section Board Dependent
 
@@ -141,7 +157,12 @@
 @end example
 
+@i{CPU_MODEL} may be a specific CPU model name or a name indicating a CPU
+core or a set of related CPU models.  The file @code{configure.ac} in each
+@code{c/src/lib/libcpu/@i{CPU}} directory contains the logic which enables
+the appropriate subdirectories for the specific CPU model your BSP has.
+
 @section Board Support Package Structure
 
-The BSPs are all under the c/src/lib/libbsp directory.  Below this
+The BSPs are all under the @code{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
@@ -175,5 +196,5 @@
 support of timer devices.
 
-@item @b{rtc}:
+@item @b{rtc} or @code{tod}:
 support for the hardware real-time clock.
 
@@ -190,8 +211,14 @@
 include files for this BSP.
 
-@item @b{wrapup}:
-bundles all the components necessary to construct the BSP library.
+@item @b{gnatsupp}:
+BSP specific support for the GNU Ada run-time.  Each BSP that wishes
+to have the possibility to map faults or exceptions into Ada language
+exceptions or hardware interrupts into Ada interrupt tasks must provide
+this support.
 
 @end itemize
+
+There may be other directories in the BSP tree and the name should
+be indicative of the functionality of the code within that directory.
 
 The build order of the BSP is determined by the Makefile structure.
