2001-01-17 Joel Sherrill <joel@OARcorp.com>

	* SUPPORT, LICENSE: New files.
	* Numerous files touched as part of merging the 4.5 branch
	onto the mainline development trunk and ensuring that the
	script that cuts snapshots and releases works on the documentation.

1 files changed, 159 insertions, 111 deletions

diff --git a/doc/started/gdb.t b/doc/started/gdb.t
index 57f3bb1981..784f265fc6 100644
--- a/doc/started/gdb.t
+++ b/doc/started/gdb.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-1999.
+@c  COPYRIGHT (c) 1988-2002.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -8,26 +8,51 @@
 
 @chapter Building the GNU Debugger
 
-GDB is currently RTEMS aware only if you are using the remote debugging
-support via Ethernet.   The following configurations have been
+The GNU Debugger GDB supports many configurations but requires some
+means of communicating between the host computer and target board.
+This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
+The communication protocol can be the GDB remote protocol or GDB
+can talk directly to a ROM monitor.  This setup is target board 
+specific.  The following configurations have been
 successfully used with RTEMS applications:
 
 @itemize @bullet
 @item Sparc Instruction Simulator (SIS)
 @item PowerPC Instruction Simulator (PSIM)
 @item DINK32
+@item BDM with 68360 and MPC860 CPUs
+@item Motorola Mxxxbug found on M68xxx MVME boards
+@item Motorola PPCbug found on PowerPC MVME boards
 @end itemize
 
-Other configurations of gdb have successfully been used by RTEMS users
-but are not documented here.
+GDB is currently RTEMS thread/task aware only if you are using the
+remote debugging support via Ethernet.  These are configured
+using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
 
 It is recommended that when toolset binaries are available for
 your particular host, that they be used.  Prebuilt binaries
-are much easier to install.
+are much easier to install but in the case of gdb may or may
+not include support for your particular target board.
 
-@section Unarchive the gdb Distribution
+@c
+@c  Getting Ready to Build GDB
+@c
+@section Getting Ready to Build GDB
+
+This section describes the process of unarchiving GDB
+as well as applying RTEMS specific patches.  This is required when building
+the tools via the instructions in the
+@ref{Using the GDB configure Script Directly} or
+@ref{Using the bit_gdb Script} sections.  It is @b{NOT} required when
+using RPM to build tool binaries.
+
+
+@c
+@c  Unarchive the GDB Distribution
+@c
+@subsection Unarchive the GDB Distribution
 
-Use the following commands to unarchive the gdb distribution:
+Use the following commands to unarchive the GDB distribution:
 
 @example
 cd tools
@@ -37,10 +62,10 @@ tar xzf ../archive/@value{GDB-TAR}
 The directory @value{GDB-UNTAR} is created under the tools directory.
 
 @c
-@c  GDB Patch
+@c  Apply RTEMS Patch to GDB
 @c
 
-@section Apply RTEMS Patch to GDB
+@subsection Apply RTEMS Patch to GDB
 
 @ifclear GDB-RTEMSPATCH
 No RTEMS specific patches are required for @value{GDB-VERSION} to
@@ -69,153 +94,176 @@ This should not happen with a good patch file.
 
 @end ifset
 
-@section Using the bit_gdb script
-
-The simplest way to build gdb for RTEMS is to use the @code{bit_gdb} script.
-This script interprets the settings in the @code{user.cfg} file to
-produce the gdb configuration most appropriate for the target CPU.
+@c
+@c  Building the GNU Debugger GDB
+@c
 
-This script is invoked as follows:
+@section Building the GNU Debugger GDB
 
-@example
-./bit_gdb CPU
-@end example
-
-Where CPU is one of the RTEMS supported CPU families from the following
-list:
+There are three methods of build the GNU Debugger:
 
 @itemize @bullet
-@item hppa1.1
-@item i386
-@item i386-elf
-@item i386-go32
-@item i960
-@item m68k
-@item mips64orion
-@item powerpc
-@item sh
-@item sparc
+@item RPM
+@item direct invocation of configure and make
+@item using the @code{bit_gdb} script
 @end itemize
 
-If gdb supports a CPU instruction simulator for this configuration, then
-it is included in the build.
-
-@section Using the gdb configure Script Directly
+Direct invocation of configure and make provides more control
+and easier recovery from problems when building.
 
-@subsection GDB with Sparc Instruction Simulation (SIS)
+@c
+@c  Using RPM to Build GDB
+@c
 
-@subheading Make the Build Directory
+@subsection Using RPM to Build GDB
 
-Create a build directory for the SIS Debugger
+This section describes the process of building binutils, gcc, and
+newlib using RPM.  RPM is a packaging format which can be used to
+distribute binary files as well as to capture the procedure and
+source code used to produce those binary files.  Before
+attempting to build any RPM from source, it is necessary to
+ensure that all required source and patches are in the @code{SOURCES}
+directory under the RPM root (probably @code{/usr/src/redhat} or
+@code{/usr/local/src/redhat} on your machine.  This procedure
+starts by installing the source RPMs as shown in the following
+example:
 
 @example
-cd tools
-mkdir build-sis
+rpm -i i386-rtems-gdb-collection-4.18-4.nosrc.rpm
 @end example
 
-@subheading Configure for the Build
-
-Configure the GNU Debugger for the
-Sparc Instruction Simulator (SIS):
+Because RTEMS tool RPMS are called "nosrc" to indicate that one or
+more source files required to produce the RPMs are not present.
+The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
+@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
+regardless of target CPU and there was no reason
+to duplicate them.  You will have to get the required source
+archive files by hand and place them in the @code{SOURCES} directory
+before attempting to build.  If you forget to do this, RPM is
+smart -- it will tell you what is missing.  To determine what is
+included or referenced by a particular RPM, use a command like the
+following:
 
 @example
-cd tools/build-sis
-../@value{GDB-UNTAR}/configure --target-sparc-erc32-aout \
-    --program-prefix=sparc-rtems- \
-    --disable-gdbtk \
-    --enable-targets=all \
-    --prefix=<INSTALL_POINT_FOR_SIS>
+$ rpm -q -l -p i386-rtems-gdb-collection-4.18-4.nosrc.rpm
+gdb-4.18-rtems-20000524.diff
+gdb-4.18.tar.gz
+i386-rtems-gdb-4.18.spec
 @end example
 
-Where <INSTALL_POINT_FOR_SIS> is a unique location where the gdb
-with SIS will be created. 
+Notice that there is a patch file (the @code{.diff} file), a source archive
+file (the @code{.tar.gz}), and a file describing the build procedure and
+files produced (the @code{.spec} file).  The @code{.spec} file is placed
+in the @code{SPECS} directory under the RPM root directory.
+
+c
+@c  Configuring and Building GDB using RPM
+@c
 
-@subheading Make the Debugger
+@subsubsection Configuring and Building GDB using RPM
 
-From tools/build-sis execute the following command sequence:
+The following example illustrates the invocation of RPM to build a new,
+locally compiled, binutils binary RPM that matches the installed source
+RPM.  This example assumes that all of the required source is installed.
 
 @example
-make all install
+cd <RPM_ROOT_DIRECTORY>/SPECS
+rpm -bb i386-rtems-gdb-4.18.spec
 @end example
 
-NOTE: The @code{make} utility used should be GNU make.
-
-@subsection GDB with PowerPC Instruction Simulator
-
-@subheading Make the Build Directory
-
-Create a build directory for the SIS Debugger
+If the build completes successfully, RPMS like the following will
+be generated in a build-host architecture specific subdirectory
+of the RPMS directory under the RPM root directory.
 
 @example
-cd tools
-mkdir build-ppc
+rtems-base-gdb-4.18-4.i386.rpm
+i386-rtems-gdb-4.18-4.i386.rpm
 @end example
 
-@subheading Configure for the Build
-
-Configure the GNU Debugger for the PowerPC
-Instruction Simulator (PSIM):
+NOTE: It may be necessary to remove the build tree in the
+@code{BUILD} directory under the RPM root directory.
 
-@example
-cd tools/build-ppc
-../@value{GDB-UNTAR}/configure \
-      --target=powerpc-unknown-eabi \
-      --program-prefix=powerpc-rtems- \
-      --enable-sim-powerpc \
-      --enable-sim-timebase \
-      --enable-sim-inline \
-      --enable-sim-hardware \
-      --enable-targets=all \
-      --prefix=<INSTALL_POINT_FOR_PPC>
-@end example
+@c
+@c Using the GDB configure Script Directly
+@c 
 
-Where <INSTALL_POINT_FOR_PPC> is a unique location where the gdb
-with PSIM will be created. 
+@subsection Using the GDB configure Script Directly
 
+This section describes how to configure the GNU debugger for
+standard RTEMS configurations as well as some alternative
+configurations that have been used in the past.
 
-@subheading Make the Debugger
+@subsubsection Standard RTEMS GDB Configuration
 
-From tools/build-ppc execute the following command sequence:
+The following example illustrates the invocation of configure
+and make to build and install @value{GDB-UNTAR} for the
+m68k-rtems target:
 
 @example
-make all install
+mkdir b-gdb
+cd b-gdb
+../@value{GDB-UNTAR}/configure --target=m68k-rtems \
+  --prefix=/opt/rtems
+make all
+make info
+make install
 @end example
 
-NOTE: The @code{make} utility used should be GNU make.
-
-@subsection GDB for DINK32
+For some configurations, it is necessary to specify extra options
+to @code{configure} to enable and configure option components
+such as a processor simulator.  The following is a list of
+configurations for which there are extra options:
 
-@subheading Make the Build Directory
+@table @b
+@item i960-rtems
+@code{--enable-sim}
 
-Create a build directory for the DINK32 Debugger
+@item powerpc-rtems
+@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
 
-@example
-cd tools
-mkdir build-dink32
-@end example
+@item sparc-rtems
+@code{--enable-sim}
 
-@subheading Configure for the Build
+@end table
 
-Configure the GNU Debugger to communicate with
-the DINK32 ROM monitor:
+After @value{GDB-UNTAR} is built and installed the
+build directory @code{b-gdb} may be removed.
 
-@example
-cd tools/build-dink32
-../@value{GDB-UNTAR}/configure --target-powerpc-elf \
-    --program-prefix=powerpc-rtems- \
-    --enable-targets=all \
-    --prefix=<INSTALL_POINT_FOR_DINK32>
-@end example
+For more information on the invocation of @code{configure}, please
+refer to the documentation for @value{GDB-UNTAR} or
+invoke the @value{GDB-UNTAR} configure command with the
+@code{--help} option.
 
-Where <INSTALL_POINT_FOR_DINK32> is a unique location where the
-gdb Dink32 will be created. 
+@subsection Using the bit_gdb Script
 
-@subheading Make the Debugger
+The simplest way to build gdb for RTEMS is to use the @code{bit_gdb} script.
+This script interprets the settings in the @code{user.cfg} file to
+produce the GDB configuration most appropriate for the target CPU.
 
-From tools/build-dink32 execute the following command sequence:
+This script is invoked as follows:
 
 @example
-make all install
+./bit_gdb CPU
 @end example
 
-NOTE: The @code{make} utility used should be GNU make.
+Where CPU is one of the RTEMS supported CPU families from the following
+list:
+
+@itemize @bullet
+@item hppa1.1
+@item i386
+@item i386-coff
+@item i386-elf
+@item i960
+@item m68k
+@item m68k-coff
+@item mips64orion
+@item powerpc
+@item sh
+@item sh-elf
+@item sparc
+@end itemize
+
+If gdb supports a CPU instruction simulator for this configuration, then
+it is included in the build.
+