cpython/Doc/howto
Pablo Galindo Salgado 4ed40146f1
gh-149202: Fix frame pointer unwinding on s390x and ARM (GH-149362)
-fno-omit-frame-pointer is not enough to make every target walkable by the
simple manual frame pointer unwinder.

The helper used by test_frame_pointer_unwind used to assume the frame pointer
named a two-word record where fp[0] was the previous frame pointer and fp[1]
was the return address. That is only the generic layout used by some targets.
This patch keeps that default, but moves the slots behind named offsets so
architecture-specific layouts can describe where the backchain and return
address really live.

On s390x, GCC and Clang do not emit a usable backchain unless -mbackchain is
enabled. Without it, the unwinder stops at the current C frame and the test
reports no Python frames. Once backchains are present, the helper must also
stop at the current thread's known C stack bounds; otherwise it can follow the
final backchain far enough to dereference an invalid frame and segfault.
For Linux s390x backchain frames, the documented z/Architecture stack-frame
layout saves r14, the return-address register, at byte offset 112 from the
frame pointer, so read the return address from that named slot instead of fp[1].

The 112-byte offset comes from Linux's s390 debugging documentation: its Stack
Frame Layout table shows z/Architecture backchain frames with the backchain at
offset 0 and saved r14 of the caller function at offset 112:
https://www.kernel.org/doc/html/v5.3/s390/debugging390.html#stack-frame-layout

This helper remains scoped to Linux s390x backchain frames. GNU SFrame's s390x
notes state that the s390x ELF ABI does not generally mandate where RA and FP
are saved, or whether they are saved at all:
https://sourceware.org/binutils/docs/sframe-spec.html#s390x

As Jens Remus noted, -fno-omit-frame-pointer is not needed when -mbackchain is
present.

On 32-bit ARM, GCC defaults to Thumb mode on common armhf toolchains. The Thumb
prologue keeps the saved frame pointer and link register at offsets that depend
on the generated frame, which breaks the fp[0]/fp[1] walk used by the helper.
Use -marm when it is supported for frame-pointer builds, and teach the helper
the GCC ARM-mode slots where the previous frame pointer is at fp[-1] and the
saved LR return address is at fp[0].


Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
2026-05-06 15:03:37 +00:00
..
a-conceptual-overview-of-asyncio.rst gh-138199: Address potential confusion regarding threading in the asyncio HOWTO (GH-138200) 2025-11-24 14:08:49 +00:00
annotations.rst gh-134370: Added clarification on instance annotations (#134387) 2025-05-22 06:46:29 -07:00
argparse-optparse.rst gh-126180: Remove getopt and optparse deprecation notices (GH-126227) 2024-12-23 14:17:19 +10:00
argparse.rst gh-126180: Remove getopt and optparse deprecation notices (GH-126227) 2024-12-23 14:17:19 +10:00
clinic.rst GH-107518: Remove the Argument Clinic How-To (#109900) 2023-10-11 14:57:51 +02:00
cporting.rst gh-133678: Document C API third party tools (#134526) 2025-05-27 17:38:30 +02:00
curses.rst gh-133579: consistently report C curses function failures (#134327) 2025-05-27 10:15:16 +00:00
descriptor.rst gh-149083: Change several other docs examples to use sentinel() (#149213) 2026-05-01 22:53:28 +03:00
enum.rst [Enum] Improve clarity of comparison sentence (GH-148753) 2026-04-21 10:17:02 -07:00
free-threading-extensions.rst gh-148892: Drop mention of deprecated cibuildwheel option (#148893) 2026-04-23 09:30:35 +05:30
free-threading-python.rst gh-140281: Update free threading Python HOWTO for 3.14 (gh-140566) 2025-12-02 05:53:12 +00:00
functional.rst GH-121970: Remove Docutils list monkeypatch (#142056) 2025-11-29 14:28:23 +00:00
gdb_helpers.rst GH-65961: Stop setting __cached__ on modules (GH-142165) 2025-12-11 11:44:46 -08:00
index.rst gh-137026: Add an explainer guide for asyncio (GH-137215) 2025-08-08 22:29:51 -07:00
instrumentation.rst gh-141004: Document PyDTrace* (GH-141856) 2026-03-14 22:58:35 -04:00
ipaddress.rst bpo-44740: Make minor edits to lowercasing "internet" and "web". (GH-27385) 2021-07-27 10:57:52 +02:00
isolating-extensions.rst gh-138189: Link references to type slots (GH-141410) 2025-11-18 16:33:52 +01:00
logging-cookbook.rst gh-86519: Update docs for prefixmatch (#148096) 2026-04-14 20:15:06 +03:00
logging.rst doc: Clarify logger creation example in logging HOWTO (GH-145540) 2026-03-05 17:48:48 +00:00
logging_flow.png gh-121035: Update PNG image for logging flow diagram. (GH-121323) 2024-07-03 12:33:28 +01:00
logging_flow.svg gh-121035: Further improve logging flow diagram with respect to dark/light modes. (GH-121265) 2024-07-02 18:57:34 +01:00
mro.rst Docs: fix typo in Doc/howto/mro.rst (GH-129095) 2025-01-21 10:22:13 +01:00
perf_profiling.rst gh-149202: Fix frame pointer unwinding on s390x and ARM (GH-149362) 2026-05-06 15:03:37 +00:00
pyporting.rst gh-119779: Fix pyporting howto docs (#119785) 2024-05-30 18:51:22 +03:00
regex.rst gh-86519: Update docs for prefixmatch (#148096) 2026-04-14 20:15:06 +03:00
remote_debugging.rst gh-148022: Add threat model to remote debugging docs (#148024) 2026-04-03 14:20:50 +00:00
sockets.rst gh-75898: make use of thread more explicit in the "Socket Programming HOWTO" document (#125023) 2024-10-08 17:43:37 +05:30
sorting.rst Sorting techniques edits (#124701) 2024-09-27 17:19:44 -07:00
timerfd.rst Fix typo in Doc/howto/timerfd.rst (GH-118376) 2024-04-29 14:01:03 +03:00
unicode.rst gh-106318: Add example for str.isalpha() (#137557) 2025-11-24 14:10:35 +00:00
urllib2.rst Docs: Prepare for Sphinx 9 (#142057) 2025-11-29 16:49:37 +02:00