PR909: baby documentation for perf.* probes

4 files changed, 91 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index e10d5226..27c2a5a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,7 +10,6 @@ config.h
 config.log
 config.status
 *.[18]
-*.3stap
 .deps
 loc2c-test
 run-stap
diff --git a/NEWS b/NEWS
index 4c3cf751..64905f1c 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,11 @@
 * What's new
 
+- Prototype support for "perf events", where the kernel supports the
+  2.6.33 in-kernel API.  Probe points may refer to low-level 
+  perf_event_attr type/config numbers, or to a number of aliases
+  defined in the new perf.stp tapset:
+     probe perf.sw.cpu_clock, perf.type(0).config(4) { }
+
 - Type-casting can now use multiple headers to resolve codependencies.
      @cast(task, "task_struct",
            "kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask
diff --git a/man/tapset::perf.3stap b/man/tapset::perf.3stap
new file mode 100644
index 00000000..5aff9799
--- /dev/null
+++ b/man/tapset::perf.3stap
@@ -0,0 +1,58 @@
+.\" -*- nroff -*-
+.TH TAPSET::PERF 3stap "" "IBM"
+.SH NAME
+tapset::perf \- systemtap perf probe points
+
+.\" macros
+.de SAMPLE
+.br
+.RS
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+..
+
+.SH DESCRIPTION
+
+This family of probe points is used to probe "perf events"
+on suitably configured kernels (2.6.33+).  It contains a
+number of aliases for the ABI-specified event type/config
+tuples.
+
+.TP
+.B perf.hw.*
+A variety of hardware events, as generalized by the kernel.  These
+generally require running on bare hardware with selected processors.
+.SAMPLE
+probe perf.hw.cpu_cycles
+probe perf.hw.instructions
+probe perf.hw.cache_references
+probe perf.hw.cache_misses
+probe perf.hw.branch_instructions
+probe perf.hw.branch_misses
+probe perf.hw.bus_cycles
+.ESAMPLE
+
+.TP
+.B perf.sw.*
+Special "software" events provided by the kernel.  These sometimes work
+in virtualized environments and with more processor architectures.
+.SAMPLE
+probe perf.sw.cpu_clock
+probe perf.sw.task_clock
+probe perf.sw.page_faults
+probe perf.sw.context_switches
+probe perf.sw.cpu_migrations
+probe perf.sw.page_faults_min
+probe perf.sw.page_faults_maj
+probe perf.sw.alignment_faults
+probe perf.sw.emulation_faults
+.ESAMPLE
+
+.SH SEE ALSO
+.IR stap (1),
+.IR stapprobes (3stap)
diff --git a/stapprobes.3stap.in b/stapprobes.3stap.in
index 3c482252..394aa218 100644
--- a/stapprobes.3stap.in
+++ b/stapprobes.3stap.in
@@ -785,6 +785,33 @@ refers to a hardware preakpoint of type "write" set on pid_max
 syscall.*.return
 refers to the group of probe aliases with any name in the third position
 
+.SS PERF
+
+This 
+.IR prototype
+family of probe points interfaces to the kernel "perf event"
+infrasture for controlling hardware performance counters.
+The events being attached to are described by the "type",
+"config" fields of the 
+.IR perf_event_attr
+structure, and are sampled at an interval governed by the
+"sample_period" field.
+
+These fields are made available to systemtap scripts using
+the following syntax:
+.SAMPLE
+probe perf.type(NN).config(MM).samples(XX)
+probe perf.type(NN).config(MM)
+.ESAMPLE
+The range of valid type/config is described by the 
+.IR perf_event_open (2)
+system call, and/or the 
+.IR linux/perf_event.h
+file.  Invalid combinations or unavailable resources result
+in errors during systemtap script startup.  Systemtap does
+not sanity-check the values: it merely passes them through to
+the kernel for error- and safety-checking.
+
 .SH SEE ALSO
 .IR stap (1),
 .IR tapset::iosched (3stap),