#include "_remote_debugging.h"

#include "binary_io.h"

typedef struct {

PyObject_HEAD

BinaryWriter *writer;

uint32_t cached_total_samples; /* Preserved after finalize */

} BinaryWriterObject;

typedef struct {

PyObject_HEAD

BinaryReader *reader;

} BinaryReaderObject;

#include "clinic/module.c.h"

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}

};

PyStructSequence_Desc TaskInfo_desc = {

"_remote_debugging.TaskInfo",

"Information about an asyncio task",

TaskInfo_fields,

4

};

static PyStructSequence_Field LocationInfo_fields[] = {

{"lineno", "Line number"},

{"end_lineno", "End line number"},

{"col_offset", "Column offset"},

{"end_col_offset", "End column offset"},

{NULL}

};

PyStructSequence_Desc LocationInfo_desc = {

"_remote_debugging.LocationInfo",

"Source location information: (lineno, end_lineno, col_offset, end_col_offset)",

LocationInfo_fields,

4

};

static PyStructSequence_Field FrameInfo_fields[] = {

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

{"location", "LocationInfo structseq or None for synthetic frames"},

{"funcname", "Function name"},

{"opcode", "Opcode being executed (None if not gathered)"},

{NULL}

};

PyStructSequence_Desc FrameInfo_desc = {

"_remote_debugging.FrameInfo",

"Information about a frame",

FrameInfo_fields,

4

};

static PyStructSequence_Field CoroInfo_fields[] = {

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

{"task_name", "Task name"},

{NULL}

};

PyStructSequence_Desc CoroInfo_desc = {

"_remote_debugging.CoroInfo",

"Information about a coroutine",

CoroInfo_fields,

2

};

static PyStructSequence_Field ThreadInfo_fields[] = {

{"thread_id", "Thread ID"},

{"status", "Thread status (flags: HAS_GIL, ON_CPU, UNKNOWN or legacy enum)"},

{"frame_info", "Frame information"},

{NULL}

};

PyStructSequence_Desc ThreadInfo_desc = {

"_remote_debugging.ThreadInfo",

"Information about a thread",

ThreadInfo_fields,

3

};

static PyStructSequence_Field InterpreterInfo_fields[] = {

{"interpreter_id", "Interpreter ID"},

{"threads", "List of threads in this interpreter"},

{NULL}

};

PyStructSequence_Desc InterpreterInfo_desc = {

"_remote_debugging.InterpreterInfo",

"Information about an interpreter",

InterpreterInfo_fields,

2

};

static PyStructSequence_Field AwaitedInfo_fields[] = {

{"thread_id", "Thread ID"},

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

{NULL}

};

PyStructSequence_Desc AwaitedInfo_desc = {

"_remote_debugging.AwaitedInfo",

"Information about what a thread is awaiting",

AwaitedInfo_fields,

2

};

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);

}

RemoteDebuggingState *

RemoteDebugging_GetState(PyObject *module)

{

void *state = _PyModule_GetState(module);

assert(state != NULL);

return (RemoteDebuggingState *)state;

}

RemoteDebuggingState *

RemoteDebugging_GetStateFromType(PyTypeObject *type)

{

PyObject *module = PyType_GetModule(type);

assert(module != NULL);

return RemoteDebugging_GetState(module);

}

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;

}

RemoteDebugging_InitState(RemoteDebuggingState *st)

{

return 0;

}

is_prerelease_version(uint64_t version)

{

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

}

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 0;

}

static int

_remote_debugging_RemoteUnwinder___init___impl(RemoteUnwinderObject *self,

int stats)

{

// Validate that all_threads and only_active_thread are not both True

if (all_threads && only_active_thread) {

PyErr_SetString(PyExc_ValueError,

"all_threads and only_active_thread cannot both be True");

return -1;

}

#ifdef Py_GIL_DISABLED

if (only_active_thread) {

PyErr_SetString(PyExc_ValueError,

"only_active_thread is not supported in free-threaded builds");

return -1;

}

self->native = native;

self->gc = gc;

self->opcodes = opcodes;

self->cache_frames = cache_frames;

self->collect_stats = stats;

self->stale_invalidation_counter = 0;

self->debug = debug;

self->only_active_thread = only_active_thread;

self->mode = mode;

self->skip_non_matching_threads = skip_non_matching_threads;

self->cached_state = NULL;

self->frame_cache = NULL;

#ifdef Py_REMOTE_DEBUG_SUPPORTS_BLOCKING

self->threads_stopped = 0;

// Initialize stats to zero

memset(&self->stats, 0, sizeof(self->stats));

if (_Py_RemoteDebug_InitProcHandle(&self->handle, pid) < 0) {

set_exception_cause(self, PyExc_RuntimeError, "Failed to initialize process handle");

return -1;

}

self->runtime_start_address = _Py_RemoteDebug_GetPyRuntimeAddress(&self->handle);

if (self->runtime_start_address == 0) {

set_exception_cause(self, PyExc_RuntimeError, "Failed to get Python runtime address");

return -1;

}

if (_Py_RemoteDebug_ReadDebugOffsets(&self->handle,

&self->runtime_start_address,

&self->debug_offsets) < 0)

{

set_exception_cause(self, PyExc_RuntimeError, "Failed to read debug offsets");

return -1;

}

// Validate that the debug offsets are valid

if (validate_debug_offsets(&self->debug_offsets) == -1) {

set_exception_cause(self, PyExc_RuntimeError, "Invalid debug offsets found");

return -1;

}

// Try to read async debug offsets, but don't fail if they're not available

self->async_debug_offsets_available = 1;

if (read_async_debug(self) < 0) {

PyErr_Clear();

memset(&self->async_debug_offsets, 0, sizeof(self->async_debug_offsets));

self->async_debug_offsets_available = 0;

}

if (populate_initial_state_data(all_threads, self, self->runtime_start_address,

&self->interpreter_addr ,&self->tstate_addr) < 0)

{

set_exception_cause(self, PyExc_RuntimeError, "Failed to populate initial state data");

return -1;

}

self->code_object_cache = _Py_hashtable_new_full(

_Py_hashtable_hash_ptr,

_Py_hashtable_compare_direct,

NULL, // keys are stable pointers, don't destroy

cached_code_metadata_destroy,

NULL

);

if (self->code_object_cache == NULL) {

PyErr_NoMemory();

set_exception_cause(self, PyExc_MemoryError, "Failed to create code object cache");

return -1;

}

#ifdef Py_GIL_DISABLED

// Initialize TLBC cache

self->tlbc_generation = 0;

self->tlbc_cache = _Py_hashtable_new_full(

_Py_hashtable_hash_ptr,

_Py_hashtable_compare_direct,

NULL, // keys are stable pointers, don't destroy

tlbc_cache_entry_destroy,

NULL

);

if (self->tlbc_cache == NULL) {

_Py_hashtable_destroy(self->code_object_cache);

PyErr_NoMemory();

set_exception_cause(self, PyExc_MemoryError, "Failed to create TLBC cache");

return -1;

}

#if defined(__APPLE__)

self->thread_id_offset = 0;

self->thread_id_offset_initialized = 0;

#ifdef MS_WINDOWS

self->win_process_buffer = NULL;

self->win_process_buffer_size = 0;

#ifdef __linux__

self->thread_tids = NULL;

self->thread_tids_capacity = 0;

if (cache_frames && frame_cache_init(self) < 0) {

return -1;

}

// Clear stale last_profiled_frame values from previous profilers

// This prevents us from stopping frame walking early due to stale values

if (cache_frames) {

clear_last_profiled_frames(self);

}

return 0;

}

static PyObject *

_remote_debugging_RemoteUnwinder_get_stack_trace_impl(RemoteUnwinderObject *self)

{

STATS_INC(self, total_samples);

PyObject* result = PyList_New(0);

if (!result) {

set_exception_cause(self, PyExc_MemoryError, "Failed to create stack trace result list");

return NULL;

}

// Iterate over all interpreters

uintptr_t current_interpreter = self->interpreter_addr;

while (current_interpreter != 0) {

// Read interpreter state to get the interpreter ID

char interp_state_buffer[INTERP_STATE_BUFFER_SIZE];

if (_Py_RemoteDebug_PagedReadRemoteMemory(

&self->handle,

current_interpreter,

INTERP_STATE_BUFFER_SIZE,

interp_state_buffer) < 0) {

set_exception_cause(self, PyExc_RuntimeError, "Failed to read interpreter state buffer");

Py_CLEAR(result);

goto exit;

}

uintptr_t gc_frame = 0;

if (self->gc) {

gc_frame = GET_MEMBER(uintptr_t, interp_state_buffer,

self->debug_offsets.interpreter_state.gc

+ self->debug_offsets.gc.frame);

}

int64_t interpreter_id = GET_MEMBER(int64_t, interp_state_buffer,

self->debug_offsets.interpreter_state.id);

// Get code object generation from buffer

uint64_t code_object_generation = GET_MEMBER(uint64_t, interp_state_buffer,

self->debug_offsets.interpreter_state.code_object_generation);

if (code_object_generation != self->code_object_generation) {

self->code_object_generation = code_object_generation;

_Py_hashtable_clear(self->code_object_cache);

}

#ifdef Py_GIL_DISABLED

// Check TLBC generation and invalidate cache if needed

uint32_t current_tlbc_generation = GET_MEMBER(uint32_t, interp_state_buffer,

self->debug_offsets.interpreter_state.tlbc_generation);

if (current_tlbc_generation != self->tlbc_generation) {

self->tlbc_generation = current_tlbc_generation;

_Py_hashtable_clear(self->tlbc_cache);

}

// Create a list to hold threads for this interpreter

PyObject *interpreter_threads = PyList_New(0);

if (!interpreter_threads) {

set_exception_cause(self, PyExc_MemoryError, "Failed to create interpreter threads list");

Py_CLEAR(result);

goto exit;

}

// Get the GIL holder for this interpreter (needed for GIL_WAIT logic)

uintptr_t gil_holder_tstate = 0;

int gil_locked = GET_MEMBER(int, interp_state_buffer,

self->debug_offsets.interpreter_state.gil_runtime_state_locked);

if (gil_locked) {

gil_holder_tstate = (uintptr_t)GET_MEMBER(PyThreadState*, interp_state_buffer,

self->debug_offsets.interpreter_state.gil_runtime_state_holder);

}

uintptr_t current_tstate;

if (self->only_active_thread) {

// Find the GIL holder for THIS interpreter

if (!gil_locked) {

// This interpreter's GIL is not locked, skip it

Py_DECREF(interpreter_threads);

goto next_interpreter;

}

current_tstate = gil_holder_tstate;

} else if (self->tstate_addr == 0) {

// Get all threads for this interpreter

current_tstate = GET_MEMBER(uintptr_t, interp_state_buffer,

self->debug_offsets.interpreter_state.threads_head);

} else {

// Target specific thread (only process first interpreter)

current_tstate = self->tstate_addr;

}

// Acquire main thread state information

uintptr_t main_thread_tstate = GET_MEMBER(uintptr_t, interp_state_buffer,

self->debug_offsets.interpreter_state.threads_main);

while (current_tstate != 0) {

uintptr_t prev_tstate = current_tstate;

PyObject* frame_info = unwind_stack_for_thread(self, &current_tstate,

gil_holder_tstate,

gc_frame,

main_thread_tstate);

if (!frame_info) {

// Check if this was an intentional skip due to mode-based filtering

if ((self->mode == PROFILING_MODE_CPU || self->mode == PROFILING_MODE_GIL ||

self->mode == PROFILING_MODE_EXCEPTION) && !PyErr_Occurred()) {

// Detect cycle: if current_tstate didn't advance, we have corrupted data

if (current_tstate == prev_tstate) {

Py_DECREF(interpreter_threads);

PyErr_Format(PyExc_RuntimeError,

"Thread list cycle detected at address 0x%lx (corrupted remote memory)",

current_tstate);

set_exception_cause(self, PyExc_RuntimeError,

"Thread list cycle detected (corrupted remote memory)");

Py_CLEAR(result);

goto exit;

}

// Thread was skipped due to mode filtering, continue to next thread

continue;

}

// This was an actual error

Py_DECREF(interpreter_threads);

set_exception_cause(self, PyExc_RuntimeError, "Failed to unwind stack for thread");

Py_CLEAR(result);

goto exit;

}

if (PyList_Append(interpreter_threads, frame_info) == -1) {

Py_DECREF(frame_info);

Py_DECREF(interpreter_threads);

set_exception_cause(self, PyExc_RuntimeError, "Failed to append thread frame info");

Py_CLEAR(result);

goto exit;

}

Py_DECREF(frame_info);

// If targeting specific thread or only active thread, process just one

if (self->tstate_addr || self->only_active_thread) {

break;

}

}

// Create the InterpreterInfo StructSequence

RemoteDebuggingState *state = RemoteDebugging_GetStateFromObject((PyObject*)self);

PyObject *interpreter_info = PyStructSequence_New(state->InterpreterInfo_Type);

if (!interpreter_info) {

Py_DECREF(interpreter_threads);

set_exception_cause(self, PyExc_MemoryError, "Failed to create InterpreterInfo");

Py_CLEAR(result);

goto exit;

}

PyObject *interp_id = PyLong_FromLongLong(interpreter_id);

if (!interp_id) {

Py_DECREF(interpreter_threads);

Py_DECREF(interpreter_info);

set_exception_cause(self, PyExc_MemoryError, "Failed to create interpreter ID");

Py_CLEAR(result);

goto exit;

}

PyStructSequence_SetItem(interpreter_info, 0, interp_id); // steals reference

PyStructSequence_SetItem(interpreter_info, 1, interpreter_threads); // steals reference

// Add this interpreter to the result list

if (PyList_Append(result, interpreter_info) == -1) {

Py_DECREF(interpreter_info);

set_exception_cause(self, PyExc_RuntimeError, "Failed to append interpreter info");

Py_CLEAR(result);

goto exit;

}

Py_DECREF(interpreter_info);

next_interpreter:

// Get the next interpreter address

current_interpreter = GET_MEMBER(uintptr_t, interp_state_buffer,

self->debug_offsets.interpreter_state.next);

// If we're targeting a specific thread, stop after first interpreter

if (self->tstate_addr != 0) {

break;

}

}

exit:

// Invalidate cache entries for threads not seen in this sample.

// Only do this every 1024 iterations to avoid performance overhead.

if (self->cache_frames && result) {

if (++self->stale_invalidation_counter >= 1024) {

self->stale_invalidation_counter = 0;

frame_cache_invalidate_stale(self, result);

}

}

_Py_RemoteDebug_ClearCache(&self->handle);

return result;

}

static PyObject *

_remote_debugging_RemoteUnwinder_get_all_awaited_by_impl(RemoteUnwinderObject *self)

{

if (ensure_async_debug_offsets(self) < 0) {

return NULL;

}

PyObject *result = PyList_New(0);

if (result == NULL) {

set_exception_cause(self, PyExc_MemoryError, "Failed to create awaited_by result list");

goto result_err;

}

// Process all threads

if (iterate_threads(self, process_thread_for_awaited_by, result) < 0) {

goto result_err;

}

uintptr_t head_addr = self->interpreter_addr

+ (uintptr_t)self->async_debug_offsets.asyncio_interpreter_state.asyncio_tasks_head;

// On top of a per-thread task lists used by default by asyncio to avoid

// contention, there is also a fallback per-interpreter list of tasks;

// any tasks still pending when a thread is destroyed will be moved to the

// per-interpreter task list. It's unlikely we'll find anything here, but

// interesting for debugging.

if (append_awaited_by(self, 0, head_addr, result))

{

set_exception_cause(self, PyExc_RuntimeError, "Failed to append interpreter awaited_by in get_all_awaited_by");

goto result_err;

}

_Py_RemoteDebug_ClearCache(&self->handle);

return result;

result_err:

_Py_RemoteDebug_ClearCache(&self->handle);

Py_XDECREF(result);

return NULL;

}

static PyObject *

_remote_debugging_RemoteUnwinder_get_async_stack_trace_impl(RemoteUnwinderObject *self)

{

if (ensure_async_debug_offsets(self) < 0) {

return NULL;

}

PyObject *result = PyList_New(0);

if (result == NULL) {

set_exception_cause(self, PyExc_MemoryError, "Failed to create result list in get_async_stack_trace");

return NULL;

}

// Process all threads

if (iterate_threads(self, process_thread_for_async_stack_trace, result) < 0) {

goto result_err;

}

_Py_RemoteDebug_ClearCache(&self->handle);

return result;

result_err:

_Py_RemoteDebug_ClearCache(&self->handle);

Py_XDECREF(result);

return NULL;

}

static PyObject *

_remote_debugging_RemoteUnwinder_get_stats_impl(RemoteUnwinderObject *self)

{

if (!self->collect_stats) {

PyErr_SetString(PyExc_RuntimeError,

"Statistics collection was not enabled. "

"Create RemoteUnwinder with stats=True to collect statistics.");

return NULL;

}

PyObject *result = PyDict_New();

if (!result) {

return NULL;

}

#define ADD_STAT(name) do { \

PyObject *val = PyLong_FromUnsignedLongLong(self->stats.name); \

if (!val || PyDict_SetItemString(result, #name, val) < 0) { \

Py_XDECREF(val); \

Py_DECREF(result); \

return NULL; \

} \

Py_DECREF(val); \

} while(0)

ADD_STAT(total_samples);

ADD_STAT(frame_cache_hits);

ADD_STAT(frame_cache_misses);

ADD_STAT(frame_cache_partial_hits);

ADD_STAT(frames_read_from_cache);

ADD_STAT(frames_read_from_memory);

ADD_STAT(memory_reads);

ADD_STAT(memory_bytes_read);

ADD_STAT(code_object_cache_hits);

ADD_STAT(code_object_cache_misses);

ADD_STAT(stale_cache_invalidations);

#undef ADD_STAT

// Calculate and add derived statistics

// Hit rate is calculated as (hits + partial_hits) / total_cache_lookups

double frame_cache_hit_rate = 0.0;

uint64_t total_cache_lookups = self->stats.frame_cache_hits + self->stats.frame_cache_partial_hits + self->stats.frame_cache_misses;

if (total_cache_lookups > 0) {

frame_cache_hit_rate = 100.0 * (double)(self->stats.frame_cache_hits + self->stats.frame_cache_partial_hits)

/ (double)total_cache_lookups;

}

PyObject *hit_rate = PyFloat_FromDouble(frame_cache_hit_rate);

if (!hit_rate || PyDict_SetItemString(result, "frame_cache_hit_rate", hit_rate) < 0) {

Py_XDECREF(hit_rate);

Py_DECREF(result);

return NULL;

}

Py_DECREF(hit_rate);

double code_object_hit_rate = 0.0;

uint64_t total_code_lookups = self->stats.code_object_cache_hits + self->stats.code_object_cache_misses;

if (total_code_lookups > 0) {

code_object_hit_rate = 100.0 * (double)self->stats.code_object_cache_hits / (double)total_code_lookups;

}

PyObject *code_hit_rate = PyFloat_FromDouble(code_object_hit_rate);

if (!code_hit_rate || PyDict_SetItemString(result, "code_object_cache_hit_rate", code_hit_rate) < 0) {

Py_XDECREF(code_hit_rate);

Py_DECREF(result);

return NULL;

}

Py_DECREF(code_hit_rate);

return result;

}

static PyObject *

_remote_debugging_RemoteUnwinder_pause_threads_impl(RemoteUnwinderObject *self)

{

#ifdef Py_REMOTE_DEBUG_SUPPORTS_BLOCKING

if (self->threads_stopped) {

Py_RETURN_FALSE;

}

_Py_RemoteDebug_InitThreadsState(self, &self->threads_state);

if (_Py_RemoteDebug_StopAllThreads(self, &self->threads_state) < 0) {

return NULL;

}

self->threads_stopped = 1;

Py_RETURN_TRUE;

PyErr_SetString(PyExc_NotImplementedError,

"pause_threads is not supported on this platform");

return NULL;

}