1 /* Python interface to stack frames
3 Copyright (C) 2008-2020 Free Software Foundation, Inc.
5 This file is part of GDB.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
27 #include "python-internal.h"
30 #include "user-regs.h"
34 struct frame_id frame_id
;
35 struct gdbarch
*gdbarch
;
37 /* Marks that the FRAME_ID member actually holds the ID of the frame next
38 to this, and not this frames' ID itself. This is a hack to permit Python
39 frame objects which represent invalid frames (i.e., the last frame_info
40 in a corrupt stack). The problem arises from the fact that this code
41 relies on FRAME_ID to uniquely identify a frame, which is not always true
42 for the last "frame" in a corrupt stack (it can have a null ID, or the same
43 ID as the previous frame). Whenever get_prev_frame returns NULL, we
44 record the frame_id of the next frame and set FRAME_ID_IS_NEXT to 1. */
48 /* Require a valid frame. This must be called inside a TRY_CATCH, or
49 another context in which a gdb exception is allowed. */
50 #define FRAPY_REQUIRE_VALID(frame_obj, frame) \
52 frame = frame_object_to_frame_info (frame_obj); \
54 error (_("Frame is invalid.")); \
57 /* Returns the frame_info object corresponding to the given Python Frame
58 object. If the frame doesn't exist anymore (the frame id doesn't
59 correspond to any frame in the inferior), returns NULL. */
62 frame_object_to_frame_info (PyObject
*obj
)
64 frame_object
*frame_obj
= (frame_object
*) obj
;
65 struct frame_info
*frame
;
67 frame
= frame_find_by_id (frame_obj
->frame_id
);
71 if (frame_obj
->frame_id_is_next
)
72 frame
= get_prev_frame (frame
);
77 /* Called by the Python interpreter to obtain string representation
81 frapy_str (PyObject
*self
)
85 fprint_frame_id (&strfile
, ((frame_object
*) self
)->frame_id
);
86 return PyString_FromString (strfile
.c_str ());
89 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
90 Returns True if the frame corresponding to the frame_id of this
91 object still exists in the inferior. */
94 frapy_is_valid (PyObject
*self
, PyObject
*args
)
96 struct frame_info
*frame
= NULL
;
100 frame
= frame_object_to_frame_info (self
);
102 catch (const gdb_exception
&except
)
104 GDB_PY_HANDLE_EXCEPTION (except
);
113 /* Implementation of gdb.Frame.name (self) -> String.
114 Returns the name of the function corresponding to this frame. */
117 frapy_name (PyObject
*self
, PyObject
*args
)
119 struct frame_info
*frame
;
120 gdb::unique_xmalloc_ptr
<char> name
;
126 FRAPY_REQUIRE_VALID (self
, frame
);
128 name
= find_frame_funname (frame
, &lang
, NULL
);
130 catch (const gdb_exception
&except
)
132 GDB_PY_HANDLE_EXCEPTION (except
);
137 result
= PyUnicode_Decode (name
.get (), strlen (name
.get ()),
138 host_charset (), NULL
);
149 /* Implementation of gdb.Frame.type (self) -> Integer.
150 Returns the frame type, namely one of the gdb.*_FRAME constants. */
153 frapy_type (PyObject
*self
, PyObject
*args
)
155 struct frame_info
*frame
;
156 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
160 FRAPY_REQUIRE_VALID (self
, frame
);
162 type
= get_frame_type (frame
);
164 catch (const gdb_exception
&except
)
166 GDB_PY_HANDLE_EXCEPTION (except
);
169 return PyInt_FromLong (type
);
172 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
173 Returns the frame's architecture as a gdb.Architecture object. */
176 frapy_arch (PyObject
*self
, PyObject
*args
)
178 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
179 frame_object
*obj
= (frame_object
*) self
;
183 FRAPY_REQUIRE_VALID (self
, frame
);
185 catch (const gdb_exception
&except
)
187 GDB_PY_HANDLE_EXCEPTION (except
);
190 return gdbarch_to_arch_object (obj
->gdbarch
);
193 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
194 Returns one of the gdb.FRAME_UNWIND_* constants. */
197 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
199 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
200 enum unwind_stop_reason stop_reason
;
204 FRAPY_REQUIRE_VALID (self
, frame
);
206 catch (const gdb_exception
&except
)
208 GDB_PY_HANDLE_EXCEPTION (except
);
211 stop_reason
= get_frame_unwind_stop_reason (frame
);
213 return PyInt_FromLong (stop_reason
);
216 /* Implementation of gdb.Frame.pc (self) -> Long.
217 Returns the frame's resume address. */
220 frapy_pc (PyObject
*self
, PyObject
*args
)
222 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
223 struct frame_info
*frame
;
227 FRAPY_REQUIRE_VALID (self
, frame
);
229 pc
= get_frame_pc (frame
);
231 catch (const gdb_exception
&except
)
233 GDB_PY_HANDLE_EXCEPTION (except
);
236 return gdb_py_long_from_ulongest (pc
);
239 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
240 Returns the value of a register in this frame. */
243 frapy_read_register (PyObject
*self
, PyObject
*args
)
245 const char *regnum_str
;
246 struct value
*val
= NULL
;
248 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
253 struct frame_info
*frame
;
256 FRAPY_REQUIRE_VALID (self
, frame
);
258 regnum
= user_reg_map_name_to_regnum (get_frame_arch (frame
),
260 strlen (regnum_str
));
262 val
= value_of_register (regnum
, frame
);
265 PyErr_SetString (PyExc_ValueError
, _("Unknown register."));
267 catch (const gdb_exception
&except
)
269 GDB_PY_HANDLE_EXCEPTION (except
);
272 return val
== NULL
? NULL
: value_to_value_object (val
);
275 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
276 Returns the frame's code block. */
279 frapy_block (PyObject
*self
, PyObject
*args
)
281 struct frame_info
*frame
;
282 const struct block
*block
= NULL
, *fn_block
;
286 FRAPY_REQUIRE_VALID (self
, frame
);
287 block
= get_frame_block (frame
, NULL
);
289 catch (const gdb_exception
&except
)
291 GDB_PY_HANDLE_EXCEPTION (except
);
294 for (fn_block
= block
;
295 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
296 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
299 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
301 PyErr_SetString (PyExc_RuntimeError
,
302 _("Cannot locate block for frame."));
308 return block_to_block_object
309 (block
, symbol_objfile (BLOCK_FUNCTION (fn_block
)));
316 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
317 Returns the symbol for the function corresponding to this frame. */
320 frapy_function (PyObject
*self
, PyObject
*args
)
322 struct symbol
*sym
= NULL
;
323 struct frame_info
*frame
;
327 enum language funlang
;
329 FRAPY_REQUIRE_VALID (self
, frame
);
331 gdb::unique_xmalloc_ptr
<char> funname
332 = find_frame_funname (frame
, &funlang
, &sym
);
334 catch (const gdb_exception
&except
)
336 GDB_PY_HANDLE_EXCEPTION (except
);
340 return symbol_to_symbol_object (sym
);
345 /* Convert a frame_info struct to a Python Frame object.
346 Sets a Python exception and returns NULL on error. */
349 frame_info_to_frame_object (struct frame_info
*frame
)
351 gdbpy_ref
<frame_object
> frame_obj (PyObject_New (frame_object
,
352 &frame_object_type
));
353 if (frame_obj
== NULL
)
359 /* Try to get the previous frame, to determine if this is the last frame
360 in a corrupt stack. If so, we need to store the frame_id of the next
361 frame and not of this one (which is possibly invalid). */
362 if (get_prev_frame (frame
) == NULL
363 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
364 && get_next_frame (frame
) != NULL
)
366 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
367 frame_obj
->frame_id_is_next
= 1;
371 frame_obj
->frame_id
= get_frame_id (frame
);
372 frame_obj
->frame_id_is_next
= 0;
374 frame_obj
->gdbarch
= get_frame_arch (frame
);
376 catch (const gdb_exception
&except
)
378 gdbpy_convert_exception (except
);
382 return (PyObject
*) frame_obj
.release ();
385 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
386 Returns the frame immediately older (outer) to this frame, or None if
390 frapy_older (PyObject
*self
, PyObject
*args
)
392 struct frame_info
*frame
, *prev
= NULL
;
393 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
397 FRAPY_REQUIRE_VALID (self
, frame
);
399 prev
= get_prev_frame (frame
);
401 catch (const gdb_exception
&except
)
403 GDB_PY_HANDLE_EXCEPTION (except
);
407 prev_obj
= frame_info_to_frame_object (prev
);
417 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
418 Returns the frame immediately newer (inner) to this frame, or None if
422 frapy_newer (PyObject
*self
, PyObject
*args
)
424 struct frame_info
*frame
, *next
= NULL
;
425 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
429 FRAPY_REQUIRE_VALID (self
, frame
);
431 next
= get_next_frame (frame
);
433 catch (const gdb_exception
&except
)
435 GDB_PY_HANDLE_EXCEPTION (except
);
439 next_obj
= frame_info_to_frame_object (next
);
449 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
450 Returns the frame's symtab and line. */
453 frapy_find_sal (PyObject
*self
, PyObject
*args
)
455 struct frame_info
*frame
;
456 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
460 FRAPY_REQUIRE_VALID (self
, frame
);
462 symtab_and_line sal
= find_frame_sal (frame
);
463 sal_obj
= symtab_and_line_to_sal_object (sal
);
465 catch (const gdb_exception
&except
)
467 GDB_PY_HANDLE_EXCEPTION (except
);
473 /* Implementation of gdb.Frame.read_var_value (self, variable,
474 [block]) -> gdb.Value. If the optional block argument is provided
475 start the search from that block, otherwise search from the frame's
476 current block (determined by examining the resume address of the
477 frame). The variable argument must be a string or an instance of a
478 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
479 NULL on error, with a python exception set. */
481 frapy_read_var (PyObject
*self
, PyObject
*args
)
483 struct frame_info
*frame
;
484 PyObject
*sym_obj
, *block_obj
= NULL
;
485 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
486 const struct block
*block
= NULL
;
487 struct value
*val
= NULL
;
489 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
492 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
493 var
= symbol_object_to_symbol (sym_obj
);
494 else if (gdbpy_is_string (sym_obj
))
496 gdb::unique_xmalloc_ptr
<char>
497 var_name (python_string_to_target_string (sym_obj
));
504 block
= block_object_to_block (block_obj
);
507 PyErr_SetString (PyExc_RuntimeError
,
508 _("Second argument must be block."));
515 struct block_symbol lookup_sym
;
516 FRAPY_REQUIRE_VALID (self
, frame
);
519 block
= get_frame_block (frame
, NULL
);
520 lookup_sym
= lookup_symbol (var_name
.get (), block
, VAR_DOMAIN
, NULL
);
521 var
= lookup_sym
.symbol
;
522 block
= lookup_sym
.block
;
524 catch (const gdb_exception
&except
)
526 gdbpy_convert_exception (except
);
532 PyErr_Format (PyExc_ValueError
,
533 _("Variable '%s' not found."), var_name
.get ());
540 PyErr_SetString (PyExc_TypeError
,
541 _("Argument must be a symbol or string."));
547 FRAPY_REQUIRE_VALID (self
, frame
);
549 val
= read_var_value (var
, block
, frame
);
551 catch (const gdb_exception
&except
)
553 GDB_PY_HANDLE_EXCEPTION (except
);
556 return value_to_value_object (val
);
559 /* Select this frame. */
562 frapy_select (PyObject
*self
, PyObject
*args
)
564 struct frame_info
*fi
;
568 FRAPY_REQUIRE_VALID (self
, fi
);
572 catch (const gdb_exception
&except
)
574 GDB_PY_HANDLE_EXCEPTION (except
);
580 /* Implementation of gdb.newest_frame () -> gdb.Frame.
581 Returns the newest frame object. */
584 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
586 struct frame_info
*frame
= NULL
;
590 frame
= get_current_frame ();
592 catch (const gdb_exception
&except
)
594 GDB_PY_HANDLE_EXCEPTION (except
);
597 return frame_info_to_frame_object (frame
);
600 /* Implementation of gdb.selected_frame () -> gdb.Frame.
601 Returns the selected frame object. */
604 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
606 struct frame_info
*frame
= NULL
;
610 frame
= get_selected_frame ("No frame is currently selected.");
612 catch (const gdb_exception
&except
)
614 GDB_PY_HANDLE_EXCEPTION (except
);
617 return frame_info_to_frame_object (frame
);
620 /* Implementation of gdb.stop_reason_string (Integer) -> String.
621 Return a string explaining the unwind stop reason. */
624 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
629 if (!PyArg_ParseTuple (args
, "i", &reason
))
632 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
634 PyErr_SetString (PyExc_ValueError
,
635 _("Invalid frame stop reason."));
639 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
640 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
643 /* Implements the equality comparison for Frame objects.
644 All other comparison operators will throw a TypeError Python exception,
645 as they aren't valid for frames. */
648 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
652 if (!PyObject_TypeCheck (other
, &frame_object_type
)
653 || (op
!= Py_EQ
&& op
!= Py_NE
))
655 Py_INCREF (Py_NotImplemented
);
656 return Py_NotImplemented
;
659 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
660 ((frame_object
*) other
)->frame_id
))
670 /* Sets up the Frame API in the gdb module. */
673 gdbpy_initialize_frames (void)
675 frame_object_type
.tp_new
= PyType_GenericNew
;
676 if (PyType_Ready (&frame_object_type
) < 0)
679 /* Note: These would probably be best exposed as class attributes of
680 Frame, but I don't know how to do it except by messing with the
681 type's dictionary. That seems too messy. */
682 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
683 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
684 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
685 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
687 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
689 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
690 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
694 #define SET(name, description) \
695 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
697 #include "unwind_stop_reasons.def"
700 return gdb_pymodule_addobject (gdb_module
, "Frame",
701 (PyObject
*) &frame_object_type
);
706 static PyMethodDef frame_object_methods
[] = {
707 { "is_valid", frapy_is_valid
, METH_NOARGS
,
708 "is_valid () -> Boolean.\n\
709 Return true if this frame is valid, false if not." },
710 { "name", frapy_name
, METH_NOARGS
,
711 "name () -> String.\n\
712 Return the function name of the frame, or None if it can't be determined." },
713 { "type", frapy_type
, METH_NOARGS
,
714 "type () -> Integer.\n\
715 Return the type of the frame." },
716 { "architecture", frapy_arch
, METH_NOARGS
,
717 "architecture () -> gdb.Architecture.\n\
718 Return the architecture of the frame." },
719 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
720 "unwind_stop_reason () -> Integer.\n\
721 Return the reason why it's not possible to find frames older than this." },
722 { "pc", frapy_pc
, METH_NOARGS
,
724 Return the frame's resume address." },
725 { "read_register", frapy_read_register
, METH_VARARGS
,
726 "read_register (register_name) -> gdb.Value\n\
727 Return the value of the register in the frame." },
728 { "block", frapy_block
, METH_NOARGS
,
729 "block () -> gdb.Block.\n\
730 Return the frame's code block." },
731 { "function", frapy_function
, METH_NOARGS
,
732 "function () -> gdb.Symbol.\n\
733 Returns the symbol for the function corresponding to this frame." },
734 { "older", frapy_older
, METH_NOARGS
,
735 "older () -> gdb.Frame.\n\
736 Return the frame that called this frame." },
737 { "newer", frapy_newer
, METH_NOARGS
,
738 "newer () -> gdb.Frame.\n\
739 Return the frame called by this frame." },
740 { "find_sal", frapy_find_sal
, METH_NOARGS
,
741 "find_sal () -> gdb.Symtab_and_line.\n\
742 Return the frame's symtab and line." },
743 { "read_var", frapy_read_var
, METH_VARARGS
,
744 "read_var (variable) -> gdb.Value.\n\
745 Return the value of the variable in this frame." },
746 { "select", frapy_select
, METH_NOARGS
,
747 "Select this frame as the user's current frame." },
748 {NULL
} /* Sentinel */
751 PyTypeObject frame_object_type
= {
752 PyVarObject_HEAD_INIT (NULL
, 0)
753 "gdb.Frame", /* tp_name */
754 sizeof (frame_object
), /* tp_basicsize */
762 0, /* tp_as_number */
763 0, /* tp_as_sequence */
764 0, /* tp_as_mapping */
767 frapy_str
, /* tp_str */
770 0, /* tp_as_buffer */
771 Py_TPFLAGS_DEFAULT
, /* tp_flags */
772 "GDB frame object", /* tp_doc */
775 frapy_richcompare
, /* tp_richcompare */
776 0, /* tp_weaklistoffset */
779 frame_object_methods
, /* tp_methods */
784 0, /* tp_descr_get */
785 0, /* tp_descr_set */
786 0, /* tp_dictoffset */