Commit 1a329b1c authored by Adrian Hunter's avatar Adrian Hunter Committed by Arnaldo Carvalho de Melo
Browse files

perf scripting python: Update documentation for srcline etc 



Add new fields and functions to the perf-script-python documentation.

Signed-off-by: default avatarAdrian Hunter <adrian.hunter@intel.com>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Jiri Olsa <jolsa@redhat.com>
Link: https://lore.kernel.org/r/20210530192308.7382-12-adrian.hunter@intel.com


Signed-off-by: default avatarArnaldo Carvalho de Melo <acme@redhat.com>
parent e79457a5

tools/perf/Documentation/perf-script-python.txt

+42 −4
Original line number Diff line number Diff line
@@ -550,6 +550,27 @@ def trace_unhandled(event_name, context, event_fields_dict): 
    pass

----



*process_event*, if defined, is called for any non-tracepoint event



----

def process_event(param_dict):

    pass

----



*context_switch*, if defined, is called for any context switch



----

def context_switch(ts, cpu, pid, tid, np_pid, np_tid, machine_pid, out, out_preempt, *x):

    pass

----



*auxtrace_error*, if defined, is called for any AUX area tracing error



----

def auxtrace_error(typ, code, cpu, pid, tid, ip, ts, msg, cpumode, *x):

    pass

----



The remaining sections provide descriptions of each of the available

built-in perf script Python modules and their associated functions.
@@ -592,12 +613,18 @@ 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.

context variable passed into every tracepoint event handler as the second

argument. For non-tracepoint events, the context variable is also present

as perf_trace_context.perf_script_context .



 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_sample_insn(context) - returns the machine code instruction

 perf_set_itrace_options(context, itrace_options) - set --itrace options if they have not been set already

 perf_sample_srcline(context) - returns source_file_name, line_number

 perf_sample_srccode(context) - returns source_file_name, line_number, source_line





Util.py Module

~~~~~~~~~~~~~~
@@ -616,9 +643,20 @@ SUPPORTED FIELDS 
Currently supported fields:



ev_name, comm, pid, tid, cpu, ip, time, period, phys_addr, addr,

symbol, dso, time_enabled, time_running, values, callchain,

symbol, symoff, dso, time_enabled, time_running, values, callchain,

brstack, brstacksym, datasrc, datasrc_decode, iregs, uregs,

weight, transaction, raw_buf, attr.

weight, transaction, raw_buf, attr, cpumode.



Fields that may also be present:



 flags - sample flags

 flags_disp - sample flags display

 insn_cnt - instruction count for determining instructions-per-cycle (IPC)

 cyc_cnt - cycle count for determining IPC

 addr_correlates_sym - addr can correlate to a symbol

 addr_dso - addr dso

 addr_symbol - addr symbol

 addr_symoff - addr symbol offset



Some fields have sub items: