From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pg1-f202.google.com (mail-pg1-f202.google.com [209.85.215.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7546E383C94 for ; Thu, 23 Apr 2026 16:12:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.202 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776960732; cv=none; b=MBBgr2xcYUgwcBJXHjJuheoWji/dYig5PkD6aRlMjbEhhLSg3Bq/hA8xhpCJPjhk62dco8MzWkl/bWakPT8AfEc++LYSHuUbgPNWlFNJMVD+/xEgD1L6cv4Q0pi0JkC47M2Jbxe3j3No2bKaObH89HGplBd21y9epMgF5JR9nEA= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776960732; c=relaxed/simple; bh=6HLu0q+Ode2aBeKTpvJrdQfLrCN5KwhMvetsXqcZQ/w=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=aQOAbvhhXIaeLaaIpXu9OqLYuiZbnMAKpA0zXctyLdPKRsFLgyCskNosFzi57qZ0kT/8Z8EUhDBxAE4HZqf8bJJqiPiRu49KXAOFR4g+/owtp+dwBPwwee0a5xOD3m0okyHMKHRIT/6BtTgOnFmpo2zvWyS6WlULhpQ+MRezv48= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--irogers.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=ZrAKzYkq; arc=none smtp.client-ip=209.85.215.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--irogers.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="ZrAKzYkq" Received: by mail-pg1-f202.google.com with SMTP id 41be03b00d2f7-b6097ca315bso10072861a12.3 for ; Thu, 23 Apr 2026 09:12:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20251104; t=1776960727; x=1777565527; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=dzJhwJJbGMwLgraXuo1AC3xgKYXUNjZLM/wnBJRowp8=; b=ZrAKzYkq5DQudZS+ViqaUloJQIfKiDGT3WsVFItqVHVYJqblEad8mm15xyAWuxshCn CvaUTZEEiEf4QkXavlI5VxbZVj+RG3vZ0n7AzDMNzn329Xx+GZ5jay7Yc408Kv/MY4HG wkQHr/A+hjZlBMrJwCz1c6vY0zmFV5ABnLwXbdbcA0VmWWYToPRxKAYsq3gMXep5QAV6 vwsb3qpAyjJmlC0NTqUxNysCIwYv6uzqlsfHBX4k/K4vMgKxOGLCAjqWkgSJo+J1xpZ5 DHJYYg4B/cSHOu5RR1PsW04kOeZ+vLG0wJWWbKR+GPOkL8BdgXd740wOsFxNZadk4FGU jJUA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1776960727; x=1777565527; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=dzJhwJJbGMwLgraXuo1AC3xgKYXUNjZLM/wnBJRowp8=; b=GJtlpr95HyToyjBaY4a//2tqHWN5ZPjpzNISZ6CcJBhNPZx6AaMvG+3RZTnNc6BzlW iwiYVBp1rela6ie4+jZto6aS+LoLkBZF5knEubycDIqRN2hbbqnQ5ZB3QVqRneUYna6C 9j2bK4N9hOOdUnHWMxgpFdMNekhkNAQNQoWP+lCmhHRbAaE0mKCUZB+ZgoaDo8rFxmPv k0C3lZ0rfVzDbjFvS01iwUd8Rf3Odg7tPcp0y26m9F3CsWOFoftGfGcLAyrKZJc787gr trZkwW1itadiQz1TT3nGgzXBK42f0U/v1K2+VmOe8+qd9UABAtIKZcfC1MoGgIEKVGZP ErzQ== X-Forwarded-Encrypted: i=1; AFNElJ8rI4BY57rcPno54das0Kxvdi/x9c+sKIxgxq1UkvmFPFvn29CTfhWkguUfsZlExqwzCNNhjYNYH8Fe1L0CU0Cm@vger.kernel.org X-Gm-Message-State: AOJu0Yy5lj+2iutfwJDE2SSwTG77w8H/If+qhSJzo2eOc8Q7gLhAbj/L 0T1E4TmxI6NMZbVGSKab/lplPDBdpGBqI0WfT+0zecj9KqAM23QvEcGC9xjlN3E0CjEmf8l8Np4 zg5RjYUiR/A== X-Received: from pgbfq24.prod.google.com ([2002:a05:6a02:2998:b0:c79:3224:837d]) (user=irogers job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6a21:3389:b0:39f:5f19:7de6 with SMTP id adf61e73a8af0-3a08d67bd66mr32192347637.3.1776960726419; Thu, 23 Apr 2026 09:12:06 -0700 (PDT) Date: Thu, 23 Apr 2026 09:10:03 -0700 In-Reply-To: <20260423161006.1762700-1-irogers@google.com> Precedence: bulk X-Mailing-List: linux-perf-users@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20260423035526.1537178-1-irogers@google.com> <20260423161006.1762700-1-irogers@google.com> X-Mailer: git-send-email 2.54.0.rc2.533.g4f5dca5207-goog Message-ID: <20260423161006.1762700-57-irogers@google.com> Subject: [PATCH v3 56/58] perf Documentation: Update for standalone Python scripts and remove obsolete data From: Ian Rogers To: irogers@google.com, acme@kernel.org, adrian.hunter@intel.com, james.clark@linaro.org, leo.yan@linux.dev, namhyung@kernel.org, tmricht@linux.ibm.com Cc: 9erthalion6@gmail.com, adityab1@linux.ibm.com, alexandre.chartre@oracle.com, alice.mei.rogers@gmail.com, ankur.a.arora@oracle.com, ashelat@redhat.com, atrajeev@linux.ibm.com, blakejones@google.com, changbin.du@huawei.com, chuck.lever@oracle.com, collin.funk1@gmail.com, coresight@lists.linaro.org, ctshao@google.com, dapeng1.mi@linux.intel.com, derek.foreman@collabora.com, dsterba@suse.com, gautam@linux.ibm.com, howardchu95@gmail.com, john.g.garry@oracle.com, jolsa@kernel.org, jonathan.cameron@huawei.com, justinstitt@google.com, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, linux-perf-users@vger.kernel.org, mike.leach@arm.com, mingo@redhat.com, morbo@google.com, nathan@kernel.org, nichen@iscas.ac.cn, nick.desaulniers+lkml@gmail.com, pan.deng@intel.com, peterz@infradead.org, ravi.bangoria@amd.com, ricky.ringler@proton.me, stephen.s.brennan@oracle.com, sun.jian.kdev@gmail.com, suzuki.poulose@arm.com, swapnil.sapkal@amd.com, tanze@kylinos.cn, terrelln@fb.com, thomas.falcon@intel.com, tianyou.li@intel.com, tycho@kernel.org, wangyang.guo@intel.com, xiaqinxin@huawei.com, yang.lee@linux.alibaba.com, yuzhuo@google.com, zhiguo.zhou@intel.com, zli94@ncsu.edu Content-Type: text/plain; charset="UTF-8" - Remove documentation for -g and -s options in perf-script.txt. - Remove links to perf-script-perl in perf-script.txt. - Rewrite perf-script-python.txt to describe the new standalone script usage with perf module. - Remove obsolete perf-script-perl.txt. Assisted-by: Gemini:gemini-3.1-pro-preview Signed-off-by: Ian Rogers --- tools/perf/Documentation/perf-script-perl.txt | 216 ------ .../perf/Documentation/perf-script-python.txt | 702 +++--------------- tools/perf/Documentation/perf-script.txt | 70 +- 3 files changed, 95 insertions(+), 893 deletions(-) delete mode 100644 tools/perf/Documentation/perf-script-perl.txt diff --git a/tools/perf/Documentation/perf-script-perl.txt b/tools/perf/Documentation/perf-script-perl.txt deleted file mode 100644 index 5b479f5e62ff..000000000000 --- a/tools/perf/Documentation/perf-script-perl.txt +++ /dev/null @@ -1,216 +0,0 @@ -perf-script-perl(1) -=================== - -NAME ----- -perf-script-perl - Process trace data with a Perl script - -SYNOPSIS --------- -[verse] -'perf script' [-s [Perl]:script[.pl] ] - -DESCRIPTION ------------ - -This perf script option is used to process perf script data using perf's -built-in Perl interpreter. It reads and processes the input file and -displays the results of the trace analysis implemented in the given -Perl script, if any. - -STARTER SCRIPTS ---------------- - -You can avoid reading the rest of this document by running 'perf script --g perl' in the same directory as an existing perf.data trace file. -That will generate a starter script containing a handler for each of -the event types in the trace file; it simply prints every available -field for each event in the trace file. - -You can also look at the existing scripts in -~/libexec/perf-core/scripts/perl for typical examples showing how to -do basic things like aggregate event data, print results, etc. Also, -the check-perf-script.pl script, while not interesting for its results, -attempts to exercise all of the main scripting features. - -EVENT HANDLERS --------------- - -When perf script is invoked using a trace script, a user-defined -'handler function' is called for each event in the trace. If there's -no handler function defined for a given event type, the event is -ignored (or passed to a 'trace_unhandled' function, see below) and the -next event is processed. - -Most of the event's field values are passed as arguments to the -handler function; some of the less common ones aren't - those are -available as calls back into the perf executable (see below). - -As an example, the following perf record command can be used to record -all sched_wakeup events in the system: - - # perf record -a -e sched:sched_wakeup - -Traces meant to be processed using a script should be recorded with -the above option: -a to enable system-wide collection. - -The format file for the sched_wakeup event defines the following fields -(see /sys/kernel/tracing/events/sched/sched_wakeup/format): - ----- - format: - field:unsigned short common_type; - field:unsigned char common_flags; - field:unsigned char common_preempt_count; - field:int common_pid; - - field:char comm[TASK_COMM_LEN]; - field:pid_t pid; - field:int prio; - field:int success; - field:int target_cpu; ----- - -The handler function for this event would be defined as: - ----- -sub sched::sched_wakeup -{ - my ($event_name, $context, $common_cpu, $common_secs, - $common_nsecs, $common_pid, $common_comm, - $comm, $pid, $prio, $success, $target_cpu) = @_; -} ----- - -The handler function takes the form subsystem::event_name. - -The $common_* arguments in the handler's argument list are the set of -arguments passed to all event handlers; some of the fields correspond -to the common_* fields in the format file, but some are synthesized, -and some of the common_* fields aren't common enough to to be passed -to every event as arguments but are available as library functions. - -Here's a brief description of each of the invariant event args: - - $event_name the name of the event as text - $context an opaque 'cookie' used in calls back into perf - $common_cpu the cpu the event occurred on - $common_secs the secs portion of the event timestamp - $common_nsecs the nsecs portion of the event timestamp - $common_pid the pid of the current task - $common_comm the name of the current process - -All of the remaining fields in the event's format file have -counterparts as handler function arguments of the same name, as can be -seen in the example above. - -The above provides the basics needed to directly access every field of -every event in a trace, which covers 90% of what you need to know to -write a useful trace script. The sections below cover the rest. - -SCRIPT LAYOUT -------------- - -Every perf script Perl script should start by setting up a Perl module -search path and 'use'ing a few support modules (see module -descriptions below): - ----- - use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib"; - use lib "./Perf-Trace-Util/lib"; - use Perf::Trace::Core; - use Perf::Trace::Context; - use Perf::Trace::Util; ----- - -The rest of the script can contain handler functions and support -functions in any order. - -Aside from the event handler functions discussed above, every script -can implement a set of optional functions: - -*trace_begin*, if defined, is called before any event is processed and -gives scripts a chance to do setup tasks: - ----- - sub trace_begin - { - } ----- - -*trace_end*, if defined, is called after all events have been - processed and gives scripts a chance to do end-of-script tasks, such - as display results: - ----- -sub trace_end -{ -} ----- - -*trace_unhandled*, if defined, is called after for any event that - doesn't have a handler explicitly defined for it. The standard set - of common arguments are passed into it: - ----- -sub trace_unhandled -{ - my ($event_name, $context, $common_cpu, $common_secs, - $common_nsecs, $common_pid, $common_comm) = @_; -} ----- - -The remaining sections provide descriptions of each of the available -built-in perf script Perl modules and their associated functions. - -AVAILABLE MODULES AND FUNCTIONS -------------------------------- - -The following sections describe the functions and variables available -via the various Perf::Trace::* Perl modules. To use the functions and -variables from the given module, add the corresponding 'use -Perf::Trace::XXX' line to your perf script script. - -Perf::Trace::Core Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -These functions provide some essential functions to user scripts. - -The *flag_str* and *symbol_str* functions provide human-readable -strings for flag and symbolic fields. These correspond to the strings -and values parsed from the 'print fmt' fields of the event format -files: - - flag_str($event_name, $field_name, $field_value) - returns the string representation corresponding to $field_value for the flag field $field_name of event $event_name - symbol_str($event_name, $field_name, $field_value) - returns the string representation corresponding to $field_value for the symbolic field $field_name of event $event_name - -Perf::Trace::Context Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the 'common' fields in the event format file aren't all that -common, but need to be made accessible to user scripts nonetheless. - -Perf::Trace::Context defines a set of functions that can be used to -access this data in the context of the current event. Each of these -functions expects a $context variable, which is the same as the -$context variable passed into every event handler as the second -argument. - - common_pc($context) - returns common_preempt count for the current event - common_flags($context) - returns common_flags for the current event - common_lock_depth($context) - returns common_lock_depth for the current event - -Perf::Trace::Util Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -Various utility functions for use with perf script: - - nsecs($secs, $nsecs) - returns total nsecs given secs/nsecs pair - nsecs_secs($nsecs) - returns whole secs portion given nsecs - nsecs_nsecs($nsecs) - returns nsecs remainder given nsecs - nsecs_str($nsecs) - returns printable string in the form secs.nsecs - avg($total, $n) - returns average given a sum and a total number of values - -SEE ALSO --------- -linkperf:perf-script[1] diff --git a/tools/perf/Documentation/perf-script-python.txt b/tools/perf/Documentation/perf-script-python.txt index 27a1cac6fe76..9293057cee8e 100644 --- a/tools/perf/Documentation/perf-script-python.txt +++ b/tools/perf/Documentation/perf-script-python.txt @@ -3,676 +3,152 @@ perf-script-python(1) NAME ---- -perf-script-python - Process trace data with a Python script +perf-script-python - Process trace data with a Python script using perf module SYNOPSIS -------- [verse] -'perf script' [-s [Python]:script[.py] ] +'perf script'