SystemTap: SystemTap Runtime Library

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

README
