1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<!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>
|
