Merge branch 'master' of ssh://sources.redhat.com/git/systemtap

* 'master' of ssh://sources.redhat.com/git/systemtap:
  Made kernel 2.6.25 changes in task_finder.c.
  Move examples to testsuite/systemtap.examples

1 files changed, 102 insertions, 0 deletions

diff --git a/testsuite/systemtap.examples/small_demos/demo_script.txt b/testsuite/systemtap.examples/small_demos/demo_script.txt
new file mode 100644
index 00000000..f3166a49
--- /dev/null
+++ b/testsuite/systemtap.examples/small_demos/demo_script.txt
@@ -0,0 +1,102 @@
+> cd /root/systemtap
+
+A systemtap script can be as simple as a single line. For example,
+the following script places a probepoint on the kernel sys_read()
+function and prints all callers with the function's arguments.
+
+>stap -e 'probe syscall.open {printf("%s: %s\n", execname(), argstr)}'
+
+Most scripts are a bit longer. (show top.stp)
+This script sets a probepoint on all kernel functions beginning with "sys_".
+When the probepoint is hit, it increments an entry in the map 
+(or associative array) "syscalls" with the key "probefunc()" which returns
+the name of the function that was triggered. For example, "sys_read".
+
+There is a timer that is triggered every 5000ms or 5 seconds. That timer
+calls the function print_top(). print_top() sorts the syscalls map
+and prints the top 20 entries. Then it clears the map.
+
+> ./top.stp
+
+(after stopping "top" go ahead and enter "./sys.stp". It takes a minute
+to load this script. Diplay the source in another window and talk 
+while it is loading.)
+
+The "top" script looked only at the functions called. If we want more 
+detail about the functions, we can use systemtap to examine their local 
+arguments and variables. However that would be difficult because each 
+system call has different parameters. The Syscall Tapset solves
+this problem. To use it, we set probe points using the syntax "syscall.name"
+instead of kernel.function("sys_name"). The Syscall Tapset provides three
+defined variables we can use:
+name - the name of the function
+argstr - on function entry, a formatted string containing the arguments
+retstr - on function exit, the return value and possibly error code
+
+In this example, we filter out programs named "staprun" because this is 
+part of the systemtap infrastructure. (It may be filtered out
+automatically in the future.)
+
+The next example shows how you can use systemtap to focus on
+specific programs or pids. (show prof.stp)
+
+Like the "top" example, this script places probes on all kernel
+functions starting with "sys_". Only the probepoint also checks to see
+if the tid/pid matches the one returned by "target()". We'll show how
+the target pid is set later.
+
+Unlike the previous examples, this script sets a probe point on all the 
+system call returns. When triggered, this probepoint computes the elapsed
+time since the function entry. 
+
+To run this script, we must give it a pid to use for the target, or a
+program to run, in which case target will be its pid.
+
+>  ./prof.stp -c "top -n5"
+
+--------------------------------
+
+Systemtap can also run in an unsafe mode where you can give
+it arbitrary C code to run at probepoints, or modify kernel variables
+and structures. This is very dangerous so only experts with root access will
+ever be permitted to do this.
+
+(show keyhack.stp)
+
+The next example will modify the local variable "keycode" in the "kdb_keycode"
+function in the kernel driver. We indicate it is a local variable by putting
+a dollar sign before the name.
+
+./keyhack.stp
+
+(prints error message)
+
+To tell systemtap we really want to run this script, we must use the "-g" flag.
+
+./keyhack.stp -g
+
+(type some keys. "m" should display as "b" in every window) 
+
+This example is not something you would normally want to do. There are 
+far better ways to remap a keyboard. What it demonstartes is that Systemtap 
+can modify variables in a running kernel.
+
+(show kmalloc.stp)
+This next script shows the kind of statistics systemtap can collect.
+It collects information about kernel allocations.
+
+> ./kmalloc.stp
+
+Now we can refine this further
+(show kmalloc2.stp)
+
+Remember in some previous examples, we used maps or associative arrays. Maps can contain
+statistics too.  So we have enhanced the previous script to collect statistics per
+program name.  The output might be large so we'll redirect it to a file.
+
+> ./kmalloc2.stp > out
+
+(runs for 10 seconds)
+
+> more out
+