Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) perf-script-perl(1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) NAME
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) perf-script-perl - Process trace data with a Perl script
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) SYNOPSIS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) [verse]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 'perf script' [-s [Perl]:script[.pl] ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) DESCRIPTION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) This perf script option is used to process perf script data using perf's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) built-in Perl interpreter.  It reads and processes the input file and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) displays the results of the trace analysis implemented in the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) Perl script, if any.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) STARTER SCRIPTS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) You can avoid reading the rest of this document by running 'perf script
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) -g perl' in the same directory as an existing perf.data trace file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) That will generate a starter script containing a handler for each of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) the event types in the trace file; it simply prints every available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) field for each event in the trace file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) You can also look at the existing scripts in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) ~/libexec/perf-core/scripts/perl for typical examples showing how to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) do basic things like aggregate event data, print results, etc.  Also,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) the check-perf-script.pl script, while not interesting for its results,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) attempts to exercise all of the main scripting features.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) EVENT HANDLERS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) When perf script is invoked using a trace script, a user-defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 'handler function' is called for each event in the trace.  If there's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) no handler function defined for a given event type, the event is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) ignored (or passed to a 'trace_unhandled' function, see below) and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) next event is processed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) Most of the event's field values are passed as arguments to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) handler function; some of the less common ones aren't - those are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) available as calls back into the perf executable (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) As an example, the following perf record command can be used to record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) all sched_wakeup events in the system:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)  # perf record -a -e sched:sched_wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) Traces meant to be processed using a script should be recorded with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) the above option: -a to enable system-wide collection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) The format file for the sched_wakep event defines the following fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) (see /sys/kernel/debug/tracing/events/sched/sched_wakeup/format):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61)  format:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62)         field:unsigned short common_type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63)         field:unsigned char common_flags;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64)         field:unsigned char common_preempt_count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65)         field:int common_pid;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67)         field:char comm[TASK_COMM_LEN];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68)         field:pid_t pid;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69)         field:int prio;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70)         field:int success;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)         field:int target_cpu;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) The handler function for this event would be defined as:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) sub sched::sched_wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79)    my ($event_name, $context, $common_cpu, $common_secs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)        $common_nsecs, $common_pid, $common_comm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81)        $comm, $pid, $prio, $success, $target_cpu) = @_;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) The handler function takes the form subsystem::event_name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) The $common_* arguments in the handler's argument list are the set of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) arguments passed to all event handlers; some of the fields correspond
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) to the common_* fields in the format file, but some are synthesized,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) and some of the common_* fields aren't common enough to to be passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) to every event as arguments but are available as library functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) Here's a brief description of each of the invariant event args:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)  $event_name 	  	    the name of the event as text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)  $context		    an opaque 'cookie' used in calls back into perf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)  $common_cpu		    the cpu the event occurred on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)  $common_secs		    the secs portion of the event timestamp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)  $common_nsecs		    the nsecs portion of the event timestamp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)  $common_pid		    the pid of the current task
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)  $common_comm		    the name of the current process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) All of the remaining fields in the event's format file have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) counterparts as handler function arguments of the same name, as can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) seen in the example above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The above provides the basics needed to directly access every field of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) every event in a trace, which covers 90% of what you need to know to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) write a useful trace script.  The sections below cover the rest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) SCRIPT LAYOUT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Every perf script Perl script should start by setting up a Perl module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) search path and 'use'ing a few support modules (see module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) descriptions below):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)  use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)  use lib "./Perf-Trace-Util/lib";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)  use Perf::Trace::Core;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)  use Perf::Trace::Context;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)  use Perf::Trace::Util;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) The rest of the script can contain handler functions and support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) functions in any order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Aside from the event handler functions discussed above, every script
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) can implement a set of optional functions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) *trace_begin*, if defined, is called before any event is processed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) gives scripts a chance to do setup tasks:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)  sub trace_begin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)  {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)  }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) *trace_end*, if defined, is called after all events have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)  processed and gives scripts a chance to do end-of-script tasks, such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)  as display results:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) sub trace_end
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) *trace_unhandled*, if defined, is called after for any event that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)  doesn't have a handler explicitly defined for it.  The standard set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)  of common arguments are passed into it:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) sub trace_unhandled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)     my ($event_name, $context, $common_cpu, $common_secs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)         $common_nsecs, $common_pid, $common_comm) = @_;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) The remaining sections provide descriptions of each of the available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) built-in perf script Perl modules and their associated functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) AVAILABLE MODULES AND FUNCTIONS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) The following sections describe the functions and variables available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) via the various Perf::Trace::* Perl modules.  To use the functions and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) variables from the given module, add the corresponding 'use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Perf::Trace::XXX' line to your perf script script.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) Perf::Trace::Core Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) These functions provide some essential functions to user scripts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) The *flag_str* and *symbol_str* functions provide human-readable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) strings for flag and symbolic fields.  These correspond to the strings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) and values parsed from the 'print fmt' fields of the event format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) files:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)   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
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)   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
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) Perf::Trace::Context Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) ~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Some of the 'common' fields in the event format file aren't all that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) common, but need to be made accessible to user scripts nonetheless.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) Perf::Trace::Context defines a set of functions that can be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) access this data in the context of the current event.  Each of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) functions expects a $context variable, which is the same as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) $context variable passed into every event handler as the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)  common_pc($context) - returns common_preempt count for the current event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)  common_flags($context) - returns common_flags for the current event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)  common_lock_depth($context) - returns common_lock_depth for the current event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Perf::Trace::Util Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Various utility functions for use with perf script:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)   nsecs($secs, $nsecs) - returns total nsecs given secs/nsecs pair
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)   nsecs_secs($nsecs) - returns whole secs portion given nsecs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)   nsecs_nsecs($nsecs) - returns nsecs remainder given nsecs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)   nsecs_str($nsecs) - returns printable string in the form secs.nsecs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)   avg($total, $n) - returns average given a sum and a total number of values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) SEE ALSO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) linkperf:perf-script[1]