diff options
Diffstat (limited to 'runtime/docs/html/index.html')
| -rw-r--r-- | runtime/docs/html/index.html | 37 |
1 files changed, 25 insertions, 12 deletions
diff --git a/runtime/docs/html/index.html b/runtime/docs/html/index.html index 86c7e175..e51162e4 100644 --- a/runtime/docs/html/index.html +++ b/runtime/docs/html/index.html @@ -1,40 +1,53 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> -<title>SystemTap: SystemTap Runtime Library</title> +<title>SystemTap: SystemTap Runtime</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.4.1 --> -<div class="qindex"><a class="qindexHL" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="annotated.html">Data Structures</a> | <a class="qindex" href="dirs.html">Directories</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Data Fields</a> | <a class="qindex" href="globals.html">Globals</a> | <a class="qindex" href="pages.html">Related Pages</a></div> -<h1>SystemTap Runtime Library </h1> +<div class="qindex"><a class="qindexHL" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="dirs.html">Directories</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="globals.html">Globals</a> | <a class="qindex" href="pages.html">Related Pages</a></div> +<h1>SystemTap Runtime </h1> <p> -<h3 align="center">0.1 </h3><h2><a class="anchor" name="intro_sec"> +<h3 align="center">0.2 </h3><h2><a class="anchor" name="intro_sec"> Introduction</a></h2> -The SystemTap Runtime Library consists of all functions and code fragments needed by the compiler/translator to include in building a kernel module using kprobes.<h2><a class="anchor" name="design_sec"> +This document describes the implementation of the SystemTap Runtime. It is intended for developers of the SystemTap Language translator or, possibly TapSet authors. These functions are not directly available from the SystemTap Language.<p> +The SystemTap Runtime Library consists of all functions and code fragments needed by the compiler/translator to include in building a kernel module using kprobes. It also include I/O code to transmit its output from the kernel to userspace.<p> +In addition to the library, the runtime includes a SystemTap user-space daemon (stpd). Stpd grabs data sent from the I/O code in the runtime and displays it and/or saves it to files. Stpd (or a script invoking it) will handle other issues like inserting and removing modules.<p> +Stpd and the I/O code make use of both relayfs and netlink for communication. For kernels without relayfs builtin, it is provided as a standalone module under the runtime directory.<h2><a class="anchor" name="design_sec"> Design</a></h2> <h3><a class="anchor" name="impl_sec"> Implementation</a></h3> -The library is written in <code>C</code> and is really not a library but a collection of code That can be conditionally included in a modules. It will probably become a library later.<h3><a class="anchor" name="map_sec"> +The library is written in C and is really not a library but a collection of code That can be conditionally included in a modules. It may become a library later, but for now there are some advantages to being able to change the sizes of static items with simple #defines.<h3><a class="anchor" name="map_sec"> Maps (Associative Arrays)</a></h3> Maps are implemented as hash lists. It is not expected that users will attempt to collect so much data in kernel space that performance problems will require more complex solutions such as AVL trees.<p> Maps are created with <a class="el" href="group__maps.html#ga2">_stp_map_new()</a>. Each map can hold only one type of data; int64, string, or statistics. Each element belonging to a map can have up to 2 keys and a value. Implemented key types are strings and longs.<p> To simplify the implementation, the functions to set the key and the functions to set the data are separated. That means we need only 4 functions to set the key and 3 functions to set the value.<p> -For example: <div class="fragment"><pre class="fragment"> -<span class="comment">/* create a map with a max of 100 elements */</span> -<a class="code" href="structmap__root.html">MAP</a> mymap = map_new(100, INT64); +For example: <div class="fragment"><pre class="fragment"><span class="comment">/* create a map with a max of 100 elements */</span> +<a class="code" href="group__maps.html#ga1">MAP</a> mymap = map_new(100, INT64); <span class="comment">/* mymap[birth year] = 2000 */</span> map_key_str (mymap, <span class="stringliteral">"birth year"</span>); -map_set_int64 (mymap, 2000); +map_set_int64 (mymap, 2000); </pre></div><p> All elements have a default value of 0 (or NULL). Elements are only saved to the map when their value is set to something nonzero. This means that querying for the existance of a key is inexpensive because no element is created, just a hash table lookup.<h3><a class="anchor" name="list_sec"> Lists</a></h3> -A list is a special map which has internally ascending long integer keys. Adding a value to a list does not require setting a key first. Create a list with <a class="el" href="group__lists.html#ga0">_stp_list_new()</a>. Add to it with <a class="el" href="group__lists.html#ga2">_stp_list_add_str()</a> and <a class="el" href="group__lists.html#ga3">_stp_list_add_int64()</a>. Clear it with <a class="el" href="group__lists.html#ga1">_stp_list_clear()</a>.<h2><a class="anchor" name="status_sec"> +A list is a special map which has internally ascending long integer keys. Adding a value to a list does not require setting a key first. Create a list with <a class="el" href="group__lists.html#ga0">_stp_list_new()</a>. Add to it with <a class="el" href="group__lists.html#ga2">_stp_list_add_str()</a> and <a class="el" href="group__lists.html#ga4">_stp_list_add_int64()</a>. Clear it with <a class="el" href="group__lists.html#ga1">_stp_list_clear()</a>.<h3><a class="anchor" name="string_sec"> +Strings</a></h3> +One of the biggest restrictions the library has is that it cannot allocate things like strings off the stack. It is also not a good idea to dynamically allocate space for strings with kmalloc(). That leaves us with statically allocated space for strings. This is what is implemented in the String module. Strings use preallocated per-cpu buffers and are safe to use (unlike C strings).<h3><a class="anchor" name="io_sec"> +I/O</a></h3> +Generally things are written to a "print buffer" using the internal functions _stp_print_xxx(). <div class="fragment"><pre class="fragment"><a class="code" href="group__print.html#ga11">_stp_print</a> (<span class="stringliteral">"Output is: "</span>); +<a class="code" href="group__print.html#ga3">_stp_printf</a> (<span class="stringliteral">"pid is %d "</span>, current->pid); +<a class="code" href="group__print.html#ga3">_stp_printf</a> (<span class="stringliteral">"name is %s"</span>, current->comm); +</pre></div> before the probe returns it must call <a class="el" href="group__print.html#ga2">_stp_print_flush()</a>. This timestamps the accumulated print buffer and sends it to relayfs. When relayfs fills an internal buffer, the user-space daemon is notified data is ready and reads a bug per-cpu chunk, which contains a line like: <div class="fragment"><pre class="fragment"> +[123456.000002] Output is: pid is 1234 name is bash +</pre></div><p> +The user-daemon (stpd) saves this data to a file named something like "stpd_cpu2". When the user hits ^c, a timer expires, or the probe module notifies stpd (through a netlink command channel) that it wants to terminate, stpd does "system(rmmod)" then collects the last output before exiting. As an option, if we don't need bulk per-cpu data, we can put <div class="fragment"><pre class="fragment"><span class="preprocessor">#define STP_NETLINK_ONLY</span> +</pre></div> at the top of the module and all output will go over a netlink channel. In the SystemTap language, we will provide some simple functions to control the buffering policy, which will control the use of netlink and parameters to relayfs and stpd.<h2><a class="anchor" name="status_sec"> Status</a></h2> <ul> <li>Maps are implemented and tested. Histograms are not yet finished. </li> <li>Copy_From_User functions are done. </li> <li>If maps overflow or memory runs out for some reason, globals are set but nothing is done yet. I expect to implement a function to tell the system to either ignore it or unload the module and quit. </li> -<li>Locking and per-cpu data are not yet implemented to be SMP-safe. This is not yet necessary because the current kprobes implementation single-threads probes for us.</li> +<li>Stack functions need much improvement.</li> </ul> <h2><a class="anchor" name="probe_sec"> Example Probes</a></h2> |