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