1 /* Python interface to stack frames
3 Copyright (C) 2008-2014 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
;
104 volatile struct gdb_exception except
;
106 TRY_CATCH (except
, RETURN_MASK_ALL
)
108 frame
= frame_object_to_frame_info (self
);
110 GDB_PY_HANDLE_EXCEPTION (except
);
118 /* Implementation of gdb.Frame.name (self) -> String.
119 Returns the name of the function corresponding to this frame. */
122 frapy_name (PyObject
*self
, PyObject
*args
)
124 struct frame_info
*frame
;
128 volatile struct gdb_exception except
;
130 TRY_CATCH (except
, RETURN_MASK_ALL
)
132 FRAPY_REQUIRE_VALID (self
, frame
);
134 find_frame_funname (frame
, &name
, &lang
, NULL
);
137 if (except
.reason
< 0)
140 GDB_PY_HANDLE_EXCEPTION (except
);
144 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
156 /* Implementation of gdb.Frame.type (self) -> Integer.
157 Returns the frame type, namely one of the gdb.*_FRAME constants. */
160 frapy_type (PyObject
*self
, PyObject
*args
)
162 struct frame_info
*frame
;
163 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
164 volatile struct gdb_exception except
;
166 TRY_CATCH (except
, RETURN_MASK_ALL
)
168 FRAPY_REQUIRE_VALID (self
, frame
);
170 type
= get_frame_type (frame
);
172 GDB_PY_HANDLE_EXCEPTION (except
);
174 return PyInt_FromLong (type
);
177 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
178 Returns the frame's architecture as a gdb.Architecture object. */
181 frapy_arch (PyObject
*self
, PyObject
*args
)
183 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
184 frame_object
*obj
= (frame_object
*) self
;
185 volatile struct gdb_exception except
;
187 TRY_CATCH (except
, RETURN_MASK_ALL
)
189 FRAPY_REQUIRE_VALID (self
, frame
);
191 GDB_PY_HANDLE_EXCEPTION (except
);
193 return gdbarch_to_arch_object (obj
->gdbarch
);
196 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
197 Returns one of the gdb.FRAME_UNWIND_* constants. */
200 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
202 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
203 volatile struct gdb_exception except
;
204 enum unwind_stop_reason stop_reason
;
206 TRY_CATCH (except
, RETURN_MASK_ALL
)
208 FRAPY_REQUIRE_VALID (self
, frame
);
210 GDB_PY_HANDLE_EXCEPTION (except
);
212 stop_reason
= get_frame_unwind_stop_reason (frame
);
214 return PyInt_FromLong (stop_reason
);
217 /* Implementation of gdb.Frame.pc (self) -> Long.
218 Returns the frame's resume address. */
221 frapy_pc (PyObject
*self
, PyObject
*args
)
223 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
224 struct frame_info
*frame
;
225 volatile struct gdb_exception except
;
227 TRY_CATCH (except
, RETURN_MASK_ALL
)
229 FRAPY_REQUIRE_VALID (self
, frame
);
231 pc
= get_frame_pc (frame
);
233 GDB_PY_HANDLE_EXCEPTION (except
);
235 return gdb_py_long_from_ulongest (pc
);
238 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
239 Returns the value of a register in this frame. */
242 frapy_read_register (PyObject
*self
, PyObject
*args
)
244 volatile struct gdb_exception except
;
245 const char *regnum_str
;
246 struct value
*val
= NULL
;
248 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
251 TRY_CATCH (except
, RETURN_MASK_ALL
)
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 GDB_PY_HANDLE_EXCEPTION (except
);
269 return val
== NULL
? NULL
: value_to_value_object (val
);
272 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
273 Returns the frame's code block. */
276 frapy_block (PyObject
*self
, PyObject
*args
)
278 struct frame_info
*frame
;
279 const struct block
*block
= NULL
, *fn_block
;
280 volatile struct gdb_exception except
;
282 TRY_CATCH (except
, RETURN_MASK_ALL
)
284 FRAPY_REQUIRE_VALID (self
, frame
);
285 block
= get_frame_block (frame
, NULL
);
287 GDB_PY_HANDLE_EXCEPTION (except
);
289 for (fn_block
= block
;
290 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
291 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
294 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
296 PyErr_SetString (PyExc_RuntimeError
,
297 _("Cannot locate block for frame."));
305 symt
= SYMBOL_SYMTAB (BLOCK_FUNCTION (fn_block
));
306 return block_to_block_object (block
, symt
->objfile
);
313 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
314 Returns the symbol for the function corresponding to this frame. */
317 frapy_function (PyObject
*self
, PyObject
*args
)
319 struct symbol
*sym
= NULL
;
320 struct frame_info
*frame
;
321 volatile struct gdb_exception except
;
323 TRY_CATCH (except
, RETURN_MASK_ALL
)
325 FRAPY_REQUIRE_VALID (self
, frame
);
327 sym
= find_pc_function (get_frame_address_in_block (frame
));
329 GDB_PY_HANDLE_EXCEPTION (except
);
332 return symbol_to_symbol_object (sym
);
337 /* Convert a frame_info struct to a Python Frame object.
338 Sets a Python exception and returns NULL on error. */
341 frame_info_to_frame_object (struct frame_info
*frame
)
343 frame_object
*frame_obj
;
344 volatile struct gdb_exception except
;
346 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
347 if (frame_obj
== NULL
)
350 TRY_CATCH (except
, RETURN_MASK_ALL
)
353 /* Try to get the previous frame, to determine if this is the last frame
354 in a corrupt stack. If so, we need to store the frame_id of the next
355 frame and not of this one (which is possibly invalid). */
356 if (get_prev_frame (frame
) == NULL
357 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
358 && get_next_frame (frame
) != NULL
)
360 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
361 frame_obj
->frame_id_is_next
= 1;
365 frame_obj
->frame_id
= get_frame_id (frame
);
366 frame_obj
->frame_id_is_next
= 0;
368 frame_obj
->gdbarch
= get_frame_arch (frame
);
370 if (except
.reason
< 0)
372 Py_DECREF (frame_obj
);
373 gdbpy_convert_exception (except
);
376 return (PyObject
*) frame_obj
;
379 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
380 Returns the frame immediately older (outer) to this frame, or None if
384 frapy_older (PyObject
*self
, PyObject
*args
)
386 struct frame_info
*frame
, *prev
= NULL
;
387 volatile struct gdb_exception except
;
388 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
390 TRY_CATCH (except
, RETURN_MASK_ALL
)
392 FRAPY_REQUIRE_VALID (self
, frame
);
394 prev
= get_prev_frame (frame
);
396 GDB_PY_HANDLE_EXCEPTION (except
);
399 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
409 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
410 Returns the frame immediately newer (inner) to this frame, or None if
414 frapy_newer (PyObject
*self
, PyObject
*args
)
416 struct frame_info
*frame
, *next
= NULL
;
417 volatile struct gdb_exception except
;
418 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
420 TRY_CATCH (except
, RETURN_MASK_ALL
)
422 FRAPY_REQUIRE_VALID (self
, frame
);
424 next
= get_next_frame (frame
);
426 GDB_PY_HANDLE_EXCEPTION (except
);
429 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
439 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
440 Returns the frame's symtab and line. */
443 frapy_find_sal (PyObject
*self
, PyObject
*args
)
445 struct frame_info
*frame
;
446 struct symtab_and_line sal
;
447 volatile struct gdb_exception except
;
448 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
450 TRY_CATCH (except
, RETURN_MASK_ALL
)
452 FRAPY_REQUIRE_VALID (self
, frame
);
454 find_frame_sal (frame
, &sal
);
455 sal_obj
= symtab_and_line_to_sal_object (sal
);
457 GDB_PY_HANDLE_EXCEPTION (except
);
462 /* Implementation of gdb.Frame.read_var_value (self, variable,
463 [block]) -> gdb.Value. If the optional block argument is provided
464 start the search from that block, otherwise search from the frame's
465 current block (determined by examining the resume address of the
466 frame). The variable argument must be a string or an instance of a
467 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
468 NULL on error, with a python exception set. */
470 frapy_read_var (PyObject
*self
, PyObject
*args
)
472 struct frame_info
*frame
;
473 PyObject
*sym_obj
, *block_obj
= NULL
;
474 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
475 struct value
*val
= NULL
;
476 volatile struct gdb_exception except
;
478 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
481 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
482 var
= symbol_object_to_symbol (sym_obj
);
483 else if (gdbpy_is_string (sym_obj
))
486 const struct block
*block
= NULL
;
487 struct cleanup
*cleanup
;
488 volatile struct gdb_exception except
;
490 var_name
= python_string_to_target_string (sym_obj
);
493 cleanup
= make_cleanup (xfree
, var_name
);
497 block
= block_object_to_block (block_obj
);
500 PyErr_SetString (PyExc_RuntimeError
,
501 _("Second argument must be block."));
502 do_cleanups (cleanup
);
507 TRY_CATCH (except
, RETURN_MASK_ALL
)
509 FRAPY_REQUIRE_VALID (self
, frame
);
512 block
= get_frame_block (frame
, NULL
);
513 var
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
515 if (except
.reason
< 0)
517 do_cleanups (cleanup
);
518 gdbpy_convert_exception (except
);
524 PyErr_Format (PyExc_ValueError
,
525 _("Variable '%s' not found."), var_name
);
526 do_cleanups (cleanup
);
531 do_cleanups (cleanup
);
535 PyErr_SetString (PyExc_TypeError
,
536 _("Argument must be a symbol or string."));
540 TRY_CATCH (except
, RETURN_MASK_ALL
)
542 FRAPY_REQUIRE_VALID (self
, frame
);
544 val
= read_var_value (var
, frame
);
546 GDB_PY_HANDLE_EXCEPTION (except
);
548 return value_to_value_object (val
);
551 /* Select this frame. */
554 frapy_select (PyObject
*self
, PyObject
*args
)
556 struct frame_info
*fi
;
557 volatile struct gdb_exception except
;
559 TRY_CATCH (except
, RETURN_MASK_ALL
)
561 FRAPY_REQUIRE_VALID (self
, fi
);
565 GDB_PY_HANDLE_EXCEPTION (except
);
570 /* Implementation of gdb.newest_frame () -> gdb.Frame.
571 Returns the newest frame object. */
574 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
576 struct frame_info
*frame
= NULL
;
577 volatile struct gdb_exception except
;
579 TRY_CATCH (except
, RETURN_MASK_ALL
)
581 frame
= get_current_frame ();
583 GDB_PY_HANDLE_EXCEPTION (except
);
585 return frame_info_to_frame_object (frame
);
588 /* Implementation of gdb.selected_frame () -> gdb.Frame.
589 Returns the selected frame object. */
592 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
594 struct frame_info
*frame
= NULL
;
595 volatile struct gdb_exception except
;
597 TRY_CATCH (except
, RETURN_MASK_ALL
)
599 frame
= get_selected_frame ("No frame is currently selected.");
601 GDB_PY_HANDLE_EXCEPTION (except
);
603 return frame_info_to_frame_object (frame
);
606 /* Implementation of gdb.stop_reason_string (Integer) -> String.
607 Return a string explaining the unwind stop reason. */
610 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
615 if (!PyArg_ParseTuple (args
, "i", &reason
))
618 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
620 PyErr_SetString (PyExc_ValueError
,
621 _("Invalid frame stop reason."));
625 str
= unwind_stop_reason_to_string (reason
);
626 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
629 /* Implements the equality comparison for Frame objects.
630 All other comparison operators will throw a TypeError Python exception,
631 as they aren't valid for frames. */
634 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
638 if (!PyObject_TypeCheck (other
, &frame_object_type
)
639 || (op
!= Py_EQ
&& op
!= Py_NE
))
641 Py_INCREF (Py_NotImplemented
);
642 return Py_NotImplemented
;
645 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
646 ((frame_object
*) other
)->frame_id
))
656 /* Sets up the Frame API in the gdb module. */
659 gdbpy_initialize_frames (void)
661 frame_object_type
.tp_new
= PyType_GenericNew
;
662 if (PyType_Ready (&frame_object_type
) < 0)
665 /* Note: These would probably be best exposed as class attributes of
666 Frame, but I don't know how to do it except by messing with the
667 type's dictionary. That seems too messy. */
668 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
669 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
670 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
671 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
673 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
675 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
676 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
680 #define SET(name, description) \
681 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
683 #include "unwind_stop_reasons.def"
686 return gdb_pymodule_addobject (gdb_module
, "Frame",
687 (PyObject
*) &frame_object_type
);
692 static PyMethodDef frame_object_methods
[] = {
693 { "is_valid", frapy_is_valid
, METH_NOARGS
,
694 "is_valid () -> Boolean.\n\
695 Return true if this frame is valid, false if not." },
696 { "name", frapy_name
, METH_NOARGS
,
697 "name () -> String.\n\
698 Return the function name of the frame, or None if it can't be determined." },
699 { "type", frapy_type
, METH_NOARGS
,
700 "type () -> Integer.\n\
701 Return the type of the frame." },
702 { "architecture", frapy_arch
, METH_NOARGS
,
703 "architecture () -> gdb.Architecture.\n\
704 Return the architecture of the frame." },
705 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
706 "unwind_stop_reason () -> Integer.\n\
707 Return the reason why it's not possible to find frames older than this." },
708 { "pc", frapy_pc
, METH_NOARGS
,
710 Return the frame's resume address." },
711 { "read_register", frapy_read_register
, METH_VARARGS
,
712 "read_register (register_name) -> gdb.Value\n\
713 Return the value of the register in the frame." },
714 { "block", frapy_block
, METH_NOARGS
,
715 "block () -> gdb.Block.\n\
716 Return the frame's code block." },
717 { "function", frapy_function
, METH_NOARGS
,
718 "function () -> gdb.Symbol.\n\
719 Returns the symbol for the function corresponding to this frame." },
720 { "older", frapy_older
, METH_NOARGS
,
721 "older () -> gdb.Frame.\n\
722 Return the frame that called this frame." },
723 { "newer", frapy_newer
, METH_NOARGS
,
724 "newer () -> gdb.Frame.\n\
725 Return the frame called by this frame." },
726 { "find_sal", frapy_find_sal
, METH_NOARGS
,
727 "find_sal () -> gdb.Symtab_and_line.\n\
728 Return the frame's symtab and line." },
729 { "read_var", frapy_read_var
, METH_VARARGS
,
730 "read_var (variable) -> gdb.Value.\n\
731 Return the value of the variable in this frame." },
732 { "select", frapy_select
, METH_NOARGS
,
733 "Select this frame as the user's current frame." },
734 {NULL
} /* Sentinel */
737 PyTypeObject frame_object_type
= {
738 PyVarObject_HEAD_INIT (NULL
, 0)
739 "gdb.Frame", /* tp_name */
740 sizeof (frame_object
), /* tp_basicsize */
748 0, /* tp_as_number */
749 0, /* tp_as_sequence */
750 0, /* tp_as_mapping */
753 frapy_str
, /* tp_str */
756 0, /* tp_as_buffer */
757 Py_TPFLAGS_DEFAULT
, /* tp_flags */
758 "GDB frame object", /* tp_doc */
761 frapy_richcompare
, /* tp_richcompare */
762 0, /* tp_weaklistoffset */
765 frame_object_methods
, /* tp_methods */
770 0, /* tp_descr_get */
771 0, /* tp_descr_set */
772 0, /* tp_dictoffset */