From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27338 invoked by alias); 18 Jul 2014 10:20:45 -0000 Mailing-List: contact systemtap-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Help: , Sender: systemtap-owner@sourceware.org Received: (qmail 27326 invoked by uid 89); 18 Jul 2014 10:20:44 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.6 required=5.0 tests=BAYES_00,DATE_IN_PAST_24_48,RP_MATCHES_RCVD autolearn=no version=3.3.2 X-HELO: e28smtp07.in.ibm.com Received: from e28smtp07.in.ibm.com (HELO e28smtp07.in.ibm.com) (122.248.162.7) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Fri, 18 Jul 2014 10:20:43 +0000 Received: from /spool/local by e28smtp07.in.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 18 Jul 2014 15:50:37 +0530 Received: from d28dlp03.in.ibm.com (9.184.220.128) by e28smtp07.in.ibm.com (192.168.1.137) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Fri, 18 Jul 2014 15:50:34 +0530 Received: from d28relay04.in.ibm.com (d28relay04.in.ibm.com [9.184.220.61]) by d28dlp03.in.ibm.com (Postfix) with ESMTP id 36529125804D for ; Fri, 18 Jul 2014 15:50:23 +0530 (IST) Received: from d28av05.in.ibm.com (d28av05.in.ibm.com [9.184.220.67]) by d28relay04.in.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id s6IAKr7N58327112 for ; Fri, 18 Jul 2014 15:50:53 +0530 Received: from d28av05.in.ibm.com (localhost [127.0.0.1]) by d28av05.in.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id s6IAKWb5024609 for ; Fri, 18 Jul 2014 15:50:33 +0530 Received: from [192.168.122.32] ([9.124.35.114]) by d28av05.in.ibm.com (8.14.4/8.14.4/NCO v10.0 AVin) with ESMTP id s6IAKVvW024539; Fri, 18 Jul 2014 15:50:31 +0530 Subject: [PATCH v2 3/3] perf/sdt: Documentation To: linux-kernel@vger.kernel.org From: Hemant Kumar Cc: srikar@linux.vnet.ibm.com, peterz@infradead.org, oleg@redhat.com, hegdevasant@linux.vnet.ibm.com, mingo@redhat.com, anton@redhat.com, systemtap@sourceware.org, namhyung@kernel.org, masami.hiramatsu.pt@hitachi.com, aravinda@linux.vnet.ibm.com, penberg@iki.fi Date: Fri, 18 Jul 2014 10:20:00 -0000 Message-ID: <20140717055609.19995.43454.stgit@hemant-fedora> In-Reply-To: <20140717054826.19995.61782.stgit@hemant-fedora> References: <20140717054826.19995.61782.stgit@hemant-fedora> User-Agent: StGit/0.16 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 14071810-8878-0000-0000-00000010E6BE X-SW-Source: 2014-q3/txt/msg00035.txt.bz2 This patch adds the required documentation for perf support to SDT markers. --- tools/perf/Documentation/SDT-markers.txt | 123 ++++++++++++++++++++++++++++++ tools/perf/Documentation/perf-list.txt | 7 +- 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 tools/perf/Documentation/SDT-markers.txt diff --git a/tools/perf/Documentation/SDT-markers.txt b/tools/perf/Documentation/SDT-markers.txt new file mode 100644 index 0000000..420ba2e --- /dev/null +++ b/tools/perf/Documentation/SDT-markers.txt @@ -0,0 +1,123 @@ +Support to perf for listing the SDT markers : + +This helps in listing dtrace style markers(SDT) present in user space +applications through perf. 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 + +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 + +A different example to show the same: +- Create a file with .d extension and mention the probe names in it with +provider name and marker name. + +$ cat probes.d +provider user_app { + probe foo_start(); + probe fun_start(); +}; + +- Now create the probes.h and probes.o file : +$ dtrace -C -h -s probes.d -o probes.h +$ dtrace -C -G -s probes.d -o probes.o + +- A program using the markers: + +$ cat user_app.c + +#include +#include "probes.h" + +void foo(void) +{ + USER_APP_FOO_START(); + printf("This is foo\n"); +} + +void fun(void) +{ + USER_APP_FUN_START(); + printf("Inside fun\n"); +} +int main(void) +{ + printf("In main\n"); + foo(); + fun(); + return 0; +} +- Compile it and also provide probes.o file to linker: +$ gcc user_app.c probes.o -o user_app + +- Now use perf to list the markers in the app: +# perf list sdt ./user_app + +./user_app : +%user_app:foo_start +%user_app:fun_start + +Also, we can see the SDT markers present in our system in the usual binaries. +First, scan the binaries using : +# perf list sdt --scan + +Creating a cache of SDT markers... +perf sdt cache created! + Use : "perf list sdt" + to see the SDT markers + +After the sdt cache file is created, use perf list to view the markers : +# perf list sdt + +%rtld : init_start +%rtld : init_complete +%rtld : map_failed +%rtld : map_start +%rtld : lll_futex_wake +... +... +%libgcc : unwind +%libvirt : rpc_server_client_auth_allow +%libvirt : rpc_server_client_auth_fail +%libvirt : rpc_server_client_auth_deny + +Using "perf list sdt " after this will update the entries related to that + in the cache. + +Also, this link provides important info regarding SDT notes: +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". +Here, 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 are not enabled, they are present in the ELF as nop. diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt index 6fce6a6..f146e53 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|event_glob|sdt] DESCRIPTION ----------- @@ -108,6 +108,11 @@ To limit the list use: . 'pmu' to print the kernel supplied PMU events. +. 'sdt' to print the SDT markers present in dsos and binaries. An additional + argument of filename will instruct perf to look for SDT markers only in that + file. If that file is already present in the cache and if there is any change, + then the entries for that file will be updated in the cache. + . If none of the above is matched, it will apply the supplied glob to all events, printing the ones that match.