summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/profile-manual/profile-manual-usage.xml217
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 @@
2004 </section> 2004 </section>
2005</section> 2005</section>
2006 2006
2007<section id='profile-manual-systemtap'>
2008 <title>systemtap</title>
2009
2010 <para>
2011 SystemTap is a system-wide script-based tracing and profiling tool.
2012 </para>
2013
2014 <para>
2015 SystemTap scripts are C-like programs that are executed in the
2016 kernel to gather/print/aggregate data extracted from the context
2017 they end up being invoked under.
2018 </para>
2019
2020 <para>
2021 For example, this probe from the
2022 <ulink url='http://sourceware.org/systemtap/tutorial/'>SystemTap tutorial</ulink>
2023 simply prints a line every time any process on the system open()s
2024 a file. For each line, it prints the executable name of the
2025 program that opened the file, along with its pid, and the name
2026 of the file it opened (or tried to open), which it extracts
2027 from the open syscall's argstr.
2028 <literallayout class='monospaced'>
2029 probe syscall.open
2030 {
2031 printf ("%s(%d) open (%s)\n", execname(), pid(), argstr)
2032 }
2033
2034 probe timer.ms(4000) # after 4 seconds
2035 {
2036 exit ()
2037 }
2038 </literallayout>
2039 Normally, to execute this probe, you'd simply install
2040 systemtap on the system you want to probe, and directly run
2041 the probe on that system e.g. assuming the name of the file
2042 containing the above text is trace_open.stp:
2043 <literallayout class='monospaced'>
2044 # stap trace_open.stp
2045 </literallayout>
2046 What systemtap does under the covers to run this probe is 1)
2047 parse and convert the probe to an equivalent 'C' form, 2)
2048 compile the 'C' form into a kernel module, 3) insert the
2049 module into the kernel, which arms it, and 4) collect the data
2050 generated by the probe and display it to the user.
2051 </para>
2052
2053 <para>
2054 In order to accomplish steps 1 and 2, the 'stap' program needs
2055 access to the kernel build system that produced the kernel
2056 that the probed system is running. In the case of a typical
2057 embedded system (the 'target'), the kernel build system
2058 unfortunately isn't typically part of the image running on
2059 the target. It is normally available on the 'host' system
2060 that produced the target image however; in such cases,
2061 steps 1 and 2 are executed on the host system, and steps
2062 3 and 4 are executed on the target system, using only the
2063 systemtap 'runtime'.
2064 </para>
2065
2066 <para>
2067 The systemtap support in Yocto assumes that only steps
2068 3 and 4 are run on the target; it is possible to do
2069 everything on the target, but this section assumes only
2070 the typical embedded use-case.
2071 </para>
2072
2073 <para>
2074 So basically what you need to do in order to run a systemtap
2075 script on the target is to 1) on the host system, compile the
2076 probe into a kernel module that makes sense to the target, 2)
2077 copy the module onto the target system and 3) insert the
2078 module into the target kernel, which arms it, and 4) collect
2079 the data generated by the probe and display it to the user.
2080 </para>
2081
2082 <section id='systemtap-setup'>
2083 <title>Setup</title>
2084
2085 <para>
2086 Those are a lot of steps and a lot of details, but
2087 fortunately Yocto includes a script called 'crosstap'
2088 that will take care of those details, allowing you to
2089 simply execute a systemtap script on the remote target,
2090 with arguments if necessary.
2091 </para>
2092
2093 <para>
2094 In order to do this from a remote host, however, you
2095 need to have access to the build for the image you
2096 booted. The 'crosstap' script provides details on how
2097 to do this if you run the script on the host without having
2098 done a build:
2099 <literallayout class='monospaced'>
2100 $ crosstap root@192.168.1.88 trace_open.stp
2101
2102 Error: No target kernel build found.
2103 Did you forget to create a local build of your image?
2104
2105 'crosstap' requires a local sdk build of the target system
2106 (or a build that includes 'tools-profile') in order to build
2107 kernel modules that can probe the target system.
2108
2109 Practically speaking, that means you need to do the following:
2110 - If you're running a pre-built image, download the release
2111 and/or BSP tarballs used to build the image.
2112 - If you're working from git sources, just clone the metadata
2113 and BSP layers needed to build the image you'll be booting.
2114 - Make sure you're properly set up to build a new image (see
2115 the BSP README and/or the widely available basic documentation
2116 that discusses how to build images).
2117 - Build an -sdk version of the image e.g.:
2118 $ bitbake core-image-sato-sdk
2119 OR
2120 - Build a non-sdk image but include the profiling tools:
2121 [ edit local.conf and add 'tools-profile' to the end of
2122 the EXTRA_IMAGE_FEATURES variable ]
2123 $ bitbake core-image-sato
2124
2125 [ NOTE that 'crosstap' needs to be able to ssh into the target
2126 system, which isn't enabled by default in -minimal images. ]
2127
2128 Once you've build the image on the host system, you're ready to
2129 boot it (or the equivalent pre-built image) and use 'crosstap'
2130 to probe it (you need to source the environment as usual first):
2131
2132 $ source oe-init-build-env
2133 $ cd ~/my/systemtap/scripts
2134 $ crosstap root@192.168.1.xxx myscript.stp
2135 </literallayout>
2136 So essentially what you need to do is build an SDK image or
2137 image with 'tools-profile' as detailed in the
2138 "<link linkend='profile-manual-general-setup'>General Setup</link>"
2139 section of this manual, and boot the resulting target image.
2140 </para>
2141
2142 <note>
2143 If you have a build directory containing multiple machines,
2144 you need to have the MACHINE you're connecting to selected
2145 in local.conf, and the kernel in that machine's build
2146 directory must match the kernel on the booted system exactly,
2147 or you'll get the above 'crosstap' message when you try to
2148 invoke a script.
2149 </note>
2150 </section>
2151
2152 <section id='running-a-script-on-a-target'>
2153 <title>Running a Script on a Target</title>
2154
2155 <para>
2156 Once you've done that, you should be able to run a systemtap
2157 script on the target:
2158 <literallayout class='monospaced'>
2159 $ cd /path/to/yocto
2160 $ source oe-init-build-env
2161
2162 ### Shell environment set up for builds. ###
2163
2164 You can now run 'bitbake &lt;target&gt;'
2165
2166 Common targets are:
2167 core-image-minimal
2168 core-image-sato
2169 meta-toolchain
2170 meta-toolchain-sdk
2171 adt-installer
2172 meta-ide-support
2173
2174 You can also run generated qemu images with a command like 'runqemu qemux86'
2175 </literallayout>
2176 Once you've done that, you can cd to whatever directory
2177 contains your scripts and use 'crosstap' to run the script:
2178 <literallayout class='monospaced'>
2179 $ cd /path/to/my/systemap/script
2180 $ crosstap root@192.168.7.2 trace_open.stp
2181 </literallayout>
2182 If you get an error connecting to the target e.g.:
2183 <literallayout class='monospaced'>
2184 $ crosstap root@192.168.7.2 trace_open.stp
2185 error establishing ssh connection on remote 'root@192.168.7.2'
2186 </literallayout>
2187 Try ssh'ing to the target and see what happens:
2188 <literallayout class='monospaced'>
2189 $ ssh root@192.168.7.2
2190 </literallayout>
2191 A lot of the time, connection problems are due specifying a
2192 wrong IP address or having a 'host key verification error'.
2193 </para>
2194
2195 <para>
2196 If everything worked as planned, you should see something
2197 like this (enter the password when prompted, or press enter
2198 if its set up to use no password):
2199 <literallayout class='monospaced'>
2200 $ crosstap root@192.168.7.2 trace_open.stp
2201 root@192.168.7.2's password:
2202 matchbox-termin(1036) open ("/tmp/vte3FS2LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
2203 matchbox-termin(1036) open ("/tmp/vteJMC7LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
2204 </literallayout>
2205 </para>
2206 </section>
2207
2208 <section id='systemtap-documentation'>
2209 <title>Documentation</title>
2210
2211 <para>
2212 The SystemTap language reference can be found here:
2213 <ulink url='http://sourceware.org/systemtap/langref/'>SystemTap Language Reference</ulink>
2214 </para>
2215
2216 <para>
2217 Links to other SystemTap documents, tutorials, and examples can be
2218 found here:
2219 <ulink url='http://sourceware.org/systemtap/documentation.html'>SystemTap documentation page</ulink>
2220 </para>
2221 </section>
2222</section>
2223
2007</chapter> 2224</chapter>
2008<!-- 2225<!--
2009vim: expandtab tw=80 ts=4 2226vim: expandtab tw=80 ts=4