aboutsummaryrefslogtreecommitdiffstats
path: root/handbook/development.xml
diff options
context:
space:
mode:
authorRichard Purdie <rpurdie@linux.intel.com>2010-10-15 11:55:59 +0100
committerRichard Purdie <rpurdie@linux.intel.com>2010-10-15 11:55:59 +0100
commit22083287912ebd552e33b79f7c567bc966376d43 (patch)
treea16fa012a97a249e25a405d4092b0a89321bfaf6 /handbook/development.xml
parent13a702e9e572a2dc9f6b52a1531a2237d4d98ff1 (diff)
downloadopenembedded-core-contrib-22083287912ebd552e33b79f7c567bc966376d43.tar.gz
openembedded-core-contrib-22083287912ebd552e33b79f7c567bc966376d43.tar.bz2
openembedded-core-contrib-22083287912ebd552e33b79f7c567bc966376d43.zip
handbook: Move into documentation directory
Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>
Diffstat (limited to 'handbook/development.xml')
-rw-r--r--handbook/development.xml825
1 files changed, 0 insertions, 825 deletions
diff --git a/handbook/development.xml b/handbook/development.xml
deleted file mode 100644
index a383a2f4a8..0000000000
--- a/handbook/development.xml
+++ /dev/null
@@ -1,825 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<chapter id="platdev">
-<title>Platform Development with Poky</title>
-
-<section id="platdev-appdev">
- <title>Software development</title>
- <para>
- Poky supports several methods of software development. These different
- forms of development are explained below and can be switched
- between as needed.
- </para>
-
- <section id="platdev-appdev-external-sdk">
- <title>Developing externally using the Poky SDK</title>
-
- <para>
- The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see
- the images section</link>) build tarballs which contain toolchains and
- libraries suitable for application development outside Poky. These unpack into the
- <filename class="directory">/opt/poky</filename> directory and contain
- a setup script, e.g.
- <filename>/opt/poky/environment-setup-i586-poky-linux</filename> which
- can be sourced to initialise a suitable environment. After sourcing this, the
- compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
- useful utilities are added to the PATH. Variables to assist pkgconfig and
- autotools are also set so that, for example, configure can find pre-generated test
- results for tests which need target hardware to run.
- </para>
-
- <para>
- Using the toolchain with autotool enabled packages is straightforward, just pass the
- appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
- For other projects it is usually a case of ensuring the cross tools are used e.g.
- CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
- </para>
- </section>
-
- <section id="platdev-appdev-external-anjuta">
- <title>Developing externally using the Anjuta plugin</title>
-
- <para>
- An Anjuta IDE plugin exists to make developing software within the Poky framework
- easier for the application developer. It presents a graphical IDE from which the
- developer can cross compile an application then deploy and execute the output in a QEMU
- emulation session. It also supports cross debugging and profiling.
- </para>
-<!-- DISBALED, TOO BIG!
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/>
- </imageobject>
- <caption>
- <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para>
- </caption>
- </mediaobject>
- </screenshot>
--->
- <para>
- To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta it's development
- headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the
- <ulink url='http://labs.o-hand.com/anjuta-poky-sdk-plugin/'>OpenedHand labs</ulink> page or
- directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface
- to the repository can be accessed at <ulink url='http://git.pokylinux.org/?p=anjuta-poky.git;a=summary'/>.
- </para>
- <para>
- See the README file contained in the project for more information on dependencies and building
- the plugin. If you want to disable remote gdb debugging, please pass --diable-gdb-integration
- switch when doing configure.
- </para>
-
- <section id="platdev-appdev-external-anjuta-setup">
- <title>Setting up the Anjuta plugin</title>
-
- <para>Extract the tarball for the toolchain into / as root. The
- toolchain will be installed into
- <filename class="directory">/opt/poky</filename>.</para>
-
- <para>To use the plugin, first open or create an existing
- project. If creating a new project the "C GTK+" project type
- will allow itself to be cross-compiled. However you should be
- aware that this uses glade for the UI.</para>
-
- <para>To activate the plugin go to
- <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
- then choose <guilabel>General</guilabel> from the left hand side. Choose the
- Installed plugins tab, scroll down to <guilabel>Poky
- SDK</guilabel> and check the
- box. The plugin is now activated but first it must be
- configured.</para>
- </section>
-
- <section id="platdev-appdev-external-anjuta-configuration">
- <title>Configuring the Anjuta plugin</title>
-
- <para>The configuration options for the SDK can be found by choosing
- the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
- need to be set:</para>
-
- <itemizedlist>
-
- <listitem><para><guilabel>SDK root</guilabel>: If we use external toolchain, we need to set SDK root.
- this is the root directory of the SDK's sysroot. For an i586 SDK this will be <filename
- class="directory">/opt/poky/</filename>.
- This directory will contain directories named like "bin",
- "include", "var", etc. under your selected target architecture subdirectory<filename class="directory">
- /opt/poky/sysroot/i586-poky-linux/</filename>. Needed cross compile tools are under
- <filename class ="directory">/opt/poky/sysroot/i586-pokysdk-linux/</filename>
- </para></listitem>
-
- <listitem><para><guilabel>Poky root</guilabel>: If we have local poky build tree, we need to set the Poky root.
- this is the root directory of the poky build tree, if you build your i586 target architecture
- under the subdirectory of build_x86 within your poky tree, the Poky root directory should be
- <filename class="directory">${Poky_tree}/build_x86/</filename>.
- </para></listitem>
-
- <listitem><para><guilabel>Target Architecture</guilabel>: this is the cross compile
- triplet, e.g. "i586-poky-linux". This target triplet is the prefix extracted from
- the set up script file name. For examle, "i586-poky-linux" is extracted from set up script file
- <filename>/opt/poky/environment-setup-i586-poky-linux</filename>
- </para></listitem>
-
- <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
- to use with QEMU</para></listitem>
-
- <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
- the root filesystem directory, this is the directory where you use "poky-extract-sdk" command to
- extract the poky-image-sdk tarball.</para></listitem>
- </itemizedlist>
-<!-- DISBALED, TOO BIG!
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/>
- </imageobject>
- <caption>
- <para>Anjuta Preferences Dialog</para>
- </caption>
- </mediaobject>
- </screenshot>
--->
-
- </section>
-
- <section id="platdev-appdev-external-anjuta-usage">
- <title>Using the Anjuta plugin</title>
-
- <para>As an example, cross-compiling a project, deploying it into
- QEMU and running a debugger against it and then doing a system
- wide profile.</para>
-
- <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
- Configure</guimenuitem></menuchoice> or
- <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
- Autogenerate</guimenuitem></menuchoice> to run "configure"
- (or to run "autogen") for the project. This passes command line
- arguments to instruct it to cross-compile.</para>
-
- <para>Next do
- <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
- Project</guimenuitem></menuchoice> to build and compile the
- project. If you have previously built the project in the same
- tree without using the cross-compiler you may find that your
- project fails to link. Simply do
- <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
- Project</guimenuitem></menuchoice> to remove the old
- binaries. You may then try building again.</para>
-
- <para>Next start QEMU by using
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
- QEMU</guimenuitem></menuchoice>, this will start QEMU and
- will show any error messages in the message view. Once Poky has
- fully booted within QEMU you may now deploy into it.</para>
-
- <para>Once built and QEMU is running, choose
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
- this will install the package into a temporary directory and
- then copy using rsync over SSH into the target. Progress and
- messages will be shown in the message view.</para>
-
- <para>To debug a program installed into onto the target choose
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
- remote</guimenuitem></menuchoice>. This prompts for the
- local binary to debug and also the command line to run on the
- target. The command line to run should include the full path to
- the to binary installed in the target. This will start a
- gdbserver over SSH on the target and also an instance of a
- cross-gdb in a local terminal. This will be preloaded to connect
- to the server and use the <guilabel>SDK root</guilabel> to find
- symbols. This gdb will connect to the target and load in
- various libraries and the target program. You should setup any
- breakpoints or watchpoints now since you might not be able to
- interrupt the execution later. You may stop
- the debugger on the target using
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
- debugger</guimenuitem></menuchoice>.</para>
-
- <para>It is also possible to execute a command in the target over
- SSH, the appropriate environment will be be set for the
- execution. Choose
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
- remote</guimenuitem></menuchoice> to do this. This will open
- a terminal with the SSH command inside.</para>
-
- <para>To do a system wide profile against the system running in
- QEMU choose
- <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
- remote</guimenuitem></menuchoice>. This will start up
- OProfileUI with the appropriate parameters to connect to the
- server running inside QEMU and will also supply the path to the
- debug information necessary to get a useful profile.</para>
-
- </section>
- </section>
-
-
- <section id="platdev-appdev-qemu">
- <title>Developing externally in QEMU</title>
- <para>
- Running Poky QEMU images is covered in the <link
- linkend='intro-quickstart-qemu'>Running an Image</link> section.
- </para>
- <para>
- Poky's QEMU images contain a complete native toolchain. This means
- that applications can be developed within QEMU in the same was as a
- normal system. Using qemux86 on an x86 machine is fast since the
- guest and host architectures match, qemuarm is slower but gives
- faithful emulation of ARM specific issues. To speed things up these
- images support using distcc to call a cross-compiler outside the
- emulated system too. If <command>runqemu</command> was used to start
- QEMU, and distccd is present on the host system, any bitbake cross
- compiling toolchain available from the build system will automatically
- be used from within qemu simply by calling distcc
- (<command>export CC="distcc"</command> can be set in the enviroment).
- Alterntatively, if a suitable SDK/toolchain is present in
- <filename class="directory">/opt/poky</filename> it will also
- automatically be used.
- </para>
-
- <para>
- There are several options for connecting into the emulated system.
- QEMU provides a framebuffer interface which has standard consoles
- available. There is also a serial connection available which has a
- console to the system running on it and IP networking as standard.
- The images have a dropbear ssh server running with the root password
- disabled allowing standard ssh and scp commands to work. The images
- also contain an NFS server exporting the guest's root filesystem
- allowing that to be made available to the host.
- </para>
- </section>
-
- <section id="platdev-appdev-insitu">
- <title>Developing in Poky directly</title>
- <para>
- Working directly in Poky is a fast and effective development technique.
- The idea is that you can directly edit files in
- <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
- or the source directory <glossterm><link linkend='var-S'>S</link></glossterm>
- and then force specific tasks to rerun in order to test the changes.
- An example session working on the matchbox-desktop package might
- look like this:
- </para>
-
- <para>
- <literallayout class='monospaced'>
-$ bitbake matchbox-desktop
-$ sh
-$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
-$ cd matchbox-desktop-2
-$ vi src/main.c
-$ exit
-$ bitbake matchbox-desktop -c compile -f
-$ bitbake matchbox-desktop
-</literallayout>
- </para>
-
- <para>
- Here, we build the package, change into the work directory for the package,
- change a file, then recompile the package. Instead of using sh like this,
- you can also use two different terminals. The risk with working like this
- is that a command like unpack could wipe out the changes you've made to the
- work directory so you need to work carefully.
- </para>
-
- <para>
- It is useful when making changes directly to the work directory files to do
- so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'>
- modifying packages with quilt</link> section. The resulting patches can be copied
- into the recipe directory and used directly in the <glossterm><link
- linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
- </para>
- <para>
- For a review of the skills used in this section see Sections <link
- linkend="usingpoky-components-bitbake">2.1.1</link> and <link
- linkend="usingpoky-debugging-taskrunning">2.4.2</link>.
- </para>
-
- </section>
-
- <section id="platdev-appdev-devshell">
- <title>Developing with 'devshell'</title>
-
- <para>
- When debugging certain commands or even to just edit packages, the
- 'devshell' can be a useful tool. To start it you run a command like:
- </para>
-
- <para>
- <literallayout class='monospaced'>
-$ bitbake matchbox-desktop -c devshell
-</literallayout>
- </para>
-
- <para>
- which will open a terminal with a shell prompt within the Poky
- environment. This means PATH is setup to include the cross toolchain,
- the pkgconfig variables are setup to find the right .pc files,
- configure will be able to find the Poky site files etc. Within this
- environment, you can run configure or compile command as if they
- were being run by Poky itself. You are also changed into the
- source (<glossterm><link linkend='var-S'>S</link></glossterm>)
- directory automatically. When finished with the shell just exit it
- or close the terminal window.
- </para>
-
- <para>
- The default shell used by devshell is the gnome-terminal. Other
- forms of terminal can also be used by setting the <glossterm>
- <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm>
- <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables
- in local.conf. For examples of the other options available, see
- <filename>meta/conf/bitbake.conf</filename>. An external shell is
- launched rather than opening directly into the original terminal
- window to make interaction with bitbakes multiple threads easier
- and also allow a client/server split of bitbake in the future
- (devshell will still work over X11 forwarding or similar).
- </para>
-
- <para>
- It is worth remembering that inside devshell you need to use the full
- compiler name such as <command>arm-poky-linux-gnueabi-gcc</command>
- instead of just <command>gcc</command> and the same applies to other
- applications from gcc, bintuils, libtool etc. Poky will have setup
- environmental variables such as CC to assist applications, such as make,
- find the correct tools.
- </para>
-
- </section>
-
- <section id="platdev-appdev-srcrev">
- <title>Developing within Poky with an external SCM based package</title>
-
- <para>
- If you're working on a recipe which pulls from an external SCM it
- is possible to have Poky notice new changes added to the
- SCM and then build the latest version. This only works for SCMs
- where its possible to get a sensible revision number for changes.
- Currently it works for svn, git and bzr repositories.
- </para>
-
- <para>
- To enable this behaviour it is simply a case of adding <glossterm>
- <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm>
- <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to
- local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm>
- is the name of the package for which you want to enable automatic source
- revision updating.
- </para>
- </section>
-
- </section>
-
-<section id="platdev-gdb-remotedebug">
- <title>Debugging with GDB Remotely</title>
-
- <para>
- <ulink url="http://sourceware.org/gdb/">GDB</ulink> (The GNU Project Debugger)
- allows you to examine running programs to understand and fix problems and
- also to perform postmortem style analsys of program crashes. It is available
- as a package within poky and installed by default in sdk images. It works best
- when -dbg packages for the application being debugged are installed as the
- extra symbols give more meaningful output from GDB.
- </para>
-
- <para>
- Sometimes, due to memory or disk space constraints, it is not possible
- to use GDB directly on the remote target to debug applications. This is
- due to the fact that
- GDB needs to load the debugging information and the binaries of the
- process being debugged. GDB then needs to perform many
- computations to locate information such as function names, variable
- names and values, stack traces, etc. even before starting the debugging
- process. This places load on the target system and can alter the
- characteristics of the program being debugged.
- </para>
- <para>
- This is where GDBSERVER comes into play as it runs on the remote target
- and does not load any debugging information from the debugged process.
- Instead, the debugging information processing is done by a GDB instance
- running on a distant computer - the host GDB. The host GDB then sends
- control commands to GDBSERVER to make it stop or start the debugged
- program, as well as read or write some memory regions of that debugged
- program. All the debugging information loading and processing as well
- as the heavy debugging duty is done by the host GDB, giving the
- GDBSERVER running on the target a chance to remain small and fast.
- </para>
- <para>
- As the host GDB is responsible for loading the debugging information and
- doing the necessary processing to make actual debugging happen, the
- user has to make sure it can access the unstripped binaries complete
- with their debugging information and compiled with no optimisations. The
- host GDB must also have local access to all the libraries used by the
- debugged program. On the remote target the binaries can remain stripped
- as GDBSERVER does not need any debugging information there. However they
- must also be compiled without optimisation matching the host's binaries.
- </para>
-
- <para>
- The binary being debugged on the remote target machine is hence referred
- to as the 'inferior' in keeping with GDB documentation and terminology.
- Further documentation on GDB, is available on
- <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>.
- </para>
-
- <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 not,
- install the gdbserver package (which needs the libthread-db1
- package).
- </para>
- <para>
- To launch GDBSERVER on the target and make it ready to "debug" a
- program located at <emphasis>/path/to/inferior</emphasis>, connect
- to the target and launch:
- <programlisting>$ gdbserver localhost:2345 /path/to/inferior</programlisting>
- After that, gdbserver should be listening on port 2345 for debugging
- commands coming from a remote GDB process running on the host computer.
- Communication between the GDBSERVER and the host GDB will be done using
- TCP. To use other communication protocols please refer to the
- GDBSERVER documentation.
- </para>
- </section>
-
- <section id="platdev-gdb-remotedebug-launch-gdb">
- <title>Launching GDB on the host computer</title>
-
- <para>
- Running GDB on the host computer takes a number of stages, described in the
- following sections.
- </para>
-
- <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
- <title>Build the cross GDB package</title>
- <para>
- A suitable gdb cross binary is required which runs on your host computer but
- knows about the the ABI of the remote target. This can be obtained from
- the the Poky toolchain, e.g.
- <filename>/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/armv5te-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb</filename>
- which "x86_64" is the host architecture, "arm" is the target architecture and "linux-gnueabi" the target ABI.
- </para>
-
- <para>
- Alternatively this can be built directly by Poky. To do this you would build
- the gdb-cross package so for example you would run:
- <programlisting>bitbake gdb-cross</programlisting>
- Once built, the cross gdb binary can be found at
- <programlisting>tmp/sysroots/&lt;host-arch&gt;/usr/bin/\
-&lt;target-arch&gt;-poky-&lt;target-abi&gt;/&lt;target-arch&gt;-poky-&lt;target-abi&gt;-gdb </programlisting>
- </para>
-
- </section>
- <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
-
- <title>Making the inferior binaries available</title>
-
- <para>
- The inferior binary needs to be available to GDB complete with all debugging
- symbols in order to get the best possible results along with any libraries
- the inferior depends on and their debugging symbols. There are a number of
- ways this can be done.
- </para>
-
- <para>
- Perhaps the easiest is to have an 'sdk' image corresponding to the plain
- image installed on the device. In the case of 'pky-image-sato',
- 'poky-image-sdk' would contain suitable symbols. The sdk images already
- have the debugging symbols installed so its just a question expanding the
- archive to some location and telling GDB where this is.
- </para>
-
- <para>
- Alternatively, poky can build a custom directory of files for a specific
- debugging purpose by reusing its tmp/rootfs directory, on the host computer
- in a slightly different way to normal. This directory contains the contents
- of the last built image. This process assumes the image running on the
- target was the last image to be built by Poky, the package <emphasis>foo</emphasis>
- contains the inferior binary to be debugged has been built without without
- optimisation and has debugging information available.
- </para>
- <para>
- Firstly you want to install the <emphasis>foo</emphasis> package to tmp/rootfs
- by doing:
- </para>
- <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
-tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf -o \
-tmp/rootfs/ update</programlisting>
- <para>
- then,
- </para>
- <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
-tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf \
--o tmp/rootfs install foo
-
-tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
-tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf \
--o tmp/rootfs install foo-dbg</programlisting>
- <para>
- which installs the debugging information too.
- </para>
-
- </section>
- <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
-
- <title>Launch the host GDB</title>
- <para>
- To launch the host GDB, run the cross gdb binary identified above with
- the inferior binary specified on the commandline:
- <programlisting>&lt;target-arch&gt;-poky-&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</programlisting>
- This loads the binary of program <emphasis>foo</emphasis>
- as well as its debugging information. Once the gdb prompt
- appears, you must instruct GDB to load all the libraries
- of the inferior from tmp/rootfs:
- <programlisting>set solib-absolute-prefix /path/to/tmp/rootfs</programlisting>
- where <filename>/path/to/tmp/rootfs</filename> must be
- the absolute path to <filename>tmp/rootfs</filename> or wherever the
- binaries with debugging information are located.
- </para>
- <para>
- Now, tell GDB to connect to the GDBSERVER running on the remote target:
- <programlisting>target remote remote-target-ip-address:2345</programlisting>
- Where remote-target-ip-address is the IP address of the
- remote target where the GDBSERVER is running. 2345 is the
- port on which the GDBSERVER is running.
- </para>
-
- </section>
- <section id="platdev-gdb-remotedebug-launch-gdb-using">
-
- <title>Using the Debugger</title>
- <para>
- Debugging can now proceed as normal, as if the debugging were being done on the
- local machine, for example to tell GDB to break in the <emphasis>main</emphasis>
- function, for instance:
- <programlisting>break main</programlisting>
- and then to tell GDB to "continue" the inferior execution,
- <programlisting>continue</programlisting>
- </para>
- <para>
- For more information about using GDB please see the
- project's online documentation at <ulink
- url="http://sourceware.org/gdb/download/onlinedocs/"/>.
- </para>
- </section>
- </section>
-
-</section>
-
-<section id="platdev-oprofile">
- <title>Profiling with OProfile</title>
-
- <para>
- <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
- statistical profiler well suited to finding performance
- bottlenecks in both userspace software and the kernel. It provides
- answers to questions like "Which functions does my application spend
- the most time in when doing X?". Poky is well integrated with OProfile
- to make profiling applications on target hardware straightforward.
- </para>
-
- <para>
- To use OProfile you need an image with OProfile installed. The easiest
- way to do this is with "tools-profile" in <glossterm><link
- linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. You also
- need debugging symbols to be available on the system where the analysis
- will take place. This can be achieved with "dbg-pkgs" in <glossterm><link
- linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by
- installing the appropriate -dbg packages. For
- successful call graph analysis the binaries must preserve the frame
- pointer register and hence should be compiled with the
- "-fno-omit-framepointer" flag. In Poky this can be achieved with
- <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
- </link></glossterm> = "-fexpensive-optimizations -fno-omit-framepointer
- -frename-registers -O2" or by setting <glossterm><link
- linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> = "1" in
- local.conf (the latter will also add extra debug information making the
- debug packages large).
- </para>
-
- <section id="platdev-oprofile-target">
- <title>Profiling on the target</title>
-
- <para>
- All the profiling work can be performed on the target device. A
- simple OProfile session might look like:
- </para>
-
- <para>
- <literallayout class='monospaced'>
-# opcontrol --reset
-# opcontrol --start --separate=lib --no-vmlinux -c 5
-[do whatever is being profiled]
-# opcontrol --stop
-$ opreport -cl
-</literallayout>
- </para>
-
- <para>
- Here, the reset command clears any previously profiled data,
- OProfile is then started. The options used to start OProfile mean
- dynamic library data is kept separately per application, kernel
- profiling is disabled and callgraphing is enabled up to 5 levels
- deep. To profile the kernel, you would specify the
- <parameter>--vmlinux=/path/to/vmlinux</parameter> option (the vmlinux file is usually in
- <filename class="directory">/boot/</filename> in Poky and must match the running kernel). The profile is
- then stopped and the results viewed with opreport with options
- to see the separate library symbols and callgraph information.
- </para>
- <para>
- Callgraphing means OProfile not only logs infomation about which
- functions time is being spent in but also which functions
- called those functions (their parents) and which functions that
- function calls (its children). The higher the callgraphing depth,
- the more accurate the results but this also increased the loging
- overhead so it should be used with caution. On ARM, binaries need
- to have the frame pointer enabled for callgraphing to work (compile
- with the gcc option -fno-omit-framepointer).
- </para>
- <para>
- For more information on using OProfile please see the OProfile
- online documentation at <ulink
- url="http://oprofile.sourceforge.net/docs/"/>.
- </para>
- </section>
-
- <section id="platdev-oprofile-oprofileui">
- <title>Using OProfileUI</title>
-
- <para>
- A graphical user interface for OProfile is also available. You can
- either use prebuilt Debian packages from the <ulink
- url='http://debian.o-hand.com/'>OpenedHand repository</ulink> or
- download and build from svn at
- http://svn.o-hand.com/repos/oprofileui/trunk/. If the
- "tools-profile" image feature is selected, all necessary binaries
- are installed onto the target device for OProfileUI interaction.
- </para>
-
-<!-- DISBALED, Need a more 'contexual' shot?
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/>
- </imageobject>
- <caption>
- <para>OProfileUI Viewer showing an application being profiled on a remote device</para>
- </caption>
- </mediaobject>
- </screenshot>
--->
- <para>
- In order to convert the data in the sample format from the target
- to the host the <filename>opimport</filename> program is needed.
- This is not included in standard Debian OProfile packages but an
- OProfile package with this addition is also available from the <ulink
- url='http://debian.o-hand.com/'>OpenedHand repository</ulink>.
- We recommend using OProfile 0.9.3 or greater. Other patches to
- OProfile may be needed for recent OProfileUI features, but Poky
- usually includes all needed patches on the target device. Please
- see the <ulink
- url='http://svn.o-hand.com/repos/oprofileui/trunk/README'>
- OProfileUI README</ulink> for up to date information, and the
- <ulink url="http://labs.o-hand.com/oprofileui">OProfileUI website
- </ulink> for more information on the OProfileUI project.
- </para>
-
- <section id="platdev-oprofile-oprofileui-online">
- <title>Online mode</title>
-
- <para>
- This assumes a working network connection with the target
- hardware. In this case you just need to run <command>
- "oprofile-server"</command> on the device. By default it listens
- on port 4224. This can be changed with the <parameter>--port</parameter> command line
- option.
-
- </para>
-
- <para>
- The client program is called <command>oprofile-viewer</command>. The
- UI is relatively straightforward, the key functionality is accessed
- through the buttons on the toolbar (which are duplicated in the
- menus.) These buttons are:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Connect - connect to the remote host, the IP address or hostname for the
- target can be supplied here.
- </para>
- </listitem>
- <listitem>
- <para>
- Disconnect - disconnect from the target.
- </para>
- </listitem>
- <listitem>
- <para>
- Start - start the profiling on the device.
- </para>
- </listitem>
- <listitem>
- <para>
- Stop - stop the profiling on the device and download the data to the local
- host. This will generate the profile and show it in the viewer.
- </para>
- </listitem>
- <listitem>
- <para>
- Download - download the data from the target, generate the profile and show it
- in the viewer.
- </para>
- </listitem>
- <listitem>
- <para>
- Reset - reset the sample data on the device. This will remove the sample
- information that was collected on a previous sampling run. Ensure you do this
- if you do not want to include old sample information.
- </para>
- </listitem>
- <listitem>
- <para>
- Save - save the data downloaded from the target to another directory for later
- examination.
- </para>
- </listitem>
- <listitem>
- <para>
- Open - load data that was previously saved.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The behaviour of the client is to download the complete 'profile archive' from
- the target to the host for processing. This archive is a directory containing
- the sample data, the object files and the debug information for said object
- files. This archive is then converted using a script included in this
- distribution ('oparchconv') that uses 'opimport' to convert the archive from
- the target to something that can be processed on the host.
- </para>
-
- <para>
- Downloaded archives are kept in /tmp and cleared up when they are no longer in
- use.
- </para>
-
- <para>
- If you wish to profile into the kernel, this is possible, you just need to ensure
- a vmlinux file matching the running kernel is available. In Poky this is usually
- located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of
- the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
- it builds so it should be a question of just ensuring a matching package is
- installed (<command> opkg install kernel-vmlinux</command>. These are automatically
- installed into development and profiling images alongside OProfile. There is a
- configuration option within the OProfileUI settings page where the location of
- the vmlinux file can be entered.
- </para>
-
- <para>
- Waiting for debug symbols to transfer from the device can be slow and it's not
- always necessary to actually have them on device for OProfile use. All that is
- needed is a copy of the filesystem with the debug symbols present on the viewer
- system. The <link linkend='platdev-gdb-remotedebug-launch-gdb'>GDB remote debug
- section</link> covers how to create such a directory with Poky and the location
- of this directory can again be specified in the OProfileUI settings dialog. If
- specified, it will be used where the file checksums match those on the system
- being profiled.
- </para>
- </section>
- <section id="platdev-oprofile-oprofileui-offline">
- <title>Offline mode</title>
-
- <para>
- If no network access to the target is available an archive for processing in
- 'oprofile-viewer' can be generated with the following set of command.
- </para>
-
- <para>
- <literallayout class='monospaced'>
-# opcontrol --reset
-# opcontrol --start --separate=lib --no-vmlinux -c 5
-[do whatever is being profiled]
-# opcontrol --stop
-# oparchive -o my_archive
-</literallayout>
- </para>
-
- <para>
- Where my_archive is the name of the archive directory where you would like the
- profile archive to be kept. The directory will be created for you. This can
- then be copied to another host and loaded using 'oprofile-viewer''s open
- functionality. The archive will be converted if necessary.
- </para>
- </section>
- </section>
-</section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->