diff options
Diffstat (limited to 'documentation/profile-manual/profile-manual-usage.xml')
-rw-r--r-- | documentation/profile-manual/profile-manual-usage.xml | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml index a35a112e55..39a0c5c91f 100644 --- a/documentation/profile-manual/profile-manual-usage.xml +++ b/documentation/profile-manual/profile-manual-usage.xml @@ -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 <target>' + + 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 |