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
)
85 fprint_frame_id (&strfile
, ((frame_object
*) self
)->frame_id
);
86 return PyString_FromString (strfile
.c_str ());
89 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
90 Returns True if the frame corresponding to the frame_id of this
91 object still exists in the inferior. */
94 frapy_is_valid (PyObject
*self
, PyObject
*args
)
96 struct frame_info
*frame
= NULL
;
100 frame
= frame_object_to_frame_info (self
);
102 CATCH (except
, RETURN_MASK_ALL
)
104 GDB_PY_HANDLE_EXCEPTION (except
);
114 /* Implementation of gdb.Frame.name (self) -> String.
115 Returns the name of the function corresponding to this frame. */
118 frapy_name (PyObject
*self
, PyObject
*args
)
120 struct frame_info
*frame
;
127 FRAPY_REQUIRE_VALID (self
, frame
);
129 find_frame_funname (frame
, &name
, &lang
, NULL
);
131 CATCH (except
, RETURN_MASK_ALL
)
134 GDB_PY_HANDLE_EXCEPTION (except
);
140 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
152 /* Implementation of gdb.Frame.type (self) -> Integer.
153 Returns the frame type, namely one of the gdb.*_FRAME constants. */
156 frapy_type (PyObject
*self
, PyObject
*args
)
158 struct frame_info
*frame
;
159 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
163 FRAPY_REQUIRE_VALID (self
, frame
);
165 type
= get_frame_type (frame
);
167 CATCH (except
, RETURN_MASK_ALL
)
169 GDB_PY_HANDLE_EXCEPTION (except
);
173 return PyInt_FromLong (type
);
176 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
177 Returns the frame's architecture as a gdb.Architecture object. */
180 frapy_arch (PyObject
*self
, PyObject
*args
)
182 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
183 frame_object
*obj
= (frame_object
*) self
;
187 FRAPY_REQUIRE_VALID (self
, frame
);
189 CATCH (except
, RETURN_MASK_ALL
)
191 GDB_PY_HANDLE_EXCEPTION (except
);
195 return gdbarch_to_arch_object (obj
->gdbarch
);
198 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
199 Returns one of the gdb.FRAME_UNWIND_* constants. */
202 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
204 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
205 enum unwind_stop_reason stop_reason
;
209 FRAPY_REQUIRE_VALID (self
, frame
);
211 CATCH (except
, RETURN_MASK_ALL
)
213 GDB_PY_HANDLE_EXCEPTION (except
);
217 stop_reason
= get_frame_unwind_stop_reason (frame
);
219 return PyInt_FromLong (stop_reason
);
222 /* Implementation of gdb.Frame.pc (self) -> Long.
223 Returns the frame's resume address. */
226 frapy_pc (PyObject
*self
, PyObject
*args
)
228 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
229 struct frame_info
*frame
;
233 FRAPY_REQUIRE_VALID (self
, frame
);
235 pc
= get_frame_pc (frame
);
237 CATCH (except
, RETURN_MASK_ALL
)
239 GDB_PY_HANDLE_EXCEPTION (except
);
243 return gdb_py_long_from_ulongest (pc
);
246 /* Implementation of gdb.Frame.read_register (self, register) -> gdb.Value.
247 Returns the value of a register in this frame. */
250 frapy_read_register (PyObject
*self
, PyObject
*args
)
252 const char *regnum_str
;
253 struct value
*val
= NULL
;
255 if (!PyArg_ParseTuple (args
, "s", ®num_str
))
260 struct frame_info
*frame
;
263 FRAPY_REQUIRE_VALID (self
, frame
);
265 regnum
= user_reg_map_name_to_regnum (get_frame_arch (frame
),
267 strlen (regnum_str
));
269 val
= value_of_register (regnum
, frame
);
272 PyErr_SetString (PyExc_ValueError
, _("Unknown register."));
274 CATCH (except
, RETURN_MASK_ALL
)
276 GDB_PY_HANDLE_EXCEPTION (except
);
280 return val
== NULL
? NULL
: value_to_value_object (val
);
283 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
284 Returns the frame's code block. */
287 frapy_block (PyObject
*self
, PyObject
*args
)
289 struct frame_info
*frame
;
290 const struct block
*block
= NULL
, *fn_block
;
294 FRAPY_REQUIRE_VALID (self
, frame
);
295 block
= get_frame_block (frame
, NULL
);
297 CATCH (except
, RETURN_MASK_ALL
)
299 GDB_PY_HANDLE_EXCEPTION (except
);
303 for (fn_block
= block
;
304 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
305 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
308 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
310 PyErr_SetString (PyExc_RuntimeError
,
311 _("Cannot locate block for frame."));
317 return block_to_block_object
318 (block
, symbol_objfile (BLOCK_FUNCTION (fn_block
)));
325 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
326 Returns the symbol for the function corresponding to this frame. */
329 frapy_function (PyObject
*self
, PyObject
*args
)
331 struct symbol
*sym
= NULL
;
332 struct frame_info
*frame
;
337 enum language funlang
;
339 FRAPY_REQUIRE_VALID (self
, frame
);
341 find_frame_funname (frame
, &funname
, &funlang
, &sym
);
344 CATCH (except
, RETURN_MASK_ALL
)
346 GDB_PY_HANDLE_EXCEPTION (except
);
351 return symbol_to_symbol_object (sym
);
356 /* Convert a frame_info struct to a Python Frame object.
357 Sets a Python exception and returns NULL on error. */
360 frame_info_to_frame_object (struct frame_info
*frame
)
362 frame_object
*frame_obj
;
364 frame_obj
= PyObject_New (frame_object
, &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 Py_DECREF (frame_obj
);
391 gdbpy_convert_exception (except
);
396 return (PyObject
*) frame_obj
;
399 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
400 Returns the frame immediately older (outer) to this frame, or None if
404 frapy_older (PyObject
*self
, PyObject
*args
)
406 struct frame_info
*frame
, *prev
= NULL
;
407 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
411 FRAPY_REQUIRE_VALID (self
, frame
);
413 prev
= get_prev_frame (frame
);
415 CATCH (except
, RETURN_MASK_ALL
)
417 GDB_PY_HANDLE_EXCEPTION (except
);
422 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
432 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
433 Returns the frame immediately newer (inner) to this frame, or None if
437 frapy_newer (PyObject
*self
, PyObject
*args
)
439 struct frame_info
*frame
, *next
= NULL
;
440 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
444 FRAPY_REQUIRE_VALID (self
, frame
);
446 next
= get_next_frame (frame
);
448 CATCH (except
, RETURN_MASK_ALL
)
450 GDB_PY_HANDLE_EXCEPTION (except
);
455 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
465 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
466 Returns the frame's symtab and line. */
469 frapy_find_sal (PyObject
*self
, PyObject
*args
)
471 struct frame_info
*frame
;
472 struct symtab_and_line sal
;
473 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
477 FRAPY_REQUIRE_VALID (self
, frame
);
479 find_frame_sal (frame
, &sal
);
480 sal_obj
= symtab_and_line_to_sal_object (sal
);
482 CATCH (except
, RETURN_MASK_ALL
)
484 GDB_PY_HANDLE_EXCEPTION (except
);
491 /* Implementation of gdb.Frame.read_var_value (self, variable,
492 [block]) -> gdb.Value. If the optional block argument is provided
493 start the search from that block, otherwise search from the frame's
494 current block (determined by examining the resume address of the
495 frame). The variable argument must be a string or an instance of a
496 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
497 NULL on error, with a python exception set. */
499 frapy_read_var (PyObject
*self
, PyObject
*args
)
501 struct frame_info
*frame
;
502 PyObject
*sym_obj
, *block_obj
= NULL
;
503 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
504 const struct block
*block
= NULL
;
505 struct value
*val
= NULL
;
507 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
510 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
511 var
= symbol_object_to_symbol (sym_obj
);
512 else if (gdbpy_is_string (sym_obj
))
514 gdb::unique_xmalloc_ptr
<char>
515 var_name (python_string_to_target_string (sym_obj
));
522 block
= block_object_to_block (block_obj
);
525 PyErr_SetString (PyExc_RuntimeError
,
526 _("Second argument must be block."));
533 struct block_symbol lookup_sym
;
534 FRAPY_REQUIRE_VALID (self
, frame
);
537 block
= get_frame_block (frame
, NULL
);
538 lookup_sym
= lookup_symbol (var_name
.get (), block
, VAR_DOMAIN
, NULL
);
539 var
= lookup_sym
.symbol
;
540 block
= lookup_sym
.block
;
542 CATCH (except
, RETURN_MASK_ALL
)
544 gdbpy_convert_exception (except
);
551 PyErr_Format (PyExc_ValueError
,
552 _("Variable '%s' not found."), var_name
.get ());
559 PyErr_SetString (PyExc_TypeError
,
560 _("Argument must be a symbol or string."));
566 FRAPY_REQUIRE_VALID (self
, frame
);
568 val
= read_var_value (var
, block
, frame
);
570 CATCH (except
, RETURN_MASK_ALL
)
572 GDB_PY_HANDLE_EXCEPTION (except
);
576 return value_to_value_object (val
);
579 /* Select this frame. */
582 frapy_select (PyObject
*self
, PyObject
*args
)
584 struct frame_info
*fi
;
588 FRAPY_REQUIRE_VALID (self
, fi
);
592 CATCH (except
, RETURN_MASK_ALL
)
594 GDB_PY_HANDLE_EXCEPTION (except
);
601 /* Implementation of gdb.newest_frame () -> gdb.Frame.
602 Returns the newest frame object. */
605 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
607 struct frame_info
*frame
= NULL
;
611 frame
= get_current_frame ();
613 CATCH (except
, RETURN_MASK_ALL
)
615 GDB_PY_HANDLE_EXCEPTION (except
);
619 return frame_info_to_frame_object (frame
);
622 /* Implementation of gdb.selected_frame () -> gdb.Frame.
623 Returns the selected frame object. */
626 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
628 struct frame_info
*frame
= NULL
;
632 frame
= get_selected_frame ("No frame is currently selected.");
634 CATCH (except
, RETURN_MASK_ALL
)
636 GDB_PY_HANDLE_EXCEPTION (except
);
640 return frame_info_to_frame_object (frame
);
643 /* Implementation of gdb.stop_reason_string (Integer) -> String.
644 Return a string explaining the unwind stop reason. */
647 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
652 if (!PyArg_ParseTuple (args
, "i", &reason
))
655 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
657 PyErr_SetString (PyExc_ValueError
,
658 _("Invalid frame stop reason."));
662 str
= unwind_stop_reason_to_string ((enum unwind_stop_reason
) reason
);
663 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
666 /* Implements the equality comparison for Frame objects.
667 All other comparison operators will throw a TypeError Python exception,
668 as they aren't valid for frames. */
671 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
675 if (!PyObject_TypeCheck (other
, &frame_object_type
)
676 || (op
!= Py_EQ
&& op
!= Py_NE
))
678 Py_INCREF (Py_NotImplemented
);
679 return Py_NotImplemented
;
682 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
683 ((frame_object
*) other
)->frame_id
))
693 /* Sets up the Frame API in the gdb module. */
696 gdbpy_initialize_frames (void)
698 frame_object_type
.tp_new
= PyType_GenericNew
;
699 if (PyType_Ready (&frame_object_type
) < 0)
702 /* Note: These would probably be best exposed as class attributes of
703 Frame, but I don't know how to do it except by messing with the
704 type's dictionary. That seems too messy. */
705 if (PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
) < 0
706 || PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
) < 0
707 || PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
) < 0
708 || PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME",
710 || PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME",
712 || PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
) < 0
713 || PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME",
717 #define SET(name, description) \
718 if (PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name) < 0) \
720 #include "unwind_stop_reasons.def"
723 return gdb_pymodule_addobject (gdb_module
, "Frame",
724 (PyObject
*) &frame_object_type
);
729 static PyMethodDef frame_object_methods
[] = {
730 { "is_valid", frapy_is_valid
, METH_NOARGS
,
731 "is_valid () -> Boolean.\n\
732 Return true if this frame is valid, false if not." },
733 { "name", frapy_name
, METH_NOARGS
,
734 "name () -> String.\n\
735 Return the function name of the frame, or None if it can't be determined." },
736 { "type", frapy_type
, METH_NOARGS
,
737 "type () -> Integer.\n\
738 Return the type of the frame." },
739 { "architecture", frapy_arch
, METH_NOARGS
,
740 "architecture () -> gdb.Architecture.\n\
741 Return the architecture of the frame." },
742 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
743 "unwind_stop_reason () -> Integer.\n\
744 Return the reason why it's not possible to find frames older than this." },
745 { "pc", frapy_pc
, METH_NOARGS
,
747 Return the frame's resume address." },
748 { "read_register", frapy_read_register
, METH_VARARGS
,
749 "read_register (register_name) -> gdb.Value\n\
750 Return the value of the register in the frame." },
751 { "block", frapy_block
, METH_NOARGS
,
752 "block () -> gdb.Block.\n\
753 Return the frame's code block." },
754 { "function", frapy_function
, METH_NOARGS
,
755 "function () -> gdb.Symbol.\n\
756 Returns the symbol for the function corresponding to this frame." },
757 { "older", frapy_older
, METH_NOARGS
,
758 "older () -> gdb.Frame.\n\
759 Return the frame that called this frame." },
760 { "newer", frapy_newer
, METH_NOARGS
,
761 "newer () -> gdb.Frame.\n\
762 Return the frame called by this frame." },
763 { "find_sal", frapy_find_sal
, METH_NOARGS
,
764 "find_sal () -> gdb.Symtab_and_line.\n\
765 Return the frame's symtab and line." },
766 { "read_var", frapy_read_var
, METH_VARARGS
,
767 "read_var (variable) -> gdb.Value.\n\
768 Return the value of the variable in this frame." },
769 { "select", frapy_select
, METH_NOARGS
,
770 "Select this frame as the user's current frame." },
771 {NULL
} /* Sentinel */
774 PyTypeObject frame_object_type
= {
775 PyVarObject_HEAD_INIT (NULL
, 0)
776 "gdb.Frame", /* tp_name */
777 sizeof (frame_object
), /* tp_basicsize */
785 0, /* tp_as_number */
786 0, /* tp_as_sequence */
787 0, /* tp_as_mapping */
790 frapy_str
, /* tp_str */
793 0, /* tp_as_buffer */
794 Py_TPFLAGS_DEFAULT
, /* tp_flags */
795 "GDB frame object", /* tp_doc */
798 frapy_richcompare
, /* tp_richcompare */
799 0, /* tp_weaklistoffset */
802 frame_object_methods
, /* tp_methods */
807 0, /* tp_descr_get */
808 0, /* tp_descr_set */
809 0, /* tp_dictoffset */