2005-06-18 Martin Hunt <hunt@redhat.com>

	* counter.c: New file. Counter aggregations.

	* stat.c: New file. Stat aggregations.

	* stat.h: Header file for stats.

	* map-int.c: New file. Support for int64 values.

	* map-stat.c: New file. Support for stat values.

	* map-str.c: New file. Support for string values.

	* map-values.c: Now just includes the necessary map-*.c files.

	* stat-common.c: New file. Stats stuff common to Stats and maps
	containing stats.

	* Doxyfile: Bumped version to 0.6.

	* README: Renamed README.doc and reorganized.

1 files changed, 5 insertions, 138 deletions

diff --git a/runtime/README b/runtime/README
index aecb3282..470cad16 100644
--- a/runtime/README
+++ b/runtime/README
@@ -1,142 +1,9 @@
-/** @mainpage SystemTap Runtime
-
-@section intro_sec Introduction
-
-This document describes the implementation of the SystemTap Runtime. It is intended for developers
-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
-include in building a kernel module using kprobes. It
-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 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
-kernels without relayfs builtin, it is provided as a standalone module under the runtime directory.
-
-@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. This allows for a high degree of 
-customization and efficiency.  
-
-@subsection map_sec Maps (Associative Arrays)
-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.
-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[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.  
-
-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 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
-preallocated per-cpu buffers and are safe to use (unlike C strings).
-
-@subsection io_sec I/O
-Generally things are written to a "print buffer" using the internal
-functions _stp_print_xxx().
-\code
-_stp_print ("Output is: ");
-_stp_printf ("pid is %d ", current->pid);
-_stp_printf ("name is %s", current->comm);
-\endcode
-before the probe returns it must call _stp_print_flush().  This
-timestamps the accumulated print buffer and sends it to relayfs.
-When relayfs fills an internal buffer, the user-space daemon is notified
-data is ready and reads a bug per-cpu chunk, which contains a line like:
-\verbatim
-[123456.000002] Output is: pid is 1234 name is bash
-\endverbatim
-
-The user-daemon (stpd) saves this data to a file named something like
-"stpd_cpu2".  When the user hits ^c, a timer expires, or the probe
-module notifies stpd (through a netlink command channel) that it wants
-to terminate, stpd does "system(rmmod)" then collects the last output
-before exiting.
-As an option, if we don't need bulk per-cpu data, we can put
-\code
-#define STP_NETLINK_ONLY
-\endcode
-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 started Getting Started
-@verbatim
->cd stp/src/runtime
->cd stpd
-> make
->cd ../relayfs
-> make
-> cd ../transport
-make
-> cd ../probes/shellsnoop
+To build everything (relayfs, transport, stpd, and example probes):
 > 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
 
-Working sample probe code using the runtime is in runtime/probes.
-<a href="dir_000000.html"> Browse probes.</a>
+To clean up:
+> make clean
 
-@section todo_sec ToDo 
-\link todo Click Here for Complete List \endlink
+To build docs
+> doxygen Doxyfile
 
-@section links Links
-<a href="http://sources.redhat.com/systemtap/">SystemTap Project Page</a>
- */