812 lines
41 KiB
XML
812 lines
41 KiB
XML
<!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 the Yocto Project</title>
|
|
|
|
<section id="platdev-appdev">
|
|
<title>Application Development Using the Yocto Project</title>
|
|
<para>
|
|
The Yocto Project supports several methods of application development through which
|
|
you can create user-space software designed to run on an embedded device that uses
|
|
a Linux Yocto image developed with the Yocto Project.
|
|
This flexibility allows you to choose the method that works best for you.
|
|
This chapter describes each development method.
|
|
</para>
|
|
|
|
<section id="platdev-appdev-external-sdk">
|
|
<title>External Development Using the Meta-Toolchain</title>
|
|
<para>
|
|
The Yocto Project provides toolchains that allow you to develop your application
|
|
outside of the Yocto Project build system for specific hardware.
|
|
These toolchains (called meta-toolchains) contain cross-development tools such as compilers,
|
|
linkers, and debuggers that build your application for your target device.
|
|
The Yocto Project also provides images that have toolchains for supported
|
|
architectures included within the image.
|
|
This allows you to compile, debug, or profile applications directly on the target device.
|
|
See
|
|
<xref linkend='ref-images'>Reference: Images</xref> for a listing of the image
|
|
types that Yocto Project supports.
|
|
</para>
|
|
<para>
|
|
Using the BitBake tool you can build a meta-toolchain or meta-toolchain-sdk target,
|
|
which generates a tarball.
|
|
Unpacking this tarball into the <filename class="directory">/opt/poky</filename> directory
|
|
on your host produces a setup script
|
|
(e.g. <filename>/opt/poky/environment-setup-i586-poky-linux</filename>) that
|
|
you can <filename>source</filename> to initialize your build environment.
|
|
Sourcing this script adds the compiler, QEMU scripts, QEMU binary, a special version of
|
|
<filename>pkgconfig</filename> and other
|
|
useful utilities to the <filename>PATH</filename> variable used by the Yocto Project
|
|
build environment.
|
|
Variables to assist <filename>pkgconfig</filename> and
|
|
Autotools are also defined so that, for example, <filename>configure</filename>
|
|
can find pre-generated test results for tests that need target hardware on which to run.
|
|
</para>
|
|
<para>
|
|
Using the toolchain with Autotool-enabled packages is straightforward - just pass the
|
|
appropriate <filename>host</filename> option to <filename>configure</filename>.
|
|
Following is an example:
|
|
<literallayout class='monospaced'>
|
|
$ ./configure --host=arm-poky-linux-gnueabi
|
|
</literallayout>
|
|
For projects that are not Autotool-enabled, it is usually just a case of ensuring
|
|
you point to and use the cross-toolchain.
|
|
For example, the following two lines of code in a <filename>Makefile</filename>
|
|
that builds your application
|
|
specify to use the cross-compiler <filename>arm-poky-linux-gnueabi-gcc</filename>
|
|
and linker <filename>arm-poky-linux-gnueabi-ld</filename>, which are part of the
|
|
meta-toolchain you would have previously established:
|
|
<literallayout class='monospaced'>
|
|
CC=arm-poky-linux-gnueabi-gcc;
|
|
LD=arm-poky-linux-gnueabi-ld;
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="using-the-eclipse-and-anjuta-plug-ins">
|
|
<title>External Development Using the Eclipse Plug-in</title>
|
|
<para>
|
|
The current release of the Yocto Project supports the Eclipse IDE plug-in
|
|
to make developing software easier for the application developer.
|
|
The plug-in provides capability extensions to the graphical IDE to allow
|
|
for cross compilation, deployment and execution of the application within a QEMU
|
|
emulation session.
|
|
Support of the Eclipse plug-in also allows for cross debugging and
|
|
profiling.
|
|
Additionally, the Eclipse plug-in provides a suite of tools
|
|
that allows the developer to perform remote profiling, tracing, collection of
|
|
power consumption data, collection of latency data and collection of performance data.
|
|
</para>
|
|
<note>
|
|
The current release of the Yocto Project no longer supports the Anjuta plug-in.
|
|
However, the Poky Anjuta Plug-in is available to download directly from the Poky
|
|
Git repository located through the web interface at
|
|
<ulink url="http://git.yoctoproject.org/"></ulink> under IDE Plugins.
|
|
The community is free to continue supporting it beyond the Yocto Project 0.9
|
|
Release.
|
|
</note>
|
|
<para>
|
|
To use the Eclipse plug-in you need the Eclipse Framework (Helios 3.6.1) along
|
|
with other plug-ins installed into the Eclipse IDE.
|
|
Once you have your environment setup you need to configure the Eclipse plug-in.
|
|
For information on how to install and configure the Eclipse plug-in, see the
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html#adt-eclipse'>
|
|
"Working Within Eclipse"</ulink> chapter in the
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html'>
|
|
"Application Development Toolkit (ADT) User's Guide."</ulink>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-appdev-qemu">
|
|
<title>External Development Using the QEMU Emulator</title>
|
|
<para>
|
|
Running Poky QEMU images is covered in the
|
|
<ulink url="http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html">
|
|
Yocto Project Quick Start</ulink> in the "A Quick Test Run" section.
|
|
</para>
|
|
<para>
|
|
The QEMU images shipped with the Yocto Project contain complete toolchains
|
|
native to their target architectures.
|
|
This support allows you to develop applications within QEMU similar to the way
|
|
you would using a normal host development system.
|
|
</para>
|
|
|
|
<para>
|
|
Speed can be an issue depending on the target and host architecture mix.
|
|
For example, using the <filename>qemux86</filename> image in the emulator
|
|
on an Intel-based 32-bit (x86) host machine is fast because the target and
|
|
host architectures match.
|
|
On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
|
|
host can be slower.
|
|
But, you still achieve faithful emulation of ARM-specific issues.
|
|
</para>
|
|
|
|
<para>
|
|
To speed things up, the QEMU images support using <filename>distcc</filename>
|
|
to call a cross-compiler outside the emulated system.
|
|
If you used <filename>runqemu</filename> to start QEMU, and
|
|
<filename>distccd</filename> is present on the host system, any BitBake cross-compiling
|
|
toolchain available from the build system is automatically
|
|
used from within QEMU simply by calling <filename>distcc</filename>.
|
|
You can accomplish this by defining the cross-compiler variable
|
|
(e.g. <filename>export CC="distcc"</filename>).
|
|
Alternatively, if a suitable SDK/toolchain is present in
|
|
<filename>/opt/poky</filename> the toolchain is also automatically used.
|
|
</para>
|
|
|
|
<para>
|
|
Several mechanisms exist that let you connect to the system running on the
|
|
QEMU emulator:
|
|
<itemizedlist>
|
|
<listitem><para>QEMU provides a framebuffer interface that makes standard
|
|
consoles available.</para></listitem>
|
|
<listitem><para>Generally, headless embedded devices have a serial port.
|
|
If so, you can configure the operating system of the running image
|
|
to use that port to run a console.
|
|
The connection uses standard IP networking.</para></listitem>
|
|
<listitem><para>The QEMU images have a Dropbear secure shell (ssh) server
|
|
that runs with the root password disabled.
|
|
This allows you to use standard <filename>ssh</filename> and
|
|
<filename>scp</filename> commands.</para></listitem>
|
|
<listitem><para>The QEMU images also contain an embedded Network Files
|
|
System (NFS) server that exports the image's root filesystem.
|
|
This allows you to make the filesystem available to the
|
|
host.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-appdev-insitu">
|
|
<title>Development Using Yocto Project Directly</title>
|
|
<para>
|
|
Working directly with the Yocto Project is a fast and effective development technique.
|
|
The idea is that you can directly edit files in a working directory
|
|
(<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
|
|
.
|
|
.
|
|
[Make your changes]
|
|
.
|
|
.
|
|
$ exit
|
|
$ bitbake matchbox-desktop -c compile -f
|
|
$ bitbake matchbox-desktop
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This example builds the <filename>matchbox-desktop</filename> package,
|
|
creates a new terminal, changes into the work directory for the package,
|
|
changes a file, exits out of the terminal, and then recompiles the
|
|
package.
|
|
Instead of using <filename>sh</filename>,
|
|
you can also use two different terminals.
|
|
However, the risk of using two terminals is that a command like
|
|
<filename>unpack</filename> could destroy your changes in the
|
|
work directory.
|
|
Consequently, you need to work carefully.
|
|
</para>
|
|
|
|
<para>
|
|
It is useful when making changes directly to the work directory files to do
|
|
so using the Quilt tool as detailed in the
|
|
<link linkend='usingpoky-modifying-packages-quilt'>
|
|
Modifying Package Source Code with Quilt</link> section.
|
|
Using Quilt, you can copy patches into the recipe directory and use the patches directly
|
|
through use of the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable.
|
|
</para>
|
|
|
|
<para>
|
|
For a review of the skills used in this section, see the
|
|
<link linkend="usingpoky-components-bitbake">BitBake</link> and
|
|
<link linkend="usingpoky-debugging-taskrunning">Running Specific Tasks</link> sections
|
|
in this manual.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-appdev-devshell">
|
|
<title>Development Within a Development Shell</title>
|
|
|
|
<para>
|
|
When debugging certain commands or even when just editing packages,
|
|
<filename>devshell</filename> can be a useful tool.
|
|
Using <filename>devshell</filename> differs from the example shown in the previous
|
|
section in that when you invoke <filename>devshell</filename> source files are
|
|
extracted into your working directory and patches are applied.
|
|
Then, a new terminal is opened and you are placed in the working directory.
|
|
In the new terminal all the Yocto Project build-related environment variables are
|
|
still defined so you can use commands such as <filename>configure</filename> and
|
|
<filename>make</filename>.
|
|
The commands execute just as if the Yocto Project build system were executing them.
|
|
Consequently, workng this way can be helpful when debugging a build or preparing
|
|
software to be used with the Yocto Project build system.
|
|
</para>
|
|
|
|
<para>
|
|
Following is an example that uses <filename>devshell</filename> on a target named
|
|
<filename>matchbox-desktop</filename>:
|
|
</para>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
$ bitbake matchbox-desktop -c devshell
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This command opens a terminal with a shell prompt within the Poky
|
|
environment.
|
|
The following occurs:
|
|
<itemizedlist>
|
|
<listitem><para>The <filename>PATH</filename> variable includes the
|
|
cross-toolchain.</para></listitem>
|
|
<listitem><para>The <filename>pkgconfig</filename> variables find the correct
|
|
<filename>.pc</filename> files.</para></listitem>
|
|
<listitem><para>The <filename>configure</filename> command finds the
|
|
Yocto Project site files as well as any other necessary files.</para></listitem>
|
|
</itemizedlist>
|
|
Within this environment, you can run <filename>configure</filename>
|
|
or <filename>compile</filename> commands as if they were being run by
|
|
the Yocto Project build system itself.
|
|
As noted earlier, the working directory also automatically changes to the
|
|
source directory (<glossterm><link linkend='var-S'>S</link></glossterm>).
|
|
</para>
|
|
|
|
<para>
|
|
When you are finished, you just exit the shell or close the terminal window.
|
|
</para>
|
|
|
|
<para>
|
|
The default shell used by <filename>devshell</filename> is xterm.
|
|
You can use other terminal forms by setting the
|
|
<glossterm><link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and
|
|
<glossterm><link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables
|
|
in the Yocto Project's <filename>local.conf</filename> file found in the build
|
|
directory.
|
|
For examples of the other options available, see the "UI/Interaction Configuration"
|
|
section of the
|
|
<filename>meta/conf/bitbake.conf</filename> configuration file in the Yocto Project
|
|
files.
|
|
</para>
|
|
|
|
<para>
|
|
Because an external shell is launched rather than opening directly into the
|
|
original terminal window, it allows easier interaction with Bitbake's multiple
|
|
threads as well as accomodates a future client/server split.
|
|
</para>
|
|
|
|
<note>
|
|
<para>It is worth remembering that when using <filename>devshell</filename>
|
|
you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
|
|
instead of just using <filename>gcc</filename>.
|
|
The same applies to other applications such as <filename>binutils</filename>,
|
|
<filename>libtool</filename> and so forth.
|
|
The Yocto Project has setup environment variables such as <filename>CC</filename>
|
|
to assist applications, such as <filename>make</filename> to find the correct tools.</para>
|
|
<para>It is also worth noting that <filename>devshell</filename> still works over
|
|
X11 forwarding and similar situations</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="platdev-appdev-srcrev">
|
|
<title>Development Within Yocto Project for a Package that Uses an External SCM</title>
|
|
|
|
<para>
|
|
If you're working on a recipe that pulls from an external Source Code Manager (SCM), it
|
|
is possible to have the Yocto Project build system notice new changes added to the
|
|
SCM and then build the package that depends on them using the latest version.
|
|
This only works for SCMs from which it is possible to get a sensible revision number for changes.
|
|
Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
|
|
</para>
|
|
|
|
<para>
|
|
To enable this behavior, simply add the following to the <filename>local.conf</filename>
|
|
configuration file in the build directory of the Yocto Project files:
|
|
<literallayout class='monospaced'>
|
|
SRCREV_pn-<PN> = "${AUTOREV}"
|
|
</literallayout>
|
|
where <filename>PN</filename>
|
|
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 the GNU Project Debugger (GDB) Remotely</title>
|
|
|
|
<para>
|
|
GDB allows you to examine running programs, which in turn help you to understand and fix problems.
|
|
It also allows you to perform post-mortem style analysis of program crashes.
|
|
GDB is available as a package within the Yocto Project and by default is
|
|
installed in sdk images.
|
|
See <xref linkend='ref-images'>Reference: Images</xref> for a description of these
|
|
images.
|
|
You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
|
|
</para>
|
|
|
|
<tip>
|
|
For best results, install <filename>-dbg</filename> packages for the applications
|
|
you are going to debug.
|
|
Doing so makes available extra debug symbols that give you more meaningful output.
|
|
</tip>
|
|
|
|
<para>
|
|
Sometimes, due to memory or disk space constraints, it is not possible
|
|
to use GDB directly on the remote target to debug applications.
|
|
These constraints arise because GDB needs to load the debugging information and the
|
|
binaries of the process being debugged.
|
|
Additionally, GDB needs to perform many computations to locate information such as function
|
|
names, variable names and values, stack traces and so forth - even before starting the
|
|
debugging process.
|
|
These extra computations place more load on the target system and can alter the
|
|
characteristics of the program being debugged.
|
|
</para>
|
|
|
|
<para>
|
|
To help get past the previously mentioned constraints, you can use Gdbserver.
|
|
Gdbserver runs on the remote target and does not load any debugging information
|
|
from the debugged process.
|
|
Instead, a GDB instance processes the debugging information that is run on a
|
|
remote 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 memory regions of that debugged program.
|
|
All the debugging information loaded and processed as well
|
|
as all the heavy debugging is done by the host GDB.
|
|
Offloading these processes gives the Gdbserver running on the target a chance to remain
|
|
small and fast.
|
|
</para>
|
|
|
|
<para>
|
|
Because the host GDB is responsible for loading the debugging information and
|
|
for doing the necessary processing to make actual debugging happen, the
|
|
user has to make sure the host can access the unstripped binaries complete
|
|
with their debugging information and also be sure the target is compiled with no optimizations.
|
|
The host GDB must also have local access to all the libraries used by the
|
|
debugged program.
|
|
Because Gdbserver does not need any local debugging information, the binaries on
|
|
the remote target can remain stripped.
|
|
However, the binaries must also be compiled without optimization
|
|
so they match the host's binaries.
|
|
</para>
|
|
|
|
<para>
|
|
To remain consistent with GDB documentation and terminology, the binary being debugged
|
|
on the remote target machine is referred to as the "inferior" binary.
|
|
For documentation on GDB see the
|
|
<ulink url="http://sourceware.org/gdb/documentation/">GDB 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 it is not, install the package <filename>gdbserver</filename>, which needs the
|
|
<filename>libthread-db1</filename> package.
|
|
</para>
|
|
|
|
<para>
|
|
As an example, to launch Gdbserver on the target and make it ready to "debug" a
|
|
program located at <filename>/path/to/inferior</filename>, connect
|
|
to the target and launch:
|
|
<literallayout class='monospaced'>
|
|
$ gdbserver localhost:2345 /path/to/inferior
|
|
</literallayout>
|
|
Gdbserver should now be listening on port 2345 for debugging
|
|
commands coming from a remote GDB process that is running on the host computer.
|
|
Communication between Gdbserver and the host GDB are done using TCP.
|
|
To use other communication protocols, please refer to the
|
|
<ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
|
|
</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.
|
|
This section describes those stages.
|
|
</para>
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
|
|
<title>Building the Cross-GDB Package</title>
|
|
<para>
|
|
A suitable GDB cross-binary is required that runs on your host computer but
|
|
also knows about the the ABI of the remote target.
|
|
You can get this binary from the the Yocto Project meta-toolchain.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
|
|
</literallayout>
|
|
where <filename>arm</filename> is the target architecture and
|
|
<filename>linux-gnueabi</filename> the target ABI.
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake gdb-cross
|
|
</literallayout>
|
|
Once the binary is built, you can find it here:
|
|
<literallayout class='monospaced'>
|
|
tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
|
|
<title>Making the Inferior Binaries Available</title>
|
|
|
|
<para>
|
|
The inferior binary (complete with all debugging symbols) as well as any
|
|
libraries (and their debugging symbols) on which the inferior binary depends
|
|
need to be available.
|
|
There are a number of ways you can make these available.
|
|
</para>
|
|
|
|
<para>
|
|
Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain
|
|
image installed on the device.
|
|
In the case of <filename>core-image-sato</filename>,
|
|
<filename>core-image-sdk</filename> would contain suitable symbols.
|
|
Because the sdk images already have the debugging symbols installed, it is just a
|
|
question of expanding the archive to some location and then informing GDB.
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, Yocto Project can build a custom directory of files for a specific
|
|
debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
|
|
This directory contains the contents of the last built image.
|
|
This process assumes two things:
|
|
<itemizedlist>
|
|
<listitem><para>The image running on the target was the last image to
|
|
be built by the Yocto Project.</para></listitem>
|
|
<listitem><para>The package (<filename>foo</filename> in the following
|
|
example) that contains the inferior binary to be debugged has been built
|
|
without optimization and has debugging information available.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The following steps show how to build the custom directory of files:
|
|
<orderedlist>
|
|
<listitem><para>Install the package (<filename>foo</filename> in this case) to
|
|
<filename>tmp/rootfs</filename>:
|
|
<literallayout class='monospaced'>
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf -o \
|
|
tmp/rootfs/ update
|
|
</literallayout></para></listitem>
|
|
<listitem><para>Install the debugging information:
|
|
<literallayout class='monospaced'>
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \
|
|
-o tmp/rootfs install foo
|
|
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \
|
|
-o tmp/rootfs install foo-dbg
|
|
</literallayout></para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
|
|
<title>Launch the Host GDB</title>
|
|
|
|
<para>
|
|
To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
|
|
the inferior binary as part of the command line.
|
|
For example, the following command form continues with the example used in
|
|
the previous section.
|
|
This command form loads the <filename>foo</filename> binary
|
|
as well as the debugging information:
|
|
<literallayout class='monospaced'>
|
|
$ <target-abi>-gdb rootfs/usr/bin/foo
|
|
</literallayout>
|
|
Once the GDB prompt appears, you must instruct GDB to load all the libraries
|
|
of the inferior binary from <filename>tmp/rootfs</filename> as follows:
|
|
<literallayout class='monospaced'>
|
|
$ set solib-absolute-prefix /path/to/tmp/rootfs
|
|
</literallayout>
|
|
The pathname <filename>/path/to/tmp/rootfs</filename> must either be
|
|
the absolute path to <filename>tmp/rootfs</filename> or the location at which
|
|
binaries with debugging information reside.
|
|
</para>
|
|
|
|
<para>
|
|
At this point you can have GDB connect to the Gdbserver that is running
|
|
on the remote target by using the following command form:
|
|
<literallayout class='monospaced'>
|
|
$ target remote remote-target-ip-address:2345
|
|
</literallayout>
|
|
The <filename>remote-target-ip-address</filename> is the IP address of the
|
|
remote target where the Gdbserver is running.
|
|
Port 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>
|
|
You can now proceed with debugging as normal - as if you were debugging
|
|
on the local machine.
|
|
For example, to instruct GDB to break in the "main" function and then
|
|
continue with execution of the inferior binary use the following commands
|
|
from within GDB:
|
|
<literallayout class='monospaced'>
|
|
(gdb) break main
|
|
(gdb) continue
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
For more information about using GDB, 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 for finding performance
|
|
bottlenecks in both userspace software and in the kernel.
|
|
This profiler provides answers to questions like "Which functions does my application spend
|
|
the most time in when doing X?"
|
|
Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target
|
|
hardware straightforward.
|
|
</para>
|
|
|
|
<para>
|
|
To use OProfile, you need an image that has OProfile installed.
|
|
The easiest way to do this is with <filename>tools-profile</filename> in the
|
|
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> variable.
|
|
You also need debugging symbols to be available on the system where the analysis
|
|
takes place.
|
|
You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
|
|
<filename>IMAGE_FEATURES</filename> variable or by
|
|
installing the appropriate <filename>-dbg</filename> packages.
|
|
</para>
|
|
|
|
<para>
|
|
For successful call graph analysis, the binaries must preserve the frame
|
|
pointer register and should also be compiled with the
|
|
<filename>-fno-omit-framepointer</filename> flag.
|
|
In the Yocto Project you can achieve this by setting the
|
|
<filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
|
|
</link></filename> variable to
|
|
<filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
|
|
You can also achieve it by setting the
|
|
<filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> variable to "1" in
|
|
the <filename>local.conf</filename> configuration file.
|
|
If you use the <filename>DEBUG_BUILD</filename> variable you will also add extra debug information
|
|
that can make the debug packages large.
|
|
</para>
|
|
|
|
<section id="platdev-oprofile-target">
|
|
<title>Profiling on the Target</title>
|
|
|
|
<para>
|
|
Using OProfile you can perform all the profiling work on the target device.
|
|
A simple OProfile session might look like the following:
|
|
</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>
|
|
In this example, the <filename>reset</filename> command clears any previously profiled data.
|
|
The next command starts OProfile.
|
|
The options used when starting the profiler separate dynamic library data
|
|
within applications, disable kernel profiling, and enable callgraphing up to
|
|
five levels deep.
|
|
<note>
|
|
To profile the kernel, you would specify the
|
|
<filename>--vmlinux=/path/to/vmlinux</filename> option.
|
|
The <filename>vmlinux</filename> file is usually in the Yocto Project file's
|
|
<filename>/boot/</filename> directory and must match the running kernel.
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
After you perform your profiling tasks, the next command stops the profiler.
|
|
After that, you can view results with the <filename>opreport</filename> command with options
|
|
to see the separate library symbols and callgraph information.
|
|
</para>
|
|
|
|
<para>
|
|
Callgraphing logs information about time spent in functions and about a function's
|
|
calling function (parent) and called functions (children).
|
|
The higher the callgraphing depth, the more accurate the results.
|
|
However, higher depths also increase the logging overhead.
|
|
Consequently, you should take care when setting the callgraphing depth.
|
|
<note>
|
|
On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
|
|
To accomplish this use the <filename>-fno-omit-framepointer</filename> option
|
|
with <filename>gcc</filename>.
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
For more information on using OProfile, 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 download and build this interface from the Yocto Project at
|
|
<ulink url="http://git.yoctoproject.org/cgit.cgi/oprofileui/"></ulink>.
|
|
If the "tools-profile" image feature is selected, all necessary binaries
|
|
are installed onto the target device for OProfileUI interaction.
|
|
</para>
|
|
|
|
<para>
|
|
Even though the Yocto Project usually includes all needed patches on the target device, you
|
|
might find you need other OProfile patches for recent OProfileUI features.
|
|
If so, see the <ulink url='http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README'>
|
|
OProfileUI README</ulink> for the most recent information.
|
|
</para>
|
|
|
|
<section id="platdev-oprofile-oprofileui-online">
|
|
<title>Online Mode</title>
|
|
|
|
<para>
|
|
Using OProfile in online mode assumes a working network connection with the target
|
|
hardware.
|
|
With this connection, you just need to run "oprofile-server" on the device.
|
|
By default, OProfile listens on port 4224.
|
|
<note>
|
|
You can change the port using the <filename>--port</filename> command-line
|
|
option.
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
|
|
straightforward.
|
|
You access key functionality through the buttons on the toolbar, which
|
|
are duplicated in the menus.
|
|
Here are the buttons:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
|
|
You can also supply the IP address or hostname.</para></listitem>
|
|
<listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
|
|
downloads the data to the local host.
|
|
Stopping the profiler generates the profile and displays it in the viewer.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Download:</emphasis> Downloads the data from the
|
|
target and generates the profile, which appears in the viewer.</para></listitem>
|
|
<listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
|
|
Resetting the data removes sample information collected from previous
|
|
sampling runs.
|
|
Be sure you reset the data if you do not want to include old sample information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
|
|
target to another directory for later examination.</para></listitem>
|
|
<listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The client downloads the complete 'profile archive' from
|
|
the target to the host for processing.
|
|
This archive is a directory that contains the sample data, the object files,
|
|
and the debug information for the object files.
|
|
The archive is then converted using the <filename>oparchconv</filename> script, which is
|
|
included in this distribution.
|
|
The script uses <filename>opimport</filename> to convert the archive from
|
|
the target to something that can be processed on the host.
|
|
</para>
|
|
|
|
<para>
|
|
Downloaded archives reside in the Yocto Project's build directory in
|
|
<filename>/tmp</filename> and are cleared up when they are no longer in use.
|
|
</para>
|
|
|
|
<para>
|
|
If you wish to perform kernel profiling, you need to be sure
|
|
a <filename>vmlinux</filename> file that matches the running kernel is available.
|
|
In the Yocto Project, that file is usually located in
|
|
<filename>/boot/vmlinux-KERNELVERSION</filename>, where
|
|
<filename>KERNEL-version</filename> is the version of the kernel.
|
|
The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel
|
|
it builds.
|
|
Thus, it should just be a question of making sure a matching package is
|
|
installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
|
|
The files are automatically installed into development and profiling images
|
|
alongside OProfile.
|
|
A configuration option exists within the OProfileUI settings page that you can use to
|
|
enter the location of the <filename>vmlinux</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
Waiting for debug symbols to transfer from the device can be slow, and it
|
|
is not always necessary to actually have them on the 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'>Launching GDB
|
|
on the Host Computer</link> section covers how to create such a directory with
|
|
the Yocto Project and how to use the OProfileUI Settings dialog to specify the location.
|
|
If you specify the directory, it will be used when the file checksums
|
|
match those on the system you are profiling.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="platdev-oprofile-oprofileui-offline">
|
|
<title>Offline Mode</title>
|
|
|
|
<para>
|
|
If network access to the target is unavailable, you can generate
|
|
an archive for processing in <filename>oprofile-viewer</filename> as follows:
|
|
<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>
|
|
In the above example, <filename>my_archive</filename> is the name of the
|
|
archive directory where you would like the profile archive to be kept.
|
|
After the directory is created, you can copy it to another host and load it
|
|
using <filename>oprofile-viewer</filename> open functionality.
|
|
If necessary, the archive is converted.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
|
|
</chapter>
|
|
<!--
|
|
vim: expandtab tw=80 ts=4
|
|
-->
|