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