1 /* Python interface to stack frames
3 Copyright (C) 2008-2016 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
)
84 struct ui_file
*strfile
;
86 strfile
= mem_fileopen ();
87 fprint_frame_id (strfile
, ((frame_object
*) self
)->frame_id
);
88 std::string s
= ui_file_as_string (strfile
);
89 return PyString_FromString (s
.c_str ());
92 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
93 Returns True if the frame corresponding to the frame_id of this
94 object still exists in the inferior. */
97 frapy_is_valid (PyObject
*self
, PyObject
*args
)
99 struct frame_info
*frame
= NULL
;
103 frame
= frame_object_to_frame_info (self
);
105 CATCH (except
, RETURN_MASK_ALL
)
107 GDB_PY_HANDLE_EXCEPTION (except
);
117 /* Implementation of gdb.Frame.name (self) -> String.
118 Returns the name of the function corresponding to this frame. */
121 frapy_name (PyObject
*self
, PyObject
*args
)
123 struct frame_info
*frame
;
130 FRAPY_REQUIRE_VALID (self
, frame
);
132 find_frame_funname (frame
, &name
, &lang
, NULL
);
134 CATCH (except
, RETURN_MASK_ALL
)
137 GDB_PY_HANDLE_EXCEPTION (except
);
143 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
155 /* Implementation of gdb.Frame.type (self) -> Integer.
156 Returns the frame type, namely one of the gdb.*_FRAME constants. */
159 frapy_type (PyObject
*self
, PyObject
*args
)
161 struct frame_info
*frame
;
162 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
166 FRAPY_REQUIRE_VALID (self
, frame
);
168 type
= get_frame_type (frame
);
170 CATCH (except
, RETURN_MASK_ALL
)
172 GDB_PY_HANDLE_EXCEPTION (except
);
176 return PyInt_FromLong (type
);
179 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
180 Returns the frame's architecture as a gdb.Architecture object. */
183 frapy_arch (PyObject
*self
, PyObject
*args
)
185 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
186 frame_object
*obj
= (frame_object
*) self
;
190 FRAPY_REQUIRE_VALID (self
, frame
);
192 CATCH (except
, RETURN_MASK_ALL
)
194 GDB_PY_HANDLE_EXCEPTION (except
);
198 return gdbarch_to_arch_object (obj
->gdbarch
);
201 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
202 Returns one of the gdb.FRAME_UNWIND_* constants. */
205 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
207 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
208 enum unwind_stop_reason stop_reason
;
212 FRAPY_REQUIRE_VALID (self
, frame
);
214 CATCH (except
, RETURN_MASK_ALL
)
216 GDB_PY_HANDLE_EXCEPTION (except
);
220 stop_reason
= get_frame_unwind_stop_reason (frame
);
222 return PyInt_FromLong (stop_reason
);
225 /* Implementation of gdb.Frame.pc (self) -> Long.
226 Returns the frame's resume address. */
229 frapy_pc (PyObject
*self
, PyObject
*args
)
231 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
232 struct frame_info
*frame
;
236 FRAPY_REQUIRE_VALID (self
, frame
);
238 pc
= get_frame_pc (frame
);
240 CATCH (except
, RETURN_MASK_ALL
)
242 GDB_PY_HANDLE_EXCEPTION (except
);
246 return gdb_py_long_from_ulongest (pc
);
249 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
250 Returns the value of a register in this frame. */
253 frapy_read_register (PyObject
*self
, PyObject
*args
)
255 const char *regnum_str
;
256 struct value
*val
= NULL
;
258 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
263 struct frame_info
*frame
;
266 FRAPY_REQUIRE_VALID (self
, frame
);
268 regnum
= user_reg_map_name_to_regnum (get_frame_arch (frame
),
270 strlen (regnum_str
));
272 val
= value_of_register (regnum
, frame
);
275 PyErr_SetString (PyExc_ValueError
, _("Unknown register."));
277 CATCH (except
, RETURN_MASK_ALL
)
279 GDB_PY_HANDLE_EXCEPTION (except
);
283 return val
== NULL
? NULL
: value_to_value_object (val
);
286 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
287 Returns the frame's code block. */
290 frapy_block (PyObject
*self
, PyObject
*args
)
292 struct frame_info
*frame
;
293 const struct block
*block
= NULL
, *fn_block
;
297 FRAPY_REQUIRE_VALID (self
, frame
);
298 block
= get_frame_block (frame
, NULL
);
300 CATCH (except
, RETURN_MASK_ALL
)
302 GDB_PY_HANDLE_EXCEPTION (except
);
306 for (fn_block
= block
;
307 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
308 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
311 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
313 PyErr_SetString (PyExc_RuntimeError
,
314 _("Cannot locate block for frame."));
320 return block_to_block_object
321 (block
, symbol_objfile (BLOCK_FUNCTION (fn_block
)));
328 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
329 Returns the symbol for the function corresponding to this frame. */
332 frapy_function (PyObject
*self
, PyObject
*args
)
334 struct symbol
*sym
= NULL
;
335 struct frame_info
*frame
;
340 enum language funlang
;
342 FRAPY_REQUIRE_VALID (self
, frame
);
344 find_frame_funname (frame
, &funname
, &funlang
, &sym
);
347 CATCH (except
, RETURN_MASK_ALL
)
349 GDB_PY_HANDLE_EXCEPTION (except
);
354 return symbol_to_symbol_object (sym
);
359 /* Convert a frame_info struct to a Python Frame object.
360 Sets a Python exception and returns NULL on error. */
363 frame_info_to_frame_object (struct frame_info
*frame
)
365 frame_object
*frame_obj
;
367 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
368 if (frame_obj
== NULL
)
374 /* Try to get the previous frame, to determine if this is the last frame
375 in a corrupt stack. If so, we need to store the frame_id of the next
376 frame and not of this one (which is possibly invalid). */
377 if (get_prev_frame (frame
) == NULL
378 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
379 && get_next_frame (frame
) != NULL
)
381 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
382 frame_obj
->frame_id_is_next
= 1;
386 frame_obj
->frame_id
= get_frame_id (frame
);
387 frame_obj
->frame_id_is_next
= 0;
389 frame_obj
->gdbarch
= get_frame_arch (frame
);
391 CATCH (except
, RETURN_MASK_ALL
)
393 Py_DECREF (frame_obj
);
394 gdbpy_convert_exception (except
);
399 return (PyObject
*) frame_obj
;
402 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
403 Returns the frame immediately older (outer) to this frame, or None if
407 frapy_older (PyObject
*self
, PyObject
*args
)
409 struct frame_info
*frame
, *prev
= NULL
;
410 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
414 FRAPY_REQUIRE_VALID (self
, frame
);
416 prev
= get_prev_frame (frame
);
418 CATCH (except
, RETURN_MASK_ALL
)
420 GDB_PY_HANDLE_EXCEPTION (except
);
425 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
435 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
436 Returns the frame immediately newer (inner) to this frame, or None if
440 frapy_newer (PyObject
*self
, PyObject
*args
)
442 struct frame_info
*frame
, *next
= NULL
;
443 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
447 FRAPY_REQUIRE_VALID (self
, frame
);
449 next
= get_next_frame (frame
);
451 CATCH (except
, RETURN_MASK_ALL
)
453 GDB_PY_HANDLE_EXCEPTION (except
);
458 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
468 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
469 Returns the frame's symtab and line. */
472 frapy_find_sal (PyObject
*self
, PyObject
*args
)
474 struct frame_info
*frame
;
475 struct symtab_and_line sal
;
476 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
480 FRAPY_REQUIRE_VALID (self
, frame
);
482 find_frame_sal (frame
, &sal
);
483 sal_obj
= symtab_and_line_to_sal_object (sal
);
485 CATCH (except
, RETURN_MASK_ALL
)
487 GDB_PY_HANDLE_EXCEPTION (except
);
494 /* Implementation of gdb.Frame.read_var_value (self, variable,
495 [block]) -> gdb.Value. If the optional block argument is provided
496 start the search from that block, otherwise search from the frame's
497 current block (determined by examining the resume address of the
498 frame). The variable argument must be a string or an instance of a
499 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
500 NULL on error, with a python exception set. */
502 frapy_read_var (PyObject
*self
, PyObject
*args
)
504 struct frame_info
*frame
;
505 PyObject
*sym_obj
, *block_obj
= NULL
;
506 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
507 const struct block
*block
= NULL
;
508 struct value
*val
= NULL
;
510 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
513 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
514 var
= symbol_object_to_symbol (sym_obj
);
515 else if (gdbpy_is_string (sym_obj
))
518 struct cleanup
*cleanup
;
520 var_name
= python_string_to_target_string (sym_obj
);
523 cleanup
= make_cleanup (xfree
, var_name
);
527 block
= block_object_to_block (block_obj
);
530 PyErr_SetString (PyExc_RuntimeError
,
531 _("Second argument must be block."));
532 do_cleanups (cleanup
);
539 struct block_symbol lookup_sym
;
540 FRAPY_REQUIRE_VALID (self
, frame
);
543 block
= get_frame_block (frame
, NULL
);
544 lookup_sym
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
545 var
= lookup_sym
.symbol
;
546 block
= lookup_sym
.block
;
548 CATCH (except
, RETURN_MASK_ALL
)
550 do_cleanups (cleanup
);
551 gdbpy_convert_exception (except
);
558 PyErr_Format (PyExc_ValueError
,
559 _("Variable '%s' not found."), var_name
);
560 do_cleanups (cleanup
);
565 do_cleanups (cleanup
);
569 PyErr_SetString (PyExc_TypeError
,
570 _("Argument must be a symbol or string."));
576 FRAPY_REQUIRE_VALID (self
, frame
);
578 val
= read_var_value (var
, block
, frame
);
580 CATCH (except
, RETURN_MASK_ALL
)
582 GDB_PY_HANDLE_EXCEPTION (except
);
586 return value_to_value_object (val
);
589 /* Select this frame. */
592 frapy_select (PyObject
*self
, PyObject
*args
)
594 struct frame_info
*fi
;
598 FRAPY_REQUIRE_VALID (self
, fi
);
602 CATCH (except
, RETURN_MASK_ALL
)
604 GDB_PY_HANDLE_EXCEPTION (except
);
611 /* Implementation of gdb.newest_frame () -> gdb.Frame.
612 Returns the newest frame object. */
615 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
617 struct frame_info
*frame
= NULL
;
621 frame
= get_current_frame ();
623 CATCH (except
, RETURN_MASK_ALL
)
625 GDB_PY_HANDLE_EXCEPTION (except
);
629 return frame_info_to_frame_object (frame
);
632 /* Implementation of gdb.selected_frame () -> gdb.Frame.
633 Returns the selected frame object. */
636 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
638 struct frame_info
*frame
= NULL
;
642 frame
= get_selected_frame ("No frame is currently selected.");
644 CATCH (except
, RETURN_MASK_ALL
)
646 GDB_PY_HANDLE_EXCEPTION (except
);
650 return frame_info_to_frame_object (frame
);
653 /* Implementation of gdb.stop_reason_string (Integer) -> String.
654 Return a string explaining the unwind stop reason. */
657 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
662 if (!PyArg_ParseTuple (args
, "i", &reason
))
665 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
667 PyErr_SetString (PyExc_ValueError
,
668 _("Invalid frame stop reason."));
672 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
673 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
676 /* Implements the equality comparison for Frame objects.
677 All other comparison operators will throw a TypeError Python exception,
678 as they aren't valid for frames. */
681 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
685 if (!PyObject_TypeCheck (other
, &frame_object_type
)
686 || (op
!= Py_EQ
&& op
!= Py_NE
))
688 Py_INCREF (Py_NotImplemented
);
689 return Py_NotImplemented
;
692 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
693 ((frame_object
*) other
)->frame_id
))
703 /* Sets up the Frame API in the gdb module. */
706 gdbpy_initialize_frames (void)
708 frame_object_type
.tp_new
= PyType_GenericNew
;
709 if (PyType_Ready (&frame_object_type
) < 0)
712 /* Note: These would probably be best exposed as class attributes of
713 Frame, but I don't know how to do it except by messing with the
714 type's dictionary. That seems too messy. */
715 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
716 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
717 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
718 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
720 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
722 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
723 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
727 #define SET(name, description) \
728 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
730 #include "unwind_stop_reasons.def"
733 return gdb_pymodule_addobject (gdb_module
, "Frame",
734 (PyObject
*) &frame_object_type
);
739 static PyMethodDef frame_object_methods
[] = {
740 { "is_valid", frapy_is_valid
, METH_NOARGS
,
741 "is_valid () -> Boolean.\n\
742 Return true if this frame is valid, false if not." },
743 { "name", frapy_name
, METH_NOARGS
,
744 "name () -> String.\n\
745 Return the function name of the frame, or None if it can't be determined." },
746 { "type", frapy_type
, METH_NOARGS
,
747 "type () -> Integer.\n\
748 Return the type of the frame." },
749 { "architecture", frapy_arch
, METH_NOARGS
,
750 "architecture () -> gdb.Architecture.\n\
751 Return the architecture of the frame." },
752 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
753 "unwind_stop_reason () -> Integer.\n\
754 Return the reason why it's not possible to find frames older than this." },
755 { "pc", frapy_pc
, METH_NOARGS
,
757 Return the frame's resume address." },
758 { "read_register", frapy_read_register
, METH_VARARGS
,
759 "read_register (register_name) -> gdb.Value\n\
760 Return the value of the register in the frame." },
761 { "block", frapy_block
, METH_NOARGS
,
762 "block () -> gdb.Block.\n\
763 Return the frame's code block." },
764 { "function", frapy_function
, METH_NOARGS
,
765 "function () -> gdb.Symbol.\n\
766 Returns the symbol for the function corresponding to this frame." },
767 { "older", frapy_older
, METH_NOARGS
,
768 "older () -> gdb.Frame.\n\
769 Return the frame that called this frame." },
770 { "newer", frapy_newer
, METH_NOARGS
,
771 "newer () -> gdb.Frame.\n\
772 Return the frame called by this frame." },
773 { "find_sal", frapy_find_sal
, METH_NOARGS
,
774 "find_sal () -> gdb.Symtab_and_line.\n\
775 Return the frame's symtab and line." },
776 { "read_var", frapy_read_var
, METH_VARARGS
,
777 "read_var (variable) -> gdb.Value.\n\
778 Return the value of the variable in this frame." },
779 { "select", frapy_select
, METH_NOARGS
,
780 "Select this frame as the user's current frame." },
781 {NULL
} /* Sentinel */
784 PyTypeObject frame_object_type
= {
785 PyVarObject_HEAD_INIT (NULL
, 0)
786 "gdb.Frame", /* tp_name */
787 sizeof (frame_object
), /* tp_basicsize */
795 0, /* tp_as_number */
796 0, /* tp_as_sequence */
797 0, /* tp_as_mapping */
800 frapy_str
, /* tp_str */
803 0, /* tp_as_buffer */
804 Py_TPFLAGS_DEFAULT
, /* tp_flags */
805 "GDB frame object", /* tp_doc */
808 frapy_richcompare
, /* tp_richcompare */
809 0, /* tp_weaklistoffset */
812 frame_object_methods
, /* tp_methods */
817 0, /* tp_descr_get */
818 0, /* tp_descr_set */
819 0, /* tp_dictoffset */