From 94c3c803ea90e4d9447b9a28051ea4681c535d57 Mon Sep 17 00:00:00 2001
From: Ananth N Mavinakayanahalli <ananth@in.ibm.com>
Date: Tue, 21 Apr 2009 17:08:31 +0530
Subject: [PATCH] Documentation updates for kprobe.function family

---
 NEWS                |  6 ++++++
 stapprobes.3stap.in | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/NEWS b/NEWS
index 37a424d84..2a713ba66 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,12 @@
   Such accesses can originate from $context expressions fueled by
   erroneous debug data, or by kernel_{long,string,...}() tapset calls.
 
+- New probes kprobe.function(FUNCTION) and kprobe.function(FUNCTION).return
+  for dwarfless probing. These postpone function address resolution to
+  run-time and use the kprobe symbol-resolution mechanism.
+  Probing of absolute statements can be done using the
+  kprobe.statement(ADDRESS).absolute construct.
+
 * What's new in version 0.9.5
 
 - New probes process().insn and process().insn.block that allows
diff --git a/stapprobes.3stap.in b/stapprobes.3stap.in
index a8988c71d..e60a8fe4e 100644
--- a/stapprobes.3stap.in
+++ b/stapprobes.3stap.in
@@ -64,6 +64,7 @@ syscall.*
 kernel.function("no_such_function") ?
 module("awol").function("no_such_function") !
 signal.*? if (switch)
+kprobe.function("foo")
 .ESAMPLE
 
 
@@ -378,6 +379,40 @@ Other local variables are not generally accessible, since by the time
 a ".return" probe hits, the probed function will have already returned.
 
 
+.SS DWARFLESS
+In absence of debugging information, entry & exit points of kernel & module
+functions can be probed using the "kprobe" family of probes.
+However, these do not permit looking up the arguments / local variables
+of the function.
+Following constructs are supported :
+.SAMPLE
+kprobe.function(FUNCTION)
+kprobe.function(FUNCTION).return
+kprobe.module(NAME).function(FUNCTION)
+kprobe.module(NAME).function(FUNCTION).return
+kprobe.statement.(ADDRESS).absolute
+.ESAMPLE
+.PP
+Probes of type
+.B function
+are recommended for kernel functions, whereas probes of type
+.B module
+are recommended for probing functions of the specified module.
+In case the absolute address of a kernel or module function is known,
+.B statement
+probes can be utilized.
+.PP
+Note that
+.I FUNCTION
+and
+.I MODULE
+names
+.B must not
+contain wildcards, or the probe will not be registered.
+Also, statement probes must be run under guru-mode only.
+
+
+
 .SS USER-SPACE
 Early prototype support for user-space probing is available in the
 form of a non-symbolic probe point:
-- 
2.43.5