summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-04-10 09:59:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-04-11 12:22:30 +0100
commita4223949ad923ddac144841a255d511df497a966 (patch)
tree89258943bce5718fffb6e5a8ca5a64474146e99a /documentation
parentae353c229cfe7e82588dc53fbed10c6ba8370d26 (diff)
downloadpoky-a4223949ad923ddac144841a255d511df497a966.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml196
1 files changed, 74 insertions, 122 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 51d65016fc..8684851dcc 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3868,25 +3868,51 @@
3868 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>. 3868 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
3869 </para> 3869 </para>
3870 3870
3871 <para>
3872 The remainder of this section describes the steps you need to take
3873 to debug using the GNU project debugger.
3874 </para>
3875
3876 <section id='platdev-gdb-remotedebug-setup'>
3877 <title>Set Up the Cross-Development Debugging Environment</title>
3878
3879 <para>
3880 Before you can initiate a remote debugging session, you need
3881 to be sure you have set up the cross-development environment,
3882 toolchain, and sysroot.
3883 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
3884 chapter of the Yocto Project Application Developer's Guide
3885 describes this process.
3886 Be sure you have read that chapter and have your environment
3887 set up.
3888 </para>
3889 </section>
3890
3871 <section id="platdev-gdb-remotedebug-launch-gdbserver"> 3891 <section id="platdev-gdb-remotedebug-launch-gdbserver">
3872 <title>Launching Gdbserver on the Target</title> 3892 <title>Launching Gdbserver on the Target</title>
3873 3893
3874 <para> 3894 <para>
3875 First, make sure Gdbserver is installed on the target. 3895 Make sure Gdbserver is installed on the target.
3876 If it is not, install the package <filename>gdbserver</filename>, which needs the 3896 If it is not, install the package
3897 <filename>gdbserver</filename>, which needs the
3877 <filename>libthread-db1</filename> package. 3898 <filename>libthread-db1</filename> package.
3878 </para> 3899 </para>
3879 3900
3880 <para> 3901 <para>
3881 As an example, to launch Gdbserver on the target and make it ready to "debug" a 3902 As an example, to launch Gdbserver on the target and make it
3882 program located at <filename>/path/to/inferior</filename>, connect 3903 ready to "debug" a program located in the
3883 to the target and launch: 3904 <filename>/usr/bin/hello</filename> directory, from the host
3905 you need to enter a command like the following.
3906 This command connects to the target and launches Gdbserver
3907 on the target:
3884 <literallayout class='monospaced'> 3908 <literallayout class='monospaced'>
3885 $ gdbserver localhost:2345 /path/to/inferior 3909 $ gdbserver localhost:2345 /usr/bin/hello
3886 </literallayout> 3910 </literallayout>
3887 Gdbserver should now be listening on port 2345 for debugging 3911 Gdbserver should now be listening on port 2345 for debugging
3888 commands coming from a remote GDB process that is running on the host computer. 3912 commands coming from a remote GDB process that is running on
3889 Communication between Gdbserver and the host GDB are done using TCP. 3913 the host computer.
3914 Communication between Gdbserver and the host GDB are done
3915 using TCP.
3890 To use other communication protocols, please refer to the 3916 To use other communication protocols, please refer to the
3891 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. 3917 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
3892 </para> 3918 </para>
@@ -3903,20 +3929,24 @@
3903 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> 3929 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
3904 <title>Build the Cross-GDB Package</title> 3930 <title>Build the Cross-GDB Package</title>
3905 <para> 3931 <para>
3906 A suitable GDB cross-binary is required that runs on your host computer but 3932 A suitable GDB cross-binary is required that runs on your
3907 also knows about the the ABI of the remote target. 3933 host computer but also knows about the the ABI of the
3908 You can get this binary from the meta-toolchain. 3934 remote target.
3935 You can get this binary from the
3936 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
3909 Here is an example where the toolchain has been installed 3937 Here is an example where the toolchain has been installed
3910 in the default directory <filename>/opt/poky/&DISTRO;</filename>: 3938 in the default directory
3939 <filename>/opt/poky/&DISTRO;</filename>:
3911 <literallayout class='monospaced'> 3940 <literallayout class='monospaced'>
3912 /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb 3941 /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
3913 </literallayout> 3942 </literallayout>
3914 where <filename>arm</filename> is the target architecture and 3943 where <filename>arm</filename> is the target architecture
3915 <filename>linux-gnueabi</filename> the target ABI. 3944 and <filename>linux-gnueabi</filename> the target ABI.
3916 </para> 3945 </para>
3917 3946
3918 <para> 3947 <para>
3919 Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary. 3948 Alternatively, you can use BitBake to build the
3949 <filename>gdb-cross</filename> binary.
3920 Here is an example: 3950 Here is an example:
3921 <literallayout class='monospaced'> 3951 <literallayout class='monospaced'>
3922 $ bitbake gdb-cross 3952 $ bitbake gdb-cross
@@ -3929,7 +3959,7 @@
3929 </section> 3959 </section>
3930 3960
3931 <section id='create-the-gdb-initialization-file'> 3961 <section id='create-the-gdb-initialization-file'>
3932 <title>Create the GDB Initialization File</title> 3962 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
3933 3963
3934 <para> 3964 <para>
3935 Aside from the GDB cross-binary, you also need a GDB 3965 Aside from the GDB cross-binary, you also need a GDB
@@ -3943,17 +3973,15 @@
3943 by maintained by 3973 by maintained by
3944 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>. 3974 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
3945 </para> 3975 </para>
3946 </section>
3947
3948 <section id='point-to-your-root-filesystem'>
3949 <title>Point to Your Root Filesystem</title>
3950 3976
3951 <para> 3977 <para>
3952 Before starting your debugging session, you need to enter 3978 You need to add a statement in the
3953 the following to set your root filesystem location 3979 <filename>.gdbinit</filename> file that points to your
3954 by using a command with this form: 3980 root filesystem.
3981 Here is an example that points to the root filesystem for
3982 an ARM-based target device:
3955 <literallayout class='monospaced'> 3983 <literallayout class='monospaced'>
3956 set sysroot &lt;your-sysroot-path&gt; 3984 set sysroot /home/jzhang/sysroot_arm
3957 </literallayout> 3985 </literallayout>
3958 </para> 3986 </para>
3959 </section> 3987 </section>
@@ -3962,122 +3990,46 @@
3962 <title>Launch the Host GDB</title> 3990 <title>Launch the Host GDB</title>
3963 3991
3964 <para> 3992 <para>
3965 To launch the host GDB, you need to source the 3993 Before launching the host GDB, you need to be sure
3966 cross-debugging environment script, which if you installed 3994 you have sourced the cross-debugging environment script,
3967 the root filesystem in the default location is at 3995 which if you installed the root filesystem in the default
3968 <filename>/opt/poky/&DISTRO;</filename> and begins with the 3996 location is at <filename>/opt/poky/&DISTRO;</filename>
3969 string "environment-setup". 3997 and begins with the string "environment-setup".
3998 For more information, see the
3999 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
4000 section in the Yocto Project Application Developer's
4001 Guide.
3970 </para> 4002 </para>
3971 4003
3972 <para> 4004 <para>
3973 Finally, run the <filename>cross-gdb</filename> binary 4005 Finally, switch to the directory where the binary resides
3974 and provide the inferior binary as part of the command line. 4006 and run the <filename>cross-gdb</filename> binary.
4007 Provide the binary file you are going to debug.
3975 For example, the following command form continues with the 4008 For example, the following command form continues with the
3976 example used in the previous section. 4009 example used in the previous section.
3977 This command form loads the <filename>foo</filename> binary 4010 This command form loads the <filename>helloworld</filename>
3978 as well as the debugging information: 4011 binary as well as the debugging information:
3979 <literallayout class='monospaced'> 4012 <literallayout class='monospaced'>
3980 $ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo 4013 $ i586-poky-linux-gdb helloworld
3981 </literallayout> 4014 </literallayout>
3982 The commands in your <filename>.gdbinit</filename> execute 4015 The commands in your <filename>.gdbinit</filename> execute
3983 and the GDB prompt appears. 4016 and the GDB prompt appears.
3984 </para> 4017 </para>
3985 </section> 4018 </section>
3986 4019
3987<!-- 4020 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
3988 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"> 4021 <title>Connect to the Remote GDB Server</title>
3989 <title>Making the Inferior Binaries Available</title>
3990 4022
3991 <para> 4023 <para>
3992 The inferior binary (complete with all debugging symbols), as well as any 4024 From the target, you need to connect to the remote GDB
3993 libraries (and their debugging symbols) on which the inferior binary depends, 4025 server that is running on the host.
3994 needs to be available. 4026 You need to specify the remote host and port.
3995 There are a number of ways you can make these items available. 4027 Here is the command continuing with the example:
3996 </para>
3997
3998 <para>
3999 Perhaps the easiest way is to have an SDK image that corresponds to the plain
4000 image installed on the device.
4001 In the case of <filename>core-image-sato</filename>,
4002 <filename>core-image-sato-sdk</filename> would contain suitable symbols.
4003 Because the SDK images already have the debugging symbols installed, it is just a
4004 question of expanding the archive to some location and then informing GDB.
4005 </para>
4006
4007 <para>
4008 Alternatively, the OpenEmbedded build system can build a custom directory of files
4009 for a specific
4010 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
4011 This directory contains the contents of the last built image.
4012 This process assumes two things:
4013 <itemizedlist>
4014 <listitem><para>The image running on the target was the last image to
4015 be built.</para></listitem>
4016 <listitem><para>The package (<filename>foo</filename> in the following
4017 example) that contains the inferior binary to be debugged has been built
4018 without optimization and has debugging information available.</para></listitem>
4019 </itemizedlist>
4020 </para>
4021
4022 <para>
4023 The following steps show how to build the custom directory of files:
4024 <orderedlist>
4025 <listitem><para>Install the package (<filename>foo</filename> in this case) to
4026 <filename>tmp/rootfs</filename>:
4027 <literallayout class='monospaced'>
4028 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
4029 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
4030 tmp/rootfs/ update
4031 </literallayout></para></listitem>
4032 <listitem><para>Install the debugging information:
4033 <literallayout class='monospaced'>
4034 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
4035 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
4036 -o tmp/rootfs install foo
4037
4038 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
4039 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
4040 -o tmp/rootfs install foo-dbg
4041 </literallayout></para></listitem>
4042 </orderedlist>
4043 </para>
4044 </section>
4045
4046 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
4047 <title>Launch the Host GDB</title>
4048
4049 <para>
4050 To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
4051 the inferior binary as part of the command line.
4052 For example, the following command form continues with the example used in
4053 the previous section.
4054 This command form loads the <filename>foo</filename> binary
4055 as well as the debugging information:
4056 <literallayout class='monospaced'>
4057 $ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
4058 </literallayout>
4059 Once the GDB prompt appears, you must instruct GDB to load all the libraries
4060 of the inferior binary from <filename>tmp/rootfs</filename> as follows:
4061 <literallayout class='monospaced'> 4028 <literallayout class='monospaced'>
4062 $ set solib-absolute-prefix /path/to/tmp/rootfs 4029 target remote 192.168.7.2:2345
4063 </literallayout> 4030 </literallayout>
4064 The pathname <filename>/path/to/tmp/rootfs</filename> must either be
4065 the absolute path to <filename>tmp/rootfs</filename> or the location at which
4066 binaries with debugging information reside.
4067 </para>
4068
4069 <para>
4070 At this point you can have GDB connect to the Gdbserver that is running
4071 on the remote target by using the following command form:
4072 <literallayout class='monospaced'>
4073 $ target remote remote-target-ip-address:2345
4074 </literallayout>
4075 The <filename>remote-target-ip-address</filename> is the IP address of the
4076 remote target where the Gdbserver is running.
4077 Port 2345 is the port on which the GDBSERVER is running.
4078 </para> 4031 </para>
4079 </section> 4032 </section>
4080-->
4081 4033
4082 <section id="platdev-gdb-remotedebug-launch-gdb-using"> 4034 <section id="platdev-gdb-remotedebug-launch-gdb-using">
4083 <title>Use the Debugger</title> 4035 <title>Use the Debugger</title>