1 /* Python interface to stack frames
3 Copyright (C) 2008-2017 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
))
517 gdb::unique_xmalloc_ptr
<char>
518 var_name (python_string_to_target_string (sym_obj
));
525 block
= block_object_to_block (block_obj
);
528 PyErr_SetString (PyExc_RuntimeError
,
529 _("Second argument must be block."));
536 struct block_symbol lookup_sym
;
537 FRAPY_REQUIRE_VALID (self
, frame
);
540 block
= get_frame_block (frame
, NULL
);
541 lookup_sym
= lookup_symbol (var_name
.get (), block
, VAR_DOMAIN
, NULL
);
542 var
= lookup_sym
.symbol
;
543 block
= lookup_sym
.block
;
545 CATCH (except
, RETURN_MASK_ALL
)
547 gdbpy_convert_exception (except
);
554 PyErr_Format (PyExc_ValueError
,
555 _("Variable '%s' not found."), var_name
.get ());
562 PyErr_SetString (PyExc_TypeError
,
563 _("Argument must be a symbol or string."));
569 FRAPY_REQUIRE_VALID (self
, frame
);
571 val
= read_var_value (var
, block
, frame
);
573 CATCH (except
, RETURN_MASK_ALL
)
575 GDB_PY_HANDLE_EXCEPTION (except
);
579 return value_to_value_object (val
);
582 /* Select this frame. */
585 frapy_select (PyObject
*self
, PyObject
*args
)
587 struct frame_info
*fi
;
591 FRAPY_REQUIRE_VALID (self
, fi
);
595 CATCH (except
, RETURN_MASK_ALL
)
597 GDB_PY_HANDLE_EXCEPTION (except
);
604 /* Implementation of gdb.newest_frame () -> gdb.Frame.
605 Returns the newest frame object. */
608 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
610 struct frame_info
*frame
= NULL
;
614 frame
= get_current_frame ();
616 CATCH (except
, RETURN_MASK_ALL
)
618 GDB_PY_HANDLE_EXCEPTION (except
);
622 return frame_info_to_frame_object (frame
);
625 /* Implementation of gdb.selected_frame () -> gdb.Frame.
626 Returns the selected frame object. */
629 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
631 struct frame_info
*frame
= NULL
;
635 frame
= get_selected_frame ("No frame is currently selected.");
637 CATCH (except
, RETURN_MASK_ALL
)
639 GDB_PY_HANDLE_EXCEPTION (except
);
643 return frame_info_to_frame_object (frame
);
646 /* Implementation of gdb.stop_reason_string (Integer) -> String.
647 Return a string explaining the unwind stop reason. */
650 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
655 if (!PyArg_ParseTuple (args
, "i", &reason
))
658 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
660 PyErr_SetString (PyExc_ValueError
,
661 _("Invalid frame stop reason."));
665 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
666 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
669 /* Implements the equality comparison for Frame objects.
670 All other comparison operators will throw a TypeError Python exception,
671 as they aren't valid for frames. */
674 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
678 if (!PyObject_TypeCheck (other
, &frame_object_type
)
679 || (op
!= Py_EQ
&& op
!= Py_NE
))
681 Py_INCREF (Py_NotImplemented
);
682 return Py_NotImplemented
;
685 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
686 ((frame_object
*) other
)->frame_id
))
696 /* Sets up the Frame API in the gdb module. */
699 gdbpy_initialize_frames (void)
701 frame_object_type
.tp_new
= PyType_GenericNew
;
702 if (PyType_Ready (&frame_object_type
) < 0)
705 /* Note: These would probably be best exposed as class attributes of
706 Frame, but I don't know how to do it except by messing with the
707 type's dictionary. That seems too messy. */
708 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
709 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
710 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
711 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
713 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
715 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
716 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
720 #define SET(name, description) \
721 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
723 #include "unwind_stop_reasons.def"
726 return gdb_pymodule_addobject (gdb_module
, "Frame",
727 (PyObject
*) &frame_object_type
);
732 static PyMethodDef frame_object_methods
[] = {
733 { "is_valid", frapy_is_valid
, METH_NOARGS
,
734 "is_valid () -> Boolean.\n\
735 Return true if this frame is valid, false if not." },
736 { "name", frapy_name
, METH_NOARGS
,
737 "name () -> String.\n\
738 Return the function name of the frame, or None if it can't be determined." },
739 { "type", frapy_type
, METH_NOARGS
,
740 "type () -> Integer.\n\
741 Return the type of the frame." },
742 { "architecture", frapy_arch
, METH_NOARGS
,
743 "architecture () -> gdb.Architecture.\n\
744 Return the architecture of the frame." },
745 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
746 "unwind_stop_reason () -> Integer.\n\
747 Return the reason why it's not possible to find frames older than this." },
748 { "pc", frapy_pc
, METH_NOARGS
,
750 Return the frame's resume address." },
751 { "read_register", frapy_read_register
, METH_VARARGS
,
752 "read_register (register_name) -> gdb.Value\n\
753 Return the value of the register in the frame." },
754 { "block", frapy_block
, METH_NOARGS
,
755 "block () -> gdb.Block.\n\
756 Return the frame's code block." },
757 { "function", frapy_function
, METH_NOARGS
,
758 "function () -> gdb.Symbol.\n\
759 Returns the symbol for the function corresponding to this frame." },
760 { "older", frapy_older
, METH_NOARGS
,
761 "older () -> gdb.Frame.\n\
762 Return the frame that called this frame." },
763 { "newer", frapy_newer
, METH_NOARGS
,
764 "newer () -> gdb.Frame.\n\
765 Return the frame called by this frame." },
766 { "find_sal", frapy_find_sal
, METH_NOARGS
,
767 "find_sal () -> gdb.Symtab_and_line.\n\
768 Return the frame's symtab and line." },
769 { "read_var", frapy_read_var
, METH_VARARGS
,
770 "read_var (variable) -> gdb.Value.\n\
771 Return the value of the variable in this frame." },
772 { "select", frapy_select
, METH_NOARGS
,
773 "Select this frame as the user's current frame." },
774 {NULL
} /* Sentinel */
777 PyTypeObject frame_object_type
= {
778 PyVarObject_HEAD_INIT (NULL
, 0)
779 "gdb.Frame", /* tp_name */
780 sizeof (frame_object
), /* tp_basicsize */
788 0, /* tp_as_number */
789 0, /* tp_as_sequence */
790 0, /* tp_as_mapping */
793 frapy_str
, /* tp_str */
796 0, /* tp_as_buffer */
797 Py_TPFLAGS_DEFAULT
, /* tp_flags */
798 "GDB frame object", /* tp_doc */
801 frapy_richcompare
, /* tp_richcompare */
802 0, /* tp_weaklistoffset */
805 frame_object_methods
, /* tp_methods */
810 0, /* tp_descr_get */
811 0, /* tp_descr_set */
812 0, /* tp_dictoffset */