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