Adjust docs & comment

Author: encukou

Doc/howto/perf_profiling.rst

@@ -218,10 +218,8 @@ How to obtain the best results
 ------------------------------
 
 For best results, keep frame pointers enabled. On supported GCC-compatible
-toolchains, CPython builds itself with ``-fno-omit-frame-pointer`` and, when
-available, ``-mno-omit-leaf-frame-pointer`` by default. On 32-bit ARM,
-CPython also adds ``-marm`` when supported. On s390 platforms, CPython also
-adds ``-mbackchain`` when supported. These flags allow
+toolchains, CPython builds itself with ``-fno-omit-frame-pointer`` and similar
+flags (see :option:`--without-frame-pointers` for details). These flags allow
 profilers to unwind using only the frame pointer and not on DWARF debug
 information. This is because as the code that is interposed to allow ``perf``
 support is dynamically generated it doesn't have any DWARF debugging information

Doc/using/configure.rst

@@ -784,13 +784,19 @@ also be used to improve performance.
 
    Disable frame pointers, which are enabled by default (see :pep:`831`).
 
-   By default, the build appends ``-fno-omit-frame-pointer``,
-   ``-mno-omit-leaf-frame-pointer`` when the compiler supports it,
-   ``-marm`` on 32-bit ARM when supported, and ``-mbackchain`` on s390
-   platforms when supported, to ``BASECFLAGS`` so
-   profilers, debuggers, and system tracing tools
-   (``perf``, ``eBPF``, ``dtrace``, ``gdb``) can walk the C call stack
-   without DWARF metadata. The flags propagate to third-party C
+   By default, the build appends flags to generate frame or backchain
+   pointers to ``BASECFLAGS``:
+
+   - ``-fno-omit-frame-pointer`` and/or ``-mno-omit-leaf-frame-pointer``
+     are added when the compiler supports them,
+   - ``-marm`` is added on 32-bit ARM when supported,
+   - on s390x platforms, when supported, ``-mbackchain`` is added *instead*
+     of the above frame pointer flags
+
+   Frame pointers enable profilers, debuggers, and system tracing tools
+   (``perf``, ``eBPF``, ``dtrace``, ``gdb``) to walk the C call stack
+   without DWARF metadata.
+   The flags propagate to third-party C
    extensions through :mod:`sysconfig`. On compilers that do not
    understand them, the build silently skips them.
 

Doc/whatsnew/3.15.rst

@@ -2490,11 +2490,13 @@ Build changes
 
 * CPython is now built with frame pointers enabled by default
   (:pep:`831`). Pass :option:`--without-frame-pointers` to opt out.
+
   Authors of C extensions and native libraries built with custom build
-  systems should add ``-fno-omit-frame-pointer`` and
-  ``-mno-omit-leaf-frame-pointer`` to their own ``CFLAGS``,
-  ``-marm`` on 32-bit ARM, and ``-mbackchain`` on s390 platforms,
-  to keep the unwind chain intact.
+  systems should ensure the unwind chain is intact.
+  This is usually done by adding ``-fno-omit-frame-pointer`` and
+  similar flags to ``CFLAGS``. See :option:`--without-frame-pointers`
+  documentation for the specific flags Python uses.
+
   (Contributed by Pablo Galindo Salgado and Savannah Ostrowski in :gh:`149201`.)
 
 .. _whatsnew315-windows-tail-calling-interpreter:

Misc/NEWS.d/next/Core_and_Builtins/2026-04-05-16-10-00.gh-issue-149202.W8sQeR.rst

@@ -1,5 +1,5 @@
 Enable frame pointers by default for GCC-compatible CPython builds, including
-``-mno-omit-leaf-frame-pointer``, ``-marm`` on 32-bit ARM, and ``-mbackchain``
-on s390 platforms when the compiler supports them, so profilers and debuggers
+``-mno-omit-leaf-frame-pointer``, ``-marm`` on 32-bit ARM, and/or ``-mbackchain``
+on s390x platforms when the compiler supports them, so profilers and debuggers
 can unwind native interpreter frames more reliably. Users can pass
-``--without-frame-pointers`` to opt out.
+:option:`--without-frame-pointers` to ``./configure`` to opt out.

configure.ac

@@ -2563,7 +2563,8 @@ AS_VAR_IF([ac_cv_gcc_compat], [yes], [
     if test -n "$frame_pointer_cflags" && test "x$with_frame_pointers" != xno; then
       BASECFLAGS="$frame_pointer_cflags $BASECFLAGS"
       AC_DEFINE([_Py_WITH_FRAME_POINTERS], [1],
-                [Define to 1 if frame unwinding via pointers is expected to work, 0 if not])
+                [Define to 1 if frame unwinding via pointers is expected
+                 to work, 0 if not. Leave undefined if unknown.])
     fi
 
     CFLAGS_NODIST="$CFLAGS_NODIST -std=c11"

pyconfig.h.in

@@ -2073,8 +2073,8 @@
 /* Define if you want to use tail-calling interpreters in CPython. */
 #undef _Py_TAIL_CALL_INTERP
 
-/* Define to 1 if frame unwinding via pointers is expected to work, 0 if not
-   */
+/* Define to 1 if frame unwinding via pointers is expected to work, 0 if not.
+   Leave undefined if unknown. */
 #undef _Py_WITH_FRAME_POINTERS
 
 /* Define to force use of thread-safe errno, h_errno, and other functions */