summaryrefslogtreecommitdiff
path: root/tools/perf/python/perf.pyi
AgeCommit message (Collapse)Author
2026-09-26perf python: Add Intel PT call_return and itrace capabilityIan Rogers
Add support for Intel PT call_return events and itrace options to the perf Python extension so standalone Python scripts can decode and inspect low-level instruction traces. Specifically: - Add a call_return callback parameter and itrace option string to perf.session, treating explicit None (Py_None) callbacks as omitted. - Expose the perf.call_return object with db_id, parent_id, insn_count, cyc_count, comm, pid, tid, call_time, return_time, branch_count, call_ref, return_ref, flags, and call_path (resolved as a perf.callchain ordered from outermost caller to callee, populating frame->map and frame->sym so call_path entries expose resolved symbol and DSO names). - Export perf.CALL_RETURN_NO_CALL, perf.CALL_RETURN_NO_RETURN, and perf.CALL_RETURN_NON_CALL flag constants. - Expose session.e_machine and session.is_64_bit properties, preferring recorded thread ELF machines (perf_session__e_machine) over perf_env so pipe-mode traces do not prematurely cache host bitness. - Support optional vmlinux, kallsyms, and symfs symbol configuration parameters (and PERF_SYMBOL_VMLINUX, PERF_SYMBOL_KALLSYMS, PERF_SYMBOL_SYMFS environment fallbacks) in perf.session, resetting symbol_conf pointers and freeing vm_tm_corr_args, cpu_bitmap, and ptime_range in pyrf_session__delete(). Assisted-by: Antigravity:gemini-3.1-pro Signed-off-by: Ian Rogers <irogers@google.com> Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2026-09-26perf python: Expose addr location, transaction, and context_switchIan Rogers
Expose destination address location components (addr_dso, addr_symbol, addr_sym_offset), branch/transaction metrics (branch_type, in_tx, flags, transaction), machine_pid, vcpu, sym_offset, and context_switch callbacks directly to the Python extension. Also include supporting fixes and infrastructure updates in util/python.c and perf.pyi: - Support fetching sym_offset on resolved sample symbols. - Populate sample machine_pid and vcpu from evlist__id2sid() when perf_guest is enabled, and resolve samples against the matching guest or host machine. - Expose next_prev_pid and next_prev_tid on switch_event only for PERF_RECORD_SWITCH_CPU_WIDE records (returning None otherwise). - Wire up tracing_data in pyrf_session__new() and update perf.pyi type stubs (including srccode() and insn() return types). Assisted-by: Antigravity:gemini-3.1-pro Signed-off-by: Ian Rogers <irogers@google.com> Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2026-09-26perf python: Update callchain stubs and session thread lookupIan Rogers
Update pyrf_session__find_thread() in util/python.c to accept an optional tid parameter (defaulting to pid) and return None instead of raising TypeError when a thread is not found in the session machines. Update perf.pyi to match: - Set session.find_thread() signature to (pid: int, tid: int = -1) -> Optional[thread]. - Update callchain_node.symbol and callchain_node.dso to str (the C getters return "[unknown]" fallback strings rather than None) and add __iter__() to callchain. Also update treport.py to handle Optional[thread] returned by session.find_thread(). Assisted-by: Antigravity:gemini-3.1-pro Signed-off-by: Ian Rogers <irogers@google.com> Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2026-09-26perf python: Update syscall helpers and expose arch_strerrnoIan Rogers
Update the PyArg_ParseTupleAndKeywords format string for pyrf__syscall_name() and pyrf__syscall_id() from "i|$i" to "i|i" (and "s|$i" to "s|i"), allowing elf_machine to be passed as an optional positional argument as well as a keyword argument. Update syscall_id() and syscall_name() in perf.pyi to match, and set the return type of syscall_name() to Optional[str] as unknown syscall numbers return None. Also expose perf_env__arch_strerrno() as perf.arch_strerrno(err, elf_machine=None) so standalone Python scripts can resolve architecture-specific errno names directly from the auto-generated trace beauty tables instead of maintaining duplicate errno dictionaries in Python. Tighten the macro pattern in arch_errno_names.sh to E[A-Z0-9]+ so compiler -D flags containing underscores (such as LLVM's -DEXPERIMENTAL_KEY_INSTRUCTIONS=1) do not shadow EPERM (1), and add EM_SPARC32PLUS alongside EM_SPARC and EM_SPARCV9. Assisted-by: Antigravity:gemini-3.1-pro Signed-off-by: Ian Rogers <irogers@google.com> Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2026-08-09perf python: Fix MetricGroup return type in perf.pyiIan Rogers
The metrics() function can return a dictionary where the value is either a string or a list of strings, so the type signature in the stub file should be Union[str, List[str]]. Fixes: 430da3cd03b4 ("perf python: Add perf.pyi stubs file") Signed-off-by: Ian Rogers <irogers@google.com> Signed-off-by: Namhyung Kim <namhyung@kernel.org>
2026-06-30perf python: Add perf.pyi stubs fileIan Rogers
Add Python type stubs for the perf module to improve IDE support and static analysis. Includes docstrings for classes, methods, and constants derived from C source and JSON definitions. Assisted-by: Gemini:gemini-3.1-pro-preview Signed-off-by: Ian Rogers <irogers@google.com> Cc: Adrian Hunter <adrian.hunter@intel.com> Cc: Alice Rogers <alice.mei.rogers@gmail.com> Cc: Dapeng Mi <dapeng1.mi@linux.intel.com> Cc: Ingo Molnar <mingo@redhat.com> Cc: James Clark <james.clark@linaro.org> Cc: Leo Yan <leo.yan@linux.dev> Cc: Namhyung Kim <namhyung@kernel.org> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Thomas Richter <tmricht@linux.ibm.com> Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com> Signed-off-by: Namhyung Kim <namhyung@kernel.org>