This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
[PATCH v3 3/3] perf/sdt : Documentation support
- From: Hemant Kumar <hemant at linux dot vnet dot ibm dot com>
- To: linux-kernel at vger dot kernel dot org
- Cc: srikar at linux dot vnet dot ibm dot com, peterz at infradead dot org, oleg at redhat dot com, hegdevasant at linux dot vnet dot ibm dot com, mingo at redhat dot com, anton at redhat dot com, systemtap at sourceware dot org, namhyung at kernel dot org, masami dot hiramatsu dot pt at hitachi dot com, aravinda at linux dot vnet dot ibm dot com, penberg at iki dot fi
- Date: Thu, 28 Aug 2014 01:49:39 +0530
- Subject: [PATCH v3 3/3] perf/sdt : Documentation support
- Authentication-results: sourceware.org; auth=none
- References: <20140827200933 dot 11095 dot 96814 dot stgit at hemant-fedora>
Adds documentation for perf support to SDT events.
Signed-off-by : Hemant Kumar <hemant@linux.vnet.ibm.com>
---
tools/perf/Documentation/SDT-support.txt | 48 ++++++++++++++++++++++++++++++
tools/perf/Documentation/perf-list.txt | 4 ++-
2 files changed, 51 insertions(+), 1 deletion(-)
create mode 100644 tools/perf/Documentation/SDT-support.txt
diff --git a/tools/perf/Documentation/SDT-support.txt b/tools/perf/Documentation/SDT-support.txt
new file mode 100644
index 0000000..273912b
--- /dev/null
+++ b/tools/perf/Documentation/SDT-support.txt
@@ -0,0 +1,48 @@
+Support to perf for listing the SDT markers :
+
+This helps in listing dtrace style markers(SDT) present in user space
+applications through perf. SDT Notes/markers are placed at important places by the
+developers. They have a negligible overhead when not enabled.
+We can enable them and probe at these places and find some important information
+like the arguments' values, etc.
+
+How to add SDT markers into user applications:
+We need to have this header sys/sdt.h present.
+sys/sdt.h used is version 3.
+If not present, install systemtap-sdt-devel package (for fedora-18).
+
+A very simple example:
+
+$ cat user_app.c
+
+#include <sys/sdt.h>
+
+void main () {
+ /* ... */
+ /*
+ * user_app is the provider name
+ * test_probe is the marker name
+ */
+ STAP_PROBE(user_app, test_mark);
+ /* ... */
+}
+
+$ gcc user_app.c
+$ perf list sdt ./a.out
+./a.out:
+%user_app:test_mark
+
+For more information on usage of SDT markers, visit the following link:
+http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation
+
+This link shows an example of marker probing with Systemtap:
+https://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps
+
+- Markers in binaries :
+These SDT markers are present in the ELF in the section named
+".note.stapsdt".
+This section contains the name of the marker, its provider, type, location, base
+address, semaphore address.
+We can retrieve these values using the members name_off and desc_off in
+Nhdr structure. If these markers are not enabled, they are present in the ELF in
+the form of a "nop" instruction.
diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 6fce6a6..5c72785 100644
--- a/tools/perf/Documentation/perf-list.txt
+++ b/tools/perf/Documentation/perf-list.txt
@@ -8,7 +8,7 @@ perf-list - List all symbolic event types
SYNOPSIS
--------
[verse]
-'perf list' [hw|sw|cache|tracepoint|pmu|event_glob]
+'perf list' [hw|sw|cache|tracepoint|pmu|sdt|event_glob]
DESCRIPTION
-----------
@@ -108,6 +108,8 @@ To limit the list use:
. 'pmu' to print the kernel supplied PMU events.
+. 'sdt' to print the SDT events present in a file. Takes a file_name as an argument.
+
. If none of the above is matched, it will apply the supplied glob to all
events, printing the ones that match.