summaryrefslogtreecommitdiffstats
path: root/doc/started/gdb.t
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2002-01-17 21:47:47 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2002-01-17 21:47:47 +0000
commit6449498bc7dea93900d6980a66af64c9116ef597 (patch)
tree7d89881d70af765dc7ad549095fb9f5f381cba6f /doc/started/gdb.t
parentd09ad1f0e0c435fce5f1d0a36f089cb69cb3f5cc (diff)
downloadrtems-6449498bc7dea93900d6980a66af64c9116ef597.tar.bz2
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.
Diffstat (limited to 'doc/started/gdb.t')
-rw-r--r--doc/started/gdb.t270
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.
+