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