sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: Updates to the debugging using GDB section. 

Fixes YOCTO #3540

Applied changes per Jessica Zhang's feedback from the bug
entry in Bugzilla.  I added some missing steps and also
tried to make the section stick with one example throughout.

(From yocto-docs rev: f995006a90a3646c92d54dc96a8fceae4de758eb)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-04-10 09:59:23 -07:00 committed by Richard Purdie
parent ae353c229c
commit a4223949ad
1 changed files with 76 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -3868,25 +3868,51 @@
<ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
</para>
<para>
The remainder of this section describes the steps you need to take
to debug using the GNU project debugger.
</para>
<section id='platdev-gdb-remotedebug-setup'>
<title>Set Up the Cross-Development Debugging Environment</title>
<para>
Before you can initiate a remote debugging session, you need
to be sure you have set up the cross-development environment,
toolchain, and sysroot.
The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
chapter of the Yocto Project Application Developer's Guide
describes this process.
Be sure you have read that chapter and have your environment
set up.
</para>
</section>
<section id="platdev-gdb-remotedebug-launch-gdbserver">
<title>Launching Gdbserver on the Target</title>
<para>
First, make sure Gdbserver is installed on the target.
If it is not, install the package <filename>gdbserver</filename>, which needs the
Make sure Gdbserver is installed on the target.
If it is not, install the package
<filename>gdbserver</filename>, which needs the
<filename>libthread-db1</filename> package.
</para>
<para>
As an example, to launch Gdbserver on the target and make it ready to "debug" a
program located at <filename>/path/to/inferior</filename>, connect
to the target and launch:
As an example, to launch Gdbserver on the target and make it
ready to "debug" a program located in the
<filename>/usr/bin/hello</filename> directory, from the host
you need to enter a command like the following.
This command connects to the target and launches Gdbserver
on the target:
<literallayout class='monospaced'>
$ gdbserver localhost:2345 /path/to/inferior
$ gdbserver localhost:2345 /usr/bin/hello
</literallayout>
Gdbserver should now be listening on port 2345 for debugging
commands coming from a remote GDB process that is running on the host computer.
Communication between Gdbserver and the host GDB are done using TCP.
commands coming from a remote GDB process that is running on
the host computer.
Communication between Gdbserver and the host GDB are done
using TCP.
To use other communication protocols, please refer to the
<ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
</para>
@ -3903,20 +3929,24 @@
<section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
<title>Build the Cross-GDB Package</title>
<para>
A suitable GDB cross-binary is required that runs on your host computer but
also knows about the the ABI of the remote target.
You can get this binary from the meta-toolchain.
A suitable GDB cross-binary is required that runs on your
host computer but also knows about the the ABI of the
remote target.
You can get this binary from the
<link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
Here is an example where the toolchain has been installed
in the default directory <filename>/opt/poky/&DISTRO;</filename>:
in the default directory
<filename>/opt/poky/&DISTRO;</filename>:
<literallayout class='monospaced'>
/opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
</literallayout>
where <filename>arm</filename> is the target architecture and
<filename>linux-gnueabi</filename> the target ABI.
where <filename>arm</filename> is the target architecture
and <filename>linux-gnueabi</filename> the target ABI.
</para>
<para>
Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary.
Alternatively, you can use BitBake to build the
<filename>gdb-cross</filename> binary.
Here is an example:
<literallayout class='monospaced'>
$ bitbake gdb-cross
@ -3929,7 +3959,7 @@
</section>
<section id='create-the-gdb-initialization-file'>
<title>Create the GDB Initialization File</title>
<title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
<para>
Aside from the GDB cross-binary, you also need a GDB
@ -3943,17 +3973,15 @@
by maintained by
<ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
</para>
</section>
<section id='point-to-your-root-filesystem'>
<title>Point to Your Root Filesystem</title>
<para>
Before starting your debugging session, you need to enter
the following to set your root filesystem location
by using a command with this form:
You need to add a statement in the
<filename>.gdbinit</filename> file that points to your
root filesystem.
Here is an example that points to the root filesystem for
an ARM-based target device:
<literallayout class='monospaced'>
set sysroot &lt;your-sysroot-path&gt;
set sysroot /home/jzhang/sysroot_arm
</literallayout>
</para>
</section>
@ -3962,123 +3990,47 @@
<title>Launch the Host GDB</title>
<para>
To launch the host GDB, you need to source the
cross-debugging environment script, which if you installed
the root filesystem in the default location is at
<filename>/opt/poky/&DISTRO;</filename> and begins with the
string "environment-setup".
Before launching the host GDB, you need to be sure
you have sourced the cross-debugging environment script,
which if you installed the root filesystem in the default
location is at <filename>/opt/poky/&DISTRO;</filename>
and begins with the string "environment-setup".
For more information, see the
"<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
section in the Yocto Project Application Developer's
Guide.
</para>
<para>
Finally, run the <filename>cross-gdb</filename> binary
and provide the inferior binary as part of the command line.
Finally, switch to the directory where the binary resides
and run the <filename>cross-gdb</filename> binary.
Provide the binary file you are going to debug.
For example, the following command form continues with the
example used in the previous section.
This command form loads the <filename>foo</filename> binary
as well as the debugging information:
This command form loads the <filename>helloworld</filename>
binary as well as the debugging information:
<literallayout class='monospaced'>
$ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
$ i586-poky-linux-gdb helloworld
</literallayout>
The commands in your <filename>.gdbinit</filename> execute
and the GDB prompt appears.
</para>
</section>
<!--
<section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
<title>Making the Inferior Binaries Available</title>
<section id='platdev-gdb-connect-to-the-remote-gdb-server'>
<title>Connect to the Remote GDB Server</title>
<para>
The inferior binary (complete with all debugging symbols), as well as any
libraries (and their debugging symbols) on which the inferior binary depends,
needs to be available.
There are a number of ways you can make these items available.
</para>
<para>
Perhaps the easiest way is to have an SDK image that corresponds to the plain
image installed on the device.
In the case of <filename>core-image-sato</filename>,
<filename>core-image-sato-sdk</filename> would contain suitable symbols.
Because the SDK images already have the debugging symbols installed, it is just a
question of expanding the archive to some location and then informing GDB.
</para>
<para>
Alternatively, the OpenEmbedded build system can build a custom directory of files
for a specific
debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
This directory contains the contents of the last built image.
This process assumes two things:
<itemizedlist>
<listitem><para>The image running on the target was the last image to
be built.</para></listitem>
<listitem><para>The package (<filename>foo</filename> in the following
example) that contains the inferior binary to be debugged has been built
without optimization and has debugging information available.</para></listitem>
</itemizedlist>
</para>
<para>
The following steps show how to build the custom directory of files:
<orderedlist>
<listitem><para>Install the package (<filename>foo</filename> in this case) to
<filename>tmp/rootfs</filename>:
<literallayout class='monospaced'>
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
tmp/rootfs/ update
</literallayout></para></listitem>
<listitem><para>Install the debugging information:
<literallayout class='monospaced'>
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
-o tmp/rootfs install foo
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
-o tmp/rootfs install foo-dbg
</literallayout></para></listitem>
</orderedlist>
From the target, you need to connect to the remote GDB
server that is running on the host.
You need to specify the remote host and port.
Here is the command continuing with the example:
<literallayout class='monospaced'>
target remote 192.168.7.2:2345
</literallayout>
</para>
</section>
<section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
<title>Launch the Host GDB</title>
<para>
To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
the inferior binary as part of the command line.
For example, the following command form continues with the example used in
the previous section.
This command form loads the <filename>foo</filename> binary
as well as the debugging information:
<literallayout class='monospaced'>
$ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
</literallayout>
Once the GDB prompt appears, you must instruct GDB to load all the libraries
of the inferior binary from <filename>tmp/rootfs</filename> as follows:
<literallayout class='monospaced'>
$ set solib-absolute-prefix /path/to/tmp/rootfs
</literallayout>
The pathname <filename>/path/to/tmp/rootfs</filename> must either be
the absolute path to <filename>tmp/rootfs</filename> or the location at which
binaries with debugging information reside.
</para>
<para>
At this point you can have GDB connect to the Gdbserver that is running
on the remote target by using the following command form:
<literallayout class='monospaced'>
$ target remote remote-target-ip-address:2345
</literallayout>
The <filename>remote-target-ip-address</filename> is the IP address of the
remote target where the Gdbserver is running.
Port 2345 is the port on which the GDBSERVER is running.
</para>
</section>
-->
<section id="platdev-gdb-remotedebug-launch-gdb-using">
<title>Use the Debugger</title>