README

/** @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>
 */