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"
35 struct frame_id frame_id
;
36 struct gdbarch
*gdbarch
;
38 /* Marks that the FRAME_ID member actually holds the ID of the frame next
39 to this, and not this frames' ID itself. This is a hack to permit Python
40 frame objects which represent invalid frames (i.e., the last frame_info
41 in a corrupt stack). The problem arises from the fact that this code
42 relies on FRAME_ID to uniquely identify a frame, which is not always true
43 for the last "frame" in a corrupt stack (it can have a null ID, or the same
44 ID as the previous frame). Whenever get_prev_frame returns NULL, we
45 record the frame_id of the next frame and set FRAME_ID_IS_NEXT to 1. */
49 /* Require a valid frame. This must be called inside a TRY_CATCH, or
50 another context in which a gdb exception is allowed. */
51 #define FRAPY_REQUIRE_VALID(frame_obj, frame) \
53 frame = frame_object_to_frame_info (frame_obj); \
55 error (_("Frame is invalid.")); \
58 /* Returns the frame_info object corresponding to the given Python Frame
59 object. If the frame doesn't exist anymore (the frame id doesn't
60 correspond to any frame in the inferior), returns NULL. */
63 frame_object_to_frame_info (PyObject
*obj
)
65 frame_object
*frame_obj
= (frame_object
*) obj
;
66 struct frame_info
*frame
;
68 frame
= frame_find_by_id (frame_obj
->frame_id
);
72 if (frame_obj
->frame_id_is_next
)
73 frame
= get_prev_frame (frame
);
78 /* Called by the Python interpreter to obtain string representation
82 frapy_str (PyObject
*self
)
86 fprint_frame_id (&strfile
, ((frame_object
*) self
)->frame_id
);
87 return PyString_FromString (strfile
.c_str ());
90 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
91 Returns True if the frame corresponding to the frame_id of this
92 object still exists in the inferior. */
95 frapy_is_valid (PyObject
*self
, PyObject
*args
)
97 struct frame_info
*frame
= NULL
;
101 frame
= frame_object_to_frame_info (self
);
103 CATCH (except
, RETURN_MASK_ALL
)
105 GDB_PY_HANDLE_EXCEPTION (except
);
115 /* Implementation of gdb.Frame.name (self) -> String.
116 Returns the name of the function corresponding to this frame. */
119 frapy_name (PyObject
*self
, PyObject
*args
)
121 struct frame_info
*frame
;
128 FRAPY_REQUIRE_VALID (self
, frame
);
130 find_frame_funname (frame
, &name
, &lang
, NULL
);
132 CATCH (except
, RETURN_MASK_ALL
)
135 GDB_PY_HANDLE_EXCEPTION (except
);
141 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
153 /* Implementation of gdb.Frame.type (self) -> Integer.
154 Returns the frame type, namely one of the gdb.*_FRAME constants. */
157 frapy_type (PyObject
*self
, PyObject
*args
)
159 struct frame_info
*frame
;
160 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
164 FRAPY_REQUIRE_VALID (self
, frame
);
166 type
= get_frame_type (frame
);
168 CATCH (except
, RETURN_MASK_ALL
)
170 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
;
188 FRAPY_REQUIRE_VALID (self
, frame
);
190 CATCH (except
, RETURN_MASK_ALL
)
192 GDB_PY_HANDLE_EXCEPTION (except
);
196 return gdbarch_to_arch_object (obj
->gdbarch
);
199 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
200 Returns one of the gdb.FRAME_UNWIND_* constants. */
203 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
205 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
206 enum unwind_stop_reason stop_reason
;
210 FRAPY_REQUIRE_VALID (self
, frame
);
212 CATCH (except
, RETURN_MASK_ALL
)
214 GDB_PY_HANDLE_EXCEPTION (except
);
218 stop_reason
= get_frame_unwind_stop_reason (frame
);
220 return PyInt_FromLong (stop_reason
);
223 /* Implementation of gdb.Frame.pc (self) -> Long.
224 Returns the frame's resume address. */
227 frapy_pc (PyObject
*self
, PyObject
*args
)
229 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
230 struct frame_info
*frame
;
234 FRAPY_REQUIRE_VALID (self
, frame
);
236 pc
= get_frame_pc (frame
);
238 CATCH (except
, RETURN_MASK_ALL
)
240 GDB_PY_HANDLE_EXCEPTION (except
);
244 return gdb_py_long_from_ulongest (pc
);
247 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
248 Returns the value of a register in this frame. */
251 frapy_read_register (PyObject
*self
, PyObject
*args
)
253 const char *regnum_str
;
254 struct value
*val
= NULL
;
256 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
261 struct frame_info
*frame
;
264 FRAPY_REQUIRE_VALID (self
, frame
);
266 regnum
= user_reg_map_name_to_regnum (get_frame_arch (frame
),
268 strlen (regnum_str
));
270 val
= value_of_register (regnum
, frame
);
273 PyErr_SetString (PyExc_ValueError
, _("Unknown register."));
275 CATCH (except
, RETURN_MASK_ALL
)
277 GDB_PY_HANDLE_EXCEPTION (except
);
281 return val
== NULL
? NULL
: value_to_value_object (val
);
284 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
285 Returns the frame's code block. */
288 frapy_block (PyObject
*self
, PyObject
*args
)
290 struct frame_info
*frame
;
291 const struct block
*block
= NULL
, *fn_block
;
295 FRAPY_REQUIRE_VALID (self
, frame
);
296 block
= get_frame_block (frame
, NULL
);
298 CATCH (except
, RETURN_MASK_ALL
)
300 GDB_PY_HANDLE_EXCEPTION (except
);
304 for (fn_block
= block
;
305 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
306 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
309 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
311 PyErr_SetString (PyExc_RuntimeError
,
312 _("Cannot locate block for frame."));
318 return block_to_block_object
319 (block
, symbol_objfile (BLOCK_FUNCTION (fn_block
)));
326 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
327 Returns the symbol for the function corresponding to this frame. */
330 frapy_function (PyObject
*self
, PyObject
*args
)
332 struct symbol
*sym
= NULL
;
333 struct frame_info
*frame
;
338 enum language funlang
;
340 FRAPY_REQUIRE_VALID (self
, frame
);
342 find_frame_funname (frame
, &funname
, &funlang
, &sym
);
345 CATCH (except
, RETURN_MASK_ALL
)
347 GDB_PY_HANDLE_EXCEPTION (except
);
352 return symbol_to_symbol_object (sym
);
357 /* Convert a frame_info struct to a Python Frame object.
358 Sets a Python exception and returns NULL on error. */
361 frame_info_to_frame_object (struct frame_info
*frame
)
363 gdbpy_ref
<frame_object
> frame_obj (PyObject_New (frame_object
,
364 &frame_object_type
));
365 if (frame_obj
== NULL
)
371 /* Try to get the previous frame, to determine if this is the last frame
372 in a corrupt stack. If so, we need to store the frame_id of the next
373 frame and not of this one (which is possibly invalid). */
374 if (get_prev_frame (frame
) == NULL
375 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
376 && get_next_frame (frame
) != NULL
)
378 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
379 frame_obj
->frame_id_is_next
= 1;
383 frame_obj
->frame_id
= get_frame_id (frame
);
384 frame_obj
->frame_id_is_next
= 0;
386 frame_obj
->gdbarch
= get_frame_arch (frame
);
388 CATCH (except
, RETURN_MASK_ALL
)
390 gdbpy_convert_exception (except
);
395 return (PyObject
*) frame_obj
.release ();
398 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
399 Returns the frame immediately older (outer) to this frame, or None if
403 frapy_older (PyObject
*self
, PyObject
*args
)
405 struct frame_info
*frame
, *prev
= NULL
;
406 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
410 FRAPY_REQUIRE_VALID (self
, frame
);
412 prev
= get_prev_frame (frame
);
414 CATCH (except
, RETURN_MASK_ALL
)
416 GDB_PY_HANDLE_EXCEPTION (except
);
421 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
431 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
432 Returns the frame immediately newer (inner) to this frame, or None if
436 frapy_newer (PyObject
*self
, PyObject
*args
)
438 struct frame_info
*frame
, *next
= NULL
;
439 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
443 FRAPY_REQUIRE_VALID (self
, frame
);
445 next
= get_next_frame (frame
);
447 CATCH (except
, RETURN_MASK_ALL
)
449 GDB_PY_HANDLE_EXCEPTION (except
);
454 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
464 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
465 Returns the frame's symtab and line. */
468 frapy_find_sal (PyObject
*self
, PyObject
*args
)
470 struct frame_info
*frame
;
471 struct symtab_and_line sal
;
472 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
476 FRAPY_REQUIRE_VALID (self
, frame
);
478 find_frame_sal (frame
, &sal
);
479 sal_obj
= symtab_and_line_to_sal_object (sal
);
481 CATCH (except
, RETURN_MASK_ALL
)
483 GDB_PY_HANDLE_EXCEPTION (except
);
490 /* Implementation of gdb.Frame.read_var_value (self, variable,
491 [block]) -> gdb.Value. If the optional block argument is provided
492 start the search from that block, otherwise search from the frame's
493 current block (determined by examining the resume address of the
494 frame). The variable argument must be a string or an instance of a
495 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
496 NULL on error, with a python exception set. */
498 frapy_read_var (PyObject
*self
, PyObject
*args
)
500 struct frame_info
*frame
;
501 PyObject
*sym_obj
, *block_obj
= NULL
;
502 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
503 const struct block
*block
= NULL
;
504 struct value
*val
= NULL
;
506 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
509 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
510 var
= symbol_object_to_symbol (sym_obj
);
511 else if (gdbpy_is_string (sym_obj
))
513 gdb::unique_xmalloc_ptr
<char>
514 var_name (python_string_to_target_string (sym_obj
));
521 block
= block_object_to_block (block_obj
);
524 PyErr_SetString (PyExc_RuntimeError
,
525 _("Second argument must be block."));
532 struct block_symbol lookup_sym
;
533 FRAPY_REQUIRE_VALID (self
, frame
);
536 block
= get_frame_block (frame
, NULL
);
537 lookup_sym
= lookup_symbol (var_name
.get (), block
, VAR_DOMAIN
, NULL
);
538 var
= lookup_sym
.symbol
;
539 block
= lookup_sym
.block
;
541 CATCH (except
, RETURN_MASK_ALL
)
543 gdbpy_convert_exception (except
);
550 PyErr_Format (PyExc_ValueError
,
551 _("Variable '%s' not found."), var_name
.get ());
558 PyErr_SetString (PyExc_TypeError
,
559 _("Argument must be a symbol or string."));
565 FRAPY_REQUIRE_VALID (self
, frame
);
567 val
= read_var_value (var
, block
, frame
);
569 CATCH (except
, RETURN_MASK_ALL
)
571 GDB_PY_HANDLE_EXCEPTION (except
);
575 return value_to_value_object (val
);
578 /* Select this frame. */
581 frapy_select (PyObject
*self
, PyObject
*args
)
583 struct frame_info
*fi
;
587 FRAPY_REQUIRE_VALID (self
, fi
);
591 CATCH (except
, RETURN_MASK_ALL
)
593 GDB_PY_HANDLE_EXCEPTION (except
);
600 /* Implementation of gdb.newest_frame () -> gdb.Frame.
601 Returns the newest frame object. */
604 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
606 struct frame_info
*frame
= NULL
;
610 frame
= get_current_frame ();
612 CATCH (except
, RETURN_MASK_ALL
)
614 GDB_PY_HANDLE_EXCEPTION (except
);
618 return frame_info_to_frame_object (frame
);
621 /* Implementation of gdb.selected_frame () -> gdb.Frame.
622 Returns the selected frame object. */
625 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
627 struct frame_info
*frame
= NULL
;
631 frame
= get_selected_frame ("No frame is currently selected.");
633 CATCH (except
, RETURN_MASK_ALL
)
635 GDB_PY_HANDLE_EXCEPTION (except
);
639 return frame_info_to_frame_object (frame
);
642 /* Implementation of gdb.stop_reason_string (Integer) -> String.
643 Return a string explaining the unwind stop reason. */
646 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
651 if (!PyArg_ParseTuple (args
, "i", &reason
))
654 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
656 PyErr_SetString (PyExc_ValueError
,
657 _("Invalid frame stop reason."));
661 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
662 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
665 /* Implements the equality comparison for Frame objects.
666 All other comparison operators will throw a TypeError Python exception,
667 as they aren't valid for frames. */
670 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
674 if (!PyObject_TypeCheck (other
, &frame_object_type
)
675 || (op
!= Py_EQ
&& op
!= Py_NE
))
677 Py_INCREF (Py_NotImplemented
);
678 return Py_NotImplemented
;
681 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
682 ((frame_object
*) other
)->frame_id
))
692 /* Sets up the Frame API in the gdb module. */
695 gdbpy_initialize_frames (void)
697 frame_object_type
.tp_new
= PyType_GenericNew
;
698 if (PyType_Ready (&frame_object_type
) < 0)
701 /* Note: These would probably be best exposed as class attributes of
702 Frame, but I don't know how to do it except by messing with the
703 type's dictionary. That seems too messy. */
704 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
705 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
706 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
707 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
709 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
711 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
712 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
716 #define SET(name, description) \
717 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
719 #include "unwind_stop_reasons.def"
722 return gdb_pymodule_addobject (gdb_module
, "Frame",
723 (PyObject
*) &frame_object_type
);
728 static PyMethodDef frame_object_methods
[] = {
729 { "is_valid", frapy_is_valid
, METH_NOARGS
,
730 "is_valid () -> Boolean.\n\
731 Return true if this frame is valid, false if not." },
732 { "name", frapy_name
, METH_NOARGS
,
733 "name () -> String.\n\
734 Return the function name of the frame, or None if it can't be determined." },
735 { "type", frapy_type
, METH_NOARGS
,
736 "type () -> Integer.\n\
737 Return the type of the frame." },
738 { "architecture", frapy_arch
, METH_NOARGS
,
739 "architecture () -> gdb.Architecture.\n\
740 Return the architecture of the frame." },
741 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
742 "unwind_stop_reason () -> Integer.\n\
743 Return the reason why it's not possible to find frames older than this." },
744 { "pc", frapy_pc
, METH_NOARGS
,
746 Return the frame's resume address." },
747 { "read_register", frapy_read_register
, METH_VARARGS
,
748 "read_register (register_name) -> gdb.Value\n\
749 Return the value of the register in the frame." },
750 { "block", frapy_block
, METH_NOARGS
,
751 "block () -> gdb.Block.\n\
752 Return the frame's code block." },
753 { "function", frapy_function
, METH_NOARGS
,
754 "function () -> gdb.Symbol.\n\
755 Returns the symbol for the function corresponding to this frame." },
756 { "older", frapy_older
, METH_NOARGS
,
757 "older () -> gdb.Frame.\n\
758 Return the frame that called this frame." },
759 { "newer", frapy_newer
, METH_NOARGS
,
760 "newer () -> gdb.Frame.\n\
761 Return the frame called by this frame." },
762 { "find_sal", frapy_find_sal
, METH_NOARGS
,
763 "find_sal () -> gdb.Symtab_and_line.\n\
764 Return the frame's symtab and line." },
765 { "read_var", frapy_read_var
, METH_VARARGS
,
766 "read_var (variable) -> gdb.Value.\n\
767 Return the value of the variable in this frame." },
768 { "select", frapy_select
, METH_NOARGS
,
769 "Select this frame as the user's current frame." },
770 {NULL
} /* Sentinel */
773 PyTypeObject frame_object_type
= {
774 PyVarObject_HEAD_INIT (NULL
, 0)
775 "gdb.Frame", /* tp_name */
776 sizeof (frame_object
), /* tp_basicsize */
784 0, /* tp_as_number */
785 0, /* tp_as_sequence */
786 0, /* tp_as_mapping */
789 frapy_str
, /* tp_str */
792 0, /* tp_as_buffer */
793 Py_TPFLAGS_DEFAULT
, /* tp_flags */
794 "GDB frame object", /* tp_doc */
797 frapy_richcompare
, /* tp_richcompare */
798 0, /* tp_weaklistoffset */
801 frame_object_methods
, /* tp_methods */
806 0, /* tp_descr_get */
807 0, /* tp_descr_set */
808 0, /* tp_dictoffset */