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