diff options
Diffstat (limited to '')
-rw-r--r-- | doc/started/gdb.t | 270 |
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. + |