Relax JIT GDB test backtrace shape

diegorusso · diegorusso · commit 445ab53a95e2 · 2026-04-24T15:02:55.000+01:00
Accept either JIT backtrace shape in test_jit.py:
- py::jit:executor -&gt; _PyEval_*
- py::jit:executor -&gt; _PyJIT_Entry -&gt; _PyEval_*

This avoids baking in architecture-specific unwind details while still
checking that GDB gets out of the JIT region and back into the eval loop.
diff --git a/Include/internal/pycore_uop_metadata.h b/Include/internal/pycore_uop_metadata.h
diff --git a/Lib/test/test_gdb/test_jit.py b/Lib/test/test_gdb/test_jit.py
@@ -24,8 +24,8 @@
 # JIT region, instead of asserting against a misleading backtrace.
 MAX_JIT_ENTRY_STEPS = 4
 EVAL_FRAME_RE = r"(_PyEval_EvalFrameDefault|_PyEval_Vector)"
-JIT_ENTRY_RE = r"_PyJIT_Entry"
 JIT_EXECUTOR_FRAME = "py::jit:executor"
+JIT_ENTRY_SYMBOL = "_PyJIT_Entry"
 BACKTRACE_FRAME_RE = re.compile(r"^#\d+\s+.*$", re.MULTILINE)
 
 FINISH_TO_JIT_EXECUTOR = (
@@ -92,14 +92,12 @@ def _assert_jit_backtrace_shape(self, gdb_output, *, anchor_at_top):
         #      py::jit:executor frame would mean the unwinder is
         #      materializing two native frames for a single logical JIT
         #      region, or failing to unwind out of the region entirely.
-        #   2. The linked shim frame appears exactly once after the
-        #      synthetic JIT frame and before the eval loop.
-        #   3. At least one _PyEval_EvalFrameDefault / _PyEval_Vector
-        #      frame appears after the JIT frame, proving the unwinder
-        #      climbs back out of the JIT region into the eval loop.
-        #      Helper frames from inside the JITted region may still
-        #      appear above the synthetic JIT frame in the backtrace.
-        #   4. For tests that assert a specific entry PC, the JIT frame
+        #   2. The unwinder must climb back out of the JIT region into
+        #      the eval loop. Some platforms materialize a real
+        #      _PyJIT_Entry frame between the synthetic executor frame
+        #      and _PyEval_*, while others unwind directly from the
+        #      executor into _PyEval_*. Accept both shapes.
+        #   3. For tests that assert a specific entry PC, the JIT frame
         #      is also at #0.
         frames = self._extract_backtrace_frames(gdb_output)
         backtrace = "\n".join(frames)
@@ -111,13 +109,6 @@ def _assert_jit_backtrace_shape(self, gdb_output, *, anchor_at_top):
             f"expected exactly 1 {JIT_EXECUTOR_FRAME} frame, got {jit_count}\n"
             f"backtrace:\n{backtrace}",
         )
-        jit_entry_frames = [frame for frame in frames if re.search(JIT_ENTRY_RE, frame)]
-        jit_entry_count = len(jit_entry_frames)
-        self.assertEqual(
-            jit_entry_count, 1,
-            f"expected exactly 1 _PyJIT_Entry frame, got {jit_entry_count}\n"
-            f"backtrace:\n{backtrace}",
-        )
         eval_frames = [frame for frame in frames if re.search(EVAL_FRAME_RE, frame)]
         eval_count = len(eval_frames)
         self.assertGreaterEqual(
@@ -128,38 +119,45 @@ def _assert_jit_backtrace_shape(self, gdb_output, *, anchor_at_top):
         jit_frame_index = next(
             i for i, frame in enumerate(frames) if JIT_EXECUTOR_FRAME in frame
         )
-        jit_entry_index = next(
-            i for i, frame in enumerate(frames) if re.search(JIT_ENTRY_RE, frame)
-        )
-        self.assertGreater(
-            jit_entry_index, jit_frame_index,
-            "expected _PyJIT_Entry after the synthetic JIT frame\n"
-            f"backtrace:\n{backtrace}",
-        )
-        eval_after_jit = any(
-            re.search(EVAL_FRAME_RE, frame)
-            for frame in frames[jit_frame_index + 1:]
+        frames_after_jit = frames[jit_frame_index + 1:]
+        first_eval_offset = next(
+            (
+                i for i, frame in enumerate(frames_after_jit)
+                if re.search(EVAL_FRAME_RE, frame)
+            ),
+            None,
         )
-        self.assertTrue(
-            eval_after_jit,
+        self.assertIsNotNone(
+            first_eval_offset,
             f"expected an eval frame after the JIT frame\n"
             f"backtrace:\n{backtrace}",
         )
-        eval_after_entry = any(
-            re.search(EVAL_FRAME_RE, frame)
-            for frame in frames[jit_entry_index + 1:]
+        between_jit_and_eval = frames_after_jit[:first_eval_offset]
+        jit_entry_frames = [
+            frame for frame in between_jit_and_eval
+            if JIT_ENTRY_SYMBOL in frame
+        ]
+        self.assertLessEqual(
+            len(jit_entry_frames), 1,
+            f"expected at most one {JIT_ENTRY_SYMBOL} frame between the "
+            f"executor and eval frames\nbacktrace:\n{backtrace}",
         )
-        self.assertTrue(
-            eval_after_entry,
-            "expected an eval frame after _PyJIT_Entry\n"
+        unexpected_between = [
+            frame for frame in between_jit_and_eval
+            if JIT_ENTRY_SYMBOL not in frame
+        ]
+        self.assertFalse(
+            unexpected_between,
+            "expected only an optional _PyJIT_Entry frame between the "
+            "executor and eval frames\n"
             f"backtrace:\n{backtrace}",
         )
         relevant_end = max(
             i
             for i, frame in enumerate(frames)
             if (
                 JIT_EXECUTOR_FRAME in frame
-                or re.search(JIT_ENTRY_RE, frame)
+                or JIT_ENTRY_SYMBOL in frame
                 or re.search(EVAL_FRAME_RE, frame)
             )
         )
@@ -188,6 +186,23 @@ def test_bt_unwinds_through_jit_frames(self):
         # the eval loop.
         self._assert_jit_backtrace_shape(gdb_output, anchor_at_top=False)
 
+    def test_bt_handoff_from_jit_entry_to_executor(self):
+        gdb_output = self.get_stack_trace(
+            script=JIT_SAMPLE_SCRIPT,
+            breakpoint=JIT_ENTRY_SYMBOL,
+            cmds_after_breakpoint=[
+                "delete 1",
+                "tbreak builtin_id",
+                "continue",
+                "bt",
+            ],
+            PYTHON_JIT="1",
+        )
+        # If we stop first in the shim and then continue into the real JIT
+        # workload, the final backtrace should match the architecture's
+        # executor unwind contract.
+        self._assert_jit_backtrace_shape(gdb_output, anchor_at_top=False)
+
     def test_bt_unwinds_from_inside_jit_executor(self):
         gdb_output = self.get_stack_trace(
             script=JIT_SAMPLE_SCRIPT,
diff --git a/Python/bytecodes.c b/Python/bytecodes.c
@@ -6118,11 +6118,6 @@ dummy_func(
 #ifndef _Py_JIT
             assert(current_executor == (_PyExecutorObject*)executor);
 #endif
-            // Keep the return-to-_PyJIT_Entry PC in a reserved
-            // callee-saved register so the executor-wide GDB FDE can
-            // always materialize _PyJIT_Entry as the immediate caller
-            // frame.
-            _Py_JIT_CAPTURE_CALLER_PC();
             assert(tstate->jit_exit == NULL || tstate->jit_exit->executor == current_executor);
             tstate->current_executor = (PyObject *)current_executor;
             if (!current_executor->vm_data.valid) {
diff --git a/Python/ceval_macros.h b/Python/ceval_macros.h
@@ -168,21 +168,6 @@
 #define STOP_TRACING() ((void)(0));
 #endif
 
-/*
- * The executor runs inside the frame established by _PyJIT_Entry. On AArch64,
- * helper-calling stencils would otherwise leave the return-to-_PyJIT_Entry PC
- * in different places at different executor PCs. Capture the entry x30 into
- * reserved x28 once so the executor-wide GDB FDE in Python/jit_unwind.c can
- * always materialize _PyJIT_Entry as the immediate caller frame.
- */
-#if defined(_Py_JIT) && defined(__aarch64__) && defined(__AARCH64EL__) && !defined(__ILP32__)
-#  define _Py_JIT_CAPTURE_CALLER_PC() \
-    __asm__ volatile("mov x28, x30")
-#else
-#  define _Py_JIT_CAPTURE_CALLER_PC() ((void)0)
-#endif
-
-
 /* PRE_DISPATCH_GOTO() does lltrace if enabled. Normally a no-op */
 #ifdef Py_DEBUG
 #define PRE_DISPATCH_GOTO() if (frame->lltrace >= 5) { \
diff --git a/Python/executor_cases.c.h b/Python/executor_cases.c.h
diff --git a/Python/jit_unwind.c b/Python/jit_unwind.c
@@ -36,7 +36,6 @@
 enum {
     DWRF_CFA_nop = 0x0,                    // No operation
     DWRF_CFA_offset_extended = 0x5,        // Extended offset instruction
-    DWRF_CFA_register = 0x9,               // Register contains saved value
     DWRF_CFA_def_cfa = 0xc,               // Define CFA rule
     DWRF_CFA_def_cfa_register = 0xd,      // Define CFA register
     DWRF_CFA_def_cfa_offset = 0xe,        // Define CFA offset
@@ -75,7 +74,6 @@ enum {
     DWRF_REG_RA,    // Return address (RIP)
 #elif defined(__aarch64__) && defined(__AARCH64EL__) && !defined(__ILP32__)
     /* AArch64 register numbering */
-    DWRF_REG_JIT_RA = 28,  // Reserved x28 holds the return PC into _PyJIT_Entry
     DWRF_REG_FP = 29,  // Frame Pointer
     DWRF_REG_RA = 30,  // Link register (return address)
     DWRF_REG_SP = 31,  // Stack pointer
@@ -620,13 +618,16 @@ static void elf_init_ehframe_perf(ELFObjectContext* ctx) {
  * executor region:
  *
  *   x86_64:  CFA = %rbp + 16, return-to-_PyJIT_Entry PC at cfa-72
- *   AArch64: CFA = x29 + 96, return-to-_PyJIT_Entry PC in reserved x28
+ *   AArch64: CFA = x29 + 96, caller x29 at cfa-96, caller x30 at cfa-88
  *
- * Executor stencils never touch the frame pointer — enforced by
- * Tools/jit/_optimizers.py _validate() and -mframe-pointer=reserved — so
- * that rule is valid at every PC and the FDE body is empty. On AArch64,
- * _START_EXECUTOR copies the entry x30 into reserved x28 once and the
- * executor stencils preserve x28 thereafter.
+ * The executor runs inside the frame established by _PyJIT_Entry. On AArch64
+ * we collapse that state into a single synthetic executor frame that unwinds
+ * directly into _PyEval_*. On x86_64 the normal call into the executor leaves
+ * a real return slot back into _PyJIT_Entry, so the executor FDE materializes
+ * _PyJIT_Entry as the caller frame. Executor stencils never touch the frame
+ * pointer — enforced by Tools/jit/_optimizers.py _validate() and
+ * -mframe-pointer=reserved — so the steady-state rule is valid at every PC
+ * and the FDE body is empty.
  */
 static void elf_init_ehframe_gdb(ELFObjectContext* ctx) {
     int fde_ptr_enc = DWRF_EH_PE_absptr;
@@ -658,9 +659,10 @@ static void elf_init_ehframe_gdb(ELFObjectContext* ctx) {
         DWRF_U8(DWRF_CFA_def_cfa);            // CFA = x29 + 96
         DWRF_UV(DWRF_REG_FP);
         DWRF_UV(96);
-        DWRF_U8(DWRF_CFA_register);           // Return PC lives in reserved x28
-        DWRF_UV(DWRF_REG_RA);
-        DWRF_UV(DWRF_REG_JIT_RA);
+        DWRF_U8(DWRF_CFA_offset | DWRF_REG_FP);
+        DWRF_UV(12);                          // caller x29 at cfa-96
+        DWRF_U8(DWRF_CFA_offset | DWRF_REG_RA);
+        DWRF_UV(11);                          // caller x30 at cfa-88
 #else
 #    error "Unsupported target architecture"
 #endif
diff --git a/Tools/jit/_targets.py b/Tools/jit/_targets.py
@@ -200,10 +200,6 @@ async def _build_stencil_group(
         ]
         if self.frame_pointers:
             args_s += ["-Xclang", "-mframe-pointer=reserved"]
-            if self.triple.startswith("aarch64-"):
-                # Keep x28 free so _START_EXECUTOR can stash the return-to-_PyJIT_Entry
-                # PC there for a single executor-wide unwind rule.
-                args_s += ["-ffixed-x28"]
         args_s += self._compile_args()
         # Allow user-provided CFLAGS to override any defaults
         args_s += shlex.split(self.cflags)
@@ -238,7 +234,7 @@ async def _build_shim_object(self, output: pathlib.Path) -> None:
             args_o += self._shim_compile_args()
             args_o += [
                 "-c",
-                # The linked shim is a real function in the final binary, so
+                # The shim is a real function in the final binary, so
                 # keep unwind info for debuggers and stack walkers.
                 "-fasynchronous-unwind-tables",
             ]
@@ -336,7 +332,7 @@ class _COFF(
     _Target[_schema.COFFSection, _schema.COFFRelocation]
 ):  # pylint: disable = too-few-public-methods
     def _shim_compile_args(self) -> list[str]:
-        # The linked shim is part of pythoncore, not a shared extension.
+        # The shim is part of pythoncore, not a shared extension.
         # On Windows, Py_BUILD_CORE_MODULE makes public APIs import from
         # pythonXY.lib, which creates a self-dependency when linking
         # pythoncore.dll. Build the shim with builtin/core semantics.
