Links between chapters up to Linker Script in place.

First draft of chapters up to and include Makefiles written.

doc/bsp_howto/Makefile

@@ -74,10 +74,10 @@ target.texi: target.t Makefile
 makefiles.texi: makefiles.t Makefile
 	$(BMENU) -p "Target Dependent Files Board Support Package Structure" \
 	    -u "Top" \
-	    -n "" ${*}.t
+	    -n "Linker Script" ${*}.t
 
 linkcmds.texi: linkcmds.t Makefile
-	$(BMENU) -p "" \
+	$(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \
 	    -u "Top" \
 	    -n "" ${*}.t
 

doc/bsp_howto/makefiles.t

@@ -10,17 +10,39 @@
 
 @section Makefiles Used During The BSP Building Process
 
-There's a makefile template in each directory of a BSP. They are called
+There is a file named @code{Makefile.in} in each directory of a BSP.
-"makefile.in" and are processed when building RTEMS for a given BSP. One
+RTEMS uses the @b{GNU autoconf} automatic configuration package. 
-should specify the needed files and directories before the building
+This tool specializes the @code{Makefile.in} files at the time that RTEMS
-process. 
+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.
+
+The @code{Makefile} files generated are processed when building
+RTEMS for a given BSP.
+
+The BSP developer is responsible for generating @code{Makefile.in} 
+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
 
-@item the makefile.in at the BSP root specifies which folders have to be
+@subsection Directory Makefiles
-included. For instance,
 
-@item We only build the networking device driver if HAS_NETWORKING was defined
+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.in}
+in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
+which directories are to be built for this BSP. For example, the
+following Makefile fragment shows how a BSP would only build the
+networking device driver if HAS_NETWORKING was defined:
 
 @example
 NETWORKING_DRIVER_yes_V = network
@@ -32,38 +54,93 @@ SUB_DIRS=include start340 startup clock console timer \
     $(NETWORKING_DRIVER) wrapup
 @end example
 
-states that all the directories have to be processed, except for the
+This fragment states that all the directories have to be processed,
-network directory which is included only if the user asked for it when
+except for the @code{network} directory which is included only if the
-building RTEMS. 
+user configured networking.
 
-@item the makefile.in in each driver directory. It lists the files to be
+@subsection Source Directory Makefiles
-included in the driver, so don't forget to add the reference to a new file
-in the makefile.in of a given driver when it is created! 
 
-@end itemize
+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! 
 
-
+@b{NOTE:} The @code{Makefile.in} files are ONLY processed during the configure
-Rem : the 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 take n into account! You have to
+corresponding makefile.in, it will not be taken into account! You have to
-run configure again or modify the makefile (result of the makefile.in
+run configure again or modify the @code{Makefile} (the result of the 
-process, usually in your <the RTEMS build
+configure process) by hand.  This file will be in a directory such as 
-directory>/c/src/lib/libbsp/<your BSP family>/<your BSP>/<your driver>
+the following:
-directory) by hand. 
+
+@example
+MY_BUILD_DIR/c/src/lib/libbsp/CPU/BSP/DRIVER
+@end example
+
+@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 a neat 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).rel) \
+   $(foreach piece, $(CPU_PIECES), \
+       ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).rel) \
+   $(wildcard \
+  ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \
+   $(foreach piece, $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).rel)
+@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
 
-A BSP must go with his configuration file. The configuration files can be
+When building a BSP or an application using that BSP, it is necessary
-found under $RTEMS_ROOT/c/make/custom. The configuration file is taken
+to tailor the compilation arguments to account for compiler flags, use
-into account when building one's application using the template makefiles
+custom linker scripts, include the RTEMS libraries, etc..  The BSP
-($RTEMS_ROOT/c/make/templates), whic h is strongly advised. There are
+must be built using this information.  Later, once the BSP is installed
-templates for calling recursively the makefiles in the directories beneath
+with the toolset, this same information must be used when building the
-the current one, building a library or an executable.
+application.  So a BSP must include a build configuration file.  The
+configuration file is @code{make/custom/BSP.cfg}.
 
-The following is a hevaily commented version of the make customization
+The configuration file is taken into account when building one's
-file for the gen68340 BSP.  It can be found in the $RTEMS_ROOT/make/custom
+application using the RTEMS template Makefiles (@code{make/templates}). 
-directory.
+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:
+
+@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
 
@@ -110,17 +187,21 @@ define make-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
-What you have to do:
+is as follows:
 
 @itemize @bullet
 
-@item copy any .cfg file to <your BSP>.cfg
+@item copy any @code{.cfg} file to @code{BSP.cfg}
 
-@item modify RTEMS_CPU, TARGET_ARCH, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
+@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
-RTEMS_BSP, CPU_CFLAGS, START_BASE accordingly. 
+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.
+
 

doc/bsp_howto/target.t

@@ -26,7 +26,7 @@ into one of the following categories.
 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}.
+processor families can be found in @code{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. 
@@ -191,13 +191,6 @@ bundles all the components necessary to construct the BSP library.
 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