summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-10-11 09:46:28 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-10-13 23:16:47 +0100
commitb2f1d21ff3d0e2f1f152a208394741dad789a623 (patch)
tree7883b174e6ffa6a6935e493751543d5ca3c89f5b /documentation/dev-manual/dev-manual-common-tasks.xml
parent551f7d87c9fb6e4652afd6a921c9e4f816ebc2b7 (diff)
downloadpoky-b2f1d21ff3d0e2f1f152a208394741dad789a623.tar.gz
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 <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml463
1 files changed, 193 insertions, 270 deletions
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 @@
9736 as all the heavy debugging is done by the host GDB. 9736 as all the heavy debugging is done by the host GDB.
9737 Offloading these processes gives the Gdbserver running on the target a chance to remain 9737 Offloading these processes gives the Gdbserver running on the target a chance to remain
9738 small and fast. 9738 small and fast.
9739 <note>
9740 By default, source files are part of the
9741 <filename>*-dbg</filename> packages in order to enable GDB
9742 to show source lines in its output.
9743 You can save further space on the target by setting the
9744 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink>
9745 variable to "debug-without-src" so that these packages do not
9746 include the source files.
9747 </note>
9748 </para> 9739 </para>
9749 9740
9750 <para> 9741 <para>
@@ -9768,10 +9759,200 @@
9768 </para> 9759 </para>
9769 9760
9770 <para> 9761 <para>
9771 The remainder of this section describes the steps you need to take 9762 The following steps show you how to debug using the GNU project
9772 to debug using the GNU project debugger. 9763 debugger.
9764 <orderedlist>
9765 <listitem><para>
9766 <emphasis>Configure your build system to construct the
9767 companion debug filesystem:</emphasis></para>
9768
9769 <para>In your <filename>local.conf</filename> file, set
9770 the following:
9771 <literallayout class='monospaced'>
9772 IMAGE_GEN_DEBUGFS = "1"
9773 IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
9774 </literallayout>
9775 These options cause the OpenEmbedded build system
9776 to generate a special companion filesystem fragment,
9777 which contains the matching source and debug symbols to
9778 your deployable filesystem.
9779 The build system does this by looking at what is in the
9780 deployed filesystem, and pulling the corresponding
9781 <filename>-dbg</filename> packages.</para>
9782
9783 <para>The companion debug filesystem is not a complete
9784 filesystem, but only contains the debug fragments.
9785 This filesystem must be combined with the full filesystem
9786 for debugging.
9787 Subsequent steps in this procedure show how to combine
9788 the partial filesystem with the full filesystem.
9789 </para></listitem>
9790 <listitem><para>
9791 <emphasis>Configure the system to include Gdbserver in
9792 the target filesystem:</emphasis></para>
9793
9794 <para>Make the following addition in either your
9795 <filename>local.conf</filename> file or in an image
9796 recipe:
9797 <literallayout class='monospaced'>
9798 IMAGE_INSTALL_append = “ gdbserver"
9799 </literallayout>
9800 The change makes sure the <filename>gdbserver</filename>
9801 package is included.
9802 </para></listitem>
9803 <listitem><para>
9804 <emphasis>Build the environment:</emphasis></para>
9805
9806 <para>Use the following command to construct the image and
9807 the companion Debug Filesystem:
9808 <literallayout class='monospaced'>
9809 $ bitbake <replaceable>image</replaceable>
9810 </literallayout>
9811 Build the cross GDB component and make it available
9812 for debugging.
9813 Build the SDK that matches the image.
9814 Building the SDK is best for a production build
9815 that can be used later for debugging, especially
9816 during long term maintenance:
9817 <literallayout class='monospaced'>
9818 $ bitbake -c populate_sdk <replaceable>image</replaceable>
9819 </literallayout></para>
9820
9821 <para>Alternatively, you can build the minimal
9822 toolchain components that match the target.
9823 Doing so creates a smaller than typical SDK and only
9824 contains a minimal set of components with which to
9825 build simple test applications, as well as run the
9826 debugger:
9827 <literallayout class='monospaced'>
9828 $ bitbake meta-toolchain
9829 </literallayout></para>
9830
9831 <para>A final method is to build Gdb itself within
9832 the build system:
9833 <literallayout class='monospaced'>
9834 $ bitbake gdb-cross-<replaceable>architecture</replaceable>
9835 </literallayout>
9836 Doing so produces a temporary copy of
9837 <filename>cross-gdb</filename> you can use for
9838 debugging during development.
9839 While this is the quickest approach, the two previous
9840 methods in this step are better when considering
9841 long-term maintenance strategies.
9842 <note>
9843 If you run
9844 <filename>bitbake gdb-cross</filename>, the
9845 OpenEmbedded build system suggests the actual
9846 image (e.g. <filename>gdb-cross-i586</filename>).
9847 The suggestion is usually the actual name you want
9848 to use.
9849 </note>
9850 </para></listitem>
9851 <listitem><para>
9852 <emphasis>Set up the</emphasis>&nbsp;<filename>debugfs</filename></para>
9853
9854 <para>Run the following commands to set up the
9855 <filename>debugfs</filename>:
9856 <literallayout class='monospaced'>
9857 $ mkdir debugfs
9858 $ cd debugfs
9859 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
9860 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
9861 </literallayout>
9862 </para></listitem>
9863 <listitem><para>
9864 <emphasis>Set up GDB</emphasis></para>
9865
9866 <para>Install the SDK (if you built one) and then
9867 source the correct environment file.
9868 Sourcing the environment file puts the SDK in your
9869 <filename>PATH</filename> environment variable.</para>
9870
9871 <para>If you are using the build system, Gdb is
9872 located in
9873 <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
9874 </para></listitem>
9875 <listitem><para>
9876 <emphasis>Boot the target:</emphasis></para>
9877
9878 <para>For information on how to run QEMU, see the
9879 <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
9880 <note>
9881 Be sure to verify that your host can access the
9882 target via TCP.
9883 </note>
9884 </para></listitem>
9885 <listitem><para>
9886 <emphasis>Debug a program:</emphasis></para>
9887
9888 <para>Debugging a program involves running Gdbserver
9889 on the target and then running Gdb on the host.
9890 The example in this step debugs
9891 <filename>gzip</filename>:
9892 <literallayout class='monospaced'>
9893 root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
9894 </literallayout>
9895 For additional Gdbserver options, see the
9896 <ulink url='https://www.gnu.org/software/gdb/documentation/'>Gdb Server Documentation</ulink>.
9897 </para>
9898
9899 <para>After running Gdbserver on the target, you need
9900 to run Gdb on the host and configure it and connect to
9901 the target.
9902 Use these commands:
9903 <literallayout class='monospaced'>
9904 $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
9905 $ <replaceable>arch</replaceable>-gdb
9906
9907 (gdb) set sysroot debugfs
9908 (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
9909 (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
9910 </literallayout>
9911 At this point, everything should automatically load
9912 (i.e. matching binaries, symbols and headers).
9913 <note>
9914 The Gdb <filename>set</filename> commands in the
9915 previous example can be placed into the users
9916 <filename>~/.gdbinit</filename> file.
9917 Upon starting, Gdb automatically runs whatever
9918 commands are in that file.
9919 </note>
9920 </para></listitem>
9921 <listitem><para>
9922 <emphasis>Deploying without a full image
9923 rebuild:</emphasis></para>
9924
9925 <para>In many cases, during development you want a
9926 quick method to deploy a new binary to the target and
9927 debug it, without waiting for a full image build.
9928 </para>
9929
9930 <para>One approach to solving this situation is to
9931 just build the component you want to debug.
9932 Once you have built the component, copy the
9933 executable directly to both the target and the
9934 host <filename>debugfs</filename>.</para>
9935
9936 <para>If the binary is processed through the debug
9937 splitting in OpenEmbedded, you should also
9938 copy the debug items (i.e. <filename>.debug</filename>
9939 contents and corresponding
9940 <filename>/usr/src/debug</filename> files)
9941 from the work directory.
9942 Here is an example:
9943 <literallayout class='monospaced'>
9944 $ bitbake bash
9945 $ bitbake -c devshell bash
9946 $ cd ..
9947 $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
9948 $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
9949 </literallayout>
9950 </para></listitem>
9951 </orderedlist>
9773 </para> 9952 </para>
9953 </section>
9774 9954
9955<!--
9775 <section id='platdev-gdb-remotedebug-setup'> 9956 <section id='platdev-gdb-remotedebug-setup'>
9776 <title>Set Up the Cross-Development Debugging Environment</title> 9957 <title>Set Up the Cross-Development Debugging Environment</title>
9777 9958
@@ -9945,6 +10126,7 @@
9945 </para> 10126 </para>
9946 </section> 10127 </section>
9947 </section> 10128 </section>
10129-->
9948 10130
9949 <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'> 10131 <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
9950 <title>Debugging with the GNU Project Debugger (GDB) on the Target</title> 10132 <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
@@ -10290,265 +10472,6 @@
10290 </section> 10472 </section>
10291 </section> 10473 </section>
10292 10474
10293<!--
10294 <section id="platdev-oprofile">
10295 <title>Profiling with OProfile</title>
10296
10297 <para>
10298 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
10299 statistical profiler well suited for finding performance
10300 bottlenecks in both user-space software and in the kernel.
10301 This profiler provides answers to questions like "Which functions does my application spend
10302 the most time in when doing X?"
10303 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
10304 applications on target hardware straight forward.
10305 <note>
10306 For more information on how to set up and run OProfile, see the
10307 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
10308 section in the Yocto Project Profiling and Tracing Manual.
10309 </note>
10310 </para>
10311
10312 <para>
10313 To use OProfile, you need an image that has OProfile installed.
10314 The easiest way to do this is with "tools-profile" in the
10315 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
10316 You also need debugging symbols to be available on the system where the analysis
10317 takes place.
10318 You can gain access to the symbols by using "dbg-pkgs" in the
10319 <filename>IMAGE_FEATURES</filename> variable or by
10320 installing the appropriate debug (<filename>-dbg</filename>)
10321 packages.
10322 </para>
10323
10324 <para>
10325 For successful call graph analysis, the binaries must preserve the frame
10326 pointer register and should also be compiled with the
10327 <filename>-fno-omit-framepointer</filename> flag.
10328 You can achieve this by setting the
10329 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
10330 variable with the following options:
10331 <literallayout class='monospaced'>
10332 -fexpensive-optimizations
10333 -fno-omit-framepointer
10334 -frename-registers
10335 -O2
10336 </literallayout>
10337 You can also achieve it by setting the
10338 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
10339 variable to "1" in the <filename>local.conf</filename> configuration file.
10340 If you use the <filename>DEBUG_BUILD</filename> variable,
10341 you also add extra debugging information that can make the debug
10342 packages large.
10343 </para>
10344
10345 <section id="platdev-oprofile-target">
10346 <title>Profiling on the Target</title>
10347
10348 <para>
10349 Using OProfile, you can perform all the profiling work on the target device.
10350 A simple OProfile session might look like the following:
10351 </para>
10352
10353 <para>
10354 <literallayout class='monospaced'>
10355 # opcontrol &dash;&dash;reset
10356 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
10357 .
10358 .
10359 [do whatever is being profiled]
10360 .
10361 .
10362 # opcontrol &dash;&dash;stop
10363 $ opreport -cl
10364 </literallayout>
10365 </para>
10366
10367 <para>
10368 In this example, the <filename>reset</filename> command clears any previously profiled data.
10369 The next command starts OProfile.
10370 The options used when starting the profiler separate dynamic library data
10371 within applications, disable kernel profiling, and enable callgraphing up to
10372 five levels deep.
10373 <note>
10374 To profile the kernel, you would specify the
10375 <filename>&dash;&dash;vmlinux=/path/to/vmlinux</filename> option.
10376 The <filename>vmlinux</filename> file is usually in the source directory in the
10377 <filename>/boot/</filename> directory and must match the running kernel.
10378 </note>
10379 </para>
10380
10381 <para>
10382 After you perform your profiling tasks, the next command stops the profiler.
10383 After that, you can view results with the <filename>opreport</filename> command with options
10384 to see the separate library symbols and callgraph information.
10385 </para>
10386
10387 <para>
10388 Callgraphing logs information about time spent in functions and about a function's
10389 calling function (parent) and called functions (children).
10390 The higher the callgraphing depth, the more accurate the results.
10391 However, higher depths also increase the logging overhead.
10392 Consequently, you should take care when setting the callgraphing depth.
10393 <note>
10394 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
10395 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
10396 with <filename>gcc</filename>.
10397 </note>
10398 </para>
10399
10400 <para>
10401 For more information on using OProfile, see the OProfile
10402 online documentation at
10403 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
10404 </para>
10405 </section>
10406
10407 <section id="platdev-oprofile-oprofileui">
10408 <title>Using OProfileUI</title>
10409
10410 <para>
10411 A graphical user interface for OProfile is also available.
10412 You can download and build this interface from the Yocto Project at
10413 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
10414 If the "tools-profile" image feature is selected, all necessary binaries
10415 are installed onto the target device for OProfileUI interaction.
10416 For a list of image features that ship with the Yocto Project,
10417 see the
10418 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
10419 section in the Yocto Project Reference Manual.
10420 </para>
10421
10422 <para>
10423 Even though the source directory usually includes all needed patches on the target device, you
10424 might find you need other OProfile patches for recent OProfileUI features.
10425 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
10426 OProfileUI README</ulink> for the most recent information.
10427 </para>
10428
10429 <section id="platdev-oprofile-oprofileui-online">
10430 <title>Online Mode</title>
10431
10432 <para>
10433 Using OProfile in online mode assumes a working network connection with the target
10434 hardware.
10435 With this connection, you just need to run "oprofile-server" on the device.
10436 By default, OProfile listens on port 4224.
10437 <note>
10438 You can change the port using the <filename>&dash;&dash;port</filename> command-line
10439 option.
10440 </note>
10441 </para>
10442
10443 <para>
10444 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
10445 straight forward.
10446 You access key functionality through the buttons on the toolbar, which
10447 are duplicated in the menus.
10448 Here are the buttons:
10449 <itemizedlist>
10450 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
10451 You can also supply the IP address or hostname.</para></listitem>
10452 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
10453 </para></listitem>
10454 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
10455 </para></listitem>
10456 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
10457 downloads the data to the local host.
10458 Stopping the profiler generates the profile and displays it in the viewer.
10459 </para></listitem>
10460 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
10461 target and generates the profile, which appears in the viewer.</para></listitem>
10462 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
10463 Resetting the data removes sample information collected from previous
10464 sampling runs.
10465 Be sure you reset the data if you do not want to include old sample information.
10466 </para></listitem>
10467 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
10468 target to another directory for later examination.</para></listitem>
10469 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
10470 </para></listitem>
10471 </itemizedlist>
10472 </para>
10473
10474 <para>
10475 The client downloads the complete profile archive from
10476 the target to the host for processing.
10477 This archive is a directory that contains the sample data, the object files,
10478 and the debug information for the object files.
10479 The archive is then converted using the <filename>oparchconv</filename> script, which is
10480 included in this distribution.
10481 The script uses <filename>opimport</filename> to convert the archive from
10482 the target to something that can be processed on the host.
10483 </para>
10484
10485 <para>
10486 Downloaded archives reside in the
10487 <link linkend='build-directory'>Build Directory</link> in
10488 <filename>tmp</filename> and are cleared up when they are no longer in use.
10489 </para>
10490
10491 <para>
10492 If you wish to perform kernel profiling, you need to be sure
10493 a <filename>vmlinux</filename> file that matches the running kernel is available.
10494 In the source directory, that file is usually located in
10495 <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where
10496 <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel.
10497 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
10498 packages for each kernel it builds.
10499 Thus, it should just be a question of making sure a matching package is
10500 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
10501 The files are automatically installed into development and profiling images
10502 alongside OProfile.
10503 A configuration option exists within the OProfileUI settings page that you can use to
10504 enter the location of the <filename>vmlinux</filename> file.
10505 </para>
10506
10507 <para>
10508 Waiting for debug symbols to transfer from the device can be slow, and it
10509 is not always necessary to actually have them on the device for OProfile use.
10510 All that is needed is a copy of the filesystem with the debug symbols present
10511 on the viewer system.
10512 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
10513 section covers how to create such a directory within
10514 the source directory and how to use the OProfileUI Settings
10515 Dialog to specify the location.
10516 If you specify the directory, it will be used when the file checksums
10517 match those on the system you are profiling.
10518 </para>
10519 </section>
10520
10521 <section id="platdev-oprofile-oprofileui-offline">
10522 <title>Offline Mode</title>
10523
10524 <para>
10525 If network access to the target is unavailable, you can generate
10526 an archive for processing in <filename>oprofile-viewer</filename> as follows:
10527 <literallayout class='monospaced'>
10528 # opcontrol &dash;&dash;reset
10529 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
10530 .
10531 .
10532 [do whatever is being profiled]
10533 .
10534 .
10535 # opcontrol &dash;&dash;stop
10536 # oparchive -o my_archive
10537 </literallayout>
10538 </para>
10539
10540 <para>
10541 In the above example, <filename>my_archive</filename> is the name of the
10542 archive directory where you would like the profile archive to be kept.
10543 After the directory is created, you can copy it to another host and load it
10544 using <filename>oprofile-viewer</filename> open functionality.
10545 If necessary, the archive is converted.
10546 </para>
10547 </section>
10548 </section>
10549 </section>
10550-->
10551
10552 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> 10475 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
10553 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> 10476 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
10554 10477