1 /* Python interface to stack frames
3 Copyright (C) 2008-2015 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 struct ui_file
*strfile
;
87 strfile
= mem_fileopen ();
88 fprint_frame_id (strfile
, ((frame_object
*) self
)->frame_id
);
89 s
= ui_file_xstrdup (strfile
, NULL
);
90 result
= PyString_FromString (s
);
96 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
97 Returns True if the frame corresponding to the frame_id of this
98 object still exists in the inferior. */
101 frapy_is_valid (PyObject
*self
, PyObject
*args
)
103 struct frame_info
*frame
= NULL
;
107 frame
= frame_object_to_frame_info (self
);
109 CATCH (except
, RETURN_MASK_ALL
)
111 GDB_PY_HANDLE_EXCEPTION (except
);
121 /* Implementation of gdb.Frame.name (self) -> String.
122 Returns the name of the function corresponding to this frame. */
125 frapy_name (PyObject
*self
, PyObject
*args
)
127 struct frame_info
*frame
;
134 FRAPY_REQUIRE_VALID (self
, frame
);
136 find_frame_funname (frame
, &name
, &lang
, NULL
);
138 CATCH (except
, RETURN_MASK_ALL
)
141 GDB_PY_HANDLE_EXCEPTION (except
);
147 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
159 /* Implementation of gdb.Frame.type (self) -> Integer.
160 Returns the frame type, namely one of the gdb.*_FRAME constants. */
163 frapy_type (PyObject
*self
, PyObject
*args
)
165 struct frame_info
*frame
;
166 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
170 FRAPY_REQUIRE_VALID (self
, frame
);
172 type
= get_frame_type (frame
);
174 CATCH (except
, RETURN_MASK_ALL
)
176 GDB_PY_HANDLE_EXCEPTION (except
);
180 return PyInt_FromLong (type
);
183 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
184 Returns the frame's architecture as a gdb.Architecture object. */
187 frapy_arch (PyObject
*self
, PyObject
*args
)
189 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
190 frame_object
*obj
= (frame_object
*) self
;
194 FRAPY_REQUIRE_VALID (self
, frame
);
196 CATCH (except
, RETURN_MASK_ALL
)
198 GDB_PY_HANDLE_EXCEPTION (except
);
202 return gdbarch_to_arch_object (obj
->gdbarch
);
205 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
206 Returns one of the gdb.FRAME_UNWIND_* constants. */
209 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
211 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
212 enum unwind_stop_reason stop_reason
;
216 FRAPY_REQUIRE_VALID (self
, frame
);
218 CATCH (except
, RETURN_MASK_ALL
)
220 GDB_PY_HANDLE_EXCEPTION (except
);
224 stop_reason
= get_frame_unwind_stop_reason (frame
);
226 return PyInt_FromLong (stop_reason
);
229 /* Implementation of gdb.Frame.pc (self) -> Long.
230 Returns the frame's resume address. */
233 frapy_pc (PyObject
*self
, PyObject
*args
)
235 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
236 struct frame_info
*frame
;
240 FRAPY_REQUIRE_VALID (self
, frame
);
242 pc
= get_frame_pc (frame
);
244 CATCH (except
, RETURN_MASK_ALL
)
246 GDB_PY_HANDLE_EXCEPTION (except
);
250 return gdb_py_long_from_ulongest (pc
);
253 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
254 Returns the value of a register in this frame. */
257 frapy_read_register (PyObject
*self
, PyObject
*args
)
259 const char *regnum_str
;
260 struct value
*val
= NULL
;
262 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
267 struct frame_info
*frame
;
270 FRAPY_REQUIRE_VALID (self
, frame
);
272 regnum
= user_reg_map_name_to_regnum (get_frame_arch (frame
),
274 strlen (regnum_str
));
276 val
= value_of_register (regnum
, frame
);
279 PyErr_SetString (PyExc_ValueError
, _("Unknown register."));
281 CATCH (except
, RETURN_MASK_ALL
)
283 GDB_PY_HANDLE_EXCEPTION (except
);
287 return val
== NULL
? NULL
: value_to_value_object (val
);
290 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
291 Returns the frame's code block. */
294 frapy_block (PyObject
*self
, PyObject
*args
)
296 struct frame_info
*frame
;
297 const struct block
*block
= NULL
, *fn_block
;
301 FRAPY_REQUIRE_VALID (self
, frame
);
302 block
= get_frame_block (frame
, NULL
);
304 CATCH (except
, RETURN_MASK_ALL
)
306 GDB_PY_HANDLE_EXCEPTION (except
);
310 for (fn_block
= block
;
311 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
312 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
315 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
317 PyErr_SetString (PyExc_RuntimeError
,
318 _("Cannot locate block for frame."));
324 return block_to_block_object
325 (block
, symbol_objfile (BLOCK_FUNCTION (fn_block
)));
332 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
333 Returns the symbol for the function corresponding to this frame. */
336 frapy_function (PyObject
*self
, PyObject
*args
)
338 struct symbol
*sym
= NULL
;
339 struct frame_info
*frame
;
343 FRAPY_REQUIRE_VALID (self
, frame
);
345 sym
= find_pc_function (get_frame_address_in_block (frame
));
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 */