gh-138122: Add incomplete sample detection and fix generator frame unwinding

This commit adds two related improvements to stack profiling:

1. Skip suspended generator frames during unwinding
   Generator frames at yield points have NULL previous pointers and don't
   link to callers via normal frame chains. These frames are now correctly
   skipped during stack unwinding to prevent broken chains.

2. Detect and reject incomplete samples
   Add PyThreadState.entry_frame to track the bottommost frame in each
   thread's call stack. The profiler validates that unwinding reaches
   this expected bottom frame. Samples that fail to unwind completely
   (due to race conditions, memory corruption, or other errors) are now
   rejected rather than being included as spurious single-frame stacks.

The entry_frame field is:
- Set when entering the first frame (when previous == NULL)
- Cleared when returning to no frames
- Exposed via debug offsets for remote profiling
- Compared against the last frame address reached during unwinding

This prevents corrupted profiling data from incomplete samples while
maintaining correct handling of suspended generator frames.

Author: pablogsal

Include/cpython/pystate.h

@@ -135,6 +135,11 @@ struct _ts {
     /* Pointer to currently executing frame. */
     struct _PyInterpreterFrame *current_frame;
 
+    /* Pointer to the entry/bottommost frame of the current call stack.
+     * This is the frame that was entered when starting execution.
+     * Used by profiling/sampling to detect incomplete stack traces. */
+    struct _PyInterpreterFrame *entry_frame;
+
     Py_tracefunc c_profilefunc;
     Py_tracefunc c_tracefunc;
     PyObject *c_profileobj;

Include/internal/pycore_debug_offsets.h

@@ -102,6 +102,7 @@ typedef struct _Py_DebugOffsets {
         uint64_t next;
         uint64_t interp;
         uint64_t current_frame;
+        uint64_t entry_frame;
         uint64_t thread_id;
         uint64_t native_thread_id;
         uint64_t datastack_chunk;
@@ -272,6 +273,7 @@ typedef struct _Py_DebugOffsets {
         .next = offsetof(PyThreadState, next), \
         .interp = offsetof(PyThreadState, interp), \
         .current_frame = offsetof(PyThreadState, current_frame), \
+        .entry_frame = offsetof(PyThreadState, entry_frame), \
         .thread_id = offsetof(PyThreadState, thread_id), \
         .native_thread_id = offsetof(PyThreadState, native_thread_id), \
         .datastack_chunk = offsetof(PyThreadState, datastack_chunk), \

Misc/NEWS.d/next/Core_and_Builtins/2025-11-24-16-07-57.gh-issue-138122.m3EF9E.rst

@@ -0,0 +1,11 @@
+Fix profiler stack unwinding to skip generator frames with NULL previous
+pointers. Generator frames at yield points are suspended objects that don't
+link to callers via normal frame chains, causing incomplete stack traces.
+The profiler now correctly skips these frames during stack unwinding.
+
+Add incomplete sample detection to prevent corrupted profiling data. The
+interpreter now tracks the entry frame (bottommost frame) in each thread's
+``PyThreadState.entry_frame``, which the profiler uses to validate that
+stack unwinding reached the expected bottom. Samples that fail to unwind
+completely (due to race conditions, memory corruption, or other errors)
+are now rejected rather than being included as spurious single-frame stacks.

Modules/_remote_debugging_module.c

@@ -2254,15 +2254,22 @@ is_frame_valid(
     }
 
     void* frame = (void*)frame_addr;
+    char owner = GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner);
 
-    if (GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) == FRAME_OWNED_BY_INTERPRETER) {
+    if (owner == FRAME_OWNED_BY_INTERPRETER) {
         return 0;  // C frame
     }
 
-    if (GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) != FRAME_OWNED_BY_GENERATOR
-        && GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) != FRAME_OWNED_BY_THREAD) {
-        PyErr_Format(PyExc_RuntimeError, "Unhandled frame owner %d.\n",
-                    GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner));
+    // Reject generator frames with NULL previous pointer - can't unwind past them
+    if (owner == FRAME_OWNED_BY_GENERATOR) {
+        uintptr_t previous = GET_MEMBER(uintptr_t, frame, unwinder->debug_offsets.interpreter_frame.previous);
+        if (previous == 0) {
+            return 0;  // Generator frame with no caller - skip it
+        }
+    }
+
+    if (owner != FRAME_OWNED_BY_GENERATOR && owner != FRAME_OWNED_BY_THREAD) {
+        PyErr_Format(PyExc_RuntimeError, "Unhandled frame owner %d.\n", owner);
         set_exception_cause(unwinder, PyExc_RuntimeError, "Unhandled frame owner type in async frame");
         return -1;
     }
@@ -2475,14 +2482,17 @@ process_frame_chain(
     uintptr_t initial_frame_addr,
     StackChunkList *chunks,
     PyObject *frame_info,
-    uintptr_t gc_frame)
+    uintptr_t gc_frame,
+    uintptr_t entry_frame_addr)
 {
     uintptr_t frame_addr = initial_frame_addr;
     uintptr_t prev_frame_addr = 0;
+    uintptr_t last_frame_addr = 0;  // Track the last frame we processed
     const size_t MAX_FRAMES = 1024;
     size_t frame_count = 0;
 
     while ((void*)frame_addr != NULL) {
+        last_frame_addr = frame_addr;  // Remember this frame before moving to next
         PyObject *frame = NULL;
         uintptr_t next_frame_addr = 0;
         uintptr_t stackpointer = 0;
@@ -2564,6 +2574,17 @@ process_frame_chain(
         frame_addr = next_frame_addr;
     }
 
+    // Validate we reached the entry frame if it's set
+    if (entry_frame_addr != 0 && last_frame_addr != 0) {
+        if (last_frame_addr != entry_frame_addr) {
+            // We didn't reach the expected bottom frame - incomplete sample
+            PyErr_Format(PyExc_RuntimeError,
+                "Incomplete sample: reached frame 0x%lx but expected entry frame 0x%lx",
+                last_frame_addr, entry_frame_addr);
+            return -1;
+        }
+    }
+
     return 0;
 }
 
@@ -2806,7 +2827,13 @@ unwind_stack_for_thread(
         goto error;
     }
 
-    if (process_frame_chain(unwinder, frame_addr, &chunks, frame_info, gc_frame) < 0) {
+    // Read entry_frame for validation
+    uintptr_t entry_frame_addr = 0;
+    if (unwinder->debug_offsets.thread_state.entry_frame != 0) {
+        entry_frame_addr = GET_MEMBER(uintptr_t, ts, unwinder->debug_offsets.thread_state.entry_frame);
+    }
+
+    if (process_frame_chain(unwinder, frame_addr, &chunks, frame_info, gc_frame, entry_frame_addr) < 0) {
         set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to process frame chain");
         goto error;
     }

Python/ceval.c

@@ -1234,6 +1234,10 @@ _PyEval_EvalFrameDefault(PyThreadState *tstate, _PyInterpreterFrame *frame, int
     entry.frame.previous = tstate->current_frame;
     frame->previous = &entry.frame;
     tstate->current_frame = frame;
+    /* Track entry frame for profiling/sampling */
+    if (entry.frame.previous == NULL) {
+        tstate->entry_frame = &entry.frame;
+    }
     entry.frame.localsplus[0] = PyStackRef_NULL;
 #ifdef _Py_TIER2
     if (tstate->current_executor != NULL) {
@@ -1300,6 +1304,10 @@ _PyEval_EvalFrameDefault(PyThreadState *tstate, _PyInterpreterFrame *frame, int
     assert(frame->owner == FRAME_OWNED_BY_INTERPRETER);
     /* Restore previous frame and exit */
     tstate->current_frame = frame->previous;
+    /* Clear entry frame if we're returning to no frame */
+    if (tstate->current_frame == NULL) {
+        tstate->entry_frame = NULL;
+    }
     return NULL;
 }
 #ifdef _Py_TIER2

Python/pystate.c

@@ -1483,6 +1483,7 @@ init_threadstate(_PyThreadStateImpl *_tstate,
     tstate->gilstate_counter = 1;
 
     tstate->current_frame = NULL;
+    tstate->entry_frame = NULL;
     tstate->datastack_chunk = NULL;
     tstate->datastack_top = NULL;
     tstate->datastack_limit = NULL;