Skip to contentSkip to conversation

perf mem: Update documentation for new options

PATCH Applied Namhyung Kim 3 participants 3 messages Aug 2, 2024 – Aug 5, 2024 perf events

lore
Share & tools
lore

Namhyung Kim

author maintainer
#0 lore raw

PATCH 1/1 perf mem: Update documentation for new options

Add a common options section and move some items to the section. Also add description of new options to report options.

---
 tools/perf/Documentation/perf-mem.txt | 94 ++++++++++++++++++---------
 1 file changed, 63 insertions(+), 31 deletions(-)
tools/perf/Documentation/perf-mem.txt +63 -31
index 47456b212e99..8a1bd9ff0f86 100644
@@ -28,15 +28,8 @@ and kernel support is required. See linkperf:perf-arm-spe[1] for a setup guide.
 Due to the statistical nature of SPE sampling, not every memory operation will
 be sampled.
 
-OPTIONS
--------
-<command>...::
-	Any command you can specify in a shell.
-
--i::
---input=<file>::
-	Input file name.
-
+COMMON OPTIONS
+--------------
 -f::
 --force::
 	Don't do ownership validation
@@ -45,24 +38,9 @@ OPTIONS
 --type=<type>::
 	Select the memory operation type: load or store (default: load,store)
 
--D::
---dump-raw-samples::
-	Dump the raw decoded samples on the screen in a format that is easy to parse with
-	one sample per line.
-
--x::
---field-separator=<separator>::
-	Specify the field separator used when dump raw samples (-D option). By default,
-	The separator is the space character.
-
--C::
---cpu=<cpu>::
-	Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
-        comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. Default
-        is to monitor all CPUS.
--U::
---hide-unresolved::
-	Only display entries resolved to a symbol.
+-v::
+--verbose::
+	Be more verbose (show counter open errors, etc)
 
 -p::
 --phys-data::
@@ -73,6 +51,9 @@ OPTIONS
 
 RECORD OPTIONS
 --------------
+<command>...::
+	Any command you can specify in a shell.
+
 -e::
 --event <event>::
 	Event selector. Use 'perf mem record -e list' to list available events.
@@ -85,14 +66,65 @@ RECORD OPTIONS
 --all-user::
 	Configure all used events to run in user space.
 
--v::
---verbose::
-	Be more verbose (show counter open errors, etc)
-
 --ldlat <n>::
 	Specify desired latency for loads event. Supported on Intel and Arm64
 	processors only. Ignored on other archs.
 
+REPORT OPTIONS
+--------------
+-i::
+--input=<file>::
+	Input file name.
+
+-C::
+--cpu=<cpu>::
+	Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
+        comma-separated list with no space: 0,1. Ranges of CPUs are specified with -
+	like 0-2. Default is to monitor all CPUS.
+
+-D::
+--dump-raw-samples::
+	Dump the raw decoded samples on the screen in a format that is easy to parse with
+	one sample per line.
+
+-s::
+--sort=<key>::
+	Group result by given key(s) - multiple keys can be specified
+	in CSV format.  The keys are specific to memory samples are:
+	symbol_daddr, symbol_iaddr, dso_daddr, locked, tlb, mem, snoop,
+	dcacheline, phys_daddr, data_page_size, blocked.
+
+	- symbol_daddr: name of data symbol being executed on at the time of sample
+	- symbol_iaddr: name of code symbol being executed on at the time of sample
+	- dso_daddr: name of library or module containing the data being executed
+	             on at the time of the sample
+	- locked: whether the bus was locked at the time of the sample
+	- tlb: type of tlb access for the data at the time of the sample
+	- mem: type of memory access for the data at the time of the sample
+	- snoop: type of snoop (if any) for the data at the time of the sample
+	- dcacheline: the cacheline the data address is on at the time of the sample
+	- phys_daddr: physical address of data being executed on at the time of sample
+	- data_page_size: the data page size of data being executed on at the time of sample
+	- blocked: reason of blocked load access for the data at the time of the sample
+
+	And the default sort keys are changed to local_weight, mem, sym, dso,
+	symbol_daddr, dso_daddr, snoop, tlb, locked, blocked, local_ins_lat.
+
+-T::
+--type-profile::
+	Show data-type profile result instead of code symbols.  This requires
+	the debug information and it will change the default sort keys to:
+	mem, snoop, tlb, type.
+
+-U::
+--hide-unresolved::
+	Only display entries resolved to a symbol.
+
+-x::
+--field-separator=<separator>::
+	Specify the field separator used when dump raw samples (-D option). By default,
+	The separator is the space character.
+
 In addition, for report all perf report options are valid, and for record
 all perf record options.
 
Signature · 1 line
2.46.0.rc2.264.g509ed76dc8-goog
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 5 lines · Namhyung Kim

Add a common options section and move some items to the section. Also add description of new options to report options.

Thanks,
Ian

Quoted 137 lines
---
 tools/perf/Documentation/perf-mem.txt | 94 ++++++++++++++++++---------
 1 file changed, 63 insertions(+), 31 deletions(-)
tools/perf/Documentation/perf-mem.txt +63 -32
index 47456b212e99..8a1bd9ff0f86 100644
@@ -28,15 +28,8 @@ and kernel support is required. See linkperf:perf-arm-spe[1] for a setup guide.
 Due to the statistical nature of SPE sampling, not every memory operation will
 be sampled.
 
-OPTIONS
--------
-<command>...::
-       Any command you can specify in a shell.
-
--i::
---input=<file>::
-       Input file name.
-
+COMMON OPTIONS
+--------------
 -f::
 --force::
        Don't do ownership validation
@@ -45,24 +38,9 @@ OPTIONS
 --type=<type>::
        Select the memory operation type: load or store (default: load,store)
 
--D::
---dump-raw-samples::
-       Dump the raw decoded samples on the screen in a format that is easy to parse with
-       one sample per line.
-
--x::
---field-separator=<separator>::
-       Specify the field separator used when dump raw samples (-D option). By default,
-       The separator is the space character.
-
--C::
---cpu=<cpu>::
-       Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
-        comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. Default
-        is to monitor all CPUS.
--U::
---hide-unresolved::
-       Only display entries resolved to a symbol.
+-v::
+--verbose::
+       Be more verbose (show counter open errors, etc)
 
 -p::
 --phys-data::
@@ -73,6 +51,9 @@ OPTIONS
 
 RECORD OPTIONS
 --------------
+<command>...::
+       Any command you can specify in a shell.
+
 -e::
 --event <event>::
        Event selector. Use 'perf mem record -e list' to list available events.
@@ -85,14 +66,65 @@ RECORD OPTIONS
 --all-user::
        Configure all used events to run in user space.
 
--v::
---verbose::
-       Be more verbose (show counter open errors, etc)
-
 --ldlat <n>::
        Specify desired latency for loads event. Supported on Intel and Arm64
        processors only. Ignored on other archs.
 
+REPORT OPTIONS
+--------------
+-i::
+--input=<file>::
+       Input file name.
+
+-C::
+--cpu=<cpu>::
+       Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
+        comma-separated list with no space: 0,1. Ranges of CPUs are specified with -
+       like 0-2. Default is to monitor all CPUS.
+
+-D::
+--dump-raw-samples::
+       Dump the raw decoded samples on the screen in a format that is easy to parse with
+       one sample per line.
+
+-s::
+--sort=<key>::
+       Group result by given key(s) - multiple keys can be specified
+       in CSV format.  The keys are specific to memory samples are:
+       symbol_daddr, symbol_iaddr, dso_daddr, locked, tlb, mem, snoop,
+       dcacheline, phys_daddr, data_page_size, blocked.
+
+       - symbol_daddr: name of data symbol being executed on at the time of sample
+       - symbol_iaddr: name of code symbol being executed on at the time of sample
+       - dso_daddr: name of library or module containing the data being executed
+                    on at the time of the sample
+       - locked: whether the bus was locked at the time of the sample
+       - tlb: type of tlb access for the data at the time of the sample
+       - mem: type of memory access for the data at the time of the sample
+       - snoop: type of snoop (if any) for the data at the time of the sample
+       - dcacheline: the cacheline the data address is on at the time of the sample
+       - phys_daddr: physical address of data being executed on at the time of sample
+       - data_page_size: the data page size of data being executed on at the time of sample
+       - blocked: reason of blocked load access for the data at the time of the sample
+
+       And the default sort keys are changed to local_weight, mem, sym, dso,
+       symbol_daddr, dso_daddr, snoop, tlb, locked, blocked, local_ins_lat.
+
+-T::
+--type-profile::
+       Show data-type profile result instead of code symbols.  This requires
+       the debug information and it will change the default sort keys to:
+       mem, snoop, tlb, type.
+
+-U::
+--hide-unresolved::
+       Only display entries resolved to a symbol.
+
+-x::
+--field-separator=<separator>::
+       Specify the field separator used when dump raw samples (-D option). By default,
+       The separator is the space character.
+
 In addition, for report all perf report options are valid, and for record
 all perf record options.
 
--

2.46.0.rc2.264.g509ed76dc8-goog