runtime/docs/html/index.html


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

<!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>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<div class="qindex"><a class="qindex" href="index.html">Intro</a> | <a class="qindex" href="globals_func.html">Functions</a> | <a class="qindex" href="globals_defs.html">Defines</a> | <a class="qindex" href="globals_enum.html">Enumerations</a> | <a class="qindex" href="globals_eval.html">Enumeration Values</a></div>

<!-- Generated by Doxygen 1.4.1 -->
<h1>SystemTap Runtime Library </h1>
<p>
<h3 align="center">0.1 </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">
Design</a></h2>
<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="map_8c.html#a3">_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);

<span class="comment">/* mymap[birth year] = 2000 */</span>
map_key_str (mymap, <span class="stringliteral">"birth year"</span>);
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.<p>
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. See <a class="el" href="map_8c.html#a27">_stp_list_add_str()</a> and <a class="el" href="map_8c.html#a28">_stp_list_add_int64()</a>.<h2><a class="anchor" name="status_sec">
Status</a></h2>
Maps are implemented and tested. Histograms are not yet finished.<p>
Copy_From_User functions are done.<p>
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.<h2><a class="anchor" name="probe_sec">
Example Probes</a></h2>
Working sample probe code using the runtime is in runtime/probes.<h2><a class="anchor" name="todo_sec">
ToDo</a></h2>
<a class="el" href="todo.html">Click Here for Complete List </a> The Runtime Library is not actually a library yet. It is just a collection of functions included in the probe boilerplate. Maybe it should stay that way to allow the translator more flexibility in what is included. <hr size="1"><address style="align: right;"><small>Generated on Mon Mar 21 13:29:45 2005 for SystemTap by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.1 </small></address>
</body>
</html>