annotate.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2#ifndef __PERF_ANNOTATE_H
  3#define __PERF_ANNOTATE_H
  4
  5#include <stdbool.h>
  6#include <stdint.h>
  7#include <stdio.h>
  8#include <linux/types.h>
  9#include <linux/list.h>
 10#include <linux/rbtree.h>
 11#include <asm/bug.h>
 12#include "symbol_conf.h"
 13#include "mutex.h"
 14#include "spark.h"
 15#include "hashmap.h"
 16#include "disasm.h"
 17#include "branch.h"
 18#include "evsel.h"
 19
 20struct hist_browser_timer;
 21struct hist_entry;
 22struct map;
 23struct map_symbol;
 24struct addr_map_symbol;
 25struct option;
 26struct perf_sample;
 27struct symbol;
 28struct annotated_data_type;
 29
 30#define ANNOTATION__IPC_WIDTH 6
 31#define ANNOTATION__CYCLES_WIDTH 6
 32#define ANNOTATION__MINMAX_CYCLES_WIDTH 19
 33#define ANNOTATION__AVG_IPC_WIDTH 36
 34#define ANNOTATION__BR_CNTR_WIDTH 30
 35#define ANNOTATION_DUMMY_LEN	256
 36
 37enum perf_disassembler {
 38	PERF_DISASM_UNKNOWN = 0,
 39	PERF_DISASM_LLVM,
 40	PERF_DISASM_CAPSTONE,
 41	PERF_DISASM_OBJDUMP,
 42};
 43#define MAX_DISASSEMBLERS (PERF_DISASM_OBJDUMP + 1)
 44
 45struct annotation_options {
 46	bool hide_src_code,
 47	     hide_src_code_on_title,
 48	     use_offset,
 49	     jump_arrows,
 50	     print_lines,
 51	     full_path,
 52	     show_linenr,
 53	     show_fileloc,
 54	     show_nr_jumps,
 55	     show_minmax_cycle,
 56	     show_asm_raw,
 57	     show_br_cntr,
 58	     annotate_src,
 59	     code_with_type,
 60	     full_addr;
 61	u8   offset_level;
 62	u8   disassemblers[MAX_DISASSEMBLERS];
 63	u8   disassembler_used;
 64	int  min_pcnt;
 65	int  max_lines;
 66	int  context;
 67	char *objdump_path;
 68	char *disassembler_style;
 69	const char *prefix;
 70	const char *prefix_strip;
 71	unsigned int percent_type;
 72};
 73
 74extern struct annotation_options annotate_opts;
 75
 76enum {
 77	ANNOTATION__OFFSET_JUMP_TARGETS = 1,
 78	ANNOTATION__OFFSET_CALL,
 79	ANNOTATION__MAX_OFFSET_LEVEL,
 80};
 81
 82#define ANNOTATION__MIN_OFFSET_LEVEL ANNOTATION__OFFSET_JUMP_TARGETS
 83
 84struct annotation;
 85
 86struct sym_hist_entry {
 87	u64		nr_samples;
 88	u64		period;
 89};
 90
 91enum {
 92	PERCENT_HITS_LOCAL,
 93	PERCENT_HITS_GLOBAL,
 94	PERCENT_PERIOD_LOCAL,
 95	PERCENT_PERIOD_GLOBAL,
 96	PERCENT_MAX,
 97};
 98
 99struct annotation_data {
100	double			 percent[PERCENT_MAX];
101	double			 percent_sum;
102	struct sym_hist_entry	 he;
103};
104
105struct cycles_info {
106	float			 ipc;
107	u64			 avg;
108	u64			 max;
109	u64			 min;
110};
111
112struct annotation_line {
113	struct list_head	 node;
114	struct rb_node		 rb_node;
115	s64			 offset;
116	char			*line;
117	int			 line_nr;
118	char			*fileloc;
119	char			*path;
120	struct cycles_info	*cycles;
121	int			 num_aggr;
122	int			 br_cntr_nr;
123	u64			*br_cntr;
124	struct evsel		*evsel;
125	int			 jump_sources;
126	u32			 idx;
127	int			 idx_asm;
128	int			 data_nr;
129	struct annotation_data	 data[];
130};
131
132struct disasm_line {
133	struct ins		 ins;
134	struct ins_operands	 ops;
135	union {
136		u8 bytes[4];
137		u32 raw_insn;
138	} raw;
139	/* This needs to be at the end. */
140	struct annotation_line	 al;
141};
142
143extern const char * const perf_disassembler__strs[];
144
145void annotation_line__add(struct annotation_line *al, struct list_head *head);
146
147static inline double annotation_data__percent(struct annotation_data *data,
148					      unsigned int which)
149{
150	return which < PERCENT_MAX ? data->percent[which] : -1;
151}
152
153static inline const char *percent_type_str(unsigned int type)
154{
155	static const char *str[PERCENT_MAX] = {
156		"local hits",
157		"global hits",
158		"local period",
159		"global period",
160	};
161
162	if (WARN_ON(type >= PERCENT_MAX))
163		return "N/A";
164
165	return str[type];
166}
167
168static inline struct disasm_line *disasm_line(struct annotation_line *al)
169{
170	return al ? container_of(al, struct disasm_line, al) : NULL;
171}
172
173/*
174 * Is this offset in the same function as the line it is used?
175 * asm functions jump to other functions, for instance.
176 */
177static inline bool disasm_line__has_local_offset(const struct disasm_line *dl)
178{
179	return dl->ops.target.offset_avail && !dl->ops.target.outside;
180}
181
182/*
183 * Can we draw an arrow from the jump to its target, for instance? I.e.
184 * is the jump and its target in the same function?
185 */
186bool disasm_line__is_valid_local_jump(struct disasm_line *dl, struct symbol *sym);
187
188struct annotation_line *
189annotation_line__next(struct annotation_line *pos, struct list_head *head);
190
191struct annotation_write_ops {
192	bool first_line, current_entry, change_color;
193	int  width;
194	void *obj;
195	int  (*set_color)(void *obj, int color);
196	void (*set_percent_color)(void *obj, double percent, bool current);
197	int  (*set_jumps_percent_color)(void *obj, int nr, bool current);
198	void (*printf)(void *obj, const char *fmt, ...);
199	void (*write_graph)(void *obj, int graph);
200};
201
202struct annotation_print_data {
203	struct hist_entry *he;
204	struct evsel *evsel;
205	struct arch *arch;
206	struct debuginfo *dbg;
207	/* save data type info keyed by al->offset */
208	struct hashmap *type_hash;
209	/* It'll be set in hist_entry__annotate_printf() */
210	int addr_fmt_width;
211};
212
213void annotation_line__write(struct annotation_line *al, struct annotation *notes,
214			    const struct annotation_write_ops *ops,
215			    struct annotation_print_data *apd);
216
217int __annotation__scnprintf_samples_period(struct annotation *notes,
218					   char *bf, size_t size,
219					   struct evsel *evsel,
220					   bool show_freq);
221
222size_t disasm__fprintf(struct list_head *head, FILE *fp);
223void symbol__calc_percent(struct symbol *sym, struct evsel *evsel);
224
225/**
226 * struct sym_hist - symbol histogram information for an event
227 *
228 * @nr_samples: Total number of samples.
229 * @period: Sum of sample periods.
230 */
231struct sym_hist {
232	u64		      nr_samples;
233	u64		      period;
234};
235
236/**
237 * struct cyc_hist - (CPU) cycle histogram for a basic block
238 *
239 * @start: Start address of current block (if known).
240 * @cycles: Sum of cycles for the longest basic block.
241 * @cycles_aggr: Total cycles for this address.
242 * @cycles_max: Max cycles for this address.
243 * @cycles_min: Min cycles for this address.
244 * @cycles_spark: History of cycles for the longest basic block.
245 * @num: Number of samples for the longest basic block.
246 * @num_aggr: Total number of samples for this address.
247 * @have_start: Whether the current branch info has a start address.
248 * @reset: Number of resets due to a different start address.
249 *
250 * If sample has branch_stack and cycles info, it can construct basic blocks
251 * between two adjacent branches.  It'd have start and end addresses but
252 * sometimes the start address may not be available.  So the cycles are
253 * accounted at the end address.  If multiple basic blocks end at the same
254 * address, it will take the longest one.
255 *
256 * The @start, @cycles, @cycles_spark and @num fields are used for the longest
257 * block only.  Other fields are used for all cases.
258 *
259 * See __symbol__account_cycles().
260 */
261struct cyc_hist {
262	u64	start;
263	u64	cycles;
264	u64	cycles_aggr;
265	u64	cycles_max;
266	u64	cycles_min;
267	s64	cycles_spark[NUM_SPARKS];
268	u32	num;
269	u32	num_aggr;
270	u8	have_start;
271	/* 1 byte padding */
272	u16	reset;
273};
274
275/**
276 * struct annotated_source - symbols with hits have this attached as in annotation
277 *
278 * @source: List head for annotated_line (embeded in disasm_line).
279 * @histograms: Array of symbol histograms per event to maintain the total number
280 * 		of samples and period.
281 * @nr_histograms: This may not be the same as evsel->evlist->core.nr_entries if
282 * 		  we have more than a group in a evlist, where we will want
283 * 		  to see each group separately, that is why symbol__annotate2()
284 * 		  sets src->nr_histograms to evsel->nr_members.
285 * @samples: Hash map of sym_hist_entry.  Keyed by event index and offset in symbol.
286 * @nr_events: Number of events in the current output.
287 * @nr_entries: Number of annotated_line in the source list.
288 * @nr_asm_entries: Number of annotated_line with actual asm instruction in the
289 * 		    source list.
290 * @max_jump_sources: Maximum number of jump instructions targeting to the same
291 * 		      instruction.
292 * @widths: Precalculated width of each column in the TUI output.
293 *
294 * disasm_lines are allocated, percentages calculated and all sorted by percentage
295 * when the annotation is about to be presented, so the percentages are for
296 * one of the entries in the histogram array, i.e. for the event/counter being
297 * presented. It is deallocated right after symbol__{tui,tty,etc}_annotate
298 * returns.
299 */
300struct annotated_source {
301	struct list_head	source;
302	struct sym_hist		*histograms;
303	struct hashmap	   	*samples;
304	int    			nr_histograms;
305	int    			nr_events;
306	int			nr_entries;
307	int			nr_asm_entries;
308	int			max_jump_sources;
309	bool			tried_source;
310	u64			start;
311	struct {
312		u8		addr;
313		u8		jumps;
314		u8		target;
315		u8		min_addr;
316		u8		max_addr;
317		u8		max_ins_name;
318		u16		max_line_len;
319	} widths;
320};
321
322struct annotation_line *annotated_source__get_line(struct annotated_source *src,
323						   s64 offset);
324
325/* A branch counter once saturated */
326#define ANNOTATION__BR_CNTR_SATURATED_FLAG	(1ULL << 63)
327
328/**
329 * struct annotated_branch - basic block and IPC information for a symbol.
330 *
331 * @hit_cycles: Total executed cycles.
332 * @hit_insn: Total number of instructions executed.
333 * @total_insn: Number of instructions in the function.
334 * @cover_insn: Number of distinct, actually executed instructions.
335 * @cycles_hist: Array of cyc_hist for each instruction.
336 * @max_coverage: Maximum number of covered basic block (used for block-range).
337 * @br_cntr: Array of the occurrences of events (branch counters) during a block.
338 *
339 * This struct is used by two different codes when the sample has branch stack
340 * and cycles information.  annotation__compute_ipc() calculates average IPC
341 * using @hit_insn / @hit_cycles.  The actual coverage can be calculated using
342 * @cover_insn / @total_insn.  The @cycles_hist can give IPC for each (longest)
343 * basic block ends at the given address.
344 * process_basic_block() calculates coverage of instructions (or basic blocks)
345 * in the function.
346 */
347struct annotated_branch {
348	u64			hit_cycles;
349	u64			hit_insn;
350	unsigned int		total_insn;
351	unsigned int		cover_insn;
352	struct cyc_hist		*cycles_hist;
353	u64			max_coverage;
354	u64			*br_cntr;
355};
356
357struct LOCKABLE annotation {
358	struct annotated_source *src;
359	struct annotated_branch *branch;
360};
361
362static inline void annotation__init(struct annotation *notes __maybe_unused)
363{
364}
365void annotation__exit(struct annotation *notes);
366
367void annotation__lock(struct annotation *notes) EXCLUSIVE_LOCK_FUNCTION(*notes);
368void annotation__unlock(struct annotation *notes) UNLOCK_FUNCTION(*notes);
369bool annotation__trylock(struct annotation *notes) EXCLUSIVE_TRYLOCK_FUNCTION(true, *notes);
370
371static inline int annotation__cycles_width(struct annotation *notes)
372{
373	if (notes->branch && annotate_opts.show_minmax_cycle)
374		return ANNOTATION__IPC_WIDTH + ANNOTATION__MINMAX_CYCLES_WIDTH;
375
376	return notes->branch ? ANNOTATION__IPC_WIDTH + ANNOTATION__CYCLES_WIDTH : 0;
377}
378
379static inline int annotation__pcnt_width(struct annotation *notes)
380{
381	return (symbol_conf.show_total_period ? 12 : 8) * notes->src->nr_events;
382}
383
384static inline bool annotation_line__filter(struct annotation_line *al)
385{
386	return annotate_opts.hide_src_code && al->offset == -1;
387}
388
389static inline u8 annotation__br_cntr_width(void)
390{
391	return annotate_opts.show_br_cntr ? ANNOTATION__BR_CNTR_WIDTH : 0;
392}
393
394void annotation__update_column_widths(struct annotation *notes);
395void annotation__toggle_full_addr(struct annotation *notes, struct map_symbol *ms);
396
397static inline struct sym_hist *annotated_source__histogram(struct annotated_source *src,
398							   const struct evsel *evsel)
399{
400	return &src->histograms[evsel->core.idx];
401}
402
403static inline struct sym_hist *annotation__histogram(struct annotation *notes,
404						     const struct evsel *evsel)
405{
406	return annotated_source__histogram(notes->src, evsel);
407}
408
409static inline struct sym_hist_entry *
410annotated_source__hist_entry(struct annotated_source *src, const struct evsel *evsel, u64 offset)
411{
412	struct sym_hist_entry *entry;
413	long key = offset << 16 | evsel->core.idx;
414
415	if (!hashmap__find(src->samples, key, &entry))
416		return NULL;
417	return entry;
418}
419
420static inline struct annotation *symbol__annotation(struct symbol *sym)
421{
422	return (void *)sym - symbol_conf.priv_size;
423}
424
425int addr_map_symbol__inc_samples(struct addr_map_symbol *ams, struct perf_sample *sample,
426				 struct evsel *evsel);
427
428struct annotated_branch *annotation__get_branch(struct annotation *notes);
429
430int addr_map_symbol__account_cycles(struct addr_map_symbol *ams,
431				    struct addr_map_symbol *start,
432				    unsigned cycles,
433				    struct evsel *evsel,
434				    u64 br_cntr);
435
436int hist_entry__inc_addr_samples(struct hist_entry *he, struct perf_sample *sample,
437				 struct evsel *evsel, u64 addr);
438
439struct annotated_source *symbol__hists(struct symbol *sym, int nr_hists);
440void symbol__annotate_zero_histograms(struct symbol *sym);
441
442int symbol__annotate(struct map_symbol *ms,
443		     struct evsel *evsel,
444		     struct arch **parch);
445int symbol__annotate2(struct map_symbol *ms,
446		      struct evsel *evsel,
447		      struct arch **parch);
448
449enum symbol_disassemble_errno {
450	SYMBOL_ANNOTATE_ERRNO__SUCCESS		= 0,
451
452	/*
453	 * Choose an arbitrary negative big number not to clash with standard
454	 * errno since SUS requires the errno has distinct positive values.
455	 * See 'Issue 6' in the link below.
456	 *
457	 * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html
458	 */
459	__SYMBOL_ANNOTATE_ERRNO__START		= -10000,
460
461	SYMBOL_ANNOTATE_ERRNO__NO_VMLINUX	= __SYMBOL_ANNOTATE_ERRNO__START,
462	SYMBOL_ANNOTATE_ERRNO__NO_LIBOPCODES_FOR_BPF,
463	SYMBOL_ANNOTATE_ERRNO__ARCH_INIT_CPUID_PARSING,
464	SYMBOL_ANNOTATE_ERRNO__ARCH_INIT_REGEXP,
465	SYMBOL_ANNOTATE_ERRNO__BPF_INVALID_FILE,
466	SYMBOL_ANNOTATE_ERRNO__BPF_MISSING_BTF,
467	SYMBOL_ANNOTATE_ERRNO__COULDNT_DETERMINE_FILE_TYPE,
468
469	__SYMBOL_ANNOTATE_ERRNO__END,
470};
471
472int symbol__strerror_disassemble(struct map_symbol *ms, int errnum, char *buf, size_t buflen);
473
474void symbol__annotate_zero_histogram(struct symbol *sym, struct evsel *evsel);
475void symbol__annotate_decay_histogram(struct symbol *sym, struct evsel *evsel);
476void annotated_source__purge(struct annotated_source *as);
477
478int map_symbol__annotation_dump(struct map_symbol *ms, struct evsel *evsel,
479				struct hist_entry *he);
480
481bool ui__has_annotation(void);
482
483int hist_entry__annotate_printf(struct hist_entry *he, struct evsel *evsel);
484int hist_entry__tty_annotate(struct hist_entry *he, struct evsel *evsel);
485int hist_entry__tty_annotate2(struct hist_entry *he, struct evsel *evsel);
486
487void annotation_options__init(void);
488void annotation_options__exit(void);
489
490void annotation_config__init(void);
491
492int annotate_parse_percent_type(const struct option *opt, const char *_str,
493				int unset);
494
495int annotate_check_args(void);
496
497/**
498 * struct annotated_op_loc - Location info of instruction operand
499 * @reg1: First register in the operand
500 * @reg2: Second register in the operand
501 * @offset: Memory access offset in the operand
502 * @segment: Segment selector register
503 * @mem_ref: Whether the operand accesses memory
504 * @multi_regs: Whether the second register is used
505 * @imm: Whether the operand is an immediate value (in offset)
506 */
507struct annotated_op_loc {
508	int reg1;
509	int reg2;
510	int offset;
511	u8 segment;
512	bool mem_ref;
513	bool multi_regs;
514	bool imm;
515};
516
517enum annotated_insn_ops {
518	INSN_OP_SOURCE = 0,
519	INSN_OP_TARGET = 1,
520
521	INSN_OP_MAX,
522};
523
524enum annotated_x86_segment {
525	INSN_SEG_NONE = 0,
526
527	INSN_SEG_X86_CS,
528	INSN_SEG_X86_DS,
529	INSN_SEG_X86_ES,
530	INSN_SEG_X86_FS,
531	INSN_SEG_X86_GS,
532	INSN_SEG_X86_SS,
533};
534
535/**
536 * struct annotated_insn_loc - Location info of instruction
537 * @ops: Array of location info for source and target operands
538 */
539struct annotated_insn_loc {
540	struct annotated_op_loc ops[INSN_OP_MAX];
541};
542
543#define for_each_insn_op_loc(insn_loc, i, op_loc)			\
544	for (i = INSN_OP_SOURCE, op_loc = &(insn_loc)->ops[i];		\
545	     i < INSN_OP_MAX;						\
546	     i++, op_loc++)
547
548/* Get detailed location info in the instruction */
549int annotate_get_insn_location(struct arch *arch, struct disasm_line *dl,
550			       struct annotated_insn_loc *loc);
551
552/* Returns a data type from the sample instruction (if any) */
553struct annotated_data_type *hist_entry__get_data_type(struct hist_entry *he);
554
555struct annotated_item_stat {
556	struct list_head list;
557	char *name;
558	int good;
559	int bad;
560};
561extern struct list_head ann_insn_stat;
562
563/* Calculate PC-relative address */
564u64 annotate_calc_pcrel(struct map_symbol *ms, u64 ip, int offset,
565			struct disasm_line *dl);
566
567/**
568 * struct annotated_basic_block - Basic block of instructions
569 * @list: List node
570 * @begin: start instruction in the block
571 * @end: end instruction in the block
572 */
573struct annotated_basic_block {
574	struct list_head list;
575	struct disasm_line *begin;
576	struct disasm_line *end;
577};
578
579/* Get a list of basic blocks from src to dst addresses */
580int annotate_get_basic_blocks(struct symbol *sym, s64 src, s64 dst,
581			      struct list_head *head);
582
583void debuginfo_cache__delete(void);
584
585int annotation_br_cntr_entry(char **str, int br_cntr_nr, u64 *br_cntr,
586			     int num_aggr, struct evsel *evsel);
587int annotation_br_cntr_abbr_list(char **str, struct evsel *evsel, bool header);
588
589int evsel__get_arch(struct evsel *evsel, struct arch **parch);
590#endif	/* __PERF_ANNOTATE_H */