[PATCH v4 3/3] perf/sdt : Documentation for SDT events

[Hemant Kumar <hemant@linux.vnet.ibm.com>]

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.