gh-149800: Generate the perf trampoline .eh_frame from the compiled assembly by stratakis · Pull Request #157246 · python/cpython

stratakis · 2026-09-10T01:45:14Z

The trampoline's unwind information has been a hand-maintained DWARF block per architecture in Python/jit_unwind.c.

Now all of this can be changed :)

The perf trampoline's unwind information is now produced by the assembler from .cfi directives in the trampoline assembly and extracted into a header at build time, so no architecture needs hand-written DWARF anymore.

Building the perf trampoline now needs a host Python (PYTHON_FOR_REGEN, 3.7 or newer. Wanted 3.9 for the stock Mac interpreter but 3.7 was compatible so why not). Without one, configure disables the trampoline.

Tested on Linux x86_64 (gcc, clang, CET, JIT, tail-call interpreter, free-threaded, LTO, PGO, BOLT, shared, debug, no frame pointers, out-of-tree)

Linux aarch64 (default, PAC, shared, debug, no frame pointers)

macOS arm64 (native, framework, universal2 on both slices), end to end with perf (fp and DWARF call graphs) and samply.

Plus the test suite ofc which was passing for me (let's see what the CI says though).

This can also be backported into 3.15 together with #149894 and #150364 if needed.

Fixes: #149800

THe PR and testing has been assisted by various frontier models, mainly by Fable 5.1 but also each each iteration reviewed in addition by the gpt 6 astra model.

Making it a draft for now, I believe it's ready but I'd also like to test an rpm build first, plus adding another architecture such as s390x or ppc64le to verify things work as intended.

Issue: Refactor perf trampoline proposal: split the assembly per architecture, auto-generate DWARF unwind data #149800

python-cla-bot · 2026-09-10T01:45:19Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-09-10T01:49:49Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34520339 | 📁 Comparing 48c7945 against main (69a6612)

🔍 Preview build

23 files changed · ± 23 modified

± Modified

stratakis · 2026-09-10T23:04:09Z

Undrafting, this should be ready. The failed CI jobs must be flakiness as they passed on the previous commit, the last one just skips a specific test on BOLT builds.

Did some extra verification here:

A Fedora Rawhide RPM build of python3.15 with this on top of the split and the macOS fix (so basically a 3.15 backport), which contains the multitude of Fedora compiler flags.

Tested on aarch64 and x86_64 the main, debug, free-threading and free-threading-debug interpreters . On all eight the trampoline is enabled, the jitdumps written by -X perf_jit have correctly patched FDEs, test_perf_profiler and test_perfmaps pass, and perf unwinds through every trampoline in both fp and DWARF mode.

Also I've tested with adding ppc64le support and deployed it on the ppc64le Rawhide buildbot (source build not RPM). Granted the non-fp path is not exercised on ppc64le but nontheless it works if I add this patch on top:

ppc64le patch


diff --git a/Makefile.pre.in b/Makefile.pre.in
index f9f9a5db5d4..07f494e38c5 100644
--- a/Makefile.pre.in
+++ b/Makefile.pre.in
@@ -3133,6 +3133,9 @@ Python/asm_trampoline_aarch64.o: $(srcdir)/Python/asm_trampoline_aarch64.S
 Python/asm_trampoline_riscv64.o: $(srcdir)/Python/asm_trampoline_riscv64.S
 	$(CC) -c $(PY_CORE_CFLAGS) -o $@ $<
 
+Python/asm_trampoline_ppc64le.o: $(srcdir)/Python/asm_trampoline_ppc64le.S
+	$(CC) -c $(PY_CORE_CFLAGS) -o $@ $<
+
 # On macOS universal2 builds, $(PY_CORE_CFLAGS) contains "-arch arm64 -arch x86_64",
 # which would produce fat .o files containing both architectures for each .S input.
 # lipo -create then refuses to combine them because they share architectures.
diff --git a/Python/asm_trampoline_ppc64le.S b/Python/asm_trampoline_ppc64le.S
new file mode 100644
index 00000000000..c85e6b59b31
--- /dev/null
+++ b/Python/asm_trampoline_ppc64le.S
@@ -0,0 +1,27 @@
+    .text
+#if defined(__powerpc64__) && defined(_CALL_ELF) && _CALL_ELF == 2
+    .abiversion 2
+    .globl  _Py_trampoline_func_start
+_Py_trampoline_func_start:
+    .cfi_startproc
+    mflr    0
+    std     0, 16(1)
+    stdu    1, -32(1)
+    .cfi_def_cfa_offset 32
+    .cfi_offset 65, 16
+    mr      12, 6
+    mtctr   6
+    std     2, 24(1)
+    bctrl
+    ld      2, 24(1)
+    addi    1, 1, 32
+    .cfi_def_cfa_offset 0
+    ld      0, 16(1)
+    mtlr    0
+    .cfi_restore 65
+    blr
+    .cfi_endproc
+    .globl  _Py_trampoline_func_end
+_Py_trampoline_func_end:
+#endif
+    .section .note.GNU-stack,"",@progbits
diff --git a/Python/perf_jit_trampoline.c b/Python/perf_jit_trampoline.c
index 21beead742a..1709fda8681 100644
--- a/Python/perf_jit_trampoline.c
+++ b/Python/perf_jit_trampoline.c
@@ -124,6 +124,8 @@
 #    define EM_AARCH64  183
 #  elif defined(__riscv)
 #    define EM_RISCV    243
+#  elif defined(__powerpc64__)
+#    define EM_PPC64    21
 #  endif
 #endif
 
@@ -158,6 +160,8 @@ static uint64_t GetElfMachineArchitecture(void) {
     return EM_ARM;
 #elif defined(__riscv)
     return EM_RISCV;
+#elif defined(__powerpc64__)
+    return EM_PPC64;
 #else
     Py_UNREACHABLE();  // Unsupported architecture - should never reach here
     return 0;
diff --git a/Python/perf_trampoline.c b/Python/perf_trampoline.c
index fa1cb785b41..620196ab81b 100644
--- a/Python/perf_trampoline.c
+++ b/Python/perf_trampoline.c
@@ -147,7 +147,8 @@ any DWARF information available for them).
 #include <sys/time.h>           // gettimeofday()
 
 
-#if defined(__arm__) || defined(__arm64__) || defined(__aarch64__)
+#if defined(__arm__) || defined(__arm64__) || defined(__aarch64__) \
+    || defined(__powerpc64__)
 #define PY_HAVE_INVALIDATE_ICACHE
 
 #if defined(__clang__) || defined(__GNUC__)
diff --git a/Tools/jit/_trampoline_ehframe.py b/Tools/jit/_trampoline_ehframe.py
index a87488bde25..135dae1146f 100644
--- a/Tools/jit/_trampoline_ehframe.py
+++ b/Tools/jit/_trampoline_ehframe.py
@@ -24,6 +24,7 @@
 _SHT_NOBITS = 8
 _EM_X86_64 = 62
 _EM_AARCH64 = 183
+_EM_PPC64 = 21
 
 # Mach-O constants, see llvm/BinaryFormat/MachO.h.
 _MH_MAGIC_64 = 0xFEEDFACF
@@ -62,6 +63,7 @@
 _ELF_ARCH_MACROS = {
     _EM_X86_64: "__x86_64__",
     _EM_AARCH64: "__aarch64__",
+    _EM_PPC64: "__powerpc64__",
 }
 _MACHO_ARCH_MACROS = {
     _CPU_TYPE_X86_64: "__x86_64__",
diff --git a/configure b/configure
index 1ebf1f795b0..109f2e962c0 100755
--- a/configure
+++ b/configure
@@ -14636,6 +14636,9 @@ case $PLATFORM_TRIPLET in #(
   aarch64-linux-musl) :
     perf_trampoline=yes
                          PERF_TRAMPOLINE_OBJ=Python/asm_trampoline_aarch64.o ;; #(
+  powerpc64le-linux-gnu) :
+    perf_trampoline=yes
+                            PERF_TRAMPOLINE_OBJ=Python/asm_trampoline_ppc64le.o ;; #(
   darwin) :
     case $MACOSX_DEPLOYMENT_TARGET in #(
   10.[0-9]|10.1[0-1]) :
diff --git a/configure.ac b/configure.ac
index b44c7d931d3..d21a05565d0 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3922,6 +3922,8 @@ AS_CASE([$PLATFORM_TRIPLET],
                          PERF_TRAMPOLINE_OBJ=Python/asm_trampoline_aarch64.o],
   [aarch64-linux-musl], [perf_trampoline=yes
                          PERF_TRAMPOLINE_OBJ=Python/asm_trampoline_aarch64.o],
+  [powerpc64le-linux-gnu], [perf_trampoline=yes
+                            PERF_TRAMPOLINE_OBJ=Python/asm_trampoline_ppc64le.o],
   [darwin], [AS_CASE([$MACOSX_DEPLOYMENT_TARGET],
                 [[10.[0-9]|10.1[0-1]]], [perf_trampoline=no],
                 [perf_trampoline=yes

builds, tests pass, perf back-chain and DWARF mode both unwind through the trampolines.

Did also a s390x compilation (with the relevant code added similarly as the ppc64le one) on RHEL10 (no access to Fedora s390x for now), builds with and without -mbackchain, tests pass on both, DWARF mode unwinds through the trampolines on both. Frame pointer mode doesn't work due to a kernel bug there but overall I think this covers a wider area of testing that functionality.

So if that approach seems sound, it should be fairly easy to add s390x, ppc64le, RISC-V support.

stratakis · 2026-09-10T23:04:48Z

cc @diegorusso @pablogsal

diegorusso · 2026-09-11T17:00:09Z

Thanks for the change, this is great. Two point of discussions, although very low priority:

I was exploring the idea to use the _bootstrap_python instead of requiring an existent python installation in order to run _trampoline_ehframe.py‎ but I'm not sure if it works. This could be an improvement of the current implementation
when building the unwinding information for the JIT shim, the build system uses llvm-dwarfdump. I was wondering if we could reuse part of the infrastructure of this PR to do the same job. Again, this could be a future improvement.

The first skim of the PR looks OK to me, I might need a second look to it. Also please fix the errors in the CI.

pablogsal · 2026-09-11T21:26:49Z

when building the unwinding information for the JIT shim, the build system uses llvm-dwarfdump. I was wondering if we could reuse part of the infrastructure of this PR to do the same job. Again, this could be a future improvement.

I would prefer to not depend on llvm for non-optional parts of CPython at least for now

pablogsal · 2026-09-11T21:27:19Z

Will review this soon :)

diegorusso · 2026-09-11T21:50:52Z

when building the unwinding information for the JIT shim, the build system uses llvm-dwarfdump. I was wondering if we could reuse part of the infrastructure of this PR to do the same job. Again, this could be a future improvement.

I would prefer to not depend on llvm for non-optional parts of CPython at least for now

Re reading my message I realised that I didn't express well what I meant. I meant that we could reuse the work in this PR to drop the llvm-dwarfdump when building the JIT.
At this stage it is still OK because the JIT requires llvm, hence llvm-dwarfdump is present. I wasn't suggesting to use llvm for this PR :)

Let the assembler emit an .eh_frame for the trampoline, matching the frame layout jit_unwind.c describes.

…symbols

…iled assembly Extract the .eh_frame the assembler emits for the trampoline object at build time into trampoline_ehframe.h and patch only the FDE address fields at runtime. Building with the perf trampoline now needs a host Python, and configure disables the trampoline with a warning when none is usable.

Check the FDEs in jitdump files against their code load records, cover the generator's parsers, and validate the header structure from C.

stratakis · 2026-09-11T22:39:22Z

Force pushed the get the latest changes from main, the commits are the same, I don't see how the CI could be failing so it might need something else, couldn't reproduce it.

stratakis · 2026-09-11T22:54:47Z

* I was exploring the idea to use the _bootstrap_python instead of requiring an existent python installation in order to run _trampoline_ehframe.py‎ but I'm not sure if it works. This could be an improvement of the current implementation

I'll take a jab on that, it certainly sounds like a better design. I could send another PR with it as alternative or do a followup, whatever works best.

* when building the unwinding information for the JIT shim, the build system uses `llvm-dwarfdump`. I was wondering if we could reuse part of the infrastructure of this PR to do the same job. Again, this could be a future improvement.

Sharing would mean adding a CFA program interpreter in Python, which sounds great if it's gonna start reducing the llvm dependency area of the JIT. I'd be happy to take a look at it but since I deal with the JIT as adjacent to these Perf issues I don't have the best overview of the possible impact.

stratakis · 2026-09-11T23:57:58Z

The CI on Mac fails on the llvm installation phase

pablogsal · 2026-09-12T00:32:44Z

+TRAMPOLINE_EHFRAME_H = $(if @PERF_TRAMPOLINE_OBJ@,trampoline_ehframe.h)
+
+trampoline_ehframe.h: @PERF_TRAMPOLINE_OBJ@ $(srcdir)/Tools/jit/_trampoline_ehframe.py
+	$(PYTHON_FOR_REGEN) $(srcdir)/Tools/jit/_trampoline_ehframe.py \


JIT_DEPS includes $(srcdir)/Tools/jit/*.py, so touching this script invalidates .jit-stamp and regenerates every JIT stencil, which has nothing to do with the perf trampoline. This is not JIT tooling; can we move it to Tools/build/?

Damn, yeap you are correct here, it needs to be moved.

pablogsal · 2026-09-12T00:32:44Z

+ * field offsets Python/jit_unwind.c patches. Raises instead of assert()
+ * so the checks also run in release builds. */
+static PyObject *
+test_trampoline_ehframe(PyObject *self, PyObject *Py_UNUSED(args))


parse_ehframe() already rejects a bad CIE version, a non-zR augmentation, an unsupported FDE encoding, more than one FDE and a non-zero FDE augmentation length at generation time, and test_generated_header_is_current diffs the header exactly against a fresh run. So what does this add? I am not sure ~120 lines of C plus a new _testinternalcapi entry point buy us anything here.

Fair, gonna drop this.

pablogsal · 2026-09-12T00:32:44Z

+dnl time needs a Python interpreter, 3.7 or newer (Tools/jit/_trampoline_ehframe.py).
+perf_trampoline_missing_python=no
+AS_VAR_IF([perf_trampoline], [yes], [
+  AS_IF([$PYTHON_FOR_REGEN -c 'import sys; sys.exit(sys.version_info < (3, 7))' >/dev/null 2>&1],


Why 3.7? AC_CHECK_PROGS above only probes python3.10 and newer (plus a bare python3/python), and Tools/jit/mypy.ini type-checks this script at 3.11, so 3.7 is never exercised. I would use the same floor as the rest of the build tooling so we are not claiming support we never test.

The floor is for the bare python3 fallback , which is 3.9.6 on a stock Mac and I tested that there end to end. Started with 3.10, trampoline disabled on Mac, 3.9 works. I've put 3.7 not for any premise there, but because it was compatible code wise and I've thought that maaaybe someone might try to build on something older. I think raising to 3.9 would be reasonable?

stratakis · 2026-09-12T01:13:22Z

* I was exploring the idea to use the _bootstrap_python instead of requiring an existent python installation in order to run _trampoline_ehframe.py‎ but I'm not sure if it works. This could be an improvement of the current implementation

A branch with some extra commits on top of this PR implementing that to see if it makes sense: main...stratakis:cpython:trampoline_bootstrap

However it's mostly Fable generated with a small review by gpt6, haven't checked the code much or done any rigorous testing apart from a simple build and tests. If it makes sense I can expand on this.

I'll check out the review comments the next days (or feel free to amend as you see fit :) )

pablogsal · 2026-09-12T01:37:37Z

I pushed a commit with some small cleanup for the main file to parse the debug info

stratakis requested review from AA-Turner, brandtbucher, corona10, diegorusso, emmatyping, erlend-aasland, itamaro and savannahostrowski as code owners September 10, 2026 01:45

bedevere-app Bot mentioned this pull request Sep 10, 2026

Refactor perf trampoline proposal: split the assembly per architecture, auto-generate DWARF unwind data #149800

Open

bedevere-app Bot added the awaiting review label Sep 10, 2026

stratakis marked this pull request as draft September 10, 2026 01:45

bedevere-app Bot removed the awaiting review label Sep 10, 2026

stratakis mentioned this pull request Sep 10, 2026

perf_jit activated from a subinterpreter publishes JIT executors with the trampoline's unwind info #157247

Open

stratakis marked this pull request as ready for review September 10, 2026 22:48

bedevere-app Bot added the awaiting review label Sep 10, 2026

pablogsal self-requested a review September 11, 2026 21:26

stratakis added 5 commits September 12, 2026 00:34

pythongh-149800: Add CFI directives to the perf trampoline assembly

30241aa

Let the assembler emit an .eh_frame for the trampoline, matching the frame layout jit_unwind.c describes.

pythongh-149800: Declare the perf trampoline template labels as char …

4439b52

…symbols

pythongh-149800: Test the generated perf trampoline unwind data

5534711

Check the FDEs in jitdump files against their code load records, cover the generator's parsers, and validate the header structure from C.

Skip the jitdump test on BOLT builds

0f6b805

stratakis force-pushed the trampoline_ehframe branch from 99dbd73 to 0f6b805 Compare September 11, 2026 22:37

pablogsal reviewed Sep 12, 2026

View reviewed changes

small reorganization to trampoline unwind generation

48c7945

Uh oh!

Uh oh!

Conversation

stratakis commented Sep 10, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

stratakis commented Sep 10, 2026

Uh oh!

stratakis commented Sep 10, 2026

Uh oh!

diegorusso commented Sep 11, 2026

Uh oh!

pablogsal commented Sep 11, 2026

Uh oh!

pablogsal commented Sep 11, 2026

Uh oh!

diegorusso commented Sep 11, 2026

Uh oh!

stratakis commented Sep 11, 2026

Uh oh!

stratakis commented Sep 11, 2026

Uh oh!

stratakis commented Sep 11, 2026

Uh oh!

pablogsal Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

stratakis Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

pablogsal Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stratakis Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

pablogsal Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

stratakis Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

stratakis commented Sep 12, 2026

Uh oh!

pablogsal commented Sep 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stratakis commented Sep 10, 2026 •

edited by bedevere-app Bot

Loading

python-cla-bot Bot commented Sep 10, 2026 •

edited

Loading

read-the-docs-community Bot commented Sep 10, 2026 •

edited

Loading

pablogsal Sep 12, 2026 •

edited

Loading