sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

profile-manual: Systemtap section added. 

No re-writing at all.

(From yocto-docs rev: 4ca472f8200f9d927a8d37c88c1ff75b017fcfc1)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-01-17 10:51:51 -08:00 committed by Richard Purdie
parent 44e838c612
commit fcf615546f
1 changed files with 217 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
documentation/profile-manual/profile-manual-usage.xml
View File

@ -2004,6 +2004,223 @@
</section>
</section>
<section id='profile-manual-systemtap'>
<title>systemtap</title>
<para>
SystemTap is a system-wide script-based tracing and profiling tool.
</para>
<para>
SystemTap scripts are C-like programs that are executed in the
kernel to gather/print/aggregate data extracted from the context
they end up being invoked under.
</para>
<para>
For example, this probe from the
<ulink url='http://sourceware.org/systemtap/tutorial/'>SystemTap tutorial</ulink>
simply prints a line every time any process on the system open()s
a file. For each line, it prints the executable name of the
program that opened the file, along with its pid, and the name
of the file it opened (or tried to open), which it extracts
from the open syscall's argstr.
<literallayout class='monospaced'>
probe syscall.open
{
printf ("%s(%d) open (%s)\n", execname(), pid(), argstr)
}
probe timer.ms(4000) # after 4 seconds
{
exit ()
}
</literallayout>
Normally, to execute this probe, you'd simply install
systemtap on the system you want to probe, and directly run
the probe on that system e.g. assuming the name of the file
containing the above text is trace_open.stp:
<literallayout class='monospaced'>
# stap trace_open.stp
</literallayout>
What systemtap does under the covers to run this probe is 1)
parse and convert the probe to an equivalent 'C' form, 2)
compile the 'C' form into a kernel module, 3) insert the
module into the kernel, which arms it, and 4) collect the data
generated by the probe and display it to the user.
</para>
<para>
In order to accomplish steps 1 and 2, the 'stap' program needs
access to the kernel build system that produced the kernel
that the probed system is running. In the case of a typical
embedded system (the 'target'), the kernel build system
unfortunately isn't typically part of the image running on
the target. It is normally available on the 'host' system
that produced the target image however; in such cases,
steps 1 and 2 are executed on the host system, and steps
3 and 4 are executed on the target system, using only the
systemtap 'runtime'.
</para>
<para>
The systemtap support in Yocto assumes that only steps
3 and 4 are run on the target; it is possible to do
everything on the target, but this section assumes only
the typical embedded use-case.
</para>
<para>
So basically what you need to do in order to run a systemtap
script on the target is to 1) on the host system, compile the
probe into a kernel module that makes sense to the target, 2)
copy the module onto the target system and 3) insert the
module into the target kernel, which arms it, and 4) collect
the data generated by the probe and display it to the user.
</para>
<section id='systemtap-setup'>
<title>Setup</title>
<para>
Those are a lot of steps and a lot of details, but
fortunately Yocto includes a script called 'crosstap'
that will take care of those details, allowing you to
simply execute a systemtap script on the remote target,
with arguments if necessary.
</para>
<para>
In order to do this from a remote host, however, you
need to have access to the build for the image you
booted. The 'crosstap' script provides details on how
to do this if you run the script on the host without having
done a build:
<literallayout class='monospaced'>
$ crosstap root@192.168.1.88 trace_open.stp
Error: No target kernel build found.
Did you forget to create a local build of your image?
'crosstap' requires a local sdk build of the target system
(or a build that includes 'tools-profile') in order to build
kernel modules that can probe the target system.
Practically speaking, that means you need to do the following:
- If you're running a pre-built image, download the release
and/or BSP tarballs used to build the image.
- If you're working from git sources, just clone the metadata
and BSP layers needed to build the image you'll be booting.
- Make sure you're properly set up to build a new image (see
the BSP README and/or the widely available basic documentation
that discusses how to build images).
- Build an -sdk version of the image e.g.:
$ bitbake core-image-sato-sdk
OR
- Build a non-sdk image but include the profiling tools:
[ edit local.conf and add 'tools-profile' to the end of
the EXTRA_IMAGE_FEATURES variable ]
$ bitbake core-image-sato
[ NOTE that 'crosstap' needs to be able to ssh into the target
system, which isn't enabled by default in -minimal images. ]
Once you've build the image on the host system, you're ready to
boot it (or the equivalent pre-built image) and use 'crosstap'
to probe it (you need to source the environment as usual first):
$ source oe-init-build-env
$ cd ~/my/systemtap/scripts
$ crosstap root@192.168.1.xxx myscript.stp
</literallayout>
So essentially what you need to do is build an SDK image or
image with 'tools-profile' as detailed in the
"<link linkend='profile-manual-general-setup'>General Setup</link>"
section of this manual, and boot the resulting target image.
</para>
<note>
If you have a build directory containing multiple machines,
you need to have the MACHINE you're connecting to selected
in local.conf, and the kernel in that machine's build
directory must match the kernel on the booted system exactly,
or you'll get the above 'crosstap' message when you try to
invoke a script.
</note>
</section>
<section id='running-a-script-on-a-target'>
<title>Running a Script on a Target</title>
<para>
Once you've done that, you should be able to run a systemtap
script on the target:
<literallayout class='monospaced'>
$ cd /path/to/yocto
$ source oe-init-build-env
### Shell environment set up for builds. ###
You can now run 'bitbake &lt;target&gt;'
Common targets are:
core-image-minimal
core-image-sato
meta-toolchain
meta-toolchain-sdk
adt-installer
meta-ide-support
You can also run generated qemu images with a command like 'runqemu qemux86'
</literallayout>
Once you've done that, you can cd to whatever directory
contains your scripts and use 'crosstap' to run the script:
<literallayout class='monospaced'>
$ cd /path/to/my/systemap/script
$ crosstap root@192.168.7.2 trace_open.stp
</literallayout>
If you get an error connecting to the target e.g.:
<literallayout class='monospaced'>
$ crosstap root@192.168.7.2 trace_open.stp
error establishing ssh connection on remote 'root@192.168.7.2'
</literallayout>
Try ssh'ing to the target and see what happens:
<literallayout class='monospaced'>
$ ssh root@192.168.7.2
</literallayout>
A lot of the time, connection problems are due specifying a
wrong IP address or having a 'host key verification error'.
</para>
<para>
If everything worked as planned, you should see something
like this (enter the password when prompted, or press enter
if its set up to use no password):
<literallayout class='monospaced'>
$ crosstap root@192.168.7.2 trace_open.stp
root@192.168.7.2's password:
matchbox-termin(1036) open ("/tmp/vte3FS2LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
matchbox-termin(1036) open ("/tmp/vteJMC7LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
</literallayout>
</para>
</section>
<section id='systemtap-documentation'>
<title>Documentation</title>
<para>
The SystemTap language reference can be found here:
<ulink url='http://sourceware.org/systemtap/langref/'>SystemTap Language Reference</ulink>
</para>
<para>
Links to other SystemTap documents, tutorials, and examples can be
found here:
<ulink url='http://sourceware.org/systemtap/documentation.html'>SystemTap documentation page</ulink>
</para>
</section>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4