[PATCH v8 17/58] perf python: Add callchain support

Ian Rogers
2026-04-28T07:21:04Z

Implement pyrf_callchain_node and pyrf_callchain types for lazy
iteration over callchain frames. Add callchain property to
sample_event.

Assisted-by: Gemini:gemini-3.1-pro-preview
Signed-off-by: Ian Rogers <irogers@google.com>
---
v2:

1. Eager Callchain Resolution: Moved the callchain resolution from
deferred iteration to eager processing in
pyrf_session_tool__sample() . This avoids risks of reading from
unmapped memory or following dangling pointers to closed sessions.

2. Cached Callchain: Added a callchain field to struct pyrf_event to
store the resolved object.

3. Simplified Access: pyrf_sample_event__get_callchain() now just
returns the cached object if available.

4. Avoided Double Free: Handled lazy cleanups properly.

v6:
- Moved callchain resolution from `session_tool__sample` to
`pyrf_event__new`.
---
tools/perf/util/python.c | 241 ++++++++++++++++++++++++++++++++++++++-
1 file changed, 240 insertions(+), 1 deletion(-)

diff --git a/tools/perf/util/python.c b/tools/perf/util/python.c
index ae009bc9a0d7..2ff588517c29 100644
--- a/tools/perf/util/python.c
+++ b/tools/perf/util/python.c
@@ -64,6 +64,8 @@ struct pyrf_event {
struct addr_location al;
/** @al_resolved: True when machine__resolve been called. */
bool al_resolved;
+ /** @callchain: Resolved callchain, eagerly computed if requested. */
+ PyObject *callchain;
/** @event: The underlying perf_event that may be in a file or ring buffer. */
union perf_event event;
};
@@ -101,6 +103,7 @@ static void pyrf_event__delete(struct pyrf_event *pevent)
{
if (pevent->al_resolved)
addr_location__exit(&pevent->al);
+ Py_XDECREF(pevent->callchain);
perf_sample__exit(&pevent->sample);
Py_TYPE(pevent)->tp_free((PyObject *)pevent);
}
@@ -667,6 +670,181 @@ static PyObject *pyrf_sample_event__insn(PyObject *self, PyObject *args __maybe_
pevent->sample.insn_len);
}

+struct pyrf_callchain_node {
+ PyObject_HEAD
+ u64 ip;
+ struct map *map;
+ struct symbol *sym;
+};
+
+static void pyrf_callchain_node__delete(struct pyrf_callchain_node *pnode)
+{
+ map__put(pnode->map);
+ Py_TYPE(pnode)->tp_free((PyObject*)pnode);
+}
+
+static PyObject *pyrf_callchain_node__get_ip(struct pyrf_callchain_node *pnode,
+ void *closure __maybe_unused)
+{
+ return PyLong_FromUnsignedLongLong(pnode->ip);
+}
+
+static PyObject *pyrf_callchain_node__get_symbol(struct pyrf_callchain_node *pnode,
+ void *closure __maybe_unused)
+{
+ if (pnode->sym)
+ return PyUnicode_FromString(pnode->sym->name);
+ return PyUnicode_FromString("[unknown]");
+}
+
+static PyObject *pyrf_callchain_node__get_dso(struct pyrf_callchain_node *pnode,
+ void *closure __maybe_unused)
+{
+ const char *dsoname = "[unknown]";
+
+ if (pnode->map) {
+ struct dso *dso = map__dso(pnode->map);
+ if (dso) {
+ if (symbol_conf.show_kernel_path && dso__long_name(dso))
+ dsoname = dso__long_name(dso);
+ else
+ dsoname = dso__name(dso);
+ }
+ }
+ return PyUnicode_FromString(dsoname);
+}
+
+static PyGetSetDef pyrf_callchain_node__getset[] = {
+ { .name = "ip", .get = (getter)pyrf_callchain_node__get_ip, },
+ { .name = "symbol", .get = (getter)pyrf_callchain_node__get_symbol, },
+ { .name = "dso", .get = (getter)pyrf_callchain_node__get_dso, },
+ { .name = NULL, },
+};
+
+static PyTypeObject pyrf_callchain_node__type = {
+ PyVarObject_HEAD_INIT(NULL, 0)
+ .tp_name = "perf.callchain_node",
+ .tp_basicsize = sizeof(struct pyrf_callchain_node),
+ .tp_dealloc = (destructor)pyrf_callchain_node__delete,
+ .tp_flags = Py_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE,
+ .tp_doc = "perf callchain node object.",
+ .tp_getset = pyrf_callchain_node__getset,
+};
+
+struct pyrf_callchain_frame {
+ u64 ip;
+ struct map *map;
+ struct symbol *sym;
+};
+
+struct pyrf_callchain {
+ PyObject_HEAD
+ struct pyrf_event *pevent;
+ struct pyrf_callchain_frame *frames;
+ u64 nr_frames;
+ u64 pos;
+ bool resolved;
+};
+
+static void pyrf_callchain__delete(struct pyrf_callchain *pchain)
+{
+ Py_XDECREF(pchain->pevent);
+ if (pchain->frames) {
+ for (u64 i = 0; i < pchain->nr_frames; i++)
+ map__put(pchain->frames[i].map);
+ free(pchain->frames);
+ }
+ Py_TYPE(pchain)->tp_free((PyObject*)pchain);
+}
+
+static PyObject *pyrf_callchain__next(struct pyrf_callchain *pchain)
+{
+ struct pyrf_callchain_node *pnode;
+
+ if (!pchain->resolved) {
+ struct evsel *evsel = pchain->pevent->sample.evsel;
+ struct evlist *evlist = evsel->evlist;
+ struct perf_session *session = evlist ? evlist__session(evlist) : NULL;
+ struct addr_location al;
+ struct callchain_cursor *cursor;
+ struct callchain_cursor_node *node;
+ u64 i;
+
+ if (!session || !pchain->pevent->sample.callchain)
+ return NULL;
+
+ addr_location__init(&al);
+ if (machine__resolve(&session->machines.host, &al, &pchain->pevent->sample) < 0) {
+ addr_location__exit(&al);
+ return NULL;
+ }
+
+ cursor = get_tls_callchain_cursor();
+ if (thread__resolve_callchain(al.thread, cursor, evsel,
+ &pchain->pevent->sample, NULL, NULL,
+ PERF_MAX_STACK_DEPTH) != 0) {
+ addr_location__exit(&al);
+ return NULL;
+ }
+ callchain_cursor_commit(cursor);
+
+ pchain->nr_frames = cursor->nr;
+ if (pchain->nr_frames > 0) {
+ pchain->frames = calloc(pchain->nr_frames, sizeof(*pchain->frames));
+ if (!pchain->frames) {
+ addr_location__exit(&al);
+ return PyErr_NoMemory();
+ }
+
+ for (i = 0; i < pchain->nr_frames; i++) {
+ node = callchain_cursor_current(cursor);
+ pchain->frames[i].ip = node->ip;
+ pchain->frames[i].map = map__get(node->ms.map);
+ pchain->frames[i].sym = node->ms.sym;
+ callchain_cursor_advance(cursor);
+ }
+ }
+ pchain->resolved = true;
+ addr_location__exit(&al);
+ }
+
+ if (pchain->pos >= pchain->nr_frames)
+ return NULL;
+
+ pnode = PyObject_New(struct pyrf_callchain_node, &pyrf_callchain_node__type);
+ if (!pnode)
+ return NULL;
+
+ pnode->ip = pchain->frames[pchain->pos].ip;
+ pnode->map = map__get(pchain->frames[pchain->pos].map);
+ pnode->sym = pchain->frames[pchain->pos].sym;
+
+ pchain->pos++;
+ return (PyObject *)pnode;
+}
+
+static PyTypeObject pyrf_callchain__type = {
+ PyVarObject_HEAD_INIT(NULL, 0)
+ .tp_name = "perf.callchain",
+ .tp_basicsize = sizeof(struct pyrf_callchain),
+ .tp_dealloc = (destructor)pyrf_callchain__delete,
+ .tp_flags = Py_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE,
+ .tp_doc = "perf callchain object.",
+ .tp_iter = PyObject_SelfIter,
+ .tp_iternext = (iternextfunc)pyrf_callchain__next,
+};
+
+static PyObject *pyrf_sample_event__get_callchain(PyObject *self, void *closure __maybe_unused)
+{
+ struct pyrf_event *pevent = (void *)self;
+
+ if (!pevent->callchain)
+ Py_RETURN_NONE;
+
+ Py_INCREF(pevent->callchain);
+ return pevent->callchain;
+}
+
static PyObject*
pyrf_sample_event__getattro(struct pyrf_event *pevent, PyObject *attr_name)
{
@@ -681,6 +859,12 @@ pyrf_sample_event__getattro(struct pyrf_event *pevent, PyObject *attr_name)
}

static PyGetSetDef pyrf_sample_event__getset[] = {
+ {
+ .name = "callchain",
+ .get = pyrf_sample_event__get_callchain,
+ .set = NULL,
+ .doc = "event callchain.",
+ },
{
.name = "raw_buf",
.get = (getter)pyrf_sample_event__get_raw_buf,
@@ -850,6 +1034,12 @@ static int pyrf_event__setup_types(void)
err = PyType_Ready(&pyrf_context_switch_event__type);
if (err < 0)
goto out;
+ err = PyType_Ready(&pyrf_callchain_node__type);
+ if (err < 0)
+ goto out;
+ err = PyType_Ready(&pyrf_callchain__type);
+ if (err < 0)
+ goto out;
out:
return err;
}
@@ -870,9 +1060,11 @@ static PyTypeObject *pyrf_event__type[] = {
};

static PyObject *pyrf_event__new(const union perf_event *event, struct evsel *evsel,
- struct perf_session *session __maybe_unused)
+ struct perf_session *session)
{
struct pyrf_event *pevent;
+ struct perf_sample *sample;
+ struct machine *machine = session ? &session->machines.host : NULL;
size_t size;
int err;
size_t min_size = sizeof(struct perf_event_header);
@@ -1031,6 +1223,7 @@ static PyObject *pyrf_event__new(const union perf_event *event, struct evsel *ev
}

perf_sample__init(&pevent->sample, /*all=*/true);
+ pevent->callchain = NULL;
pevent->al_resolved = false;
addr_location__init(&pevent->al);

@@ -1044,6 +1237,49 @@ static PyObject *pyrf_event__new(const union perf_event *event, struct evsel *ev
return PyErr_Format(PyExc_OSError,
"perf: can't parse sample, err=%d", err);
}
+ sample = &pevent->sample;
+ if (machine && sample->callchain) {
+ struct addr_location al;
+ struct callchain_cursor *cursor;
+ u64 i;
+ struct pyrf_callchain *pchain;
+
+ addr_location__init(&al);
+ if (machine__resolve(machine, &al, sample) >= 0) {
+ cursor = get_tls_callchain_cursor();
+ if (thread__resolve_callchain(al.thread, cursor, evsel, sample,
+ NULL, NULL, PERF_MAX_STACK_DEPTH) == 0) {
+ callchain_cursor_commit(cursor);
+
+ pchain = PyObject_New(struct pyrf_callchain, &pyrf_callchain__type);
+ if (pchain) {
+ pchain->pevent = pevent;
+ Py_INCREF(pevent);
+ pchain->nr_frames = cursor->nr;
+ pchain->pos = 0;
+ pchain->resolved = true;
+ pchain->frames = calloc(pchain->nr_frames,
+ sizeof(*pchain->frames));
+ if (pchain->frames) {
+ struct callchain_cursor_node *node;
+
+ for (i = 0; i < pchain->nr_frames; i++) {
+ node = callchain_cursor_current(cursor);
+ pchain->frames[i].ip = node->ip;
+ pchain->frames[i].map =
+ map__get(node->ms.map);
+ pchain->frames[i].sym = node->ms.sym;
+ callchain_cursor_advance(cursor);
+ }
+ pevent->callchain = (PyObject *)pchain;
+ } else {
+ Py_DECREF(pchain);
+ }
+ }
+ }
+ addr_location__exit(&al);
+ }
+ }
return (PyObject *)pevent;
}

@@ -3141,6 +3377,9 @@ static PyObject *pyrf_session__new(PyTypeObject *type, PyObject *args, PyObject
}
psession->session = session;

+ symbol_conf.use_callchain = true;
+ symbol_conf.show_kernel_path = true;
+ symbol_conf.inline_name = false;
if (symbol__init(perf_session__env(session)) < 0) {
PyErr_SetString(PyExc_OSError, "perf: symbol__init failed");
goto err_out;
--
2.54.0.545.g6539524ca2-goog