From acf7bde90d8babfdee8ab6476810c5b87da6b551 Mon Sep 17 00:00:00 2001
From: Serguei Makarov <smakarov@redhat.com>
Date: Fri, 10 May 2013 16:48:06 -0400
Subject: [PATCH] probe timer.profile: document new timer.profile.tick, new
 behavour of timer.profile

---
 doc/langref.tex      | 8 +++++++-
 man/stapprobes.3stap | 9 ++++++++-
 tapset/timers.stp    | 7 +++++++
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/doc/langref.tex b/doc/langref.tex
index 9494c5a76..8145dda2b 100644
--- 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 6e2d1bbc8..396909341 100644
--- 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 770a40ee4..8b397bdea 100644
--- 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) {}
-- 
2.43.5