lib/libpmcstat/libpmcstat.h

   1 /*-
   2  * Copyright (c) 2005-2007, Joseph Koshy
   3  * Copyright (c) 2007 The FreeBSD Foundation
   4  * All rights reserved.
   5  *
   6  * Portions of this software were developed by A. Joseph Koshy under
   7  * sponsorship from the FreeBSD Foundation and Google, Inc.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in the
  16  *    documentation and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28  * SUCH DAMAGE.
  29  *
  30  * $FreeBSD$
  31  */
  32
  33 #ifndef _LIBPMCSTAT_H_
  34 #define _LIBPMCSTAT_H_
  35
  36 #include <sys/_cpuset.h>
  37 #include <sys/queue.h>
  38
  39 #include <stdio.h>
  40 #include <gelf.h>
  41
  42 #define PMCSTAT_ALLOCATE                1
  43
  44 #define NSOCKPAIRFD                     2
  45 #define PARENTSOCKET                    0
  46 #define CHILDSOCKET                     1
  47
  48 #define PMCSTAT_OPEN_FOR_READ           0
  49 #define PMCSTAT_OPEN_FOR_WRITE          1
  50 #define READPIPEFD                      0
  51 #define WRITEPIPEFD                     1
  52 #define NPIPEFD                         2
  53
  54 #define PMCSTAT_NHASH                   256
  55 #define PMCSTAT_HASH_MASK               0xFF
  56 #define DEFAULT_SAMPLE_COUNT            65536
  57
  58 typedef const void *pmcstat_interned_string;
  59 struct pmc_plugins;
  60
  61 enum pmcstat_state {
  62         PMCSTAT_FINISHED = 0,
  63         PMCSTAT_EXITING  = 1,
  64         PMCSTAT_RUNNING  = 2
  65 };
  66
  67 struct pmcstat_ev {
  68         STAILQ_ENTRY(pmcstat_ev) ev_next;
  69         int             ev_count; /* associated count if in sampling mode */
  70         uint32_t        ev_cpu;   /* cpus for this event */
  71         int             ev_cumulative;  /* show cumulative counts */
  72         int             ev_flags; /* PMC_F_* */
  73         int             ev_fieldskip;   /* #leading spaces */
  74         int             ev_fieldwidth;  /* print width */
  75         enum pmc_mode   ev_mode;  /* desired mode */
  76         char           *ev_name;  /* (derived) event name */
  77         pmc_id_t        ev_pmcid; /* allocated ID */
  78         pmc_value_t     ev_saved; /* for incremental counts */
  79         char           *ev_spec;  /* event specification */
  80 };
  81
  82 struct pmcstat_target {
  83         SLIST_ENTRY(pmcstat_target) pt_next;
  84         pid_t           pt_pid;
  85 };
  86
  87 struct pmcstat_args {
  88         int     pa_flags;               /* argument flags */
  89 #define FLAG_HAS_TARGET                 0x00000001      /* process target */
  90 #define FLAG_HAS_WAIT_INTERVAL          0x00000002      /* -w secs */
  91 #define FLAG_HAS_OUTPUT_LOGFILE         0x00000004      /* -O file or pipe */
  92 #define FLAG_HAS_COMMANDLINE            0x00000008      /* command */
  93 #define FLAG_HAS_SAMPLING_PMCS          0x00000010      /* -S or -P */
  94 #define FLAG_HAS_COUNTING_PMCS          0x00000020      /* -s or -p */
  95 #define FLAG_HAS_PROCESS_PMCS           0x00000040      /* -P or -p */
  96 #define FLAG_HAS_SYSTEM_PMCS            0x00000080      /* -S or -s */
  97 #define FLAG_HAS_PIPE                   0x00000100      /* implicit log */
  98 #define FLAG_READ_LOGFILE               0x00000200      /* -R file */
  99 #define FLAG_DO_GPROF                   0x00000400      /* -g */
 100 #define FLAG_HAS_SAMPLESDIR             0x00000800      /* -D dir */
 101 #define FLAG_HAS_KERNELPATH             0x00001000      /* -k kernel */
 102 #define FLAG_DO_PRINT                   0x00002000      /* -o */
 103 #define FLAG_DO_CALLGRAPHS              0x00004000      /* -G or -F */
 104 #define FLAG_DO_ANNOTATE                0x00008000      /* -m */
 105 #define FLAG_DO_TOP                     0x00010000      /* -T */
 106 #define FLAG_DO_ANALYSIS                0x00020000      /* -g or -G or -m or -T */
 107 #define FLAGS_HAS_CPUMASK               0x00040000      /* -c */
 108 #define FLAG_HAS_DURATION               0x00080000      /* -l secs */
 109 #define FLAG_DO_WIDE_GPROF_HC           0x00100000      /* -e */
 110 #define FLAG_SKIP_TOP_FN_RES            0x00200000      /* -I */
 111 #define FLAG_FILTER_THREAD_ID           0x00400000      /* -L */
 112
 113         int     pa_required;            /* required features */
 114         int     pa_pplugin;             /* pre-processing plugin */
 115         int     pa_plugin;              /* analysis plugin */
 116         int     pa_verbosity;           /* verbosity level */
 117         FILE    *pa_printfile;          /* where to send printed output */
 118         int     pa_logfd;               /* output log file */
 119         char    *pa_inputpath;          /* path to input log */
 120         char    *pa_outputpath;         /* path to output log */
 121         void    *pa_logparser;          /* log file parser */
 122         const char      *pa_fsroot;     /* FS root where executables reside */
 123         char    *pa_kernel;             /* pathname of the kernel */
 124         const char      *pa_samplesdir; /* directory for profile files */
 125         const char      *pa_mapfilename;/* mapfile name */
 126         FILE    *pa_graphfile;          /* where to send the callgraph */
 127         int     pa_graphdepth;          /* print depth for callgraphs */
 128         double  pa_interval;            /* printing interval in seconds */
 129         cpuset_t        pa_cpumask;     /* filter for CPUs analysed */
 130         int     pa_ctdumpinstr;         /* dump instructions with calltree */
 131         int     pa_topmode;             /* delta or accumulative */
 132         int     pa_toptty;              /* output to tty or file */
 133         int     pa_topcolor;            /* terminal support color */
 134         int     pa_mergepmc;            /* merge PMC with same name */
 135         double  pa_duration;            /* time duration */
 136         uint32_t pa_tid;
 137         int     pa_argc;
 138         char    **pa_argv;
 139         STAILQ_HEAD(, pmcstat_ev) pa_events;
 140         SLIST_HEAD(, pmcstat_target) pa_targets;
 141 };
 142
 143 /*
 144  * Each function symbol tracked by pmcstat(8).
 145  */
 146
 147 struct pmcstat_symbol {
 148         pmcstat_interned_string ps_name;
 149         uint64_t        ps_start;
 150         uint64_t        ps_end;
 151 };
 152
 153 /*
 154  * A 'pmcstat_image' structure describes an executable program on
 155  * disk.  'pi_execpath' is a cookie representing the pathname of
 156  * the executable.  'pi_start' and 'pi_end' are the least and greatest
 157  * virtual addresses for the text segments in the executable.
 158  * 'pi_gmonlist' contains a linked list of gmon.out files associated
 159  * with this image.
 160  */
 161
 162 enum pmcstat_image_type {
 163         PMCSTAT_IMAGE_UNKNOWN = 0,      /* never looked at the image */
 164         PMCSTAT_IMAGE_INDETERMINABLE,   /* can't tell what the image is */
 165         PMCSTAT_IMAGE_ELF32,            /* ELF 32 bit object */
 166         PMCSTAT_IMAGE_ELF64,            /* ELF 64 bit object */
 167         PMCSTAT_IMAGE_AOUT              /* AOUT object */
 168 };
 169
 170 struct pmcstat_image {
 171         LIST_ENTRY(pmcstat_image) pi_next;      /* hash link */
 172         pmcstat_interned_string pi_execpath;    /* cookie */
 173         pmcstat_interned_string pi_samplename;  /* sample path name */
 174         pmcstat_interned_string pi_fullpath;    /* path to FS object */
 175         pmcstat_interned_string pi_name;        /* display name */
 176
 177         enum pmcstat_image_type pi_type;        /* executable type */
 178
 179         /*
 180          * Executables have pi_start and pi_end; these are zero
 181          * for shared libraries.
 182          */
 183         uintfptr_t      pi_start;       /* start address (inclusive) */
 184         uintfptr_t      pi_end;         /* end address (exclusive) */
 185         uintfptr_t      pi_entry;       /* entry address */
 186         uintfptr_t      pi_vaddr;       /* virtual address where loaded */
 187         int             pi_isdynamic;   /* whether a dynamic object */
 188         int             pi_iskernelmodule;
 189         pmcstat_interned_string pi_dynlinkerpath; /* path in .interp */
 190
 191         /* All symbols associated with this object. */
 192         struct pmcstat_symbol *pi_symbols;
 193         size_t          pi_symcount;
 194
 195         /* Handle to addr2line for this image. */
 196         FILE *pi_addr2line;
 197
 198         /*
 199          * Plugins private data
 200          */
 201
 202         /* gprof:
 203          * An image can be associated with one or more gmon.out files;
 204          * one per PMC.
 205          */
 206         LIST_HEAD(,pmcstat_gmonfile) pi_gmlist;
 207 };
 208
 209 extern LIST_HEAD(pmcstat_image_hash_list, pmcstat_image) pmcstat_image_hash[PMCSTAT_NHASH];
 210
 211 /*
 212  * A simple implementation of interned strings.  Each interned string
 213  * is assigned a unique address, so that subsequent string compares
 214  * can be done by a simple pointer comparison instead of using
 215  * strcmp().  This speeds up hash table lookups and saves memory if
 216  * duplicate strings are the norm.
 217  */
 218 struct pmcstat_string {
 219         LIST_ENTRY(pmcstat_string)      ps_next;        /* hash link */
 220         int             ps_len;
 221         int             ps_hash;
 222         char            *ps_string;
 223 };
 224
 225 /*
 226  * A 'pmcstat_pcmap' structure maps a virtual address range to an
 227  * underlying 'pmcstat_image' descriptor.
 228  */
 229 struct pmcstat_pcmap {
 230         TAILQ_ENTRY(pmcstat_pcmap) ppm_next;
 231         uintfptr_t      ppm_lowpc;
 232         uintfptr_t      ppm_highpc;
 233         struct pmcstat_image *ppm_image;
 234 };
 235
 236 /*
 237  * A 'pmcstat_process' structure models processes.  Each process is
 238  * associated with a set of pmcstat_pcmap structures that map
 239  * addresses inside it to executable objects.  This set is implemented
 240  * as a list, kept sorted in ascending order of mapped addresses.
 241  *
 242  * 'pp_pid' holds the pid of the process.  When a process exits, the
 243  * 'pp_isactive' field is set to zero, but the process structure is
 244  * not immediately reclaimed because there may still be samples in the
 245  * log for this process.
 246  */
 247
 248 struct pmcstat_process {
 249         LIST_ENTRY(pmcstat_process) pp_next;    /* hash-next */
 250         pid_t                   pp_pid;         /* associated pid */
 251         int                     pp_isactive;    /* whether active */
 252         uintfptr_t              pp_entryaddr;   /* entry address */
 253         TAILQ_HEAD(,pmcstat_pcmap) pp_map;      /* address range map */
 254 };
 255 extern LIST_HEAD(pmcstat_process_hash_list, pmcstat_process) pmcstat_process_hash[PMCSTAT_NHASH];
 256
 257 /*
 258  * 'pmcstat_pmcrecord' is a mapping from PMC ids to human-readable
 259  * names.
 260  */
 261
 262 struct pmcstat_pmcrecord {
 263         LIST_ENTRY(pmcstat_pmcrecord)   pr_next;
 264         pmc_id_t                        pr_pmcid;
 265         int                             pr_pmcin;
 266         pmcstat_interned_string         pr_pmcname;
 267         int                             pr_samples;
 268         int                             pr_dubious_frames;
 269         struct pmcstat_pmcrecord        *pr_merge;
 270 };
 271 extern LIST_HEAD(pmcstat_pmcs, pmcstat_pmcrecord) pmcstat_pmcs; /* PMC list */
 272
 273 struct pmc_plugins {
 274         const char *pl_name;
 275
 276         /* configure */
 277         int (*pl_configure)(char *opt);
 278
 279         /* init and shutdown */
 280         int (*pl_init)(void);
 281         void (*pl_shutdown)(FILE *mf);
 282
 283         /* sample processing */
 284         void (*pl_process)(struct pmcstat_process *pp,
 285             struct pmcstat_pmcrecord *pmcr, uint32_t nsamples,
 286             uintfptr_t *cc, int usermode, uint32_t cpu);
 287
 288         /* image */
 289         void (*pl_initimage)(struct pmcstat_image *pi);
 290         void (*pl_shutdownimage)(struct pmcstat_image *pi);
 291
 292         /* pmc */
 293         void (*pl_newpmc)(pmcstat_interned_string ps,
 294                 struct pmcstat_pmcrecord *pr);
 295
 296         /* top display */
 297         void (*pl_topdisplay)(void);
 298
 299         /* top keypress */
 300         int (*pl_topkeypress)(int c, void *w);
 301 };
 302
 303 /*
 304  * Misc. statistics
 305  */
 306 struct pmcstat_stats {
 307         int ps_exec_aout;       /* # a.out executables seen */
 308         int ps_exec_elf;        /* # elf executables seen */
 309         int ps_exec_errors;     /* # errors processing executables */
 310         int ps_exec_indeterminable; /* # unknown executables seen */
 311         int ps_samples_total;   /* total number of samples processed */
 312         int ps_samples_skipped; /* #samples filtered out for any reason */
 313         int ps_samples_unknown_offset;  /* #samples of rank 0 not in a map */
 314         int ps_samples_indeterminable;  /* #samples in indeterminable images */
 315         int ps_samples_unknown_function;/* #samples with unknown function at offset */
 316         int ps_callchain_dubious_frames;/* #dubious frame pointers seen */
 317 };
 318
 319 __BEGIN_DECLS
 320 int pmcstat_symbol_compare(const void *a, const void *b);
 321 struct pmcstat_symbol *pmcstat_symbol_search(struct pmcstat_image *image,
 322     uintfptr_t addr);
 323 void pmcstat_image_add_symbols(struct pmcstat_image *image, Elf *e,
 324     Elf_Scn *scn, GElf_Shdr *sh);
 325
 326 const char *pmcstat_string_unintern(pmcstat_interned_string _is);
 327 pmcstat_interned_string pmcstat_string_intern(const char *_s);
 328 int pmcstat_string_compute_hash(const char *s);
 329 pmcstat_interned_string pmcstat_string_lookup(const char *_s);
 330 void pmcstat_image_get_elf_params(struct pmcstat_image *image, struct pmcstat_args *args);
 331
 332 struct pmcstat_image *
 333     pmcstat_image_from_path(pmcstat_interned_string internedpath,
 334     int iskernelmodule, struct pmcstat_args *args,
 335     struct pmc_plugins *plugins);
 336 int pmcstat_string_lookup_hash(pmcstat_interned_string _is);
 337
 338 void pmcstat_process_elf_exec(struct pmcstat_process *_pp,
 339     struct pmcstat_image *_image, uintfptr_t _entryaddr,
 340     struct pmcstat_args *args, struct pmc_plugins *plugins,
 341     struct pmcstat_stats *pmcstat_stats);
 342
 343 void pmcstat_image_link(struct pmcstat_process *_pp,
 344     struct pmcstat_image *_i, uintfptr_t _lpc);
 345
 346 void pmcstat_process_aout_exec(struct pmcstat_process *_pp,
 347     struct pmcstat_image *_image, uintfptr_t _entryaddr);
 348 void pmcstat_process_exec(struct pmcstat_process *_pp,
 349     pmcstat_interned_string _path, uintfptr_t _entryaddr,
 350     struct pmcstat_args *args, struct pmc_plugins *plugins,
 351     struct pmcstat_stats *pmcstat_stats);
 352 void pmcstat_image_determine_type(struct pmcstat_image *_image, struct pmcstat_args *args);
 353 void pmcstat_image_get_aout_params(struct pmcstat_image *_image, struct pmcstat_args *args);
 354 struct pmcstat_pcmap *pmcstat_process_find_map(struct pmcstat_process *_p,
 355     uintfptr_t _pc);
 356 void pmcstat_initialize_logging(struct pmcstat_process **pmcstat_kernproc,
 357     struct pmcstat_args *args, struct pmc_plugins *plugins,
 358     int *pmcstat_npmcs, int *pmcstat_mergepmc);
 359 void pmcstat_shutdown_logging(struct pmcstat_args *args,
 360     struct pmc_plugins *plugins,
 361     struct pmcstat_stats *pmcstat_stats);
 362 struct pmcstat_process *pmcstat_process_lookup(pid_t _pid, int _allocate);
 363 void pmcstat_clone_event_descriptor(struct pmcstat_ev *ev, const cpuset_t *cpumask, struct pmcstat_args *args);
 364
 365 void pmcstat_create_process(int *pmcstat_sockpair, struct pmcstat_args *args, int pmcstat_kq);
 366 void pmcstat_start_process(int *pmcstat_sockpair);
 367
 368 void pmcstat_attach_pmcs(struct pmcstat_args *args);
 369 struct pmcstat_symbol *pmcstat_symbol_search_by_name(struct pmcstat_process *pp, const char *pi_name, const char *name, uintptr_t *, uintptr_t *);
 370
 371 void pmcstat_string_initialize(void);
 372 void pmcstat_string_shutdown(void);
 373
 374 int pmcstat_analyze_log(struct pmcstat_args *args,
 375     struct pmc_plugins *plugins,
 376     struct pmcstat_stats *pmcstat_stats,
 377     struct pmcstat_process *pmcstat_kernproc,
 378     int pmcstat_mergepmc,
 379     int *pmcstat_npmcs,
 380     int *ps_samples_period);
 381
 382 int pmcstat_open_log(const char *_p, int _mode);
 383 int pmcstat_close_log(struct pmcstat_args *args);
 384
 385 uint64_t pmcstat_pmu_sample_rate_get(const char *);
 386
 387 __END_DECLS
 388
 389 #endif /* !_LIBPMCSTAT_H_ */