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>

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 &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