summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-11-15 14:14:14 -0800
committerSaul Wold <Saul.Wold@intel.com>2010-12-10 22:01:06 -0800
commita20a167cf7e0b53c4a878c7c0161433bfcae8566 (patch)
tree96b2500a77a313c9fa4b71fb8ab5c29aeaf204bc /documentation/poky-ref-manual
parent8feae1342393dcf1dad5d86df2ebe3727ea40d88 (diff)
downloadpoky-a20a167cf7e0b53c4a878c7c0161433bfcae8566.tar.gz
Poky Reference Manual: General edits to the developing chapter.
Completed the second half edits to this chapter. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation/poky-ref-manual')
-rw-r--r--documentation/poky-ref-manual/development.xml554
1 files changed, 309 insertions, 245 deletions
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index 0eda1e9a88..7a39c96c7a 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -67,7 +67,7 @@
67 <literallayout class='monospaced'> 67 <literallayout class='monospaced'>
68 Help -> Install New Software 68 Help -> Install New Software
69 </literallayout> 69 </literallayout>
70 Specify the target URL as <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink>. 70 Specify the target URL as <ulink url='http://www.yoctoproject.org/downloads/eclipse-plug-in/'></ulink>.
71 </para> 71 </para>
72 <para> 72 <para>
73 If you want to download the source code for the plug-in you can find it in the Poky 73 If you want to download the source code for the plug-in you can find it in the Poky
@@ -97,7 +97,7 @@
97 </note> 97 </note>
98 <para> 98 <para>
99 To fix this issue you can use the <filename>-vmargs</filename> 99 To fix this issue you can use the <filename>-vmargs</filename>
100 option when you start Eclipse to increase the size of the permenant generation space: 100 option when you start Eclipse to increase the size of the permanent generation space:
101 <literallayout class='monospaced'> 101 <literallayout class='monospaced'>
102 Eclipse -vmargs -XX:PermSize=256M 102 Eclipse -vmargs -XX:PermSize=256M
103 </literallayout> 103 </literallayout>
@@ -142,7 +142,7 @@
142 Next, you need to select the architecture. 142 Next, you need to select the architecture.
143 Use the drop down list and select the architecture that you’ll be primarily 143 Use the drop down list and select the architecture that you’ll be primarily
144 working against. 144 working against.
145 For target option, select your typical target QEMU vs External HW. If you 145 For target option, select your typical target QEMU vs External hardware. If you
146 choose QEMU, you’ll need to specify your QEMU kernel file with full path and the 146 choose QEMU, you’ll need to specify your QEMU kernel file with full path and the
147 rootfs mount point. Yocto QEMU boots off user mode NFS. 147 rootfs mount point. Yocto QEMU boots off user mode NFS.
148 See the <link linkend='platdev-appdev-qemu'>Developing Externally in QEMU</link> section for 148 See the <link linkend='platdev-appdev-qemu'>Developing Externally in QEMU</link> section for
@@ -239,11 +239,11 @@
239 <para> 239 <para>
240 Here are some specifics about the remote tools: 240 Here are some specifics about the remote tools:
241 <itemizedlist> 241 <itemizedlist>
242 <listitem>Oprofile: Selecting this tool causes the oprofile-server on the remote 242 <listitem>OProfile: Selecting this tool causes the oprofile-server on the remote
243 target to launch on the local host machine. The oprofile-viewer 243 target to launch on the local host machine. The oprofile-viewer
244 must be installed on the local host machine and the oprofile-server must be 244 must be installed on the local host machine and the oprofile-server must be
245 installed on the remote target, respectively, in order to use .</listitem> 245 installed on the remote target, respectively, in order to use .</listitem>
246 <listitem>lttng: Selecting this tool runs "ustrace" on the remote target, transfers 246 <listitem>lttng: Selecting this tool runs "usttrace" on the remote target, transfers
247 the output data back to the local host machine and uses "lttv-gui" to graphically 247 the output data back to the local host machine and uses "lttv-gui" to graphically
248 display the output. The "lttv-gui" must be installed on the 248 display the output. The "lttv-gui" must be installed on the
249 local host machine to use this tool. 249 local host machine to use this tool.
@@ -291,13 +291,13 @@
291 </para> 291 </para>
292 </note> 292 </note>
293 <para> 293 <para>
294 An Anjuta IDE plugin exists to make developing software within the Poky framework 294 An Anjuta IDE plug-in exists to make developing software within the Poky framework
295 easier for the application developer familiar with that environment. 295 easier for the application developer familiar with that environment.
296 The plug-in presents a graphical IDE that allows you to cross-compile, cross-debug, 296 The plug-in presents a graphical IDE that allows you to cross-compile, cross-debug,
297 profile, deploy, and execute an application. 297 profile, deploy, and execute an application.
298 </para> 298 </para>
299 <para> 299 <para>
300 To use the plugin, a toolchain and SDK built by Poky, Anjuta, it's development headers and the Anjuta 300 To use the plug-in, a toolchain and SDK built by Poky, Anjuta, it's development headers and the Anjuta
301 Plug-in are all required. 301 Plug-in are all required.
302 The Poky Anjuta Plug-in is available to download as a tarball at the OpenedHand 302 The Poky Anjuta Plug-in is available to download as a tarball at the OpenedHand
303 labs <ulink url="http://labs.o-hand.com/anjuta-poky-sdk-plugin/"></ulink> page or 303 labs <ulink url="http://labs.o-hand.com/anjuta-poky-sdk-plugin/"></ulink> page or
@@ -309,7 +309,7 @@
309 <para> 309 <para>
310 See the README file contained in the project for more information on 310 See the README file contained in the project for more information on
311 Anjuta dependencies and building the plug-in. 311 Anjuta dependencies and building the plug-in.
312 If you want to disable remote gdb debugging, pass the "--diable-gdb-integration" switch when 312 If you want to disable remote gdb debugging, pass the "--disable-gdb-integration" switch when
313 you configure the plug-in. 313 you configure the plug-in.
314 </para> 314 </para>
315 <section id="setting-up-the-anjuta-plugin"> 315 <section id="setting-up-the-anjuta-plugin">
@@ -332,7 +332,7 @@
332 </para> 332 </para>
333 </section> 333 </section>
334 <section id="configuring-the-anjuta-plugin"> 334 <section id="configuring-the-anjuta-plugin">
335 <title>Configuring the Anjuta Plugin</title> 335 <title>Configuring the Anjuta Plug-in</title>
336 <para> 336 <para>
337 You can find the configuration options for the SDK by choosing the Poky 337 You can find the configuration options for the SDK by choosing the Poky
338 SDK icon from the left hand side. 338 SDK icon from the left hand side.
@@ -438,7 +438,7 @@
438 toolchain available from the build system is automatically 438 toolchain available from the build system is automatically
439 used from within QEMU simply by calling "distcc". You can accomplish this by defining the 439 used from within QEMU simply by calling "distcc". You can accomplish this by defining the
440 cross-compiler variable (e.g. <filename>export CC="distcc"</filename>). 440 cross-compiler variable (e.g. <filename>export CC="distcc"</filename>).
441 Alterntatively, if a suitable SDK/toolchain is present in 441 Alternatively, if a suitable SDK/toolchain is present in
442 <filename>/opt/poky</filename> it is also 442 <filename>/opt/poky</filename> it is also
443 automatically be used. 443 automatically be used.
444 </para> 444 </para>
@@ -585,173 +585,204 @@
585 <title>Debugging with GDB Remotely</title> 585 <title>Debugging with GDB Remotely</title>
586 586
587 <para> 587 <para>
588 <ulink url="http://sourceware.org/gdb/">GDB</ulink> (The GNU Project Debugger) 588 GNU Project Debugger (GDB)
589 allows you to examine running programs to understand and fix problems and 589 allows you to examine running programs to understand and fix problems and
590 also to perform postmortem style analsys of program crashes. It is available 590 also to perform post-mortem style analysis of program crashes.
591 as a package within poky and installed by default in sdk images. It works best 591 GDB is available as a package within Poky and by default is installed in sdk images.
592 when -dbg packages for the application being debugged are installed as the 592 See <ulink url="http://sourceware.org/gdb/"/> for the GDB source.
593 extra symbols give more meaningful output from GDB.
594 </para> 593 </para>
594 <tip><para>
595 For best results install <filename>-dbg</filename> packages for the applications
596 you are going to debug.
597 Doing so makes available extra debug symbols that will give you more meaningful output.
598 </para></tip>
595 599
596 <para> 600 <para>
597 Sometimes, due to memory or disk space constraints, it is not possible 601 Sometimes, due to memory or disk space constraints, it is not possible
598 to use GDB directly on the remote target to debug applications. This is 602 to use GDB directly on the remote target to debug applications.
599 due to the fact that 603 These constraints arise because GDB needs to load the debugging information and the
600 GDB needs to load the debugging information and the binaries of the 604 binaries of the process being debugged.
601 process being debugged. GDB then needs to perform many 605 Additionally, GDB needs to perform many computations to locate information such as function
602 computations to locate information such as function names, variable 606 names, variable names and values, stack traces and so forth - even before starting the
603 names and values, stack traces, etc. even before starting the debugging 607 debugging process.
604 process. This places load on the target system and can alter the 608 These extra computations place more load on the target system and can alter the
605 characteristics of the program being debugged. 609 characteristics of the program being debugged.
606 </para> 610 </para>
607 <para> 611 <para>
608 This is where GDBSERVER comes into play as it runs on the remote target 612 To help get past these constraints you can use GDBSERVER.
609 and does not load any debugging information from the debugged process. 613 It runs on the remote target and does not load any debugging information
610 Instead, the debugging information processing is done by a GDB instance 614 from the debugged process.
611 running on a distant computer - the host GDB. The host GDB then sends 615 Instead, a GDB instance processes the debugging information that is run on a
612 control commands to GDBSERVER to make it stop or start the debugged 616 remote computer - the host GDB.
613 program, as well as read or write some memory regions of that debugged 617 The host GDB then sends control commands to GDBSERVER to make it stop or start the debugged
614 program. All the debugging information loading and processing as well 618 program, as well as read or write memory regions of that debugged
615 as the heavy debugging duty is done by the host GDB, giving the 619 program.
616 GDBSERVER running on the target a chance to remain small and fast. 620 All the debugging information loaded and processed as well
621 as all the heavy debugging is done by the host GDB.
622 Offloading these processes gives the GDBSERVER running on the target a chance to remain
623 small and fast.
617 </para> 624 </para>
618 <para> 625 <para>
619 As the host GDB is responsible for loading the debugging information and 626 Because the host GDB is responsible for loading the debugging information and
620 doing the necessary processing to make actual debugging happen, the 627 for doing the necessary processing to make actual debugging happen, the
621 user has to make sure it can access the unstripped binaries complete 628 user has to make sure the host can access the unstripped binaries complete
622 with their debugging information and compiled with no optimisations. The 629 with their debugging information and also compiled with no optimizations.
623 host GDB must also have local access to all the libraries used by the 630 The host GDB must also have local access to all the libraries used by the
624 debugged program. On the remote target the binaries can remain stripped 631 debugged program.
625 as GDBSERVER does not need any debugging information there. However they 632 Because GDBSERVER does not need any local debugging information the binaries on
626 must also be compiled without optimisation matching the host's binaries. 633 the remote target can remain stripped.
634 However, the binaries must also be compiled without optimization
635 so they match the host's binaries.
627 </para> 636 </para>
628 637
629 <para> 638 <para>
630 The binary being debugged on the remote target machine is hence referred 639 To remain consistent with GDB documentation and terminology the binary being debugged
631 to as the 'inferior' in keeping with GDB documentation and terminology. 640 on the remote target machine is referred to as the 'inferior' binary.
632 Further documentation on GDB, is available on 641 For documentation on GDB see the GDB site at
633 <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>. 642 <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>.
634 </para> 643 </para>
635 644
636 <section id="platdev-gdb-remotedebug-launch-gdbserver"> 645 <section id="platdev-gdb-remotedebug-launch-gdbserver">
637 <title>Launching GDBSERVER on the target</title> 646 <title>Launching GDBSERVER on the Target</title>
638 <para> 647 <para>
639 First, make sure gdbserver is installed on the target. If not, 648 First, make sure GDBSERVER is installed on the target. If not,
640 install the gdbserver package (which needs the libthread-db1 649 install the package <filename>gdbserver</filename>, which needs the
641 package). 650 <filename>libthread-db1</filename> package.
642 </para> 651 </para>
643 <para> 652 <para>
644 To launch GDBSERVER on the target and make it ready to "debug" a 653 As an example, to launch GDBSERVER on the target and make it ready to "debug" a
645 program located at <emphasis>/path/to/inferior</emphasis>, connect 654 program located at <filename>/path/to/inferior</filename>, connect
646 to the target and launch: 655 to the target and launch:
647 <programlisting>$ gdbserver localhost:2345 /path/to/inferior</programlisting> 656 <literallayout class='monospaced'>
648 After that, gdbserver should be listening on port 2345 for debugging 657 $ gdbserver localhost:2345 /path/to/inferior
649 commands coming from a remote GDB process running on the host computer. 658 </literallayout>
650 Communication between the GDBSERVER and the host GDB will be done using 659 GDBSERVER should now be listening on port 2345 for debugging
651 TCP. To use other communication protocols please refer to the 660 commands coming from a remote GDB process that is running on the host computer.
652 GDBSERVER documentation. 661 Communication between GDBSERVER and the host GDB are done using TCP.
662 To use other communication protocols please refer to the GDBSERVER documentation.
653 </para> 663 </para>
654 </section> 664 </section>
655 665
656 <section id="platdev-gdb-remotedebug-launch-gdb"> 666 <section id="platdev-gdb-remotedebug-launch-gdb">
657 <title>Launching GDB on the host computer</title> 667 <title>Launching GDB on the Host Computer</title>
658 668
659 <para> 669 <para>
660 Running GDB on the host computer takes a number of stages, described in the 670 Running GDB on the host computer takes a number of stages.
661 following sections. 671 This section describes those stages.
662 </para> 672 </para>
663 673
664 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> 674 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
665 <title>Build the cross GDB package</title> 675 <title>Building the Cross-GDB Package</title>
666 <para> 676 <para>
667 A suitable gdb cross binary is required which runs on your host computer but 677 A suitable GDB cross-binary is required that runs on your host computer but
668 knows about the the ABI of the remote target. This can be obtained from 678 also knows about the the ABI of the remote target.
669 the the Poky toolchain, e.g. 679 You can get this binary from the the Poky toolchain - for example:
670 <filename>/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb</filename> 680 <programlisting>
671 which "arm" is the target architecture and "linux-gnueabi" the target ABI. 681/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
682 </programlisting>
683 where "arm" is the target architecture and "linux-gnueabi" the target ABI.
672 </para> 684 </para>
673 685
674 <para> 686 <para>
675 Alternatively this can be built directly by Poky. To do this you would build 687 Alternatively, Poky can build the <filename>gdb-cross</filename> binary.
676 the gdb-cross package so for example you would run: 688 For example, the following command builds it:
677 <programlisting>bitbake gdb-cross</programlisting> 689 <literallayout class='monospaced'>
678 Once built, the cross gdb binary can be found at 690 $ bitbake gdb-cross
679 <programlisting>tmp/sysroots/&lt;host-arch&lt;/usr/bin/&lt;target-abi&gt;-gdb </programlisting> 691 </literallayout>
692 Once the binary is built you can find it here:
693 <programlisting>
694tmp/sysroots/&lt;host-arch&lt;/usr/bin/&lt;target-abi&gt;-gdb
695 </programlisting>
680 </para> 696 </para>
681 697
682 </section> 698 </section>
683 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"> 699 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
684 700
685 <title>Making the inferior binaries available</title> 701 <title>Making the Inferior Binaries Available</title>
686 702
687 <para> 703 <para>
688 The inferior binary needs to be available to GDB complete with all debugging 704 The inferior binary (complete with all debugging symbols) as well as any
689 symbols in order to get the best possible results along with any libraries 705 libraries (and their debugging symbols) on which the inferior binary depends
690 the inferior depends on and their debugging symbols. There are a number of 706 need to be available.
691 ways this can be done. 707 There are a number of ways you can make these available.
692 </para> 708 </para>
693 709
694 <para> 710 <para>
695 Perhaps the easiest is to have an 'sdk' image corresponding to the plain 711 Perhaps the easiest is to have an 'sdk' image that corresponds to the plain
696 image installed on the device. In the case of 'pky-image-sato', 712 image installed on the device.
697 'poky-image-sdk' would contain suitable symbols. The sdk images already 713 In the case of 'poky-image-sato', 'poky-image-sdk' would contain suitable symbols.
698 have the debugging symbols installed so its just a question expanding the 714 Because the sdk images already have the debugging symbols installed it is just a
699 archive to some location and telling GDB where this is. 715 question of expanding the archive to some location and then informing GDB.
700 </para> 716 </para>
701 717
702 <para> 718 <para>
703 Alternatively, poky can build a custom directory of files for a specific 719 Alternatively, Poky can build a custom directory of files for a specific
704 debugging purpose by reusing its tmp/rootfs directory, on the host computer 720 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
705 in a slightly different way to normal. This directory contains the contents 721 This directory contains the contents of the last built image.
706 of the last built image. This process assumes the image running on the 722 This process assumes two things:
707 target was the last image to be built by Poky, the package <emphasis>foo</emphasis> 723 <itemizedlist>
708 contains the inferior binary to be debugged has been built without without 724 <listitem><para>The image running on the target was the last image to
709 optimisation and has debugging information available. 725 be built by Poky.</para></listitem>
726 <listitem><para>The package (<filename>foo</filename> in the following
727 example) that contains the inferior binary to be debugged has been built
728 without optimization and has debugging information available.</para></listitem>
729 </itemizedlist>
710 </para> 730 </para>
711 <para> 731 <para>
712 Firstly you want to install the <emphasis>foo</emphasis> package to tmp/rootfs 732 These steps show how to build the custom directory of files:
713 by doing: 733 </para>
714 </para> 734 <orderedlist>
715 <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ 735 <listitem>Install the package (<filename>foo</filename> in this case) to
736 <filename>tmp/rootfs</filename>:
737 <programlisting>
738tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
716tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf -o \ 739tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf -o \
717tmp/rootfs/ update</programlisting> 740tmp/rootfs/ update
718 <para> 741 </programlisting></listitem>
719 then, 742 <listitem>Install the debugging information:
720 </para> 743 <programlisting>
721 <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ 744tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
722tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \ 745tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \
723-o tmp/rootfs install foo 746-o tmp/rootfs install foo
724 747
725tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ 748tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
726tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \ 749tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \
727-o tmp/rootfs install foo-dbg</programlisting> 750-o tmp/rootfs install foo-dbg
728 <para> 751 </programlisting></listitem>
729 which installs the debugging information too. 752 </orderedlist>
730 </para>
731 753
732 </section> 754 </section>
733 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost"> 755 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
734 756
735 <title>Launch the host GDB</title> 757 <title>Launch the Host GDB</title>
736 <para> 758 <para>
737 To launch the host GDB, run the cross gdb binary identified above with 759 To launch the host GDB, you run the cross-gdb binary and provide the inferior
738 the inferior binary specified on the commandline: 760 binary as part of the command line.
739 <programlisting>&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</programlisting> 761 For example, the following command form continues with the example used in
740 This loads the binary of program <emphasis>foo</emphasis> 762 the previous section.
741 as well as its debugging information. Once the gdb prompt 763 This command form loads the <filename>foo</filename> binary
742 appears, you must instruct GDB to load all the libraries 764 as well as the debugging information:
743 of the inferior from tmp/rootfs: 765 <literallayout class='monospaced'>
744 <programlisting>set solib-absolute-prefix /path/to/tmp/rootfs</programlisting> 766 $ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
745 where <filename>/path/to/tmp/rootfs</filename> must be 767 </literallayout>
746 the absolute path to <filename>tmp/rootfs</filename> or wherever the 768 Once the GDB prompt appears, you must instruct GDB to load all the libraries
747 binaries with debugging information are located. 769 of the inferior binary from <filename>tmp/rootfs</filename> as follows:
770 <literallayout class='monospaced'>
771 $ set solib-absolute-prefix /path/to/tmp/rootfs
772 </literallayout>
773 The pathname <filename>/path/to/tmp/rootfs</filename> must either be
774 the absolute path to <filename>tmp/rootfs</filename> or the location at which
775 binaries with debugging information reside.
748 </para> 776 </para>
749 <para> 777 <para>
750 Now, tell GDB to connect to the GDBSERVER running on the remote target: 778 At this point you can have GDB connect to the GDBSERVER that is running
751 <programlisting>target remote remote-target-ip-address:2345</programlisting> 779 on the remote target by using the following command form:
752 Where remote-target-ip-address is the IP address of the 780 <literallayout class='monospaced'>
753 remote target where the GDBSERVER is running. 2345 is the 781 $ target remote remote-target-ip-address:2345
754 port on which the GDBSERVER is running. 782 </literallayout>
783 The <filename>remote-target-ip-address</filename> is the IP address of the
784 remote target where the GDBSERVER is running.
785 Port 2345 is the port on which the GDBSERVER is running.
755 </para> 786 </para>
756 787
757 </section> 788 </section>
@@ -759,17 +790,19 @@ tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \
759 790
760 <title>Using the Debugger</title> 791 <title>Using the Debugger</title>
761 <para> 792 <para>
762 Debugging can now proceed as normal, as if the debugging were being done on the 793 You can now proceed with debugging as normal - as if you were debugging
763 local machine, for example to tell GDB to break in the <emphasis>main</emphasis> 794 on the local machine.
764 function, for instance: 795 For example, to instruct GDB to break in the "main" function and then
765 <programlisting>break main</programlisting> 796 continue with execution of the inferior binary use the following commands
766 and then to tell GDB to "continue" the inferior execution, 797 from within GDB:
767 <programlisting>continue</programlisting> 798 <literallayout class='monospaced'>
799 (gdb) break main
800 (gdb) continue
801 </literallayout>
768 </para> 802 </para>
769 <para> 803 <para>
770 For more information about using GDB please see the 804 For more information about using GDB, see the project's online documentation at
771 project's online documentation at <ulink 805 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
772 url="http://sourceware.org/gdb/download/onlinedocs/"/>.
773 </para> 806 </para>
774 </section> 807 </section>
775 </section> 808 </section>
@@ -781,38 +814,45 @@ tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \
781 814
782 <para> 815 <para>
783 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a 816 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
784 statistical profiler well suited to finding performance 817 statistical profiler well suited for finding performance
785 bottlenecks in both userspace software and the kernel. It provides 818 bottlenecks in both userspace software and in the kernel.
786 answers to questions like "Which functions does my application spend 819 This profiler provides answers to questions like "Which functions does my application spend
787 the most time in when doing X?". Poky is well integrated with OProfile 820 the most time in when doing X?"
788 to make profiling applications on target hardware straightforward. 821 Because Poky is well integrated with OProfile it makes profiling applications on target
822 hardware straightforward.
789 </para> 823 </para>
790 824
791 <para> 825 <para>
792 To use OProfile you need an image with OProfile installed. The easiest 826 To use OProfile you need an image that has OProfile installed.
793 way to do this is with "tools-profile" in <glossterm><link 827 The easiest way to do this is with "tools-profile" in
794 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. You also 828 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>.
795 need debugging symbols to be available on the system where the analysis 829 You also need debugging symbols to be available on the system where the analysis
796 will take place. This can be achieved with "dbg-pkgs" in <glossterm><link 830 takes place.
797 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by 831 You can gain access to the symbols by using "dbg-pkgs" in
798 installing the appropriate -dbg packages. For 832 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by
799 successful call graph analysis the binaries must preserve the frame 833 installing the appropriate <filename>-dbg</filename> packages.
800 pointer register and hence should be compiled with the 834 </para>
801 "-fno-omit-framepointer" flag. In Poky this can be achieved with 835 <para>
836 For successful call graph analysis the binaries must preserve the frame
837 pointer register and should also be compiled with the
838 "-fno-omit-framepointer" flag.
839 In Poky you can achieve this by setting
802 <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION 840 <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
803 </link></glossterm> = "-fexpensive-optimizations -fno-omit-framepointer 841 </link></glossterm> to "-fexpensive-optimizations -fno-omit-framepointer
804 -frename-registers -O2" or by setting <glossterm><link 842 -frename-registers -O2".
805 linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> = "1" in 843 You can also achieve it by setting
806 local.conf (the latter will also add extra debug information making the 844 <glossterm><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> to "1" in
807 debug packages large). 845 <filename>local.conf</filename>.
846 If you use the DEBUG_BUILD variable you will also add extra debug information
847 that can make the debug packages large.
808 </para> 848 </para>
809 849
810 <section id="platdev-oprofile-target"> 850 <section id="platdev-oprofile-target">
811 <title>Profiling on the target</title> 851 <title>Profiling on the Target</title>
812 852
813 <para> 853 <para>
814 All the profiling work can be performed on the target device. A 854 Using OProfile you can perform all the profiling work on the target device.
815 simple OProfile session might look like: 855 A simple OProfile session might look like the following:
816 </para> 856 </para>
817 857
818 <para> 858 <para>
@@ -822,34 +862,45 @@ tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/opkg.conf \
822[do whatever is being profiled] 862[do whatever is being profiled]
823# opcontrol --stop 863# opcontrol --stop
824$ opreport -cl 864$ opreport -cl
825</literallayout> 865 </literallayout>
826 </para> 866 </para>
827 867
828 <para> 868 <para>
829 Here, the reset command clears any previously profiled data, 869 In this example, the reset command clears any previously profiled data.
830 OProfile is then started. The options used to start OProfile mean 870 The next command starts OProfile.
831 dynamic library data is kept separately per application, kernel 871 The options used when starting the profiler separate dynamic library data
832 profiling is disabled and callgraphing is enabled up to 5 levels 872 within applications, disable kernel profiling, and enable callgraphing up to
833 deep. To profile the kernel, you would specify the 873 five levels deep.
834 <parameter>--vmlinux=/path/to/vmlinux</parameter> option (the vmlinux file is usually in 874 </para>
835 <filename class="directory">/boot/</filename> in Poky and must match the running kernel). The profile is 875 <note><para>
836 then stopped and the results viewed with opreport with options 876 To profile the kernel, you would specify the
877 <parameter>--vmlinux=/path/to/vmlinux</parameter> option.
878 The vmlinux file is usually in <filename class="directory">/boot/</filename>
879 in Poky and must match the running kernel.
880 </para></note>
881 <para>
882 After you perform your profiling tasks, the next command stops the profiler.
883 After that you can view results with the "opreport" command with options
837 to see the separate library symbols and callgraph information. 884 to see the separate library symbols and callgraph information.
838 </para> 885 </para>
839 <para> 886 <para>
840 Callgraphing means OProfile not only logs infomation about which 887 Callgraphing logs information about time spent in functions and about a function's
841 functions time is being spent in but also which functions 888 calling function (parent) and called functions (children).
842 called those functions (their parents) and which functions that 889 The higher the callgraphing depth,
843 function calls (its children). The higher the callgraphing depth, 890 the more accurate the results.
844 the more accurate the results but this also increased the loging 891 However, higher depths also increase the logging
845 overhead so it should be used with caution. On ARM, binaries need 892 overhead.
846 to have the frame pointer enabled for callgraphing to work (compile 893 Consequently, you should take care when setting the callgraphing depth.
847 with the gcc option -fno-omit-framepointer).
848 </para> 894 </para>
895 <note><para>
896 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
897 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
898 with <filename>gcc</filename>.
899 </para></note>
849 <para> 900 <para>
850 For more information on using OProfile please see the OProfile 901 For more information on using OProfile, see the OProfile
851 online documentation at <ulink 902 online documentation at
852 url="http://oprofile.sourceforge.net/docs/"/>. 903 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
853 </para> 904 </para>
854 </section> 905 </section>
855 906
@@ -857,15 +908,14 @@ $ opreport -cl
857 <title>Using OProfileUI</title> 908 <title>Using OProfileUI</title>
858 909
859 <para> 910 <para>
860 A graphical user interface for OProfile is also available. You can 911 A graphical user interface for OProfile is also available.
861 download and build it from svn at 912 You can download and build it from svn at
862 <ulink url="http://svn.o-hand.com/repos/oprofileui/trunk/"></ulink>. 913 <ulink url="http://svn.o-hand.com/repos/oprofileui/trunk/"></ulink>.
863 If the 914 If the "tools-profile" image feature is selected, all necessary binaries
864 "tools-profile" image feature is selected, all necessary binaries
865 are installed onto the target device for OProfileUI interaction. 915 are installed onto the target device for OProfileUI interaction.
866 </para> 916 </para>
867 917
868<!-- DISBALED, Need a more 'contexual' shot? 918<!-- DISABLED, Need a more 'contextual' shot?
869 <screenshot> 919 <screenshot>
870 <mediaobject> 920 <mediaobject>
871 <imageobject> 921 <imageobject>
@@ -879,148 +929,162 @@ $ opreport -cl
879--> 929-->
880 <para> 930 <para>
881 In order to convert the data in the sample format from the target 931 In order to convert the data in the sample format from the target
882 to the host the <filename>opimport</filename> program is needed. 932 to the host you need the <filename>opimport</filename> program.
883 This is not included in standard Debian OProfile packages but an 933 This program is not included in standard Debian OProfile packages.
884 OProfile package with this addition is also available from the <ulink 934 However, an OProfile package with this addition is available from the
885 url='http://debian.o-hand.com/'>OpenedHand repository</ulink>. 935 <ulink url='http://debian.o-hand.com/'>OpenedHand repository</ulink>.
886 We recommend using OProfile 0.9.3 or greater. Other patches to 936 We recommend using OProfile 0.9.3 or greater.
887 OProfile may be needed for recent OProfileUI features, but Poky 937 </para>
888 usually includes all needed patches on the target device. Please 938 <para>
889 see the <ulink 939 Even though Poky usually includes all needed patches on the target device, you
890 url='http://svn.o-hand.com/repos/oprofileui/trunk/README'> 940 might find you need other OProfile patches for recent OProfileUI features.
891 OProfileUI README</ulink> for up to date information, and the 941 If so, see the <ulink url='http://svn.o-hand.com/repos/oprofileui/trunk/README'>
892 <ulink url="http://labs.o-hand.com/oprofileui">OProfileUI website 942 OProfileUI README</ulink> for the most recent information.
893 </ulink> for more information on the OProfileUI project. 943 You can also see <ulink url="http://labs.o-hand.com/oprofileui">OProfileUI website
944 </ulink> for general information on the OProfileUI project.
894 </para> 945 </para>
895 946
896 <section id="platdev-oprofile-oprofileui-online"> 947 <section id="platdev-oprofile-oprofileui-online">
897 <title>Online mode</title> 948 <title>Online Mode</title>
898 949
899 <para> 950 <para>
900 This assumes a working network connection with the target 951 Using OProfile in online mode assumes a working network connection with the target
901 hardware. In this case you just need to run <command> 952 hardware.
902 "oprofile-server"</command> on the device. By default it listens 953 With this connection, you just need to run "oprofile-server" on the device.
903 on port 4224. This can be changed with the <parameter>--port</parameter> command line 954 By default OProfile listens on port 4224.
904 option.
905
906 </para> 955 </para>
956 <note><para>
957 You can change the port using the <filename>--port</filename> command-line
958 option.
959 </para></note>
907 960
908 <para> 961 <para>
909 The client program is called <command>oprofile-viewer</command>. The 962 The client program is called "oprofile-viewer" and its UI is relatively
910 UI is relatively straightforward, the key functionality is accessed 963 straightforward.
911 through the buttons on the toolbar (which are duplicated in the 964 You access key functionality through the buttons on the toolbar, which
912 menus.) These buttons are: 965 are duplicated in the menus.
966 The buttons are:
913 </para> 967 </para>
914 968
915 <itemizedlist> 969 <itemizedlist>
916 <listitem> 970 <listitem>
917 <para> 971 <para>
918 Connect - connect to the remote host, the IP address or hostname for the 972 Connect - Connects to the remote host.
919 target can be supplied here. 973 You can also supply the IP address or hostname.
920 </para> 974 </para>
921 </listitem> 975 </listitem>
922 <listitem> 976 <listitem>
923 <para> 977 <para>
924 Disconnect - disconnect from the target. 978 Disconnect - Disconnects from the target.
925 </para> 979 </para>
926 </listitem> 980 </listitem>
927 <listitem> 981 <listitem>
928 <para> 982 <para>
929 Start - start the profiling on the device. 983 Start - Starts profiling on the device.
930 </para> 984 </para>
931 </listitem> 985 </listitem>
932 <listitem> 986 <listitem>
933 <para> 987 <para>
934 Stop - stop the profiling on the device and download the data to the local 988 Stop - Stops profiling on the device and downloads the data to the local
935 host. This will generate the profile and show it in the viewer. 989 host.
990 Stopping the profiler generates the profile and displays it in the viewer.
936 </para> 991 </para>
937 </listitem> 992 </listitem>
938 <listitem> 993 <listitem>
939 <para> 994 <para>
940 Download - download the data from the target, generate the profile and show it 995 Download - Downloads the data from the target and generates the profile,
941 in the viewer. 996 which appears in the viewer.
942 </para> 997 </para>
943 </listitem> 998 </listitem>
944 <listitem> 999 <listitem>
945 <para> 1000 <para>
946 Reset - reset the sample data on the device. This will remove the sample 1001 Reset - Resets the sample data on the device.
947 information that was collected on a previous sampling run. Ensure you do this 1002 Resetting the data removes sample information collected from previous
948 if you do not want to include old sample information. 1003 sampling runs.
1004 Be sure you reset the data if you do not want to include old sample information.
949 </para> 1005 </para>
950 </listitem> 1006 </listitem>
951 <listitem> 1007 <listitem>
952 <para> 1008 <para>
953 Save - save the data downloaded from the target to another directory for later 1009 Save - Saves the data downloaded from the target to another directory for later
954 examination. 1010 examination.
955 </para> 1011 </para>
956 </listitem> 1012 </listitem>
957 <listitem> 1013 <listitem>
958 <para> 1014 <para>
959 Open - load data that was previously saved. 1015 Open - Loads previously saved data.
960 </para> 1016 </para>
961 </listitem> 1017 </listitem>
962 </itemizedlist> 1018 </itemizedlist>
963 1019
964 <para> 1020 <para>
965 The behaviour of the client is to download the complete 'profile archive' from 1021 The client downloads the complete 'profile archive' from
966 the target to the host for processing. This archive is a directory containing 1022 the target to the host for processing.
967 the sample data, the object files and the debug information for said object 1023 This archive is a directory that contains the sample data, the object files
968 files. This archive is then converted using a script included in this 1024 and the debug information for the object files.
969 distribution ('oparchconv') that uses 'opimport' to convert the archive from 1025 The archive is then converted using the "oparchconv" script, which is
1026 included in this distribution.
1027 The script uses "opimport" to convert the archive from
970 the target to something that can be processed on the host. 1028 the target to something that can be processed on the host.
971 </para> 1029 </para>
972 1030
973 <para> 1031 <para>
974 Downloaded archives are kept in /tmp and cleared up when they are no longer in 1032 Downloaded archives reside in <filename>/tmp</filename> and are cleared up
975 use. 1033 when they are no longer in use.
976 </para> 1034 </para>
977 1035
978 <para> 1036 <para>
979 If you wish to profile into the kernel, this is possible, you just need to ensure 1037 If you wish to perform kernel profiling you need to be sure
980 a vmlinux file matching the running kernel is available. In Poky this is usually 1038 a "vmlinux" file that matches the running kernel is available.
981 located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of 1039 In Poky, that file is usually located in
982 the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel 1040 <filename>/boot/vmlinux-KERNELVERSION</filename>, where KERNEL-version is the
983 it builds so it should be a question of just ensuring a matching package is 1041 version of the kernel (e.g. 2.6.23).
984 installed (<command> opkg install kernel-vmlinux</command>. These are automatically 1042 Poky generates separate vmlinux packages for each kernel
985 installed into development and profiling images alongside OProfile. There is a 1043 it builds so it should be a question of just making sure a matching package is
986 configuration option within the OProfileUI settings page where the location of 1044 installed - for example: <filename>opkg install kernel-vmlinux</filename>.
987 the vmlinux file can be entered. 1045 The files are automatically installed into development and profiling images
1046 alongside OProfile.
1047 There is a configuration option within the OProfileUI settings page where
1048 you can enter the location of the vmlinux file.
988 </para> 1049 </para>
989 1050
990 <para> 1051 <para>
991 Waiting for debug symbols to transfer from the device can be slow and it's not 1052 Waiting for debug symbols to transfer from the device can be slow, and it
992 always necessary to actually have them on device for OProfile use. All that is 1053 is not always necessary to actually have them on the device for OProfile use.
993 needed is a copy of the filesystem with the debug symbols present on the viewer 1054 All that is needed is a copy of the filesystem with the debug symbols present
994 system. The <link linkend='platdev-gdb-remotedebug-launch-gdb'>GDB remote debug 1055 on the viewer system.
995 section</link> covers how to create such a directory with Poky and the location 1056 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB
996 of this directory can again be specified in the OProfileUI settings dialog. If 1057 on the Host Computer</link>" section covers how to create such a directory with Poky and
997 specified, it will be used where the file checksums match those on the system 1058 how to use the OProfileUI Settings dialog to specify the location.
998 being profiled. 1059 If you specify the directory, it will be used when the file checksums
1060 match those on the system you are profiling.
999 </para> 1061 </para>
1000 </section> 1062 </section>
1063
1001 <section id="platdev-oprofile-oprofileui-offline"> 1064 <section id="platdev-oprofile-oprofileui-offline">
1002 <title>Offline mode</title> 1065 <title>Offline Mode</title>
1003 1066
1004 <para> 1067 <para>
1005 If no network access to the target is available an archive for processing in 1068 If network access to the target is unavailable, you can generate
1006 'oprofile-viewer' can be generated with the following set of command. 1069 an archive for processing in "oprofile-viewer" as follows:
1007 </para> 1070 </para>
1008 1071
1009 <para> 1072 <para>
1010 <literallayout class='monospaced'> 1073 <literallayout class='monospaced'>
1011# opcontrol --reset 1074 # opcontrol --reset
1012# opcontrol --start --separate=lib --no-vmlinux -c 5 1075 # opcontrol --start --separate=lib --no-vmlinux -c 5
1013[do whatever is being profiled] 1076 [do whatever is being profiled]
1014# opcontrol --stop 1077 # opcontrol --stop
1015# oparchive -o my_archive 1078 # oparchive -o my_archive
1016</literallayout> 1079 </literallayout>
1017 </para> 1080 </para>
1018 1081
1019 <para> 1082 <para>
1020 Where my_archive is the name of the archive directory where you would like the 1083 In the above example <filename>my_archive</filename> is the name of the
1021 profile archive to be kept. The directory will be created for you. This can 1084 archive directory where you would like the profile archive to be kept.
1022 then be copied to another host and loaded using 'oprofile-viewer''s open 1085 After the directory is created, you can copy it to another host and load it
1023 functionality. The archive will be converted if necessary. 1086 using "oprofile-viewer" open functionality.
1087 If necessary, the archive is converted.
1024 </para> 1088 </para>
1025 </section> 1089 </section>
1026 </section> 1090 </section>