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
58typedef const void *pmcstat_interned_string;
59struct pmc_plugins;
60
61enum pmcstat_state {
62	PMCSTAT_FINISHED = 0,
63	PMCSTAT_EXITING  = 1,
64	PMCSTAT_RUNNING  = 2
65};
66
67struct 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
82struct pmcstat_target {
83	SLIST_ENTRY(pmcstat_target) pt_next;
84	pid_t		pt_pid;
85};
86
87struct 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
148struct 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
163enum 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
171struct 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
210extern 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 */
219struct 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 */
230struct 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
249struct 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};
256extern 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
263struct 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};
272extern LIST_HEAD(pmcstat_pmcs, pmcstat_pmcrecord) pmcstat_pmcs; /* PMC list */
273
274struct 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 */
307struct 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
321int pmcstat_symbol_compare(const void *a, const void *b);
322struct pmcstat_symbol *pmcstat_symbol_search(struct pmcstat_image *image,
323    uintfptr_t addr);
324void pmcstat_image_add_symbols(struct pmcstat_image *image, Elf *e,
325    Elf_Scn *scn, GElf_Shdr *sh);
326
327const char *pmcstat_string_unintern(pmcstat_interned_string _is);
328pmcstat_interned_string pmcstat_string_intern(const char *_s);
329int pmcstat_string_compute_hash(const char *s);
330pmcstat_interned_string pmcstat_string_lookup(const char *_s);
331void pmcstat_image_get_elf_params(struct pmcstat_image *image, struct pmcstat_args *args);
332
333struct pmcstat_image *
334    pmcstat_image_from_path(pmcstat_interned_string internedpath,
335    int iskernelmodule, struct pmcstat_args *args,
336    struct pmc_plugins *plugins);
337int pmcstat_string_lookup_hash(pmcstat_interned_string _is);
338
339void 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
344void pmcstat_image_link(struct pmcstat_process *_pp,
345    struct pmcstat_image *_i, uintfptr_t _lpc);
346
347void pmcstat_process_aout_exec(struct pmcstat_process *_pp,
348    struct pmcstat_image *_image, uintfptr_t _entryaddr);
349void 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);
353void pmcstat_image_determine_type(struct pmcstat_image *_image, struct pmcstat_args *args);
354void pmcstat_image_get_aout_params(struct pmcstat_image *_image, struct pmcstat_args *args);
355struct pmcstat_pcmap *pmcstat_process_find_map(struct pmcstat_process *_p,
356    uintfptr_t _pc);
357void pmcstat_initialize_logging(struct pmcstat_process **pmcstat_kernproc,
358    struct pmcstat_args *args, struct pmc_plugins *plugins,
359    int *pmcstat_npmcs, int *pmcstat_mergepmc);
360void pmcstat_shutdown_logging(struct pmcstat_args *args,
361    struct pmc_plugins *plugins,
362    struct pmcstat_stats *pmcstat_stats);
363struct pmcstat_process *pmcstat_process_lookup(pid_t _pid, int _allocate);
364void pmcstat_clone_event_descriptor(struct pmcstat_ev *ev, const cpuset_t *cpumask, struct pmcstat_args *args);
365
366void pmcstat_create_process(int *pmcstat_sockpair, struct pmcstat_args *args, int pmcstat_kq);
367void pmcstat_start_process(int *pmcstat_sockpair);
368
369void pmcstat_attach_pmcs(struct pmcstat_args *args);
370struct pmcstat_symbol *pmcstat_symbol_search_by_name(struct pmcstat_process *pp, const char *pi_name, const char *name, uintptr_t *, uintptr_t *);
371
372void pmcstat_string_initialize(void);
373void pmcstat_string_shutdown(void);
374
375int 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
383int pmcstat_open_log(const char *_p, int _mode);
384int pmcstat_close_log(struct pmcstat_args *args);
385
386__END_DECLS
387
388#endif /* !_LIBPMCSTAT_H_ */
389