/******************************************************************************

* Python Remote Debugging Module

*

* This module provides functionality to debug Python processes remotely by

* reading their memory and reconstructing stack traces and asyncio task states.

******************************************************************************/

#define _GNU_SOURCE

/* ============================================================================

* HEADERS AND INCLUDES

* ============================================================================ */

#ifndef Py_BUILD_CORE_BUILTIN

# define Py_BUILD_CORE_MODULE 1

#endif

#include "Python.h"

#include <internal/pycore_debug_offsets.h> // _Py_DebugOffsets

#include <internal/pycore_frame.h> // FRAME_SUSPENDED_YIELD_FROM

#include <internal/pycore_interpframe.h> // FRAME_OWNED_BY_CSTACK

#include <internal/pycore_llist.h> // struct llist_node

#include <internal/pycore_stackref.h> // Py_TAG_BITS

#include <internal/pycore_tstate.h> // _PyThreadStateImpl

#include "../Python/remote_debug.h"

// gh-141784: Python.h header must be included first, before system headers.

// Otherwise, some types such as ino_t can be defined differently, causing ABI

// issues.

#include <errno.h>

#include <fcntl.h>

#include <stddef.h>

#include <stdint.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#ifndef HAVE_PROCESS_VM_READV

# define HAVE_PROCESS_VM_READV 0

#endif

/* ============================================================================

* TYPE DEFINITIONS AND STRUCTURES

* ============================================================================ */

#define GET_MEMBER(type, obj, offset) \

(*(type *)memcpy(&(type){0}, (const char *)(obj) + (offset), sizeof(type)))

#define CLEAR_PTR_TAG(ptr) (((uintptr_t)(ptr) & ~Py_TAG_BITS))

#define GET_MEMBER_NO_TAG(type, obj, offset) \

(type)(CLEAR_PTR_TAG(GET_MEMBER(type, obj, offset)))

/* Size macros for opaque buffers */

#define SIZEOF_BYTES_OBJ sizeof(PyBytesObject)

#define SIZEOF_CODE_OBJ sizeof(PyCodeObject)

#define SIZEOF_GEN_OBJ sizeof(PyGenObject)

#define SIZEOF_INTERP_FRAME sizeof(_PyInterpreterFrame)

#define SIZEOF_LLIST_NODE sizeof(struct llist_node)

#define SIZEOF_PAGE_CACHE_ENTRY sizeof(page_cache_entry_t)

#define SIZEOF_PYOBJECT sizeof(PyObject)

#define SIZEOF_SET_OBJ sizeof(PySetObject)

#define SIZEOF_TASK_OBJ 4096

#define SIZEOF_THREAD_STATE sizeof(PyThreadState)

#define SIZEOF_TYPE_OBJ sizeof(PyTypeObject)

#define SIZEOF_UNICODE_OBJ sizeof(PyUnicodeObject)

#define SIZEOF_LONG_OBJ sizeof(PyLongObject)

// Calculate the minimum buffer size needed to read interpreter state fields

// We need to read code_object_generation and potentially tlbc_generation

#ifndef MAX

#define MAX(a, b) ((a) > (b) ? (a) : (b))

#endif

#ifdef Py_GIL_DISABLED

#define INTERP_STATE_MIN_SIZE MAX(MAX(MAX(offsetof(PyInterpreterState, _code_object_generation) + sizeof(uint64_t), \

offsetof(PyInterpreterState, tlbc_indices.tlbc_generation) + sizeof(uint32_t)), \

offsetof(PyInterpreterState, threads.head) + sizeof(void*)), \

offsetof(PyInterpreterState, _gil.last_holder) + sizeof(PyThreadState*))

#else

#define INTERP_STATE_MIN_SIZE MAX(MAX(offsetof(PyInterpreterState, _code_object_generation) + sizeof(uint64_t), \

offsetof(PyInterpreterState, threads.head) + sizeof(void*)), \

offsetof(PyInterpreterState, _gil.last_holder) + sizeof(PyThreadState*))

#endif

#define INTERP_STATE_BUFFER_SIZE MAX(INTERP_STATE_MIN_SIZE, 256)

#define MAX_STACK_CHUNK_SIZE (16 * 1024 * 1024) /* 16 MB max for stack chunks */

#define MAX_SET_TABLE_SIZE (1 << 20) /* 1 million entries max for set iteration */

#define MAX_LONG_DIGITS 64 /* Allows values up to ~2^1920 */

// Copied from Modules/_asynciomodule.c because it's not exported

struct _Py_AsyncioModuleDebugOffsets {

struct _asyncio_task_object {

uint64_t size;

uint64_t task_name;

uint64_t task_awaited_by;

uint64_t task_is_task;

uint64_t task_awaited_by_is_set;

uint64_t task_coro;

uint64_t task_node;

} asyncio_task_object;

struct _asyncio_interpreter_state {

uint64_t size;

uint64_t asyncio_tasks_head;

} asyncio_interpreter_state;

struct _asyncio_thread_state {

uint64_t size;

uint64_t asyncio_running_loop;

uint64_t asyncio_running_task;

uint64_t asyncio_tasks_head;

} asyncio_thread_state;

};

/* Treat the remote debug tables as untrusted input and validate every

* size/offset we later dereference against a fixed local buffer or object

* layout before the unwinder starts using them. */

#define FIELD_SIZE(type, member) sizeof(((type *)0)->member)

#define PY_REMOTE_DEBUG_INVALID_ASYNC_DEBUG_OFFSETS (-2)

static inline int

validate_section_size(const char *section_name, uint64_t size)

{

if (size == 0) {

PyErr_Format(

PyExc_RuntimeError,

"Invalid debug offsets: %s.size must be greater than zero",

section_name);

return -1;

}

return 0;

}

static inline int

validate_read_size(const char *section_name, uint64_t size, size_t buffer_size)

{

if (validate_section_size(section_name, size) < 0) {

return -1;

}

if (size > buffer_size) {

PyErr_Format(

PyExc_RuntimeError,

"Invalid debug offsets: %s.size=%llu exceeds local buffer size %zu",

section_name,

(unsigned long long)size,

buffer_size);

return -1;

}

return 0;

}

static inline int

validate_span(

const char *field_name,

uint64_t offset,

size_t width,

uint64_t limit,

const char *limit_name)

{

uint64_t span = (uint64_t)width;

if (span > limit || offset > limit - span) {

PyErr_Format(

PyExc_RuntimeError,

"Invalid debug offsets: %s=%llu with width %zu exceeds %s %llu",

field_name,

(unsigned long long)offset,

width,

limit_name,

(unsigned long long)limit);

return -1;

}

return 0;

}

static inline int

validate_alignment(

const char *field_name,

uint64_t offset,

size_t alignment)

{

if (alignment > 1 && offset % alignment != 0) {

PyErr_Format(

PyExc_RuntimeError,

"Invalid debug offsets: %s=%llu is not aligned to %zu bytes",

field_name,

(unsigned long long)offset,

alignment);

return -1;

}

return 0;

}

static inline int

validate_field(

const char *field_name,

uint64_t offset,

uint64_t reported_size,

size_t width,

size_t alignment,

size_t buffer_size)

{

if (validate_alignment(field_name, offset, alignment) < 0) {

return -1;

}

if (validate_span(field_name, offset, width, reported_size, "reported size") < 0) {

return -1;

}

return validate_span(field_name, offset, width, buffer_size, "local buffer size");

}

static inline int

validate_fixed_field(

const char *field_name,

uint64_t offset,

size_t width,

size_t alignment,

size_t buffer_size)

{

if (validate_alignment(field_name, offset, alignment) < 0) {

return -1;

}

return validate_span(field_name, offset, width, buffer_size, "local buffer size");

}

#define PY_REMOTE_DEBUG_VALIDATE_SECTION(section) \

do { \

if (validate_section_size(#section, debug_offsets->section.size) < 0) { \

return -1; \

} \

} while (0)

#define PY_REMOTE_DEBUG_VALIDATE_READ_SECTION(section, buffer_size) \

do { \

if (validate_read_size(#section, debug_offsets->section.size, buffer_size) < 0) { \

return -1; \

} \

} while (0)

#define PY_REMOTE_DEBUG_VALIDATE_FIELD(section, field, field_size, field_alignment, buffer_size) \

do { \

if (validate_field( \

#section "." #field, \

debug_offsets->section.field, \

debug_offsets->section.size, \

field_size, \

field_alignment, \

buffer_size) < 0) { \

return -1; \

} \

} while (0)

#define PY_REMOTE_DEBUG_VALIDATE_FIXED_FIELD(section, field, field_size, field_alignment, buffer_size) \

do { \

if (validate_fixed_field( \

#section "." #field, \

debug_offsets->section.field, \

field_size, \

field_alignment, \

buffer_size) < 0) { \

return -1; \

} \

} while (0)

static inline int

validate_debug_offsets_layout(struct _Py_DebugOffsets *debug_offsets)

{

PY_REMOTE_DEBUG_VALIDATE_SECTION(runtime_state);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

runtime_state,

interpreters_head,

sizeof(uintptr_t),

_Alignof(uintptr_t),

sizeof(_PyRuntimeState));

PY_REMOTE_DEBUG_VALIDATE_SECTION(interpreter_state);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

threads_head,

sizeof(uintptr_t),

_Alignof(uintptr_t),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

threads_main,

sizeof(uintptr_t),

_Alignof(uintptr_t),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

gil_runtime_state_locked,

sizeof(int),

_Alignof(int),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

gil_runtime_state_holder,

sizeof(PyThreadState *),

_Alignof(PyThreadState *),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

code_object_generation,

sizeof(uint64_t),

_Alignof(uint64_t),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_state,

tlbc_generation,

sizeof(uint32_t),

_Alignof(uint32_t),

INTERP_STATE_BUFFER_SIZE);

PY_REMOTE_DEBUG_VALIDATE_READ_SECTION(thread_state, SIZEOF_THREAD_STATE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

thread_state,

next,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_THREAD_STATE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

thread_state,

current_frame,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_THREAD_STATE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

thread_state,

native_thread_id,

sizeof(unsigned long),

_Alignof(unsigned long),

SIZEOF_THREAD_STATE);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

thread_state,

datastack_chunk,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_THREAD_STATE);

PY_REMOTE_DEBUG_VALIDATE_SECTION(interpreter_frame);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

previous,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

executable,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

instr_ptr,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

owner,

sizeof(char),

_Alignof(char),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

stackpointer,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

interpreter_frame,

tlbc_index,

sizeof(int32_t),

_Alignof(int32_t),

SIZEOF_INTERP_FRAME);

PY_REMOTE_DEBUG_VALIDATE_SECTION(code_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

qualname,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

filename,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

linetable,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

firstlineno,

sizeof(int),

_Alignof(int),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

co_code_adaptive,

sizeof(char),

_Alignof(char),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

code_object,

co_tlbc,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_CODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(pyobject);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

pyobject,

ob_type,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_PYOBJECT);

PY_REMOTE_DEBUG_VALIDATE_SECTION(type_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

type_object,

tp_flags,

sizeof(unsigned long),

_Alignof(unsigned long),

SIZEOF_TYPE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(set_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

set_object,

used,

sizeof(Py_ssize_t),

_Alignof(Py_ssize_t),

SIZEOF_SET_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

set_object,

mask,

sizeof(Py_ssize_t),

_Alignof(Py_ssize_t),

SIZEOF_SET_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

set_object,

table,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_SET_OBJ);

PY_REMOTE_DEBUG_VALIDATE_READ_SECTION(long_object, SIZEOF_LONG_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

long_object,

lv_tag,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_LONG_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

long_object,

ob_digit,

sizeof(digit),

_Alignof(digit),

SIZEOF_LONG_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(bytes_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

bytes_object,

ob_size,

sizeof(Py_ssize_t),

_Alignof(Py_ssize_t),

SIZEOF_BYTES_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

bytes_object,

ob_sval,

sizeof(char),

_Alignof(char),

SIZEOF_BYTES_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(unicode_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

unicode_object,

length,

sizeof(Py_ssize_t),

_Alignof(Py_ssize_t),

SIZEOF_UNICODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

unicode_object,

asciiobject_size,

sizeof(char),

_Alignof(char),

SIZEOF_UNICODE_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(gen_object);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

gen_object,

gi_frame_state,

sizeof(int8_t),

_Alignof(int8_t),

SIZEOF_GEN_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

gen_object,

gi_iframe,

FIELD_SIZE(PyGenObject, gi_iframe),

_Alignof(_PyInterpreterFrame),

SIZEOF_GEN_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIXED_FIELD(

llist_node,

next,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_LLIST_NODE);

return 0;

}

static inline int

validate_async_debug_offsets_layout(struct _Py_AsyncioModuleDebugOffsets *debug_offsets)

{

PY_REMOTE_DEBUG_VALIDATE_READ_SECTION(asyncio_task_object, SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_name,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_awaited_by,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_is_task,

sizeof(char),

_Alignof(char),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_awaited_by_is_set,

sizeof(char),

_Alignof(char),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_coro,

sizeof(uintptr_t),

_Alignof(uintptr_t),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_task_object,

task_node,

SIZEOF_LLIST_NODE,

_Alignof(struct llist_node),

SIZEOF_TASK_OBJ);

PY_REMOTE_DEBUG_VALIDATE_SECTION(asyncio_interpreter_state);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_interpreter_state,

asyncio_tasks_head,

SIZEOF_LLIST_NODE,

_Alignof(struct llist_node),

sizeof(PyInterpreterState));

PY_REMOTE_DEBUG_VALIDATE_SECTION(asyncio_thread_state);

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_thread_state,

asyncio_running_loop,

sizeof(uintptr_t),

_Alignof(uintptr_t),

sizeof(_PyThreadStateImpl));

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_thread_state,

asyncio_running_task,

sizeof(uintptr_t),

_Alignof(uintptr_t),

sizeof(_PyThreadStateImpl));

PY_REMOTE_DEBUG_VALIDATE_FIELD(

asyncio_thread_state,

asyncio_tasks_head,

SIZEOF_LLIST_NODE,

_Alignof(struct llist_node),

sizeof(_PyThreadStateImpl));

return 0;

}

#undef PY_REMOTE_DEBUG_VALIDATE_SECTION

#undef PY_REMOTE_DEBUG_VALIDATE_READ_SECTION

#undef PY_REMOTE_DEBUG_VALIDATE_FIELD

#undef PY_REMOTE_DEBUG_VALIDATE_FIXED_FIELD

#undef FIELD_SIZE

/* ============================================================================

* STRUCTSEQ TYPE DEFINITIONS

* ============================================================================ */

// TaskInfo structseq type - replaces 4-tuple (task_id, task_name, coroutine_stack, awaited_by)

static PyStructSequence_Field TaskInfo_fields[] = {

{"task_id", "Task ID (memory address)"},

{"task_name", "Task name"},

{"coroutine_stack", "Coroutine call stack"},

{"awaited_by", "Tasks awaiting this task"},

{NULL}

};

static PyStructSequence_Desc TaskInfo_desc = {

"_remote_debugging.TaskInfo",

"Information about an asyncio task",

TaskInfo_fields,

4

};

// FrameInfo structseq type - replaces 3-tuple (filename, lineno, funcname)

static PyStructSequence_Field FrameInfo_fields[] = {

{"filename", "Source code filename"},

{"lineno", "Line number"},

{"funcname", "Function name"},

{NULL}

};

static PyStructSequence_Desc FrameInfo_desc = {

"_remote_debugging.FrameInfo",

"Information about a frame",

FrameInfo_fields,

3

};

// CoroInfo structseq type - replaces 2-tuple (call_stack, task_name)

static PyStructSequence_Field CoroInfo_fields[] = {

{"call_stack", "Coroutine call stack"},

{"task_name", "Task name"},

{NULL}

};

static PyStructSequence_Desc CoroInfo_desc = {

"_remote_debugging.CoroInfo",

"Information about a coroutine",

CoroInfo_fields,

2

};

// ThreadInfo structseq type - replaces 2-tuple (thread_id, frame_info)

static PyStructSequence_Field ThreadInfo_fields[] = {

{"thread_id", "Thread ID"},

{"frame_info", "Frame information"},

{NULL}

};

static PyStructSequence_Desc ThreadInfo_desc = {

"_remote_debugging.ThreadInfo",

"Information about a thread",

ThreadInfo_fields,

2

};

// AwaitedInfo structseq type - replaces 2-tuple (tid, awaited_by_list)

static PyStructSequence_Field AwaitedInfo_fields[] = {

{"thread_id", "Thread ID"},

{"awaited_by", "List of tasks awaited by this thread"},

{NULL}

};

static PyStructSequence_Desc AwaitedInfo_desc = {

"_remote_debugging.AwaitedInfo",

"Information about what a thread is awaiting",

AwaitedInfo_fields,

2

};

typedef struct {

PyObject *func_name;

PyObject *file_name;

int first_lineno;

PyObject *linetable; // bytes

uintptr_t addr_code_adaptive;

} CachedCodeMetadata;

typedef struct {

/* Types */

PyTypeObject *RemoteDebugging_Type;

PyTypeObject *TaskInfo_Type;

PyTypeObject *FrameInfo_Type;

PyTypeObject *CoroInfo_Type;

PyTypeObject *ThreadInfo_Type;

PyTypeObject *AwaitedInfo_Type;

} RemoteDebuggingState;

typedef struct {

PyObject_HEAD

proc_handle_t handle;

uintptr_t runtime_start_address;

struct _Py_DebugOffsets debug_offsets;

int async_debug_offsets_available;

struct _Py_AsyncioModuleDebugOffsets async_debug_offsets;

uintptr_t interpreter_addr;

uintptr_t tstate_addr;

uint64_t code_object_generation;

_Py_hashtable_t *code_object_cache;

int debug;

int only_active_thread;

RemoteDebuggingState *cached_state; // Cached module state

#ifdef Py_GIL_DISABLED

// TLBC cache invalidation tracking

uint32_t tlbc_generation; // Track TLBC index pool changes

_Py_hashtable_t *tlbc_cache; // Cache of TLBC arrays by code object address

#endif

} RemoteUnwinderObject;

#define RemoteUnwinder_CAST(op) ((RemoteUnwinderObject *)(op))

typedef struct

{

int lineno;

int end_lineno;

int column;

int end_column;

} LocationInfo;

typedef struct {

uintptr_t remote_addr;

size_t size;

void *local_copy;

} StackChunkInfo;

typedef struct {

StackChunkInfo *chunks;

size_t count;

} StackChunkList;

#include "clinic/_remote_debugging_module.c.h"

/*[clinic input]

module _remote_debugging

[clinic start generated code]*/

/*[clinic end generated code: output=da39a3ee5e6b4b0d input=5f507d5b2e76a7f7]*/

/* ============================================================================

* FORWARD DECLARATIONS

* ============================================================================ */

static inline int

is_frame_valid(

RemoteUnwinderObject *unwinder,

uintptr_t frame_addr,

uintptr_t code_object_addr

);

typedef int (*thread_processor_func)(

RemoteUnwinderObject *unwinder,

uintptr_t thread_state_addr,

unsigned long tid,

void *context

);

typedef int (*set_entry_processor_func)(

RemoteUnwinderObject *unwinder,

uintptr_t key_addr,

void *context

);

static int

parse_task(

RemoteUnwinderObject *unwinder,

uintptr_t task_address,

PyObject *render_to

);

static int

parse_coro_chain(

RemoteUnwinderObject *unwinder,

uintptr_t coro_address,

PyObject *render_to

);

/* Forward declarations for task parsing functions */

static int parse_frame_object(

RemoteUnwinderObject *unwinder,

PyObject** result,

uintptr_t address,

uintptr_t* address_of_code_object,

uintptr_t* previous_frame

);

static int

parse_async_frame_chain(

RemoteUnwinderObject *unwinder,

PyObject *calls,

uintptr_t address_of_thread,

uintptr_t running_task_code_obj

);

static int read_py_ptr(RemoteUnwinderObject *unwinder, uintptr_t address, uintptr_t *ptr_addr);

static int read_Py_ssize_t(RemoteUnwinderObject *unwinder, uintptr_t address, Py_ssize_t *size);

static int process_task_and_waiters(RemoteUnwinderObject *unwinder, uintptr_t task_addr, PyObject *result);

static int process_task_awaited_by(RemoteUnwinderObject *unwinder, uintptr_t task_address, set_entry_processor_func processor, void *context);

static int find_running_task_in_thread(RemoteUnwinderObject *unwinder, uintptr_t thread_state_addr, uintptr_t *running_task_addr);

static int get_task_code_object(RemoteUnwinderObject *unwinder, uintptr_t task_addr, uintptr_t *code_obj_addr);

static int append_awaited_by(RemoteUnwinderObject *unwinder, unsigned long tid, uintptr_t head_addr, PyObject *result);

/* ============================================================================

* UTILITY FUNCTIONS AND HELPERS

* ============================================================================ */

#define set_exception_cause(unwinder, exc_type, message) \

do { \

assert(PyErr_Occurred() && "function returned -1 without setting exception"); \

if (unwinder->debug) { \

_set_debug_exception_cause(exc_type, message); \

} \

} while (0)

static void

cached_code_metadata_destroy(void *ptr)

{

CachedCodeMetadata *meta = (CachedCodeMetadata *)ptr;

Py_DECREF(meta->func_name);

Py_DECREF(meta->file_name);

Py_DECREF(meta->linetable);

PyMem_RawFree(meta);

}

static inline RemoteDebuggingState *

RemoteDebugging_GetState(PyObject *module)

{

void *state = _PyModule_GetState(module);

assert(state != NULL);

return (RemoteDebuggingState *)state;

}

static inline RemoteDebuggingState *

RemoteDebugging_GetStateFromType(PyTypeObject *type)

{

PyObject *module = PyType_GetModule(type);

assert(module != NULL);

return RemoteDebugging_GetState(module);

}

static inline RemoteDebuggingState *

RemoteDebugging_GetStateFromObject(PyObject *obj)

{

RemoteUnwinderObject *unwinder = (RemoteUnwinderObject *)obj;

if (unwinder->cached_state == NULL) {

unwinder->cached_state = RemoteDebugging_GetStateFromType(Py_TYPE(obj));

}

return unwinder->cached_state;

}

static inline int

RemoteDebugging_InitState(RemoteDebuggingState *st)

{

return 0;

}

static int

is_prerelease_version(uint64_t version)

{

return (version & 0xF0) != 0xF0;

}

static inline int

validate_debug_offsets(struct _Py_DebugOffsets *debug_offsets)

{

if (memcmp(debug_offsets->cookie, _Py_Debug_Cookie, sizeof(debug_offsets->cookie)) != 0) {

// The remote is probably running a Python version predating debug offsets.

PyErr_SetString(

PyExc_RuntimeError,

"Can't determine the Python version of the remote process");

return -1;

}

// Assume debug offsets could change from one pre-release version to another,

// or one minor version to another, but are stable across patch versions.

if (is_prerelease_version(Py_Version) && Py_Version != debug_offsets->version) {

PyErr_SetString(

PyExc_RuntimeError,

"Can't attach from a pre-release Python interpreter"

" to a process running a different Python version");

return -1;

}

if (is_prerelease_version(debug_offsets->version) && Py_Version != debug_offsets->version) {

PyErr_SetString(

PyExc_RuntimeError,

"Can't attach to a pre-release Python interpreter"

" from a process running a different Python version");

return -1;

}

unsigned int remote_major = (debug_offsets->version >> 24) & 0xFF;

unsigned int remote_minor = (debug_offsets->version >> 16) & 0xFF;

if (PY_MAJOR_VERSION != remote_major || PY_MINOR_VERSION != remote_minor) {

PyErr_Format(

PyExc_RuntimeError,

"Can't attach from a Python %d.%d process to a Python %d.%d process",

PY_MAJOR_VERSION, PY_MINOR_VERSION, remote_major, remote_minor);

return -1;

}

// The debug offsets differ between free threaded and non-free threaded builds.

if (_Py_Debug_Free_Threaded && !debug_offsets->free_threaded) {

PyErr_SetString(

PyExc_RuntimeError,

"Cannot attach from a free-threaded Python process"

" to a process running a non-free-threaded version");

return -1;

}

if (!_Py_Debug_Free_Threaded && debug_offsets->free_threaded) {

PyErr_SetString(

PyExc_RuntimeError,

"Cannot attach to a free-threaded Python process"

" from a process running a non-free-threaded version");

return -1;

}

return validate_debug_offsets_layout(debug_offsets);

}

// Generic function to iterate through all threads

static int

iterate_threads(

RemoteUnwinderObject *unwinder,

thread_processor_func processor,

void *context

) {

uintptr_t thread_state_addr;

unsigned long tid = 0;

if (0 > _Py_RemoteDebug_PagedReadRemoteMemory(

&unwinder->handle,

unwinder->interpreter_addr + (uintptr_t)unwinder->debug_offsets.interpreter_state.threads_main,

sizeof(void*),

&thread_state_addr))

{

set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to read main thread state");

return -1;

}

while (thread_state_addr != 0) {

if (0 > _Py_RemoteDebug_PagedReadRemoteMemory(

&unwinder->handle,

thread_state_addr + (uintptr_t)unwinder->debug_offsets.thread_state.native_thread_id,

sizeof(tid),

&tid))

{

set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to read thread ID");

return -1;

}

// Call the processor function for this thread

if (processor(unwinder, thread_state_addr, tid, context) < 0) {

return -1;

}

// Move to next thread

if (0 > _Py_RemoteDebug_PagedReadRemoteMemory(

&unwinder->handle,

thread_state_addr + (uintptr_t)unwinder->debug_offsets.thread_state.next,

sizeof(void*),

&thread_state_addr))

{

set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to read next thread state");

return -1;

}

}

return 0;

}

// Generic function to iterate through set entries

static int

iterate_set_entries(

RemoteUnwinderObject *unwinder,

uintptr_t set_addr,

set_entry_processor_func processor,

void *context

) {

char set_object[SIZEOF_SET_OBJ];

if (_Py_RemoteDebug_PagedReadRemoteMemory(&unwinder->handle, set_addr,

SIZEOF_SET_OBJ, set_object) < 0) {

set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to read set object");

return -1;

}

Py_ssize_t num_els = GET_MEMBER(Py_ssize_t, set_object, unwinder->debug_offsets.set_object.used);

Py_ssize_t mask = GET_MEMBER(Py_ssize_t, set_object, unwinder->debug_offsets.set_object.mask);

uintptr_t table_ptr = GET_MEMBER(uintptr_t, set_object, unwinder->debug_offsets.set_object.table);

if (mask < 0 || mask >= MAX_SET_TABLE_SIZE || num_els < 0 || num_els > mask + 1) {

PyErr_SetString(PyExc_RuntimeError, "Invalid set object (corrupted remote memory)");

set_exception_cause(unwinder, PyExc_RuntimeError,

"Invalid set object (corrupted remote memory)");

return -1;

}

Py_ssize_t set_len = mask + 1;

Py_ssize_t i = 0;