diff options
Diffstat (limited to 'runtime/README')
| -rw-r--r-- | runtime/README | 93 |
1 files changed, 62 insertions, 31 deletions
diff --git a/runtime/README b/runtime/README index e0e32a37..aecb3282 100644 --- a/runtime/README +++ b/runtime/README @@ -3,8 +3,8 @@ @section intro_sec Introduction This document describes the implementation of the SystemTap Runtime. It is intended for developers -of the SystemTap Language translator or, possibly TapSet authors. These functions are not directly -available from the SystemTap Language. +of the SystemTap Language translator, TapSet authors or kprobes programmers. +These functions are not directly available from the SystemTap Language. The SystemTap Runtime Library consists of all functions and code fragments needed by the compiler/translator to @@ -13,7 +13,7 @@ also include I/O code to transmit its output from the kernel to userspace. In addition to the library, the runtime includes a SystemTap user-space daemon (stpd). Stpd grabs data sent from the I/O code in the runtime and displays it -and/or saves it to files. Stpd (or a script invoking it) will handle other issues like +and/or saves it to files. Stpd will handle other issues like inserting and removing modules. Stpd and the I/O code make use of both relayfs and netlink for communication. For @@ -22,41 +22,58 @@ kernels without relayfs builtin, it is provided as a standalone module under the @section design_sec Design @subsection impl_sec Implementation The library is written in C and is really not a library but a collection of code -That can be conditionally included in a modules. It may become a library later, but for now -there are some advantages to being able to change the sizes of static items with simple #defines. +that can be conditionally included in a modules. This allows for a high degree of +customization and efficiency. @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. +Maps are implemented as hash lists. In order to efficiently handle maps with up to five keys of any combination +of int64s and strings, the functions to create maps, set keys, and set and get values +are all generated as needed. To do this, you must simply do some defines and +include the proper files. For example, if you need a map with 3 keys, int64, int64, and string +that stores strings, you need to do +@code +#define KEY1_TYPE INT64 +#define KEY2_TYPE INT64 +#define KEY3_TYPE STRING +#include "map-keys.c" + +#define VALUE_TYPE STRING +#include "map-values.c" + +#include "map.c" +@endcode + +In the above example, maps are created with _stp_map_new_int64_int64_str(). All the +generated functions start with a base name (such as _stp_map_new) and add the key types separated +by underscores. + +Each map can hold only one type of data; int64, string, or statistics. Each element belonging to a map can have up to +5 keys and a value. Implemented key types are strings and int64. 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: -\code -/* create a map with a max of 100 elements */ -MAP mymap = map_new(100, INT64); +The map remembers what the current key is. +For example, to continue our previous example, +@code +/* create a map with a max of 100 elements containing strings */ +MAP mymap = _stp_map_new_int64_int64_str(100, STRING); -/* mymap[birth year] = 2000 */ -map_key_str (mymap, "birth year"); -map_set_int64 (mymap, 2000); -\endcode +/* mymap[100, 300, "Ohio"] = "Columbus" */ +_stp_map_key_int64_int64_str (mymap, 100, 300, "Ohio"); +_stp_map_set_str (mymap, "Columbus"); +@endcode 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. +to something nonzero. + +For good examples, see the runtime/tests/maps directory or the example probes. @subsection list_sec Lists -A list is a special map which has internally ascending long integer keys. Adding a value to +A list is a special map which has internally ascending int64 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(). @subsection string_sec Strings + One of the biggest restrictions the library has is that it cannot allocate things like strings off the stack. It is also not a good idea to dynamically allocate space for strings with kmalloc(). That leaves us with statically allocated space for strings. This is what is implemented in the String module. Strings use @@ -91,12 +108,26 @@ at the top of the module and all output will go over a netlink channel. In the SystemTap language, we will provide some simple functions to control the buffering policy, which will control the use of netlink and parameters to relayfs and stpd. -@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 Stack functions need much improvement. + +@section started Getting Started +@verbatim +>cd stp/src/runtime +>cd stpd +> make +>cd ../relayfs +> make +> cd ../transport +make +> cd ../probes/shellsnoop +> make +> su +> ./stp shellsnoop.ko +@endverbatim + +When building the example probes, ignore the warnings about relayfs and +_stp_ctrl_xxx functions undefined. These are in other modules. + +Hit ^C to exit from a probe. @section probe_sec Example Probes |