blob: cf38f8821165740e7f69b5da016a34acf1da2887 (
plain)
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
|
/** @mainpage SystemTap Runtime Library
*
* @section intro_sec Introduction
*
* 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.
*
* @section design_sec Design
* @subsection impl_sec Implementation
* The library is written in \c C 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.
*
* @subsection map_sec Maps (Associative Arrays)
* 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.
*
* Maps are created with _stp_map_new(). 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.
*
* 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.
*
* For example:
* @include map.c
* 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.
*
* @subsection list_sec Lists
* 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 _stp_list_new(). Add to it
* with _stp_list_add_str() and _stp_list_add_int64(). Clear it with _stp_list_clear().
*
* @section status_sec Status
* @li Maps are implemented and tested. Histograms are not yet finished.
* @li Copy_From_User functions are done.
* @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 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.
*
* @section probe_sec Example Probes
*
* Working sample probe code using the runtime is in runtime/probes.
* <a href="dir_000000.html"> Browse probes.</a>
*
* @section todo_sec ToDo
* \link todo Click Here for Complete List \endlink
*
* @section links Links
* <a href="http://sources.redhat.com/systemtap/">SystemTap Project Page</a>
*/
|
