1perf-dlfilter(1)
  2================
  3
  4NAME
  5----
  6perf-dlfilter - Filter sample events using a dynamically loaded shared
  7object file
  8
  9SYNOPSIS
 10--------
 11[verse]
 12'perf script' [--dlfilter file.so ] [ --dlarg arg ]...
 13
 14DESCRIPTION
 15-----------
 16
 17This option is used to process data through a custom filter provided by a
 18dynamically loaded shared object file. Arguments can be passed using --dlarg
 19and retrieved using perf_dlfilter_fns.args().
 20
 21If 'file.so' does not contain "/", then it will be found either in the current
 22directory, or perf tools exec path which is ~/libexec/perf-core/dlfilters for
 23a local build and install (refer perf --exec-path), or the dynamic linker
 24paths.
 25
 26API
 27---
 28
 29The API for filtering consists of the following:
 30
 31[source,c]
 32----
 33#include <perf/perf_dlfilter.h>
 34
 35struct perf_dlfilter_fns perf_dlfilter_fns;
 36
 37int start(void **data, void *ctx);
 38int stop(void *data, void *ctx);
 39int filter_event(void *data, const struct perf_dlfilter_sample *sample, void *ctx);
 40int filter_event_early(void *data, const struct perf_dlfilter_sample *sample, void *ctx);
 41const char *filter_description(const char **long_description);
 42----
 43
 44If implemented, 'start' will be called at the beginning, before any
 45calls to 'filter_event' or 'filter_event_early'. Return 0 to indicate success,
 46or return a negative error code. '*data' can be assigned for use by other
 47functions. 'ctx' is needed for calls to perf_dlfilter_fns, but most
 48perf_dlfilter_fns are not valid when called from 'start'.
 49
 50If implemented, 'stop' will be called at the end, after any calls to
 51'filter_event' or 'filter_event_early'. Return 0 to indicate success, or
 52return a negative error code. 'data' is set by 'start'. 'ctx' is needed
 53for calls to perf_dlfilter_fns, but most perf_dlfilter_fns are not valid
 54when called from 'stop'.
 55
 56If implemented, 'filter_event' will be called for each sample event.
 57Return 0 to keep the sample event, 1 to filter it out, or return a negative
 58error code. 'data' is set by 'start'. 'ctx' is needed for calls to
 59'perf_dlfilter_fns'.
 60
 61'filter_event_early' is the same as 'filter_event' except it is called before
 62internal filtering.
 63
 64If implemented, 'filter_description' should return a one-line description
 65of the filter, and optionally a longer description.
 66
 67Do not assume the 'sample' argument is valid (dereferenceable)
 68after 'filter_event' and 'filter_event_early' return.
 69
 70Do not assume data referenced by pointers in struct perf_dlfilter_sample
 71is valid (dereferenceable) after 'filter_event' and 'filter_event_early' return.
 72
 73The perf_dlfilter_sample structure
 74~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 75
 76'filter_event' and 'filter_event_early' are passed a perf_dlfilter_sample
 77structure, which contains the following fields:
 78[source,c]
 79----
 80/*
 81 * perf sample event information (as per perf script and <linux/perf_event.h>)
 82 */
 83struct perf_dlfilter_sample {
 84	__u32 size; /* Size of this structure (for compatibility checking) */
 85	__u16 ins_lat;		/* Refer PERF_SAMPLE_WEIGHT_TYPE in <linux/perf_event.h> */
 86	__u16 p_stage_cyc;	/* Refer PERF_SAMPLE_WEIGHT_TYPE in <linux/perf_event.h> */
 87	__u64 ip;
 88	__s32 pid;
 89	__s32 tid;
 90	__u64 time;
 91	__u64 addr;
 92	__u64 id;
 93	__u64 stream_id;
 94	__u64 period;
 95	__u64 weight;		/* Refer PERF_SAMPLE_WEIGHT_TYPE in <linux/perf_event.h> */
 96	__u64 transaction;	/* Refer PERF_SAMPLE_TRANSACTION in <linux/perf_event.h> */
 97	__u64 insn_cnt;	/* For instructions-per-cycle (IPC) */
 98	__u64 cyc_cnt;		/* For instructions-per-cycle (IPC) */
 99	__s32 cpu;
100	__u32 flags;		/* Refer PERF_DLFILTER_FLAG_* above */
101	__u64 data_src;		/* Refer PERF_SAMPLE_DATA_SRC in <linux/perf_event.h> */
102	__u64 phys_addr;	/* Refer PERF_SAMPLE_PHYS_ADDR in <linux/perf_event.h> */
103	__u64 data_page_size;	/* Refer PERF_SAMPLE_DATA_PAGE_SIZE in <linux/perf_event.h> */
104	__u64 code_page_size;	/* Refer PERF_SAMPLE_CODE_PAGE_SIZE in <linux/perf_event.h> */
105	__u64 cgroup;		/* Refer PERF_SAMPLE_CGROUP in <linux/perf_event.h> */
106	__u8  cpumode;		/* Refer CPUMODE_MASK etc in <linux/perf_event.h> */
107	__u8  addr_correlates_sym; /* True => resolve_addr() can be called */
108	__u16 misc;		/* Refer perf_event_header in <linux/perf_event.h> */
109	__u32 raw_size;		/* Refer PERF_SAMPLE_RAW in <linux/perf_event.h> */
110	const void *raw_data;	/* Refer PERF_SAMPLE_RAW in <linux/perf_event.h> */
111	__u64 brstack_nr;	/* Number of brstack entries */
112	const struct perf_branch_entry *brstack; /* Refer <linux/perf_event.h> */
113	__u64 raw_callchain_nr;	/* Number of raw_callchain entries */
114	const __u64 *raw_callchain; /* Refer <linux/perf_event.h> */
115	const char *event;
116	__s32 machine_pid;
117	__s32 vcpu;
118};
119----
120
121Note: 'machine_pid' and 'vcpu' are not original members, but were added together later.
122'size' can be used to determine their presence at run time.
123PERF_DLFILTER_HAS_MACHINE_PID will be defined if they are present at compile time.
124For example:
125[source,c]
126----
127#include <perf/perf_dlfilter.h>
128#include <stddef.h>
129#include <stdbool.h>
130
131static inline bool have_machine_pid(const struct perf_dlfilter_sample *sample)
132{
133#ifdef PERF_DLFILTER_HAS_MACHINE_PID
134	return sample->size >= offsetof(struct perf_dlfilter_sample, vcpu) + sizeof(sample->vcpu);
135#else
136	return false;
137#endif
138}
139----
140
141The perf_dlfilter_fns structure
142~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143
144The 'perf_dlfilter_fns' structure is populated with function pointers when the
145file is loaded. The functions can be called by 'filter_event' or
146'filter_event_early'.
147
148[source,c]
149----
150struct perf_dlfilter_fns {
151	const struct perf_dlfilter_al *(*resolve_ip)(void *ctx);
152	const struct perf_dlfilter_al *(*resolve_addr)(void *ctx);
153	char **(*args)(void *ctx, int *dlargc);
154	__s32 (*resolve_address)(void *ctx, __u64 address, struct perf_dlfilter_al *al);
155	const __u8 *(*insn)(void *ctx, __u32 *length);
156	const char *(*srcline)(void *ctx, __u32 *line_number);
157	struct perf_event_attr *(*attr)(void *ctx);
158	__s32 (*object_code)(void *ctx, __u64 ip, void *buf, __u32 len);
159	void (*al_cleanup)(void *ctx, struct perf_dlfilter_al *al);
160	void *(*reserved[119])(void *);
161};
162----
163
164'resolve_ip' returns information about ip.
165
166'resolve_addr' returns information about addr (if addr_correlates_sym).
167
168'args' returns arguments from --dlarg options.
169
170'resolve_address' provides information about 'address'. al->size must be set
171before calling. Returns 0 on success, -1 otherwise. Call al_cleanup() (if present,
172see below) when 'al' data is no longer needed.
173
174'insn' returns instruction bytes and length.
175
176'srcline' return source file name and line number.
177
178'attr' returns perf_event_attr, refer <linux/perf_event.h>.
179
180'object_code' reads object code and returns the number of bytes read.
181
182'al_cleanup' must be called (if present, so check perf_dlfilter_fns.al_cleanup != NULL)
183after resolve_address() to free any associated resources.
184
185Do not assume pointers obtained via perf_dlfilter_fns are valid (dereferenceable)
186after 'filter_event' and 'filter_event_early' return.
187
188The perf_dlfilter_al structure
189~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190
191The 'perf_dlfilter_al' structure contains information about an address.
192
193[source,c]
194----
195/*
196 * Address location (as per perf script)
197 */
198struct perf_dlfilter_al {
199	__u32 size; /* Size of this structure (for compatibility checking) */
200	__u32 symoff;
201	const char *sym;
202	__u64 addr; /* Mapped address (from dso) */
203	__u64 sym_start;
204	__u64 sym_end;
205	const char *dso;
206	__u8  sym_binding; /* STB_LOCAL, STB_GLOBAL or STB_WEAK, refer <elf.h> */
207	__u8  is_64_bit; /* Only valid if dso is not NULL */
208	__u8  is_kernel_ip; /* True if in kernel space */
209	__u32 buildid_size;
210	__u8 *buildid;
211	/* Below members are only populated by resolve_ip() */
212	__u8 filtered; /* true if this sample event will be filtered out */
213	const char *comm;
214	void *priv; /* Private data. Do not change */
215};
216----
217
218Do not assume data referenced by pointers in struct perf_dlfilter_al
219is valid (dereferenceable) after 'filter_event' and 'filter_event_early' return.
220
221perf_dlfilter_sample flags
222~~~~~~~~~~~~~~~~~~~~~~~~~~
223
224The 'flags' member of 'perf_dlfilter_sample' corresponds with the flags field
225of perf script. The bits of the flags are as follows:
226
227[source,c]
228----
229/* Definitions for perf_dlfilter_sample flags */
230enum {
231	PERF_DLFILTER_FLAG_BRANCH	= 1ULL << 0,
232	PERF_DLFILTER_FLAG_CALL		= 1ULL << 1,
233	PERF_DLFILTER_FLAG_RETURN	= 1ULL << 2,
234	PERF_DLFILTER_FLAG_CONDITIONAL	= 1ULL << 3,
235	PERF_DLFILTER_FLAG_SYSCALLRET	= 1ULL << 4,
236	PERF_DLFILTER_FLAG_ASYNC	= 1ULL << 5,
237	PERF_DLFILTER_FLAG_INTERRUPT	= 1ULL << 6,
238	PERF_DLFILTER_FLAG_TX_ABORT	= 1ULL << 7,
239	PERF_DLFILTER_FLAG_TRACE_BEGIN	= 1ULL << 8,
240	PERF_DLFILTER_FLAG_TRACE_END	= 1ULL << 9,
241	PERF_DLFILTER_FLAG_IN_TX	= 1ULL << 10,
242	PERF_DLFILTER_FLAG_VMENTRY	= 1ULL << 11,
243	PERF_DLFILTER_FLAG_VMEXIT	= 1ULL << 12,
244};
245----
246
247EXAMPLE
248-------
249
250Filter out everything except branches from "foo" to "bar":
251
252[source,c]
253----
254#include <perf/perf_dlfilter.h>
255#include <string.h>
256
257struct perf_dlfilter_fns perf_dlfilter_fns;
258
259int filter_event(void *data, const struct perf_dlfilter_sample *sample, void *ctx)
260{
261	const struct perf_dlfilter_al *al;
262	const struct perf_dlfilter_al *addr_al;
263
264	if (!sample->ip || !sample->addr_correlates_sym)
265		return 1;
266
267	al = perf_dlfilter_fns.resolve_ip(ctx);
268	if (!al || !al->sym || strcmp(al->sym, "foo"))
269		return 1;
270
271	addr_al = perf_dlfilter_fns.resolve_addr(ctx);
272	if (!addr_al || !addr_al->sym || strcmp(addr_al->sym, "bar"))
273		return 1;
274
275	return 0;
276}
277----
278
279To build the shared object, assuming perf has been installed for the local user
280i.e. perf_dlfilter.h is in ~/include/perf :
281
282	gcc -c -I ~/include -fpic dlfilter-example.c
283	gcc -shared -o dlfilter-example.so dlfilter-example.o
284
285To use the filter with perf script:
286
287	perf script --dlfilter dlfilter-example.so
288
289NOTES
290-----
291
292The dlfilter .so file will be dependent on shared libraries. If those change,
293it may be necessary to rebuild the .so. Also there may be unexpected results
294if the .so uses different versions of the shared libraries that perf uses.
295Versions can be checked using the ldd command.
296
297SEE ALSO
298--------
299linkperf:perf-script[1]