[PATCH 1/3] perf intel-pt: Rename intel-pt.txt and put it in man page format
From: Adrian Hunter
Date: Wed Mar 11 2020 - 08:21:25 EST
Make the Intel PT documentation into a man page.
Signed-off-by: Adrian Hunter <adrian.hunter@xxxxxxxxx>
---
.../{intel-pt.txt => perf-intel-pt.txt} | 57 +++++++++++--------
1 file changed, 33 insertions(+), 24 deletions(-)
rename tools/perf/Documentation/{intel-pt.txt => perf-intel-pt.txt} (98%)
diff --git a/tools/perf/Documentation/intel-pt.txt b/tools/perf/Documentation/perf-intel-pt.txt
similarity index 98%
rename from tools/perf/Documentation/intel-pt.txt
rename to tools/perf/Documentation/perf-intel-pt.txt
index 2cf2d9e9d0da..7d743a98a9c1 100644
--- a/tools/perf/Documentation/intel-pt.txt
+++ b/tools/perf/Documentation/perf-intel-pt.txt
@@ -1,8 +1,17 @@
-Intel Processor Trace
-=====================
+perf-intel-pt(1)
+================
-Overview
-========
+NAME
+----
+perf-intel-pt - Support for Intel Processor Trace within perf tools
+
+SYNOPSIS
+--------
+[verse]
+'perf record' -e intel_pt//
+
+DESCRIPTION
+-----------
Intel Processor Trace (Intel PT) is an extension of Intel Architecture that
collects information about software execution such as control flow, execution
@@ -43,7 +52,7 @@ vary depending on the use-case and architecture.
Quickstart
-==========
+----------
It is important to start small. That is because it is easy to capture vastly
more data than can possibly be processed.
@@ -156,10 +165,10 @@ for more details.
perf record
-===========
+-----------
new event
----------
+~~~~~~~~~
The Intel PT kernel driver creates a new PMU for Intel PT. PMU events are
selected by providing the PMU name followed by the "config" separated by slashes.
@@ -245,7 +254,7 @@ perf_event_attr is displayed if the -vv option is used e.g.
config terms
-------------
+~~~~~~~~~~~~
The June 2015 version of Intel 64 and IA-32 Architectures Software Developer
Manuals, Chapter 36 Intel Processor Trace, defined new Intel PT features.
@@ -435,7 +444,7 @@ pwr_evt Enable power events. The power events provide information about
AUX area sampling option
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
To select Intel PT "sampling" the AUX area sampling option can be used:
@@ -485,7 +494,7 @@ but the tool validates that the sample size is not greater than 60KiB.
new snapshot option
--------------------
+~~~~~~~~~~~~~~~~~~~
The difference between full trace and snapshot from the kernel's perspective is
that in full trace we don't overwrite trace data that the user hasn't collected
@@ -514,7 +523,7 @@ The snapshot size is displayed if the option -vv is used e.g.
new auxtrace mmap size option
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Intel PT buffer size is specified by an addition to the -m option e.g.
@@ -547,7 +556,7 @@ The mmap size and auxtrace mmap size are displayed if the -vv option is used e.g
Intel PT modes of operation
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Intel PT can be used in 2 modes:
full-trace mode
@@ -577,7 +586,7 @@ The 2 modes cannot be used together.
Buffer handling
----------------
+~~~~~~~~~~~~~~~
There may be buffer limitations (i.e. single ToPa entry) which means that actual
buffer sizes are limited to powers of 2 up to 4MiB (MAX_ORDER). In order to
@@ -601,7 +610,7 @@ data.
Intel PT and build ids
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
By default "perf record" post-processes the event stream to find all build ids
for executables for all addresses sampled. Deliberately, Intel PT is not
@@ -619,7 +628,7 @@ If the perf.data file contains Intel PT data, that is the same as:
Snapshot mode and event disabling
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to make a snapshot, the intel_pt event is disabled using an IOCTL,
namely PERF_EVENT_IOC_DISABLE. However doing that can also disable the
@@ -642,7 +651,7 @@ To run the test:
perf record modes (nothing new here)
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
perf record essentially operates in one of three modes:
per thread
@@ -668,7 +677,7 @@ mode by using the --per-thread option.
Privileged vs non-privileged users
-----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unless /proc/sys/kernel/perf_event_paranoid is set to -1, unprivileged users
have memory limits imposed upon them. That affects what buffer sizes they can
@@ -697,7 +706,7 @@ be possible to decode Intel PT in per-cpu mode.
sched_switch tracepoint
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
The sched_switch tracepoint is used to provide side-band data for Intel PT
decoding in kernels where the PERF_RECORD_SWITCH metadata event isn't
@@ -783,14 +792,14 @@ cannot be matched against the Intel PT trace.
perf script
-===========
+-----------
By default, perf script will decode trace data found in the perf.data file.
This can be further controlled by new option --itrace.
New --itrace option
--------------------
+~~~~~~~~~~~~~~~~~~~
Having no option is the same as
@@ -913,7 +922,7 @@ at the beginning. This is useful to ignore initialization code.
skips the first million instructions.
dump option
------------
+~~~~~~~~~~~
perf script has an option (-D) to "dump" the events i.e. display the binary
data.
@@ -931,7 +940,7 @@ To disable the display of Intel PT packets, combine the -D option with
perf report
-===========
+-----------
By default, perf report will decode trace data found in the perf.data file.
This can be further controlled by new option --itrace exactly the same as
@@ -939,7 +948,7 @@ perf script, with the exception that the default is --itrace=igxe.
perf inject
-===========
+-----------
perf inject also accepts the --itrace option in which case tracing data is
removed and replaced with the synthesized events. e.g.
@@ -977,7 +986,7 @@ that may change in the future if greater use is made of the data.
PEBS via Intel PT
-=================
+-----------------
Some hardware has the feature to redirect PEBS records to the Intel PT trace.
Recording is selected by using the aux-output config term e.g.
--
2.17.1