From b2f1d21ff3d0e2f1f152a208394741dad789a623 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 11 Oct 2016 09:46:28 -0700 Subject: dev-manual: Re-wrote the remote GDB debugging section. Fixed [YOCTO #9481] Complete re-write based on Mark Hatle's steps. I converted from sub-sections to an ordered list. (From yocto-docs rev: f83bfe5d3dc012b924b6870672d7260a9c0bc3ee) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 463 +++++++++------------ 1 file changed, 193 insertions(+), 270 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 5c7284238d..a2376f67a8 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -9736,15 +9736,6 @@ as all the heavy debugging is done by the host GDB. Offloading these processes gives the Gdbserver running on the target a chance to remain small and fast. - - By default, source files are part of the - *-dbg packages in order to enable GDB - to show source lines in its output. - You can save further space on the target by setting the - PACKAGE_DEBUG_SPLIT_STYLE - variable to "debug-without-src" so that these packages do not - include the source files. - @@ -9768,10 +9759,200 @@ - The remainder of this section describes the steps you need to take - to debug using the GNU project debugger. + The following steps show you how to debug using the GNU project + debugger. + + + Configure your build system to construct the + companion debug filesystem: + + In your local.conf file, set + the following: + + IMAGE_GEN_DEBUGFS = "1" + IMAGE_FSTYPES_DEBUGFS = "tar.bz2" + + These options cause the OpenEmbedded build system + to generate a special companion filesystem fragment, + which contains the matching source and debug symbols to + your deployable filesystem. + The build system does this by looking at what is in the + deployed filesystem, and pulling the corresponding + -dbg packages. + + The companion debug filesystem is not a complete + filesystem, but only contains the debug fragments. + This filesystem must be combined with the full filesystem + for debugging. + Subsequent steps in this procedure show how to combine + the partial filesystem with the full filesystem. + + + Configure the system to include Gdbserver in + the target filesystem: + + Make the following addition in either your + local.conf file or in an image + recipe: + + IMAGE_INSTALL_append = “ gdbserver" + + The change makes sure the gdbserver + package is included. + + + Build the environment: + + Use the following command to construct the image and + the companion Debug Filesystem: + + $ bitbake image + + Build the cross GDB component and make it available + for debugging. + Build the SDK that matches the image. + Building the SDK is best for a production build + that can be used later for debugging, especially + during long term maintenance: + + $ bitbake -c populate_sdk image + + + Alternatively, you can build the minimal + toolchain components that match the target. + Doing so creates a smaller than typical SDK and only + contains a minimal set of components with which to + build simple test applications, as well as run the + debugger: + + $ bitbake meta-toolchain + + + A final method is to build Gdb itself within + the build system: + + $ bitbake gdb-cross-architecture + + Doing so produces a temporary copy of + cross-gdb you can use for + debugging during development. + While this is the quickest approach, the two previous + methods in this step are better when considering + long-term maintenance strategies. + + If you run + bitbake gdb-cross, the + OpenEmbedded build system suggests the actual + image (e.g. gdb-cross-i586). + The suggestion is usually the actual name you want + to use. + + + + Set up the debugfs + + Run the following commands to set up the + debugfs: + + $ mkdir debugfs + $ cd debugfs + $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2 + $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image-dbg.rootfs.tar.bz2 + + + + Set up GDB + + Install the SDK (if you built one) and then + source the correct environment file. + Sourcing the environment file puts the SDK in your + PATH environment variable. + + If you are using the build system, Gdb is + located in + build-dir/tmp/sysroots/host/usr/bin/architecture/architecture-gdb + + + Boot the target: + + For information on how to run QEMU, see the + QEMU Documentation. + + Be sure to verify that your host can access the + target via TCP. + + + + Debug a program: + + Debugging a program involves running Gdbserver + on the target and then running Gdb on the host. + The example in this step debugs + gzip: + + root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help + + For additional Gdbserver options, see the + Gdb Server Documentation. + + + After running Gdbserver on the target, you need + to run Gdb on the host and configure it and connect to + the target. + Use these commands: + + $ cd directory-holding-the-debugfs-directory + $ arch-gdb + + (gdb) set sysroot debugfs + (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug + (gdb) target remote IP-of-target:1234 + + At this point, everything should automatically load + (i.e. matching binaries, symbols and headers). + + The Gdb set commands in the + previous example can be placed into the users + ~/.gdbinit file. + Upon starting, Gdb automatically runs whatever + commands are in that file. + + + + Deploying without a full image + rebuild: + + In many cases, during development you want a + quick method to deploy a new binary to the target and + debug it, without waiting for a full image build. + + + One approach to solving this situation is to + just build the component you want to debug. + Once you have built the component, copy the + executable directly to both the target and the + host debugfs. + + If the binary is processed through the debug + splitting in OpenEmbedded, you should also + copy the debug items (i.e. .debug + contents and corresponding + /usr/src/debug files) + from the work directory. + Here is an example: + + $ bitbake bash + $ bitbake -c devshell bash + $ cd .. + $ scp packages-split/bash/bin/bash target:/bin/bash + $ cp -a packages-split/bash-dbg/* path/debugfs + + + + +
Debugging with the GNU Project Debugger (GDB) on the Target @@ -10290,265 +10472,6 @@
- -
Maintaining Open Source License Compliance During Your Product's Lifecycle -- cgit v1.2.3-54-g00ecf