perf tools: Add more usage tips

Thanks to Andi Kleen for providing useful tips.

---
 tools/perf/Documentation/tips.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

index a1c10e360db5..2319ff7fa53b 100644
@@ -12,3 +12,18 @@ List events using substring match: perf list <keyword>
 To see list of saved events and attributes: perf evlist -v
 Use --symfs <dir> if your symbol files are in non-standard locations
 To see callchains in a more compact form: perf report -g folded
+Show individual samples with: perf script
+Limit to show entries above 5% only: perf report --percent-limit 5
+Profiling branch (mis)predictions with: perf record -b / perf report
+Treat branches as callchains: perf report --branch-history
+To count events in every 1000 msec: perf stat -I 1000
+Print event counts in CSV format with: perf stat -x
+If you have debuginfo enabled, try: perf report -s sym,srcline
+For memory address profiling, try: perf mem record / perf mem report
+For tracepoint events, try: perf report -s trace_fields
+To record callchains for each sample: perf record -g
+To record every process run by an user: perf record -u <user>
+Skip collecing build-id when recording: perf record -B
+To change sampling frequency to 100 Hz: perf record -F 100
+See assembly instructions with percentage: perf annotate <symbol>
+If you prefer Intel style assembly, try: perf annotate -M intel

2.6.4

If strlist_config.dirname is present, the strlist__new() tries to load stirngs from dirname/list file first but if it failes it falls back to add 'list' as string. But sometimes it's not desired so adds new file_only field to prevent it.

---
 tools/perf/util/strlist.c | 8 ++++++++
 tools/perf/util/strlist.h | 4 +++-
 2 files changed, 11 insertions(+), 1 deletion(-)

index bdf98f6f27bb..0d3dfcb919b4 100644
@@ -126,6 +126,11 @@ static int strlist__parse_list_entry(struct strlist *slist, const char *s,
 			err = strlist__load(slist, subst);
 			goto out;
 		}
+
+		if (slist->file_only) {
+			err = -ENOENT;
+			goto out;
+		}
 	}
 
 	err = strlist__add(slist, s);

@@ -157,11 +162,13 @@ struct strlist *strlist__new(const char *list, const struct strlist_config *conf
 
 	if (slist != NULL) {
 		bool dupstr = true;
+		bool file_only = false;
 		const char *dirname = NULL;
 
 		if (config) {
 			dupstr = !config->dont_dupstr;
 			dirname = config->dirname;
+			file_only = config->file_only;
 		}
 
 		rblist__init(&slist->rblist);

@@ -170,6 +177,7 @@ struct strlist *strlist__new(const char *list, const struct strlist_config *conf
 		slist->rblist.node_delete = strlist__node_delete;
 
 		slist->dupstr	 = dupstr;
+		slist->file_only = file_only;
 
 		if (list && strlist__parse_list(slist, list, dirname) != 0)
 			goto out_error;

index 297565aa7535..93e2c58b40cc 100644
@@ -13,11 +13,13 @@ struct str_node {
 
 struct strlist {
 	struct rblist rblist;
-	bool	       dupstr;
+	bool	      dupstr;
+	bool	      file_only;
 };
 
 struct strlist_config {
 	bool dont_dupstr;
+	bool file_only;
 	const char *dirname;
 };
 

2.6.4

It'll be used to locate perf document directory to find tips.txt in case it's not installed on the system.

---
 tools/perf/Build           | 1 +
 tools/perf/config/Makefile | 3 +++
 2 files changed, 4 insertions(+)

index 6b67e6f4179f..a43fae7f439a 100644
@@ -42,6 +42,7 @@ CFLAGS_perf.o              += -DPERF_HTML_PATH="BUILD_STR($(htmldir_SQ))"	\
 			      -include $(OUTPUT)PERF-VERSION-FILE
 CFLAGS_builtin-trace.o	   += -DSTRACE_GROUPS_DIR="BUILD_STR($(STRACE_GROUPS_DIR_SQ))"
 CFLAGS_builtin-report.o	   += -DTIPDIR="BUILD_STR($(tipdir_SQ))"
+CFLAGS_builtin-report.o	   += -DDOCDIR="BUILD_STR($(srcdir_SQ)/Documentation)"
 
 libperf-y += util/
 libperf-y += arch/

index 254d06e39bea..39d642d18c4e 100644
@@ -692,6 +692,7 @@ template_dir = share/perf-core/templates
 STRACE_GROUPS_DIR = share/perf-core/strace/groups
 htmldir = share/doc/perf-doc
 tipdir = share/doc/perf-tip
+srcdir = $(srctree)/tools/perf
 ifeq ($(prefix),/usr)
 sysconfdir = /etc
 ETC_PERFCONFIG = $(sysconfdir)/perfconfig

@@ -722,6 +723,7 @@ tipdir_SQ = $(subst ','\'',$(tipdir))
 prefix_SQ = $(subst ','\'',$(prefix))
 sysconfdir_SQ = $(subst ','\'',$(sysconfdir))
 libdir_SQ = $(subst ','\'',$(libdir))
+srcdir_SQ = $(subst ','\'',$(srcdir))
 
 ifneq ($(filter /%,$(firstword $(perfexecdir))),)
 perfexec_instdir = $(perfexecdir)

@@ -776,6 +778,7 @@ $(call detected_var,STRACE_GROUPS_DIR_SQ)
 $(call detected_var,prefix_SQ)
 $(call detected_var,perfexecdir_SQ)
 $(call detected_var,tipdir_SQ)
+$(call detected_var,srcdir_SQ)
 $(call detected_var,LIBDIR)
 $(call detected_var,GTK_CFLAGS)
 $(call detected_var,PERL_EMBED_CCOPTS)

2.6.4

Some people don't install perf, but just use compiled version in the source. Fallback to lookup the source directory for those poor guys. :)

---
 tools/perf/builtin-report.c | 10 +++++++++-
 tools/perf/util/util.c      | 11 ++++++-----
 2 files changed, 15 insertions(+), 6 deletions(-)

index d5a42ee12529..2bf537f190a0 100644
@@ -28,6 +28,7 @@
 #include "util/tool.h"
 
 #include <subcmd/parse-options.h>
+#include <subcmd/exec-cmd.h>
 #include "util/parse-events.h"
 
 #include "util/thread.h"

@@ -433,7 +434,14 @@ static int report__browse_hists(struct report *rep)
 	int ret;
 	struct perf_session *session = rep->session;
 	struct perf_evlist *evlist = session->evlist;
-	const char *help = perf_tip(TIPDIR);
+	const char *help = perf_tip(system_path(TIPDIR));
+
+	if (help == NULL) {
+		/* fallback for people who don't install perf ;-) */
+		help = perf_tip(DOCDIR);
+		if (help == NULL)
+			help = "Cannot load tips.txt file, please install perf!";
+	}
 
 	switch (use_browser) {
 	case 1:

index 88b8f8d21f58..92e8543dadf9 100644
@@ -17,7 +17,6 @@
 #include <unistd.h>
 #include "callchain.h"
 #include "strlist.h"
-#include <subcmd/exec-cmd.h>
 
 struct callchain_param	callchain_param = {
 	.mode	= CHAIN_GRAPH_ABS,

@@ -672,14 +671,16 @@ const char *perf_tip(const char *dirpath)
 	struct str_node *node;
 	char *tip = NULL;
 	struct strlist_config conf = {
-		.dirname = system_path(dirpath) ,
+		.dirname = dirpath,
+		.file_only = true,
 	};
 
 	tips = strlist__new("tips.txt", &conf);
-	if (tips == NULL || strlist__nr_entries(tips) == 1) {
-		tip = (char *)"Cannot find tips.txt file";
+	if (tips == NULL)
+		return "Tip: get more memory! ;-p";
+
+	if (strlist__nr_entries(tips) == 0)
 		goto out;
-	}
 
 	node = strlist__entry(tips, random() % strlist__nr_entries(tips));
 	if (asprintf(&tip, "Tip: %s", node->s) < 0)

2.6.4

Em Mon, Jan 11, 2016 at 10:18:20AM +0100, Jiri Olsa escreveu:

Neither me, fixing it up, this fallback will never take place.

- Arnaldo

Em Tue, Jan 12, 2016 at 12:34:35PM -0300, Arnaldo Carvalho de Melo escreveu:

With this patch on top, it works:

[root@felicio ~]# perf trace --no-inherit -e access perf report --stdio

     0.094 ( 0.017 ms): access(filename: /etc/ld.so.preload, mode: R                          ) = -1 ENOENT No such file or directory
     1.940 ( 0.008 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     1.979 ( 0.004 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     2.000 ( 0.004 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     2.177 ( 0.006 ms): access(filename: /usr/bin/pager, mode: X                              ) = -1 ENOENT No such file or directory
     2.189 ( 0.011 ms): access(filename: /usr/bin/less, mode: X                               ) = 0
    17.250 ( 0.018 ms): access(filename: /home/acme/share/doc/perf-tip/tips.txt               ) = -1 ENOENT No such file or directory
    17.259 ( 0.006 ms): access(filename: /home/acme/git/linux/tools/perf/Documentation/tips.txt) = 0

# To display the perf.data header info, please use --header/--header-only options. #
#
# Total Lost Samples: 0
#
# Samples: 5 of event 'cycles:pp'
# Event count (approx.): 24954605
#

# Overhead  Command  Shared Object     Symbol                   
# ........  .......  ................  .........................
#
    99.68%  usleep   [kernel.vmlinux]  [k] vma_rb_erase         
     0.32%  perf     [kernel.vmlinux]  [k] nmi_cpu_backtrace    
     0.00%  perf     [kernel.vmlinux]  [k] native_write_msr_safe

#
# (Tip: To see callchains in a more compact form: perf report -g folded) #
[root@felicio ~]#

Em Sat, Jan 09, 2016 at 07:16:29PM +0900, Namhyung Kim escreveu:

So, after applying this I tried:

  $ rm -f ~/share/doc/perf-tip/tips.txt

To make it fallback and:

  $ perf report --stdio | tail -3
  #
  # (Tip: get more memory! ;-p)
  #
  $ 

Doesn't work, looking at what it is trying to find:

  # perf trace --no-inherit -e access perf report --stdio
     0.090 ( 0.010 ms): access(filename: /etc/ld.so.preload, mode: R                          ) = -1 ENOENT No such file or directory
     2.013 ( 0.014 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     2.045 ( 0.004 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     2.076 ( 0.005 ms): access(filename: /home/acme/etc/perfconfig, mode: R                   ) = -1 ENOENT No such file or directory
     2.239 ( 0.006 ms): access(filename: /usr/bin/pager, mode: X                              ) = -1 ENOENT No such file or directory
     2.244 ( 0.004 ms): access(filename: /usr/bin/less, mode: X                               ) = 0
    16.969 ( 0.018 ms): access(filename: /home/acme/share/doc/perf-tip/tips.txt               ) = -1 ENOENT No such file or directory
  # To display the perf.data header info, please use --header/--header-only options.
  # 
  #
  # Total Lost Samples: 0
  #
  # Samples: 5  of event 'cycles:pp'
  # Event count (approx.): 24954605
  #
  # Overhead  Command  Shared Object     Symbol                   
  # ........  .......  ................  .........................
  #
    99.68%  usleep   [kernel.vmlinux]  [k] vma_rb_erase         
     0.32%  perf     [kernel.vmlinux]  [k] nmi_cpu_backtrace    
     0.00%  perf     [kernel.vmlinux]  [k] native_write_msr_safe

#
# (Tip: get more memory! ;-p)
#
#

Also you're not just fallbacking, you did this other unrelated change, no?

- const char *help = perf_tip(TIPDIR);
+ const char *help = perf_tip(system_path(TIPDIR));

Investigating...

Thanks to Andi Kleen for providing useful tips.

---
 tools/perf/Documentation/tips.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

index a1c10e360db5..e0ce9573b79b 100644
@@ -12,3 +12,18 @@ List events using substring match: perf list <keyword>
 To see list of saved events and attributes: perf evlist -v
 Use --symfs <dir> if your symbol files are in non-standard locations
 To see callchains in a more compact form: perf report -g folded
+Show individual samples with: perf script
+Limit to show entries above 5% only: perf report --percent-limit 5
+Profiling branch (mis)predictions with: perf record -b / perf report
+Treat branches as callchains: perf report --branch-history
+To count events in every 1000 msec: perf stat -I 1000
+Print event counts in CSV format with: perf stat -x,
+If you have debuginfo enabled, try: perf report -s sym,srcline
+For memory address profiling, try: perf mem record / perf mem report
+For tracepoint events, try: perf report -s trace_fields
+To record callchains for each sample: perf record -g
+To record every process run by an user: perf record -u <user>
+Skip collecing build-id when recording: perf record -B
+To change sampling frequency to 100 Hz: perf record -F 100
+See assembly instructions with percentage: perf annotate <symbol>
+If you prefer Intel style assembly, try: perf annotate -M intel

2.6.4

When a tip message contains a percent sign, it was treated printf format specifier so broken string was printed like below.

Tip: Limit to show entries above 577nly: perf report --percent-limit 5

                                   ^^^

As ui_browser__show receives format string, pass additional "%s" so that the help (tip) message can be printed as is.

Tip: Limit to show entries above 5% only: perf report --percent-limit 5

---
 tools/perf/ui/browsers/hists.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 901d481e6cea..08c09ad755d2 100644
@@ -480,7 +480,7 @@ static int hist_browser__run(struct hist_browser *browser, const char *help)
 
 	hists__browser_title(browser->hists, hbt, title, sizeof(title));
 
-	if (ui_browser__show(&browser->b, title, help) < 0)
+	if (ui_browser__show(&browser->b, title, "%s", help) < 0)
 		return -1;
 
 	while (1) {

2.6.4

Em Mon, Jan 11, 2016 at 07:53:14PM +0900, Namhyung Kim escreveu:

Applied.