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>. <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
</para> </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"> <section id="platdev-gdb-remotedebug-launch-gdbserver">
<title>Launching Gdbserver on the Target</title> <title>Launching Gdbserver on the Target</title>
<para> <para>
First, make sure Gdbserver is installed on the target. Make sure Gdbserver is installed on the target.
If it is not, install the package <filename>gdbserver</filename>, which needs the If it is not, install the package
<filename>gdbserver</filename>, which needs the
<filename>libthread-db1</filename> package. <filename>libthread-db1</filename> package.
</para> </para>
<para> <para>
As an example, to launch Gdbserver on the target and make it ready to "debug" a As an example, to launch Gdbserver on the target and make it
program located at <filename>/path/to/inferior</filename>, connect ready to "debug" a program located in the
to the target and launch: <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'> <literallayout class='monospaced'>
$ gdbserver localhost:2345 /path/to/inferior $ gdbserver localhost:2345 /usr/bin/hello
</literallayout> </literallayout>
Gdbserver should now be listening on port 2345 for debugging Gdbserver should now be listening on port 2345 for debugging
commands coming from a remote GDB process that is running on the host computer. commands coming from a remote GDB process that is running on
Communication between Gdbserver and the host GDB are done using TCP. the host computer.
Communication between Gdbserver and the host GDB are done
using TCP.
To use other communication protocols, please refer to the To use other communication protocols, please refer to the
<ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
</para> </para>
@ -3903,20 +3929,24 @@
<section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
<title>Build the Cross-GDB Package</title> <title>Build the Cross-GDB Package</title>
<para> <para>
A suitable GDB cross-binary is required that runs on your host computer but A suitable GDB cross-binary is required that runs on your
also knows about the the ABI of the remote target. host computer but also knows about the the ABI of the
You can get this binary from the meta-toolchain. 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 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'> <literallayout class='monospaced'>
/opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
</literallayout> </literallayout>
where <filename>arm</filename> is the target architecture and where <filename>arm</filename> is the target architecture
<filename>linux-gnueabi</filename> the target ABI. and <filename>linux-gnueabi</filename> the target ABI.
</para> </para>
<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: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake gdb-cross $ bitbake gdb-cross
@ -3929,7 +3959,7 @@
</section> </section>
<section id='create-the-gdb-initialization-file'> <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> <para>
Aside from the GDB cross-binary, you also need a GDB Aside from the GDB cross-binary, you also need a GDB
@ -3943,17 +3973,15 @@
by maintained by by maintained by
<ulink url='http://www.sourceware.org'>sourceware.org</ulink>. <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
</para> </para>
</section>
<section id='point-to-your-root-filesystem'>
<title>Point to Your Root Filesystem</title>
<para> <para>
Before starting your debugging session, you need to enter You need to add a statement in the
the following to set your root filesystem location <filename>.gdbinit</filename> file that points to your
by using a command with this form: root filesystem.
Here is an example that points to the root filesystem for
an ARM-based target device:
<literallayout class='monospaced'> <literallayout class='monospaced'>
set sysroot &lt;your-sysroot-path&gt; set sysroot /home/jzhang/sysroot_arm
</literallayout> </literallayout>
</para> </para>
</section> </section>
@ -3962,123 +3990,47 @@
<title>Launch the Host GDB</title> <title>Launch the Host GDB</title>
<para> <para>
To launch the host GDB, you need to source the Before launching the host GDB, you need to be sure
cross-debugging environment script, which if you installed you have sourced the cross-debugging environment script,
the root filesystem in the default location is at which if you installed the root filesystem in the default
<filename>/opt/poky/&DISTRO;</filename> and begins with the location is at <filename>/opt/poky/&DISTRO;</filename>
string "environment-setup". 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>
<para> <para>
Finally, run the <filename>cross-gdb</filename> binary Finally, switch to the directory where the binary resides
and provide the inferior binary as part of the command line. 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 For example, the following command form continues with the
example used in the previous section. example used in the previous section.
This command form loads the <filename>foo</filename> binary This command form loads the <filename>helloworld</filename>
as well as the debugging information: binary as well as the debugging information:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo $ i586-poky-linux-gdb helloworld
</literallayout> </literallayout>
The commands in your <filename>.gdbinit</filename> execute The commands in your <filename>.gdbinit</filename> execute
and the GDB prompt appears. and the GDB prompt appears.
</para> </para>
</section> </section>
<!-- <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
<section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"> <title>Connect to the Remote GDB Server</title>
<title>Making the Inferior Binaries Available</title>
<para> <para>
The inferior binary (complete with all debugging symbols), as well as any From the target, you need to connect to the remote GDB
libraries (and their debugging symbols) on which the inferior binary depends, server that is running on the host.
needs to be available. You need to specify the remote host and port.
There are a number of ways you can make these items available. Here is the command continuing with the example:
</para> <literallayout class='monospaced'>
target remote 192.168.7.2:2345
<para> </literallayout>
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>
</para> </para>
</section> </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"> <section id="platdev-gdb-remotedebug-launch-gdb-using">
<title>Use the Debugger</title> <title>Use the Debugger</title>