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
)
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
;
344 enum language funlang
;
346 FRAPY_REQUIRE_VALID (self
, frame
);
348 find_frame_funname (frame
, &funname
, &funlang
, &sym
);
351 CATCH (except
, RETURN_MASK_ALL
)
353 GDB_PY_HANDLE_EXCEPTION (except
);
358 return symbol_to_symbol_object (sym
);
363 /* Convert a frame_info struct to a Python Frame object.
364 Sets a Python exception and returns NULL on error. */
367 frame_info_to_frame_object (struct frame_info
*frame
)
369 frame_object
*frame_obj
;
371 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
372 if (frame_obj
== NULL
)
378 /* Try to get the previous frame, to determine if this is the last frame
379 in a corrupt stack. If so, we need to store the frame_id of the next
380 frame and not of this one (which is possibly invalid). */
381 if (get_prev_frame (frame
) == NULL
382 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
383 && get_next_frame (frame
) != NULL
)
385 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
386 frame_obj
->frame_id_is_next
= 1;
390 frame_obj
->frame_id
= get_frame_id (frame
);
391 frame_obj
->frame_id_is_next
= 0;
393 frame_obj
->gdbarch
= get_frame_arch (frame
);
395 CATCH (except
, RETURN_MASK_ALL
)
397 Py_DECREF (frame_obj
);
398 gdbpy_convert_exception (except
);
403 return (PyObject
*) frame_obj
;
406 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
407 Returns the frame immediately older (outer) to this frame, or None if
411 frapy_older (PyObject
*self
, PyObject
*args
)
413 struct frame_info
*frame
, *prev
= NULL
;
414 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
418 FRAPY_REQUIRE_VALID (self
, frame
);
420 prev
= get_prev_frame (frame
);
422 CATCH (except
, RETURN_MASK_ALL
)
424 GDB_PY_HANDLE_EXCEPTION (except
);
429 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
439 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
440 Returns the frame immediately newer (inner) to this frame, or None if
444 frapy_newer (PyObject
*self
, PyObject
*args
)
446 struct frame_info
*frame
, *next
= NULL
;
447 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
451 FRAPY_REQUIRE_VALID (self
, frame
);
453 next
= get_next_frame (frame
);
455 CATCH (except
, RETURN_MASK_ALL
)
457 GDB_PY_HANDLE_EXCEPTION (except
);
462 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
472 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
473 Returns the frame's symtab and line. */
476 frapy_find_sal (PyObject
*self
, PyObject
*args
)
478 struct frame_info
*frame
;
479 struct symtab_and_line sal
;
480 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
484 FRAPY_REQUIRE_VALID (self
, frame
);
486 find_frame_sal (frame
, &sal
);
487 sal_obj
= symtab_and_line_to_sal_object (sal
);
489 CATCH (except
, RETURN_MASK_ALL
)
491 GDB_PY_HANDLE_EXCEPTION (except
);
498 /* Implementation of gdb.Frame.read_var_value (self, variable,
499 [block]) -> gdb.Value. If the optional block argument is provided
500 start the search from that block, otherwise search from the frame's
501 current block (determined by examining the resume address of the
502 frame). The variable argument must be a string or an instance of a
503 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
504 NULL on error, with a python exception set. */
506 frapy_read_var (PyObject
*self
, PyObject
*args
)
508 struct frame_info
*frame
;
509 PyObject
*sym_obj
, *block_obj
= NULL
;
510 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
511 const struct block
*block
= NULL
;
512 struct value
*val
= NULL
;
514 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
517 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
518 var
= symbol_object_to_symbol (sym_obj
);
519 else if (gdbpy_is_string (sym_obj
))
522 struct cleanup
*cleanup
;
524 var_name
= python_string_to_target_string (sym_obj
);
527 cleanup
= make_cleanup (xfree
, var_name
);
531 block
= block_object_to_block (block_obj
);
534 PyErr_SetString (PyExc_RuntimeError
,
535 _("Second argument must be block."));
536 do_cleanups (cleanup
);
543 struct block_symbol lookup_sym
;
544 FRAPY_REQUIRE_VALID (self
, frame
);
547 block
= get_frame_block (frame
, NULL
);
548 lookup_sym
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
549 var
= lookup_sym
.symbol
;
550 block
= lookup_sym
.block
;
552 CATCH (except
, RETURN_MASK_ALL
)
554 do_cleanups (cleanup
);
555 gdbpy_convert_exception (except
);
562 PyErr_Format (PyExc_ValueError
,
563 _("Variable '%s' not found."), var_name
);
564 do_cleanups (cleanup
);
569 do_cleanups (cleanup
);
573 PyErr_SetString (PyExc_TypeError
,
574 _("Argument must be a symbol or string."));
580 FRAPY_REQUIRE_VALID (self
, frame
);
582 val
= read_var_value (var
, block
, frame
);
584 CATCH (except
, RETURN_MASK_ALL
)
586 GDB_PY_HANDLE_EXCEPTION (except
);
590 return value_to_value_object (val
);
593 /* Select this frame. */
596 frapy_select (PyObject
*self
, PyObject
*args
)
598 struct frame_info
*fi
;
602 FRAPY_REQUIRE_VALID (self
, fi
);
606 CATCH (except
, RETURN_MASK_ALL
)
608 GDB_PY_HANDLE_EXCEPTION (except
);
615 /* Implementation of gdb.newest_frame () -> gdb.Frame.
616 Returns the newest frame object. */
619 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
621 struct frame_info
*frame
= NULL
;
625 frame
= get_current_frame ();
627 CATCH (except
, RETURN_MASK_ALL
)
629 GDB_PY_HANDLE_EXCEPTION (except
);
633 return frame_info_to_frame_object (frame
);
636 /* Implementation of gdb.selected_frame () -> gdb.Frame.
637 Returns the selected frame object. */
640 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
642 struct frame_info
*frame
= NULL
;
646 frame
= get_selected_frame ("No frame is currently selected.");
648 CATCH (except
, RETURN_MASK_ALL
)
650 GDB_PY_HANDLE_EXCEPTION (except
);
654 return frame_info_to_frame_object (frame
);
657 /* Implementation of gdb.stop_reason_string (Integer) -> String.
658 Return a string explaining the unwind stop reason. */
661 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
666 if (!PyArg_ParseTuple (args
, "i", &reason
))
669 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
671 PyErr_SetString (PyExc_ValueError
,
672 _("Invalid frame stop reason."));
676 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
677 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
680 /* Implements the equality comparison for Frame objects.
681 All other comparison operators will throw a TypeError Python exception,
682 as they aren't valid for frames. */
685 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
689 if (!PyObject_TypeCheck (other
, &frame_object_type
)
690 || (op
!= Py_EQ
&& op
!= Py_NE
))
692 Py_INCREF (Py_NotImplemented
);
693 return Py_NotImplemented
;
696 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
697 ((frame_object
*) other
)->frame_id
))
707 /* Sets up the Frame API in the gdb module. */
710 gdbpy_initialize_frames (void)
712 frame_object_type
.tp_new
= PyType_GenericNew
;
713 if (PyType_Ready (&frame_object_type
) < 0)
716 /* Note: These would probably be best exposed as class attributes of
717 Frame, but I don't know how to do it except by messing with the
718 type's dictionary. That seems too messy. */
719 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
720 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
721 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
722 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
724 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
726 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
727 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
731 #define SET(name, description) \
732 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
734 #include "unwind_stop_reasons.def"
737 return gdb_pymodule_addobject (gdb_module
, "Frame",
738 (PyObject
*) &frame_object_type
);
743 static PyMethodDef frame_object_methods
[] = {
744 { "is_valid", frapy_is_valid
, METH_NOARGS
,
745 "is_valid () -> Boolean.\n\
746 Return true if this frame is valid, false if not." },
747 { "name", frapy_name
, METH_NOARGS
,
748 "name () -> String.\n\
749 Return the function name of the frame, or None if it can't be determined." },
750 { "type", frapy_type
, METH_NOARGS
,
751 "type () -> Integer.\n\
752 Return the type of the frame." },
753 { "architecture", frapy_arch
, METH_NOARGS
,
754 "architecture () -> gdb.Architecture.\n\
755 Return the architecture of the frame." },
756 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
757 "unwind_stop_reason () -> Integer.\n\
758 Return the reason why it's not possible to find frames older than this." },
759 { "pc", frapy_pc
, METH_NOARGS
,
761 Return the frame's resume address." },
762 { "read_register", frapy_read_register
, METH_VARARGS
,
763 "read_register (register_name) -> gdb.Value\n\
764 Return the value of the register in the frame." },
765 { "block", frapy_block
, METH_NOARGS
,
766 "block () -> gdb.Block.\n\
767 Return the frame's code block." },
768 { "function", frapy_function
, METH_NOARGS
,
769 "function () -> gdb.Symbol.\n\
770 Returns the symbol for the function corresponding to this frame." },
771 { "older", frapy_older
, METH_NOARGS
,
772 "older () -> gdb.Frame.\n\
773 Return the frame that called this frame." },
774 { "newer", frapy_newer
, METH_NOARGS
,
775 "newer () -> gdb.Frame.\n\
776 Return the frame called by this frame." },
777 { "find_sal", frapy_find_sal
, METH_NOARGS
,
778 "find_sal () -> gdb.Symtab_and_line.\n\
779 Return the frame's symtab and line." },
780 { "read_var", frapy_read_var
, METH_VARARGS
,
781 "read_var (variable) -> gdb.Value.\n\
782 Return the value of the variable in this frame." },
783 { "select", frapy_select
, METH_NOARGS
,
784 "Select this frame as the user's current frame." },
785 {NULL
} /* Sentinel */
788 PyTypeObject frame_object_type
= {
789 PyVarObject_HEAD_INIT (NULL
, 0)
790 "gdb.Frame", /* tp_name */
791 sizeof (frame_object
), /* tp_basicsize */
799 0, /* tp_as_number */
800 0, /* tp_as_sequence */
801 0, /* tp_as_mapping */
804 frapy_str
, /* tp_str */
807 0, /* tp_as_buffer */
808 Py_TPFLAGS_DEFAULT
, /* tp_flags */
809 "GDB frame object", /* tp_doc */
812 frapy_richcompare
, /* tp_richcompare */
813 0, /* tp_weaklistoffset */
816 frame_object_methods
, /* tp_methods */
821 0, /* tp_descr_get */
822 0, /* tp_descr_set */
823 0, /* tp_dictoffset */