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>

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 @@
             <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,122 +3990,46 @@
                 <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>
-                </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:
+                    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'>
-     $ set solib-absolute-prefix /path/to/tmp/rootfs
+     target remote 192.168.7.2:2345
                     </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>