probe timer.profile: document new timer.profile.tick, new behavour of timer.profile

diff --git a/doc/langref.tex b/doc/langref.tex
index 9494c5a768cc914c3e52fea66fd37edafab52a0d..8145dda2b35481c2cabd558ab951e182188d04c1 100644 (file)
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1646,12 +1646,18 @@ at each system tick. This probe takes no parameters, as follows.
 
 \begin{vindent}
 \begin{verbatim}
-timer.profile
+timer.profile.tick
 \end{verbatim}
 \end{vindent}
 Full context information of the interrupted process is available, making
 this probe suitable for implementing a time-based sampling profiler.
 
+It is recommended to use the tapset probe \verb+timer.profile+ rather
+than \verb+timer.profile.tick+. This probe point behaves identically
+to \verb+timer.profile.tick+ when the underlying functionality is
+available, and falls back to using \verb+perf.sw.cpu_clock+ on some
+recent kernels which lack the profile timer facility entirely.
+
 The following is an example of timer usage.
 
 \begin{vindent}

diff --git a/man/stapprobes.3stap b/man/stapprobes.3stap
index 6e2d1bbc851403652610d215fab856cdc9a43af8..3969093416bae3892b4f4fa30b11f49f3dab1c77 100644 (file)
--- a/man/stapprobes.3stap
+++ b/man/stapprobes.3stap
@@ -293,11 +293,18 @@ disabled facility, resulting in error \-16 (EBUSY) during probe
 registration.
 
 .SAMPLE
-timer.profile
+timer.profile.tick
 .ESAMPLE
 
 Full context information of the interrupted process is available, making
 this probe suitable for a time-based sampling profiler.
+.PP
+It is recommended to use the tapset probe
+.IR timer.profile
+rather than timer.profile.tick. This probe point behaves identically
+to timer.profile.tick when the underlying functionality is available,
+and falls back to using perf.sw.cpu_clock on some recent kernels which
+lack the corresponding profile timer facility.
 
 .SS DWARF
 

diff --git a/tapset/timers.stp b/tapset/timers.stp
index 770a40ee4ff45465064f0d4cf1be464e3c0ffa05..8b397bdeaf673f45177e3d916201101460db958a 100644 (file)
--- a/tapset/timers.stp
+++ b/tapset/timers.stp
@@ -11,4 +11,11 @@
 // however, timer.profile needs to fall back to perf in certain
 // circumstances.
 
+/**
+ * probe timer.profile - timer.profile.tick with a perf fallback on recent kernels
+ *
+ * This probe behaves identically to timer.profile.tick, except on
+ * some recent kernels which lack the underlying profile timer
+ * functionality. In those cases, timer.profile falls back to using
+ * perf.sw.cpu_clock. */
 probe timer.profile = timer.profile.tick ! , perf.sw.cpu_clock.sample(1000000) {}