Commit c46bf3bd authored by Namhyung Kim's avatar Namhyung Kim Committed by Arnaldo Carvalho de Melo
Browse files

perf record: Update documentation for BPF filters 



Add more description and examples.

Signed-off-by: default avatarNamhyung Kim <namhyung@kernel.org>
Cc: Adrian Hunter <adrian.hunter@intel.com>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Hao Luo <haoluo@google.com>
Cc: Ian Rogers <irogers@google.com>
Cc: Ingo Molnar <mingo@kernel.org>
Cc: James Clark <james.clark@arm.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Leo Yan <leo.yan@linaro.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Ravi Bangoria <ravi.bangoria@amd.com>
Cc: Song Liu <song@kernel.org>
Cc: Stephane Eranian <eranian@google.com>
Cc: bpf@vger.kernel.org
Link: https://lore.kernel.org/r/20230314234237.3008956-2-namhyung@kernel.org


Signed-off-by: default avatarArnaldo Carvalho de Melo <acme@redhat.com>
parent 4310551b

tools/perf/Documentation/perf-record.txt

+46 −1
Original line number Diff line number Diff line
@@ -183,7 +183,52 @@ OPTIONS 


	A BPF filter can access the sample data and make a decision based on the

	data.  Users need to set an appropriate sample type to use the BPF

	filter.

	filter.  BPF filters need root privilege.



	The sample data field can be specified in lower case letter.  Multiple

	filters can be separated with comma.  For example,



	  --filter 'period > 1000, cpu == 1'

	or

	  --filter 'mem_op == load || mem_op == store, mem_lvl > l1'



	The former filter only accept samples with period greater than 1000 AND

	CPU number is 1.  The latter one accepts either load and store memory

	operations but it should have memory level above the L1.  Since the

	mem_op and mem_lvl fields come from the (memory) data_source, it'd only

	work with some events which set the data_source field.



	Also user should request to collect that information (with -d option in

	the above case).  Otherwise, the following message will be shown.



	  $ sudo perf record -e cycles --filter 'mem_op == load'

	  Error: cycles event does not have PERF_SAMPLE_DATA_SRC

	   Hint: please add -d option to perf record.

	  failed to set filter "BPF" on event cycles with 22 (Invalid argument)



	Essentially the BPF filter expression is:



	  <term> <operator> <value> (("," | "||") <term> <operator> <value>)*



	The <term> can be one of:

	  ip, id, tid, pid, cpu, time, addr, period, txn, weight, phys_addr,

	  code_pgsz, data_pgsz, weight1, weight2, weight3, ins_lat, retire_lat,

	  p_stage_cyc, mem_op, mem_lvl, mem_snoop, mem_remote, mem_lock,

	  mem_dtlb, mem_blk, mem_hops



	The <operator> can be one of:

	  ==, !=, >, >=, <, <=, &



	The <value> can be one of:

	  <number> (for any term)

	  na, load, store, pfetch, exec (for mem_op)

	  l1, l2, l3, l4, cxl, io, any_cache, lfb, ram, pmem (for mem_lvl)

	  na, none, hit, miss, hitm, fwd, peer (for mem_snoop)

	  remote (for mem_remote)

	  na, locked (for mem_locked)

	  na, l1_hit, l1_miss, l2_hit, l2_miss, any_hit, any_miss, walk, fault (for mem_dtlb)

	  na, by_data, by_addr (for mem_blk)

	  hops0, hops1, hops2, hops3 (for mem_hops)



--exclude-perf::

	Don't record events issued by perf itself. This option should follow