perf report: Add titles for percent/ipc/cycle in annotate browser

v2:
---
Thanks for the comments and ideas from Arnaldo and Milian.

1. Change "Percnt" to "Percent"
2. Add explanations for "Percent", "IPC" and "Cycle".

When user hit hotkey 'h', the help window is popup. Explanations are added at the bottom of window.

│Report explanation:                                           │
│    Percent: sample percentage for a block                    │
│        IPC: instructions per cycle for a block               │
│      cycle: average number of cycles for a block             │

I don't use a new window to display the report explanation, instead, I just display the info in current help window so that user doesn't need to press one more hotkey to get the explanation.

Changed patch:
--------------
perf report: Display titles in left frame of annotate browser

Unchanged patch:
----------------
perf report: Remove the unnecessary checking in annotate_browser_write

Initial post
------------

The patch series adds the titles "Percnt", "IPC" and "Cycle" in annotate browser. It helps user to understand easily for what the columns in left frame represents for.

For example:

    Percnt  IPC Cycle  │
                       │25  __attribute__((noinline))
                       │26  int compute_flag()
                       │27  {
     22.80  1.20       │      sub    $0x8,%rsp
                       │25          int i;
                       │
                       │27          i = rand() % 2;
     22.78  1.20     1 │    → callq  rand@plt

The patch "perf report: Remove the unnecessary checking in annotate_browser_write" removes the invalid condition checking in current code.

Jin Yao (2):
perf report: Remove the unnecessary checking in annotate_browser_write perf report: Display titles in left frame of annotate browser

 tools/perf/ui/browsers/annotate.c | 59 +++++++++++++++++++++++++++------------
 1 file changed, 41 insertions(+), 18 deletions(-)

2.7.4

In annotate_browser_write(),

        if (dl->offset != -1 && percent_max != 0.0) {
                if (percent_max != 0.0) {
			...
                }
                ...
        }

The second checking of (percent_max != 0.0) is not necessary, so remove it.

Change log:
-----------
v2: not changed.

---
 tools/perf/ui/browsers/annotate.c | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

index d990ad0..52c1e8d 100644
@@ -132,21 +132,17 @@ static void annotate_browser__write(struct ui_browser *browser, void *entry, int
 	}
 
 	if (dl->offset != -1 && percent_max != 0.0) {
-		if (percent_max != 0.0) {
-			for (i = 0; i < ab->nr_events; i++) {
-				ui_browser__set_percent_color(browser,
-							bdl->samples[i].percent,
-							current_entry);
-				if (annotate_browser__opts.show_total_period) {
-					ui_browser__printf(browser, "%6" PRIu64 " ",
-							   bdl->samples[i].nr);
-				} else {
-					ui_browser__printf(browser, "%6.2f ",
-							   bdl->samples[i].percent);
-				}
+		for (i = 0; i < ab->nr_events; i++) {
+			ui_browser__set_percent_color(browser,
+						bdl->samples[i].percent,
+						current_entry);
+			if (annotate_browser__opts.show_total_period) {
+				ui_browser__printf(browser, "%6" PRIu64 " ",
+						   bdl->samples[i].nr);
+			} else {
+				ui_browser__printf(browser, "%6.2f ",
+						   bdl->samples[i].percent);
 			}
-		} else {
-			ui_browser__write_nstring(browser, " ", 7 * ab->nr_events);
 		}
 	} else {
 		ui_browser__set_percent_color(browser, 0, current_entry);

2.7.4

The annotate browser is divided into 2 frames. Left frame contains 3 columns (some platforms only have one column).

For example:

                   │26  int compute_flag()
                   │27  {
 22.80  1.20       │      sub    $0x8,%rsp
                   │25          int i;
                   │
                   │27          i = rand() % 2;
 22.78  1.20     1 │    → callq  rand@plt

While it's hard for user to understand what the data is.

This patch adds the titles "Percent", "IPC" and "Cycle" on columns.

Percent  IPC Cycle │
                   │25  __attribute__((noinline))
                   │26  int compute_flag()
                   │27  {
 22.80  1.20       │      sub    $0x8,%rsp
                   │25          int i;
                   │
                   │27          i = rand() % 2;
 22.78  1.20     1 │    → callq  rand@plt

The titles are displayed at row 0 of annotate browser if row 0 doesn't have values of percent, ipc and cycle.

Change log:
----------
v2:
1. Change "Percnt" to "Percent"
2. Add explanations for "Percent", "IPC" and "Cycle".

When user hit hotkey 'h', the help window is popup. Explanations are added at the bottom of window.

│Report explanation:                                           │
│    Percent: sample percentage for a block                    │
│        IPC: instructions per cycle for a block               │
│      cycle: average number of cycles for a block             │

---
 tools/perf/ui/browsers/annotate.c | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

index 52c1e8d..f015813 100644
@@ -125,12 +125,21 @@ static void annotate_browser__write(struct ui_browser *browser, void *entry, int
 	int i, pcnt_width = annotate_browser__pcnt_width(ab);
 	double percent_max = 0.0;
 	char bf[256];
+	bool show_title = false;
 
 	for (i = 0; i < ab->nr_events; i++) {
 		if (bdl->samples[i].percent > percent_max)
 			percent_max = bdl->samples[i].percent;
 	}
 
+	if ((row == 0) && (dl->offset == -1 || percent_max == 0.0)) {
+		if (ab->have_cycles) {
+			if (dl->ipc == 0.0 && dl->cycles == 0)
+				show_title = true;
+		} else
+			show_title = true;
+	}
+
 	if (dl->offset != -1 && percent_max != 0.0) {
 		for (i = 0; i < ab->nr_events; i++) {
 			ui_browser__set_percent_color(browser,

@@ -146,18 +155,30 @@ static void annotate_browser__write(struct ui_browser *browser, void *entry, int
 		}
 	} else {
 		ui_browser__set_percent_color(browser, 0, current_entry);
-		ui_browser__write_nstring(browser, " ", 7 * ab->nr_events);
+
+		if (!show_title)
+			ui_browser__write_nstring(browser, " ",
+						  7 * ab->nr_events);
+		else
+			ui_browser__printf(browser, "%*s", 7, "Percent");
 	}
 	if (ab->have_cycles) {
 		if (dl->ipc)
 			ui_browser__printf(browser, "%*.2f ", IPC_WIDTH - 1, dl->ipc);
-		else
+		else if (!show_title)
 			ui_browser__write_nstring(browser, " ", IPC_WIDTH);
+		else
+			ui_browser__printf(browser, "%*s ",
+					   IPC_WIDTH - 1, "IPC");
+
 		if (dl->cycles)
 			ui_browser__printf(browser, "%*" PRIu64 " ",
 					   CYCLES_WIDTH - 1, dl->cycles);
-		else
+		else if (!show_title)
 			ui_browser__write_nstring(browser, " ", CYCLES_WIDTH);
+		else
+			ui_browser__printf(browser, "%*s ",
+					   CYCLES_WIDTH - 1, "Cycle");
 	}
 
 	SLsmg_write_char(' ');

@@ -781,7 +802,13 @@ static int annotate_browser__run(struct annotate_browser *browser,
 		"/             Search string\n"
 		"k             Toggle line numbers\n"
 		"r             Run available scripts\n"
-		"?             Search string backwards\n");
+		"?             Search string backwards\n"
+		"\n"
+		"Report explanation:\n"
+		"    Percent: sample percentage for a block\n"
+		"        IPC: instructions per cycle for a block\n"
+		"      cycle: average number of cycles for a block\n"
+		);
 			continue;
 		case 'r':
 			{

2.7.4