From fcf615546f88e28caa56b2e977c183c792e071a6 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 17 Jan 2013 10:51:51 -0800 Subject: profile-manual: Systemtap section added. No re-writing at all. (From yocto-docs rev: 4ca472f8200f9d927a8d37c88c1ff75b017fcfc1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../profile-manual/profile-manual-usage.xml | 217 +++++++++++++++++++++ 1 file changed, 217 insertions(+) (limited to 'documentation/profile-manual') 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 @@ +
+ systemtap + + + SystemTap is a system-wide script-based tracing and profiling tool. + + + + 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. + + + + For example, this probe from the + SystemTap tutorial + 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. + + probe syscall.open + { + printf ("%s(%d) open (%s)\n", execname(), pid(), argstr) + } + + probe timer.ms(4000) # after 4 seconds + { + exit () + } + + 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: + + # stap trace_open.stp + + 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. + + + + 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'. + + + + 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. + + + + 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. + + +
+ Setup + + + 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. + + + + 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: + + $ 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 + + So essentially what you need to do is build an SDK image or + image with 'tools-profile' as detailed in the + "General Setup" + section of this manual, and boot the resulting target image. + + + + 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. + +
+ +
+ Running a Script on a Target + + + Once you've done that, you should be able to run a systemtap + script on the target: + + $ 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' + + Once you've done that, you can cd to whatever directory + contains your scripts and use 'crosstap' to run the script: + + $ cd /path/to/my/systemap/script + $ crosstap root@192.168.7.2 trace_open.stp + + If you get an error connecting to the target e.g.: + + $ crosstap root@192.168.7.2 trace_open.stp + error establishing ssh connection on remote 'root@192.168.7.2' + + Try ssh'ing to the target and see what happens: + + $ ssh root@192.168.7.2 + + A lot of the time, connection problems are due specifying a + wrong IP address or having a 'host key verification error'. + + + + 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): + + $ 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) + + +
+ +
+ Documentation + + + The SystemTap language reference can be found here: + SystemTap Language Reference + + + + Links to other SystemTap documents, tutorials, and examples can be + found here: + SystemTap documentation page + +
+
+