diff options
Diffstat (limited to 'runtime/docs/html/README-source.html')
| -rw-r--r-- | runtime/docs/html/README-source.html | 169 |
1 files changed, 112 insertions, 57 deletions
diff --git a/runtime/docs/html/README-source.html b/runtime/docs/html/README-source.html index 1b03993d..1421d7e2 100644 --- a/runtime/docs/html/README-source.html +++ b/runtime/docs/html/README-source.html @@ -4,61 +4,116 @@ <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="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>README</h1><div class="fragment"><pre class="fragment">00001 <span class="comment">/** @mainpage SystemTap Runtime Library</span> -00002 <span class="comment"> *</span> -00003 <span class="comment"> * @section intro_sec Introduction</span> -00004 <span class="comment"> *</span> -00005 <span class="comment"> * The SystemTap Runtime Library consists of all functions</span> -00006 <span class="comment"> * and code fragments needed by the compiler/translator to</span> -00007 <span class="comment"> * include in building a kernel module using kprobes.</span> -00008 <span class="comment"> *</span> -00009 <span class="comment"> * @section design_sec Design</span> -00010 <span class="comment"> * @subsection impl_sec Implementation</span> -00011 <span class="comment"> * The library is written in \c C and is really not a library but a collection of code</span> -00012 <span class="comment"> * That can be conditionally included in a modules. It will probably become a library later.</span> -00013 <span class="comment"> *</span> -00014 <span class="comment"> * @subsection map_sec Maps (Associative Arrays)</span> -00015 <span class="comment"> * Maps are implemented as hash lists. It is not expected that users will</span> -00016 <span class="comment"> * attempt to collect so much data in kernel space that performance problems will require</span> -00017 <span class="comment"> * more complex solutions such as AVL trees.</span> -00018 <span class="comment"> *</span> -00019 <span class="comment"> * Maps are created with _stp_map_new(). Each map can hold only one type of </span> -00020 <span class="comment"> * data; int64, string, or statistics. Each element belonging to a map can have up to 2 keys</span> -00021 <span class="comment"> * and a value. Implemented key types are strings and longs.</span> -00022 <span class="comment"> * </span> -00023 <span class="comment"> * To simplify the implementation, the functions to set the key and the functions to set the data are separated.</span> -00024 <span class="comment"> * That means we need only 4 functions to set the key and 3 functions to set the value. </span> -00025 <span class="comment"> *</span> -00026 <span class="comment"> * For example:</span> -00027 <span class="comment"> * @include map.c</span> -00028 <span class="comment"></span> -00029 <span class="comment"> * All elements have a default value of 0 (or NULL). Elements are only saved to the map when their value is set</span> -00030 <span class="comment"> * to something nonzero. This means that querying for the existance of a key is inexpensive because</span> -00031 <span class="comment"> * no element is created, just a hash table lookup.</span> -00032 <span class="comment"> *</span> -00033 <span class="comment"> * @subsection list_sec Lists</span> -00034 <span class="comment"> * A list is a special map which has internally ascending long integer keys. Adding a value to</span> -00035 <span class="comment"> * a list does not require setting a key first. Create a list with _stp_list_new(). Add to it</span> -00036 <span class="comment"> * with _stp_list_add_str() and _stp_list_add_int64(). Clear it with _stp_list_clear().</span> -00037 <span class="comment"> *</span> -00038 <span class="comment"> * @section status_sec Status</span> -00039 <span class="comment"> * @li Maps are implemented and tested. Histograms are not yet finished.</span> -00040 <span class="comment"> * @li Copy_From_User functions are done.</span> -00041 <span class="comment"> * @li If maps overflow or memory runs out for some reason, globals are set but nothing is done yet.</span> -00042 <span class="comment"> * I expect to implement a function to tell the system to either ignore it or unload the module and quit.</span> -00043 <span class="comment"> * @li Locking and per-cpu data are not yet implemented to be SMP-safe. This is not yet necessary because the</span> -00044 <span class="comment"> * current kprobes implementation single-threads probes for us. </span> -00045 <span class="comment"> *</span> -00046 <span class="comment"> * @section probe_sec Example Probes</span> -00047 <span class="comment"> * </span> -00048 <span class="comment"> * Working sample probe code using the runtime is in runtime/probes.</span> -00049 <span class="comment"> * <a href="dir_000000.html"> Browse probes.</a></span> -00050 <span class="comment"> * </span> -00051 <span class="comment"> * @section todo_sec ToDo </span> -00052 <span class="comment"> * \link todo Click Here for Complete List \endlink</span> -00053 <span class="comment"> *</span> -00054 <span class="comment"> * @section links Links</span> -00055 <span class="comment"> * <a href="http://sources.redhat.com/systemtap/">SystemTap Project Page</a></span> -00056 <span class="comment"> */</span> +<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> |