blob: f9e95f3aec36adc1f6599f4db1f7ba4da30c5cfd [file]
/* Python interface to stack frames
Copyright (C) 2008-2026 Free Software Foundation, Inc.
This file is part of GDB.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>. */
#include "language.h"
#include "charset.h"
#include "block.h"
#include "frame.h"
#include "symtab.h"
#include "stack.h"
#include "value.h"
#include "python-internal.h"
#include "symfile.h"
#include "objfiles.h"
struct frame_object : public PyObject
{
struct frame_id frame_id;
struct gdbarch *gdbarch;
/* Marks that the FRAME_ID member actually holds the ID of the frame next
to this, and not this frames' ID itself. This is a hack to permit Python
frame objects which represent invalid frames (i.e., the last frame_info
in a corrupt stack). The problem arises from the fact that this code
relies on FRAME_ID to uniquely identify a frame, which is not always true
for the last "frame" in a corrupt stack (it can have a null ID, or the same
ID as the previous frame). Whenever get_prev_frame returns NULL, we
record the frame_id of the next frame and set FRAME_ID_IS_NEXT to 1. */
int frame_id_is_next;
/* Return the associated frame. Throws an exception on error. */
frame_info_ptr require_frame ()
{
frame_info_ptr frame = frame_object_to_frame_info (this);
/* FIXME: Python safety. frame_object_to_frame_info should be
converted, but the callers aren't ready yet. */
if (frame == nullptr)
gdbpy_err_format (PyExc_RuntimeError, _("Frame is invalid."));
return frame;
}
/* Called by the Python interpreter to obtain string representation
of the object. */
gdbpy_ref<> str ()
{
return gdbpy_unicode_from_string (frame_id.to_string ());
}
/* Implement repr() for gdb.Frame. */
gdbpy_ref<> repr ();
/* Implementation of gdb.Frame.is_valid (self) -> Boolean. Returns
True if the frame corresponding to the frame_id of this object
still exists in the inferior. */
bool is_valid ()
{
return frame_object_to_frame_info (this) != nullptr;
}
/* Implementation of gdb.Frame.name (self) -> String.
Returns the name of the function corresponding to this frame. */
gdb::unique_xmalloc_ptr<char> name ();
/* Implementation of gdb.Frame.type (self) -> Integer.
Returns the frame type, namely one of the gdb.*_FRAME constants. */
ULONGEST type ();
/* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
Returns the frame's architecture as a gdb.Architecture object. */
gdbpy_ref<> arch ();
/* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
Returns one of the gdb.FRAME_UNWIND_* constants. */
int unwind_stop_reason ();
/* Implementation of gdb.Frame.pc (self) -> Long.
Returns the frame's resume address. */
ULONGEST pc ();
/* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
Returns the value of a register in this frame. */
gdbpy_ref<> read_register (gdbpy_borrowed_ref<> args,
gdbpy_opt_borrowed_ref<> kw);
/* Implementation of gdb.Frame.block (self) -> gdb.Block.
Returns the frame's code block. */
gdbpy_ref<> block ();
/* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
Returns the symbol for the function corresponding to this frame. */
symbol *function ();
/* Implementation of gdb.Frame.older (self) -> gdb.Frame.
Returns the frame immediately older (outer) to this frame, or None if
there isn't one. */
frame_info_ptr older ();
/* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
Returns the frame immediately newer (inner) to this frame, or None if
there isn't one. */
frame_info_ptr newer ();
/* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
Returns the frame's symtab and line. */
gdbpy_ref<> find_sal ();
/* Implementation of gdb.Frame.read_var_value (self, variable,
[block]) -> gdb.Value. If the optional block argument is provided
start the search from that block, otherwise search from the frame's
current block (determined by examining the resume address of the
frame). The variable argument must be a string or an instance of a
gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
NULL on error, with a python exception set. */
gdbpy_ref<> read_var (gdbpy_borrowed_ref<> args,
gdbpy_opt_borrowed_ref<> kw);
/* Select this frame. */
void select ();
/* The stack frame level for this frame. */
int level ();
/* The language for this frame. */
const char *language ();
/* The static link for this frame. */
gdbpy_ref<> static_link ();
/* Implementation of the Python richcompare API. */
std::optional<bool> richcompare (gdbpy_borrowed_ref<> other, int op);
static PyTypeObject *corresponding_object_type;
};
static_assert (gdb::is_python_allocatable_v<frame_object>);
/* Returns the frame_info object corresponding to the given Python Frame
object. If the frame doesn't exist anymore (the frame id doesn't
correspond to any frame in the inferior), returns NULL. */
/* FIXME: Python safety. This function should be converted, but the
callers aren't ready yet. */
frame_info_ptr
frame_object_to_frame_info (PyObject *obj)
{
frame_object *frame_obj = (frame_object *) obj;
frame_info_ptr frame;
frame = frame_find_by_id (frame_obj->frame_id);
if (frame == NULL)
return NULL;
return frame;
}
gdbpy_ref<>
frame_object::repr ()
{
frame_info_ptr f_info = frame_find_by_id (frame_id);
if (f_info == nullptr)
return gdbpy_safe_invalid_object_repr (this);
return gdbpy_unicode_from_format ("<%s level=%d frame-id=%s>",
gdbpy_py_obj_tp_name (this).c_str (),
frame_relative_level (f_info),
frame_id.to_string ().c_str ());
}
gdb::unique_xmalloc_ptr<char>
frame_object::name ()
{
frame_info_ptr frame = require_frame ();
enum language lang;
return find_frame_funname (frame, &lang, nullptr);
}
ULONGEST
frame_object::type ()
{
frame_info_ptr frame = require_frame ();
return get_frame_type (frame);
}
gdbpy_ref<>
frame_object::arch ()
{
require_frame ();
return gdbarch_to_arch_object (gdbarch);
}
int
frame_object::unwind_stop_reason ()
{
frame_info_ptr frame = require_frame ();
return get_frame_unwind_stop_reason (frame);
}
ULONGEST
frame_object::pc ()
{
frame_info_ptr frame = require_frame ();
return get_frame_pc (frame);
}
gdbpy_ref<>
frame_object::read_register (gdbpy_borrowed_ref<> args,
gdbpy_opt_borrowed_ref<> kw)
{
PyObject *pyo_reg_id;
static const char *keywords[] = { "register", nullptr };
gdbpy_arg_parse_tuple_and_keywords (args, kw, "O", keywords, &pyo_reg_id);
scoped_value_mark free_values;
frame_info_ptr frame = require_frame ();
int regnum;
if (!gdbpy_parse_register_id (get_frame_arch (frame), pyo_reg_id, &regnum))
{
/* FIXME: Python safety. gdbpy_parse_register_id should throw
on error. */
throw gdb_python_exception ();
}
gdb_assert (regnum >= 0);
value *val
= value_of_register (regnum, get_next_frame_sentinel_okay (frame));
if (val == nullptr)
gdbpy_err_set_string (PyExc_ValueError, _("Can't read register."));
return value_to_value_object (val);
}
gdbpy_ref<>
frame_object::block ()
{
frame_info_ptr frame = require_frame ();
const struct block *block = get_frame_block (frame, nullptr);
const struct block *fn_block;
for (fn_block = block;
fn_block != NULL && fn_block->function () == NULL;
fn_block = fn_block->superblock ())
;
if (block == NULL || fn_block == NULL || fn_block->function () == NULL)
gdbpy_err_set_string (PyExc_RuntimeError,
_("Cannot locate block for frame."));
return block_to_block_object (block, fn_block->function ()->objfile ());
}
symbol *
frame_object::function ()
{
frame_info_ptr frame = require_frame ();
struct symbol *sym = nullptr;
enum language funlang;
gdb::unique_xmalloc_ptr<char> funname
= find_frame_funname (frame, &funlang, &sym);
return sym;
}
/* Convert a frame_info struct to a Python Frame object.
Sets a Python exception and returns NULL on error. */
gdbpy_ref<>
frame_info_to_frame_object (const frame_info_ptr &frame)
{
gdbpy_ref<frame_object> frame_obj (PyObject_New (frame_object,
&frame_object_type));
if (frame_obj == NULL)
return NULL;
try
{
frame_obj->frame_id = get_frame_id (frame);
frame_obj->gdbarch = get_frame_arch (frame);
}
catch (const gdb_exception &except)
{
return gdbpy_handle_gdb_exception (nullptr, except);
}
return frame_obj;
}
gdbpy_ref<>
safe_frame_info_to_frame_object (const frame_info_ptr &frame)
{
gdbpy_ref<> result = frame_info_to_frame_object (frame);
if (result == nullptr)
throw gdb_python_exception ();
return result;
}
frame_info_ptr
frame_object::older ()
{
frame_info_ptr frame = require_frame ();
return get_prev_frame (frame);
}
frame_info_ptr
frame_object::newer ()
{
frame_info_ptr frame = require_frame ();
return get_next_frame (frame);
}
gdbpy_ref<>
frame_object::find_sal ()
{
frame_info_ptr frame = require_frame ();
symtab_and_line sal = find_frame_sal (frame);
return symtab_and_line_to_sal_object (sal);
}
gdbpy_ref<>
frame_object::read_var (gdbpy_borrowed_ref<> args,
gdbpy_opt_borrowed_ref<> kw)
{
PyObject *sym_obj, *block_obj = NULL;
static const char *keywords[] = { "variable", "block", nullptr };
gdbpy_arg_parse_tuple_and_keywords (args, kw, "O|O!", keywords,
&sym_obj, &block_object_type,
&block_obj);
const struct block *block = NULL;
struct symbol *var = NULL; /* gcc-4.3.2 false warning. */
if (PyObject_TypeCheck (sym_obj, &symbol_object_type))
var = symbol_object_to_symbol (sym_obj);
else if (gdbpy_is_string (sym_obj))
{
gdb::unique_xmalloc_ptr<char> var_name
= safe_python_string_to_target_string (sym_obj);
if (block_obj != nullptr)
{
/* This call should only fail if the type of BLOCK_OBJ is wrong,
and we ensure the type is correct when we parse the arguments,
so we can just assert the return value is not nullptr. */
block = block_object_to_block (block_obj);
gdb_assert (block != nullptr);
}
frame_info_ptr frame = require_frame ();
if (!block)
block = get_frame_block (frame, NULL);
block_symbol lookup_sym = lookup_symbol (var_name.get (), block,
SEARCH_VFT, nullptr);
var = lookup_sym.symbol;
block = lookup_sym.block;
if (var == nullptr)
gdbpy_err_format (PyExc_ValueError,
_("Variable '%s' not found."), var_name.get ());
}
else
gdbpy_err_format (PyExc_TypeError,
_("argument 1 must be gdb.Symbol or str, not %s"),
gdbpy_py_obj_tp_name (sym_obj).c_str ());
frame_info_ptr frame = require_frame ();
scoped_value_mark free_values;
struct value *val = read_var_value (var, block, frame);
return value_to_value_object (val);
}
void
frame_object::select ()
{
frame_info_ptr fi = require_frame ();
select_frame (fi);
}
int
frame_object::level ()
{
frame_info_ptr fi = require_frame ();
return frame_relative_level (fi);
}
const char *
frame_object::language ()
{
frame_info_ptr fi = require_frame ();
enum language lang = get_frame_language (fi);
const language_defn *lang_def = language_def (lang);
return lang_def->name ();
}
gdbpy_ref<>
frame_object::static_link ()
{
frame_info_ptr link = require_frame ();
link = frame_follow_static_link (link);
if (link == nullptr)
return py_none ();
return frame_info_to_frame_object (link);
}
/* Implementation of gdb.newest_frame () -> gdb.Frame.
Returns the newest frame object. */
frame_info_ptr
gdbpy_newest_frame ()
{
return get_current_frame ();
}
/* Implementation of gdb.selected_frame () -> gdb.Frame.
Returns the selected frame object. */
frame_info_ptr
gdbpy_selected_frame ()
{
return get_selected_frame ("No frame is currently selected.");
}
/* Implementation of gdb.stop_reason_string (Integer) -> String.
Return a string explaining the unwind stop reason. */
const char *
gdbpy_frame_stop_reason_string (gdbpy_borrowed_ref<> args,
gdbpy_opt_borrowed_ref<> kw)
{
int reason;
static const char *keywords[] = { "reason", nullptr };
gdbpy_arg_parse_tuple_and_keywords (args, kw, "i", keywords, &reason);
if (reason < UNWIND_FIRST || reason > UNWIND_LAST)
gdbpy_err_set_string (PyExc_ValueError,
_("Invalid frame stop reason."));
return unwind_stop_reason_to_string ((enum unwind_stop_reason) reason);
}
/* Implements the equality comparison for Frame objects. */
std::optional<bool>
frame_object::richcompare (gdbpy_borrowed_ref<> other, int op)
{
int result;
if (!PyObject_TypeCheck (other, &frame_object_type)
|| (op != Py_EQ && op != Py_NE))
return std::nullopt;
frame_object *other_frame = other;
if (frame_id == other_frame->frame_id)
result = Py_EQ;
else
result = Py_NE;
return op == result;
}
PyTypeObject *frame_object::corresponding_object_type = &frame_object_type;
/* Sets up the Frame API in the gdb module. */
static int
gdbpy_initialize_frames ()
{
frame_object_type.tp_new = PyType_GenericNew;
if (gdbpy_type_ready (&frame_object_type) < 0)
return -1;
/* Note: These would probably be best exposed as class attributes of
Frame, but I don't know how to do it except by messing with the
type's dictionary. That seems too messy. */
if (PyModule_AddIntConstant (gdb_module, "NORMAL_FRAME", NORMAL_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "DUMMY_FRAME", DUMMY_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "INLINE_FRAME", INLINE_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "TAILCALL_FRAME",
TAILCALL_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "SIGTRAMP_FRAME",
SIGTRAMP_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "ARCH_FRAME", ARCH_FRAME) < 0
|| PyModule_AddIntConstant (gdb_module, "SENTINEL_FRAME",
SENTINEL_FRAME) < 0)
return -1;
#define SET(name, description) \
if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
return -1;
#include "unwind_stop_reasons.def"
#undef SET
return 0;
}
GDBPY_INITIALIZE_FILE (gdbpy_initialize_frames);
static PyMethodDef frame_object_methods[] = {
noargs_method<frame_object, &frame_object::is_valid> ("is_valid",
"is_valid () -> Boolean.\n\
Return true if this frame is valid, false if not."),
noargs_method<frame_object, &frame_object::name> ("name",
"name () -> String.\n\
Return the function name of the frame, or None if it can't be determined."),
noargs_method<frame_object, &frame_object::type> ("type",
"type () -> Integer.\n\
Return the type of the frame."),
noargs_method<frame_object, &frame_object::arch> ("architecture",
"architecture () -> gdb.Architecture.\n\
Return the architecture of the frame."),
noargs_method<frame_object, &frame_object::unwind_stop_reason>
("unwind_stop_reason",
"unwind_stop_reason () -> Integer.\n\
Return the reason why it's not possible to find frames older than this."),
noargs_method<frame_object, &frame_object::pc> ("pc",
"pc () -> Long.\n\
Return the frame's resume address."),
varargs_method<frame_object, &frame_object::read_register> ("read_register",
"read_register (register_name) -> gdb.Value\n\
Return the value of the register in the frame."),
noargs_method<frame_object, &frame_object::block> ("block",
"block () -> gdb.Block.\n\
Return the frame's code block."),
noargs_method<frame_object, &frame_object::function> ("function",
"function () -> gdb.Symbol.\n\
Returns the symbol for the function corresponding to this frame."),
noargs_method<frame_object, &frame_object::older> ("older",
"older () -> gdb.Frame.\n\
Return the frame that called this frame."),
noargs_method<frame_object, &frame_object::newer> ("newer",
"newer () -> gdb.Frame.\n\
Return the frame called by this frame."),
noargs_method<frame_object, &frame_object::find_sal> ("find_sal",
"find_sal () -> gdb.Symtab_and_line.\n\
Return the frame's symtab and line."),
varargs_method<frame_object, &frame_object::read_var> ("read_var",
"read_var (variable) -> gdb.Value.\n\
Return the value of the variable in this frame."),
noargs_method<frame_object, &frame_object::select> ("select",
"Select this frame as the user's current frame."),
noargs_method<frame_object, &frame_object::level> ("level",
"The stack level of this frame."),
noargs_method<frame_object, &frame_object::language> ("language",
"The language of this frame."),
noargs_method<frame_object, &frame_object::static_link> ("static_link",
"The static link of this frame, or None."),
{NULL} /* Sentinel */
};
PyTypeObject frame_object_type = {
PyVarObject_HEAD_INIT (NULL, 0)
"gdb.Frame", /* tp_name */
sizeof (frame_object), /* tp_basicsize */
0, /* tp_itemsize */
0, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
0, /* tp_setattr */
0, /* tp_compare */
wrap_tp_callback<frame_object, &frame_object::repr>, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
wrap_tp_callback<frame_object, &frame_object::str>, /* tp_str */
0, /* tp_getattro */
0, /* tp_setattro */
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT, /* tp_flags */
"GDB frame object", /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
wrap_richcompare<frame_object, &frame_object::richcompare>, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
frame_object_methods, /* tp_methods */
0, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
0, /* tp_init */
0, /* tp_alloc */
};