tools/perf/Documentation/perf-dlfilter.txt

   1 perf-dlfilter(1)
   2 ================
   3
   4 NAME
   5 ----
   6 perf-dlfilter - Filter sample events using a dynamically loaded shared
   7 object file
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'perf script' [--dlfilter file.so ] [ --dlarg arg ]...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 This option is used to process data through a custom filter provided by a
  18 dynamically loaded shared object file. Arguments can be passed using --dlarg
  19 and retrieved using perf_dlfilter_fns.args().
  20
  21 If 'file.so' does not contain "/", then it will be found either in the current
  22 directory, or perf tools exec path which is ~/libexec/perf-core/dlfilters for
  23 a local build and install (refer perf --exec-path), or the dynamic linker
  24 paths.
  25
  26 API
  27 ---
  28
  29 The API for filtering consists of the following:
  30
  31 [source,c]
  32 ----
  33 #include <perf/perf_dlfilter.h>
  34
  35 struct perf_dlfilter_fns perf_dlfilter_fns;
  36
  37 int start(void **data, void *ctx);
  38 int stop(void *data, void *ctx);
  39 int filter_event(void *data, const struct perf_dlfilter_sample *sample, void *ctx);
  40 int filter_event_early(void *data, const struct perf_dlfilter_sample *sample, void *ctx);
  41 const char *filter_description(const char **long_description);
  42 ----
  43
  44 If implemented, 'start' will be called at the beginning, before any
  45 calls to 'filter_event' or 'filter_event_early'. Return 0 to indicate success,
  46 or return a negative error code. '*data' can be assigned for use by other
  47 functions. 'ctx' is needed for calls to perf_dlfilter_fns, but most
  48 perf_dlfilter_fns are not valid when called from 'start'.
  49
  50 If 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
  52 return a negative error code. 'data' is set by 'start'. 'ctx' is needed
  53 for calls to perf_dlfilter_fns, but most perf_dlfilter_fns are not valid
  54 when called from 'stop'.
  55
  56 If implemented, 'filter_event' will be called for each sample event.
  57 Return 0 to keep the sample event, 1 to filter it out, or return a negative
  58 error 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
  62 internal filtering.
  63
  64 If implemented, 'filter_description' should return a one-line description
  65 of the filter, and optionally a longer description.
  66
  67 Do not assume the 'sample' argument is valid (dereferenceable)
  68 after 'filter_event' and 'filter_event_early' return.
  69
  70 Do not assume data referenced by pointers in struct perf_dlfilter_sample
  71 is valid (dereferenceable) after 'filter_event' and 'filter_event_early' return.
  72
  73 The perf_dlfilter_sample structure
  74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  75
  76 'filter_event' and 'filter_event_early' are passed a perf_dlfilter_sample
  77 structure, 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  */
  83 struct 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
 121 Note: '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.
 123 PERF_DLFILTER_HAS_MACHINE_PID will be defined if they are present at compile time.
 124 For example:
 125 [source,c]
 126 ----
 127 #include <perf/perf_dlfilter.h>
 128 #include <stddef.h>
 129 #include <stdbool.h>
 130
 131 static 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
 141 The perf_dlfilter_fns structure
 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 143
 144 The 'perf_dlfilter_fns' structure is populated with function pointers when the
 145 file is loaded. The functions can be called by 'filter_event' or
 146 'filter_event_early'.
 147
 148 [source,c]
 149 ----
 150 struct 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
 171 before calling. Returns 0 on success, -1 otherwise. Call al_cleanup() (if present,
 172 see 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)
 183 after resolve_address() to free any associated resources.
 184
 185 Do not assume pointers obtained via perf_dlfilter_fns are valid (dereferenceable)
 186 after 'filter_event' and 'filter_event_early' return.
 187
 188 The perf_dlfilter_al structure
 189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 190
 191 The 'perf_dlfilter_al' structure contains information about an address.
 192
 193 [source,c]
 194 ----
 195 /*
 196  * Address location (as per perf script)
 197  */
 198 struct 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
 218 Do not assume data referenced by pointers in struct perf_dlfilter_al
 219 is valid (dereferenceable) after 'filter_event' and 'filter_event_early' return.
 220
 221 perf_dlfilter_sample flags
 222 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 223
 224 The 'flags' member of 'perf_dlfilter_sample' corresponds with the flags field
 225 of perf script. The bits of the flags are as follows:
 226
 227 [source,c]
 228 ----
 229 /* Definitions for perf_dlfilter_sample flags */
 230 enum {
 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
 247 EXAMPLE
 248 -------
 249
 250 Filter out everything except branches from "foo" to "bar":
 251
 252 [source,c]
 253 ----
 254 #include <perf/perf_dlfilter.h>
 255 #include <string.h>
 256
 257 struct perf_dlfilter_fns perf_dlfilter_fns;
 258
 259 int 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
 279 To build the shared object, assuming perf has been installed for the local user
 280 i.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
 285 To use the filter with perf script:
 286
 287         perf script --dlfilter dlfilter-example.so
 288
 289 NOTES
 290 -----
 291
 292 The dlfilter .so file will be dependent on shared libraries. If those change,
 293 it may be necessary to rebuild the .so. Also there may be unexpected results
 294 if the .so uses different versions of the shared libraries that perf uses.
 295 Versions can be checked using the ldd command.
 296
 297 SEE ALSO
 298 --------
 299 linkperf:perf-script[1]