Re: [PATCH v5 57/58] perf Documentation: Update for standalone Python scripts and remove obsolete data

sashiko-bot
2026-04-24T17:30:55Z

Sashiko AI review found 3 potential issue(s):
- [Low] The rewritten `perf-script-python.txt` drastically under-documents the attributes of the `Sample Object`.
- [Low] Obsolete tip referring to the removed '-g' option in tips.txt.
- [Low] Dangling reference to 'perf script report mode' in perf-script.txt.
--

commit 5be26cdce292df0900056c86e7f08c9c434bea21
Author: Ian Rogers <irogers@google.com>

perf Documentation: Update for standalone Python scripts and remove obsolete data

This commit rewrites perf-script-python.txt to describe standalone script
usage with the perf module. It also removes obsolete documentation for the -g
and -s options in perf-script.txt, and drops the obsolete perf-script-perl.txt.

> diff --git a/tools/perf/Documentation/perf-script-python.txt b/tools/perf/Documentation/perf-script-python.txt
> index 27a1cac6fe7638..9293057cee8e2d 100644
> --- a/tools/perf/Documentation/perf-script-python.txt
> +++ b/tools/perf/Documentation/perf-script-python.txt
[ ... ]
> -SUPPORTED FIELDS
> -----------------
> -
> -Currently supported fields:
> -
> -ev_name, comm, id, stream_id, pid, tid, cpu, ip, time, period, phys_addr,
> -addr, symbol, symoff, dso, time_enabled, time_running, values, callchain,
> -brstack, brstacksym, datasrc, datasrc_decode, iregs, uregs,
> -weight, transaction, raw_buf, attr, cpumode.
[ ... ]
> +### Sample Object
>
> +Passed to the callback function in `perf.session`.
>
> +- `evsel`: The event selector (name of the event).
> +- `sample_cpu`: The CPU on which the event occurred.
> +- `sample_time`: The timestamp of the event.
> +- `sample_pid`: The PID of the process.
> +- `sample_tid`: The TID of the thread.
> +- `raw_buf`: Raw buffer containing event specific data.

Does the new documentation intentionally omit the comprehensive list of supported
fields?

The C-extension (tools/perf/util/python.c) still exports many fields like
sample_ip, sample_addr, sample_phys_addr, brstack, and callchain, which are
actively used by scripts (e.g., intel-pt-events.py). The rewritten section
appears to drastically under-document the attributes of the Sample Object.

> diff --git a/tools/perf/Documentation/perf-script.txt b/tools/perf/Documentation/perf-script.txt
> index 200ea25891d88d..93ed1ea704c950 100644
> --- a/tools/perf/Documentation/perf-script.txt
> +++ b/tools/perf/Documentation/perf-script.txt
> @@ -9,10 +9,7 @@ SYNOPSIS
> --------
> [verse]
> 'perf script' [<options>]
> -'perf script' [<options>] record [<record-options>] <command>
> -'perf script' [<options>] report [script-args]
> -'perf script' [<options>] <required-script-args> [<record-options>] <command>
> -'perf script' [<options>] <top-script> [script-args]
> +'perf script' [<options>] [script-args]

Since the concept of 'report mode' has been excised here and in the
DESCRIPTION, should the documentation for the --show-info option in this file
also be updated?

It currently contains the dangling reference: "It can only be used with
the perf script report mode."

> @@ -90,18 +44,7 @@ OPTIONS
> --list=::
> Display a list of available trace scripts.
>
> --s ['lang']::
> ---script=::
> - Process trace data with the given script ([lang]:script[.ext]).
> - If the string 'lang' is specified in place of a script name, a
> - list of supported languages will be displayed instead.
>
> --g::
> ---gen-script=::
> - Generate a starter script. If a language is given then the
> - script is named perf-script.[ext] according to the
> - language. If a file path is given then python is used for
> - files ending '.py' and perl used for files ending '.pl'.

Is it also necessary to remove the obsolete tip from
tools/perf/Documentation/tips.txt?

It still suggests using the removed -g option: "Generate a script for your
data: perf script -g <lang>".

--
Sashiko AI review · https://sashiko.dev/#/patchset/20260424164721.2229025-1-irogers@google.com?part=57