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 #include "branch.h"
  18 #include "evsel.h"
  19
  20 struct hist_browser_timer;
  21 struct hist_entry;
  22 struct map;
  23 struct map_symbol;
  24 struct addr_map_symbol;
  25 struct option;
  26 struct perf_sample;
  27 struct symbol;
  28 struct 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
  37 enum 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
  45 struct 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
  74 extern struct annotation_options annotate_opts;
  75
  76 enum {
  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
  84 struct annotation;
  85
  86 struct sym_hist_entry {
  87         u64             nr_samples;
  88         u64             period;
  89 };
  90
  91 enum {
  92         PERCENT_HITS_LOCAL,
  93         PERCENT_HITS_GLOBAL,
  94         PERCENT_PERIOD_LOCAL,
  95         PERCENT_PERIOD_GLOBAL,
  96         PERCENT_MAX,
  97 };
  98
  99 struct annotation_data {
 100         double                   percent[PERCENT_MAX];
 101         double                   percent_sum;
 102         struct sym_hist_entry    he;
 103 };
 104
 105 struct cycles_info {
 106         float                    ipc;
 107         u64                      avg;
 108         u64                      max;
 109         u64                      min;
 110 };
 111
 112 struct 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
 132 struct 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
 143 extern const char * const perf_disassembler__strs[];
 144
 145 void annotation_line__add(struct annotation_line *al, struct list_head *head);
 146
 147 static 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
 153 static 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
 168 static 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  */
 177 static 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  */
 186 bool disasm_line__is_valid_local_jump(struct disasm_line *dl, struct symbol *sym);
 187
 188 struct annotation_line *
 189 annotation_line__next(struct annotation_line *pos, struct list_head *head);
 190
 191 struct 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
 202 void annotation_line__write(struct annotation_line *al, struct annotation *notes,
 203                             struct annotation_write_ops *ops);
 204
 205 int __annotation__scnprintf_samples_period(struct annotation *notes,
 206                                            char *bf, size_t size,
 207                                            struct evsel *evsel,
 208                                            bool show_freq);
 209
 210 size_t disasm__fprintf(struct list_head *head, FILE *fp);
 211 void symbol__calc_percent(struct symbol *sym, struct evsel *evsel);
 212
 213 /**
 214  * struct sym_hist - symbol histogram information for an event
 215  *
 216  * @nr_samples: Total number of samples.
 217  * @period: Sum of sample periods.
 218  */
 219 struct sym_hist {
 220         u64                   nr_samples;
 221         u64                   period;
 222 };
 223
 224 /**
 225  * struct cyc_hist - (CPU) cycle histogram for a basic block
 226  *
 227  * @start: Start address of current block (if known).
 228  * @cycles: Sum of cycles for the longest basic block.
 229  * @cycles_aggr: Total cycles for this address.
 230  * @cycles_max: Max cycles for this address.
 231  * @cycles_min: Min cycles for this address.
 232  * @cycles_spark: History of cycles for the longest basic block.
 233  * @num: Number of samples for the longest basic block.
 234  * @num_aggr: Total number of samples for this address.
 235  * @have_start: Whether the current branch info has a start address.
 236  * @reset: Number of resets due to a different start address.
 237  *
 238  * If sample has branch_stack and cycles info, it can construct basic blocks
 239  * between two adjacent branches.  It'd have start and end addresses but
 240  * sometimes the start address may not be available.  So the cycles are
 241  * accounted at the end address.  If multiple basic blocks end at the same
 242  * address, it will take the longest one.
 243  *
 244  * The @start, @cycles, @cycles_spark and @num fields are used for the longest
 245  * block only.  Other fields are used for all cases.
 246  *
 247  * See __symbol__account_cycles().
 248  */
 249 struct cyc_hist {
 250         u64     start;
 251         u64     cycles;
 252         u64     cycles_aggr;
 253         u64     cycles_max;
 254         u64     cycles_min;
 255         s64     cycles_spark[NUM_SPARKS];
 256         u32     num;
 257         u32     num_aggr;
 258         u8      have_start;
 259         /* 1 byte padding */
 260         u16     reset;
 261 };
 262
 263 /**
 264  * struct annotated_source - symbols with hits have this attached as in annotation
 265  *
 266  * @source: List head for annotated_line (embeded in disasm_line).
 267  * @histograms: Array of symbol histograms per event to maintain the total number
 268  *              of samples and period.
 269  * @nr_histograms: This may not be the same as evsel->evlist->core.nr_entries if
 270  *                we have more than a group in a evlist, where we will want
 271  *                to see each group separately, that is why symbol__annotate2()
 272  *                sets src->nr_histograms to evsel->nr_members.
 273  * @samples: Hash map of sym_hist_entry.  Keyed by event index and offset in symbol.
 274  * @nr_events: Number of events in the current output.
 275  * @nr_entries: Number of annotated_line in the source list.
 276  * @nr_asm_entries: Number of annotated_line with actual asm instruction in the
 277  *                  source list.
 278  * @max_jump_sources: Maximum number of jump instructions targeting to the same
 279  *                    instruction.
 280  * @widths: Precalculated width of each column in the TUI output.
 281  *
 282  * disasm_lines are allocated, percentages calculated and all sorted by percentage
 283  * when the annotation is about to be presented, so the percentages are for
 284  * one of the entries in the histogram array, i.e. for the event/counter being
 285  * presented. It is deallocated right after symbol__{tui,tty,etc}_annotate
 286  * returns.
 287  */
 288 struct annotated_source {
 289         struct list_head        source;
 290         struct sym_hist         *histograms;
 291         struct hashmap          *samples;
 292         int                     nr_histograms;
 293         int                     nr_events;
 294         int                     nr_entries;
 295         int                     nr_asm_entries;
 296         int                     max_jump_sources;
 297         u64                     start;
 298         struct {
 299                 u8              addr;
 300                 u8              jumps;
 301                 u8              target;
 302                 u8              min_addr;
 303                 u8              max_addr;
 304                 u8              max_ins_name;
 305                 u16             max_line_len;
 306         } widths;
 307 };
 308
 309 struct annotation_line *annotated_source__get_line(struct annotated_source *src,
 310                                                    s64 offset);
 311
 312 /* A branch counter once saturated */
 313 #define ANNOTATION__BR_CNTR_SATURATED_FLAG      (1ULL << 63)
 314
 315 /**
 316  * struct annotated_branch - basic block and IPC information for a symbol.
 317  *
 318  * @hit_cycles: Total executed cycles.
 319  * @hit_insn: Total number of instructions executed.
 320  * @total_insn: Number of instructions in the function.
 321  * @cover_insn: Number of distinct, actually executed instructions.
 322  * @cycles_hist: Array of cyc_hist for each instruction.
 323  * @max_coverage: Maximum number of covered basic block (used for block-range).
 324  * @br_cntr: Array of the occurrences of events (branch counters) during a block.
 325  *
 326  * This struct is used by two different codes when the sample has branch stack
 327  * and cycles information.  annotation__compute_ipc() calculates average IPC
 328  * using @hit_insn / @hit_cycles.  The actual coverage can be calculated using
 329  * @cover_insn / @total_insn.  The @cycles_hist can give IPC for each (longest)
 330  * basic block ends at the given address.
 331  * process_basic_block() calculates coverage of instructions (or basic blocks)
 332  * in the function.
 333  */
 334 struct annotated_branch {
 335         u64                     hit_cycles;
 336         u64                     hit_insn;
 337         unsigned int            total_insn;
 338         unsigned int            cover_insn;
 339         struct cyc_hist         *cycles_hist;
 340         u64                     max_coverage;
 341         u64                     *br_cntr;
 342 };
 343
 344 struct LOCKABLE annotation {
 345         struct annotated_source *src;
 346         struct annotated_branch *branch;
 347 };
 348
 349 static inline void annotation__init(struct annotation *notes __maybe_unused)
 350 {
 351 }
 352 void annotation__exit(struct annotation *notes);
 353
 354 void annotation__lock(struct annotation *notes) EXCLUSIVE_LOCK_FUNCTION(*notes);
 355 void annotation__unlock(struct annotation *notes) UNLOCK_FUNCTION(*notes);
 356 bool annotation__trylock(struct annotation *notes) EXCLUSIVE_TRYLOCK_FUNCTION(true, *notes);
 357
 358 static inline int annotation__cycles_width(struct annotation *notes)
 359 {
 360         if (notes->branch && annotate_opts.show_minmax_cycle)
 361                 return ANNOTATION__IPC_WIDTH + ANNOTATION__MINMAX_CYCLES_WIDTH;
 362
 363         return notes->branch ? ANNOTATION__IPC_WIDTH + ANNOTATION__CYCLES_WIDTH : 0;
 364 }
 365
 366 static inline int annotation__pcnt_width(struct annotation *notes)
 367 {
 368         return (symbol_conf.show_total_period ? 12 : 8) * notes->src->nr_events;
 369 }
 370
 371 static inline bool annotation_line__filter(struct annotation_line *al)
 372 {
 373         return annotate_opts.hide_src_code && al->offset == -1;
 374 }
 375
 376 static inline u8 annotation__br_cntr_width(void)
 377 {
 378         return annotate_opts.show_br_cntr ? ANNOTATION__BR_CNTR_WIDTH : 0;
 379 }
 380
 381 void annotation__update_column_widths(struct annotation *notes);
 382 void annotation__toggle_full_addr(struct annotation *notes, struct map_symbol *ms);
 383
 384 static inline struct sym_hist *annotated_source__histogram(struct annotated_source *src,
 385                                                            const struct evsel *evsel)
 386 {
 387         return &src->histograms[evsel->core.idx];
 388 }
 389
 390 static inline struct sym_hist *annotation__histogram(struct annotation *notes,
 391                                                      const struct evsel *evsel)
 392 {
 393         return annotated_source__histogram(notes->src, evsel);
 394 }
 395
 396 static inline struct sym_hist_entry *
 397 annotated_source__hist_entry(struct annotated_source *src, const struct evsel *evsel, u64 offset)
 398 {
 399         struct sym_hist_entry *entry;
 400         long key = offset << 16 | evsel->core.idx;
 401
 402         if (!hashmap__find(src->samples, key, &entry))
 403                 return NULL;
 404         return entry;
 405 }
 406
 407 static inline struct annotation *symbol__annotation(struct symbol *sym)
 408 {
 409         return (void *)sym - symbol_conf.priv_size;
 410 }
 411
 412 int addr_map_symbol__inc_samples(struct addr_map_symbol *ams, struct perf_sample *sample,
 413                                  struct evsel *evsel);
 414
 415 struct annotated_branch *annotation__get_branch(struct annotation *notes);
 416
 417 int addr_map_symbol__account_cycles(struct addr_map_symbol *ams,
 418                                     struct addr_map_symbol *start,
 419                                     unsigned cycles,
 420                                     struct evsel *evsel,
 421                                     u64 br_cntr);
 422
 423 int hist_entry__inc_addr_samples(struct hist_entry *he, struct perf_sample *sample,
 424                                  struct evsel *evsel, u64 addr);
 425
 426 struct annotated_source *symbol__hists(struct symbol *sym, int nr_hists);
 427 void symbol__annotate_zero_histograms(struct symbol *sym);
 428
 429 int symbol__annotate(struct map_symbol *ms,
 430                      struct evsel *evsel,
 431                      struct arch **parch);
 432 int symbol__annotate2(struct map_symbol *ms,
 433                       struct evsel *evsel,
 434                       struct arch **parch);
 435
 436 enum symbol_disassemble_errno {
 437         SYMBOL_ANNOTATE_ERRNO__SUCCESS          = 0,
 438
 439         /*
 440          * Choose an arbitrary negative big number not to clash with standard
 441          * errno since SUS requires the errno has distinct positive values.
 442          * See 'Issue 6' in the link below.
 443          *
 444          * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html
 445          */
 446         __SYMBOL_ANNOTATE_ERRNO__START          = -10000,
 447
 448         SYMBOL_ANNOTATE_ERRNO__NO_VMLINUX       = __SYMBOL_ANNOTATE_ERRNO__START,
 449         SYMBOL_ANNOTATE_ERRNO__NO_LIBOPCODES_FOR_BPF,
 450         SYMBOL_ANNOTATE_ERRNO__ARCH_INIT_CPUID_PARSING,
 451         SYMBOL_ANNOTATE_ERRNO__ARCH_INIT_REGEXP,
 452         SYMBOL_ANNOTATE_ERRNO__BPF_INVALID_FILE,
 453         SYMBOL_ANNOTATE_ERRNO__BPF_MISSING_BTF,
 454         SYMBOL_ANNOTATE_ERRNO__COULDNT_DETERMINE_FILE_TYPE,
 455
 456         __SYMBOL_ANNOTATE_ERRNO__END,
 457 };
 458
 459 int symbol__strerror_disassemble(struct map_symbol *ms, int errnum, char *buf, size_t buflen);
 460
 461 void symbol__annotate_zero_histogram(struct symbol *sym, struct evsel *evsel);
 462 void symbol__annotate_decay_histogram(struct symbol *sym, struct evsel *evsel);
 463 void annotated_source__purge(struct annotated_source *as);
 464
 465 int map_symbol__annotation_dump(struct map_symbol *ms, struct evsel *evsel);
 466
 467 bool ui__has_annotation(void);
 468
 469 int hist_entry__annotate_printf(struct hist_entry *he, struct evsel *evsel);
 470 int hist_entry__tty_annotate(struct hist_entry *he, struct evsel *evsel);
 471 int hist_entry__tty_annotate2(struct hist_entry *he, struct evsel *evsel);
 472
 473 #ifdef HAVE_SLANG_SUPPORT
 474 int symbol__tui_annotate(struct map_symbol *ms, struct evsel *evsel,
 475                          struct hist_browser_timer *hbt);
 476 #else
 477 static inline int symbol__tui_annotate(struct map_symbol *ms __maybe_unused,
 478                                 struct evsel *evsel  __maybe_unused,
 479                                 struct hist_browser_timer *hbt __maybe_unused)
 480 {
 481         return 0;
 482 }
 483 #endif
 484
 485 void annotation_options__init(void);
 486 void annotation_options__exit(void);
 487
 488 void annotation_config__init(void);
 489
 490 int annotate_parse_percent_type(const struct option *opt, const char *_str,
 491                                 int unset);
 492
 493 int annotate_check_args(void);
 494
 495 /**
 496  * struct annotated_op_loc - Location info of instruction operand
 497  * @reg1: First register in the operand
 498  * @reg2: Second register in the operand
 499  * @offset: Memory access offset in the operand
 500  * @segment: Segment selector register
 501  * @mem_ref: Whether the operand accesses memory
 502  * @multi_regs: Whether the second register is used
 503  * @imm: Whether the operand is an immediate value (in offset)
 504  */
 505 struct annotated_op_loc {
 506         int reg1;
 507         int reg2;
 508         int offset;
 509         u8 segment;
 510         bool mem_ref;
 511         bool multi_regs;
 512         bool imm;
 513 };
 514
 515 enum annotated_insn_ops {
 516         INSN_OP_SOURCE = 0,
 517         INSN_OP_TARGET = 1,
 518
 519         INSN_OP_MAX,
 520 };
 521
 522 enum annotated_x86_segment {
 523         INSN_SEG_NONE = 0,
 524
 525         INSN_SEG_X86_CS,
 526         INSN_SEG_X86_DS,
 527         INSN_SEG_X86_ES,
 528         INSN_SEG_X86_FS,
 529         INSN_SEG_X86_GS,
 530         INSN_SEG_X86_SS,
 531 };
 532
 533 /**
 534  * struct annotated_insn_loc - Location info of instruction
 535  * @ops: Array of location info for source and target operands
 536  */
 537 struct annotated_insn_loc {
 538         struct annotated_op_loc ops[INSN_OP_MAX];
 539 };
 540
 541 #define for_each_insn_op_loc(insn_loc, i, op_loc)                       \
 542         for (i = INSN_OP_SOURCE, op_loc = &(insn_loc)->ops[i];          \
 543              i < INSN_OP_MAX;                                           \
 544              i++, op_loc++)
 545
 546 /* Get detailed location info in the instruction */
 547 int annotate_get_insn_location(struct arch *arch, struct disasm_line *dl,
 548                                struct annotated_insn_loc *loc);
 549
 550 /* Returns a data type from the sample instruction (if any) */
 551 struct annotated_data_type *hist_entry__get_data_type(struct hist_entry *he);
 552
 553 struct annotated_item_stat {
 554         struct list_head list;
 555         char *name;
 556         int good;
 557         int bad;
 558 };
 559 extern struct list_head ann_insn_stat;
 560
 561 /* Calculate PC-relative address */
 562 u64 annotate_calc_pcrel(struct map_symbol *ms, u64 ip, int offset,
 563                         struct disasm_line *dl);
 564
 565 /**
 566  * struct annotated_basic_block - Basic block of instructions
 567  * @list: List node
 568  * @begin: start instruction in the block
 569  * @end: end instruction in the block
 570  */
 571 struct annotated_basic_block {
 572         struct list_head list;
 573         struct disasm_line *begin;
 574         struct disasm_line *end;
 575 };
 576
 577 /* Get a list of basic blocks from src to dst addresses */
 578 int annotate_get_basic_blocks(struct symbol *sym, s64 src, s64 dst,
 579                               struct list_head *head);
 580
 581 void debuginfo_cache__delete(void);
 582
 583 int annotation_br_cntr_entry(char **str, int br_cntr_nr, u64 *br_cntr,
 584                              int num_aggr, struct evsel *evsel);
 585 int annotation_br_cntr_abbr_list(char **str, struct evsel *evsel, bool header);
 586 #endif  /* __PERF_ANNOTATE_H */