diff options
Diffstat (limited to 'runtime/docs/html/README-source.html')
-rw-r--r-- | runtime/docs/html/README-source.html | 119 |
1 files changed, 0 insertions, 119 deletions
diff --git a/runtime/docs/html/README-source.html b/runtime/docs/html/README-source.html deleted file mode 100644 index 1421d7e2..00000000 --- a/runtime/docs/html/README-source.html +++ /dev/null @@ -1,119 +0,0 @@ -<!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: README Source File</title> -<link href="doxygen.css" rel="stylesheet" type="text/css"> -</head><body> -<!-- Generated by Doxygen 1.4.1 --> -<div class="qindex"><a class="qindex" 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>README</h1><div class="fragment"><pre class="fragment">00001 <span class="comment">/** @mainpage SystemTap Runtime</span> -00002 <span class="comment"></span> -00003 <span class="comment">@section intro_sec Introduction</span> -00004 <span class="comment"></span> -00005 <span class="comment">This document describes the implementation of the SystemTap Runtime. It is intended for developers</span> -00006 <span class="comment">of the SystemTap Language translator or, possibly TapSet authors. These functions are not directly</span> -00007 <span class="comment">available from the SystemTap Language.</span> -00008 <span class="comment"></span> -00009 <span class="comment">The SystemTap Runtime Library consists of all functions</span> -00010 <span class="comment">and code fragments needed by the compiler/translator to</span> -00011 <span class="comment">include in building a kernel module using kprobes. It</span> -00012 <span class="comment">also include I/O code to transmit its output from the kernel to userspace.</span> -00013 <span class="comment"> </span> -00014 <span class="comment">In addition to the library, the runtime includes a SystemTap user-space daemon</span> -00015 <span class="comment">(stpd). Stpd grabs data sent from the I/O code in the runtime and displays it</span> -00016 <span class="comment">and/or saves it to files. Stpd (or a script invoking it) will handle other issues like</span> -00017 <span class="comment">inserting and removing modules.</span> -00018 <span class="comment"></span> -00019 <span class="comment">Stpd and the I/O code make use of both relayfs and netlink for communication. For</span> -00020 <span class="comment">kernels without relayfs builtin, it is provided as a standalone module under the runtime directory.</span> -00021 <span class="comment"></span> -00022 <span class="comment">@section design_sec Design</span> -00023 <span class="comment">@subsection impl_sec Implementation</span> -00024 <span class="comment">The library is written in C and is really not a library but a collection of code</span> -00025 <span class="comment">That can be conditionally included in a modules. It may become a library later, but for now</span> -00026 <span class="comment">there are some advantages to being able to change the sizes of static items with simple #defines.</span> -00027 <span class="comment"></span> -00028 <span class="comment">@subsection map_sec Maps (Associative Arrays)</span> -00029 <span class="comment">Maps are implemented as hash lists. It is not expected that users will</span> -00030 <span class="comment">attempt to collect so much data in kernel space that performance problems will require</span> -00031 <span class="comment">more complex solutions such as AVL trees.</span> -00032 <span class="comment"></span> -00033 <span class="comment">Maps are created with _stp_map_new(). Each map can hold only one type of </span> -00034 <span class="comment">data; int64, string, or statistics. Each element belonging to a map can have up to 2 keys</span> -00035 <span class="comment">and a value. Implemented key types are strings and longs.</span> -00036 <span class="comment"> </span> -00037 <span class="comment">To simplify the implementation, the functions to set the key and the functions to set the data are separated.</span> -00038 <span class="comment">That means we need only 4 functions to set the key and 3 functions to set the value. </span> -00039 <span class="comment"></span> -00040 <span class="comment">For example:</span> -00041 <span class="comment">\code</span> -00042 <span class="comment">/* create a map with a max of 100 elements */</span> -00043 <a class="code" href="group__maps.html#ga1">MAP</a> mymap = map_new(100, INT64); -00044 -00045 <span class="comment">/* mymap[birth year] = 2000 */</span> -00046 map_key_str (mymap, <span class="stringliteral">"birth year"</span>); -00047 map_set_int64 (mymap, 2000); -00048 \endcode -00049 -00050 All elements have a <span class="keywordflow">default</span> value of 0 (or NULL). Elements are only saved to the map when their value is set -00051 to something nonzero. This means that querying <span class="keywordflow">for</span> the existance of a key is inexpensive because -00052 no element is created, just a hash table lookup. -00053 -00054 @subsection list_sec Lists -00055 A list is a special map which has internally ascending <span class="keywordtype">long</span> integer keys. Adding a value to -00056 a list does not require setting a key first. Create a list with <a class="code" href="group__lists.html#ga0">_stp_list_new</a>(). Add to it -00057 with <a class="code" href="group__lists.html#ga2">_stp_list_add_str</a>() and _stp_list_add_int64(). Clear it with _stp_list_clear(). -00058 -00059 @subsection string_sec Strings -00060 One of the biggest restrictions the library has is that it cannot allocate things like strings off the stack. -00061 It is also not a good idea to dynamically allocate space for strings with kmalloc(). That leaves us with -00062 statically allocated space for strings. This is what is implemented in the String module. Strings use -00063 preallocated per-cpu buffers and are safe to use (unlike C strings). -00064 -00065 @subsection io_sec I/O -00066 Generally things are written to a "print buffer" using the internal -00067 functions _stp_print_xxx(). -00068 \code -00069 _stp_print ("Output is: "); -00070 _stp_printf ("pid is %d ", current->pid); -00071 _stp_printf ("name is %s", current->comm); -00072 \endcode -00073 before the probe returns it must call _stp_print_flush(). This -00074 timestamps the accumulated print buffer and sends it to relayfs. -00075 When relayfs fills an internal buffer, the user-space daemon is notified -00076 data is ready and reads a bug per-cpu chunk, which contains a line like: -00077 \verbatim -00078 [123456.000002] Output is: pid is 1234 name is bash -00079 \endverbatim -00080 -00081 The user-daemon (stpd) saves this data to a file named something like -00082 "stpd_cpu2". When the user hits ^c, a timer expires, or the probe -00083 module notifies stpd (through a netlink command channel) that it wants -00084 to terminate, stpd does "system(rmmod)" then collects the last output -00085 before exiting. -00086 As an option, if we don't need bulk per-cpu data, we can put -00087 \code -00088 #define STP_NETLINK_ONLY -00089 \endcode -00090 at the top of the module and all output will go over a netlink channel. -00091 In the SystemTap language, we will provide some simple functions to control the buffering policy, which -00092 will control the use of netlink and parameters to relayfs and stpd. -00093 -00094 @section status_sec Status -00095 @li Maps are implemented and tested. Histograms are not yet finished. -00096 @li Copy_From_User functions are done. -00097 @li If maps overflow or memory runs out for some reason, globals are set but nothing is done yet. -00098 I expect to implement a function to tell the system to either ignore it or unload the module and quit. -00099 @li Stack functions need much improvement. -00100 -00101 @section probe_sec Example Probes -00102 -00103 Working sample probe code using the runtime is in runtime/probes. -00104 <a href="dir_000000.html"> Browse probes.</a> -00105 -00106 @section todo_sec ToDo -00107 \link todo Click Here for Complete List \endlink -00108 -00109 @section links Links -00110 <a href="http:<span class="comment">//sources.redhat.com/systemtap/">SystemTap Project Page</a></span> -00111 */ -</pre></div></body></html> |