1 /* Python interface to stack frames
3 Copyright (C) 2008-2013 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/>. */
24 #include "exceptions.h"
28 #include "python-internal.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);
136 GDB_PY_HANDLE_EXCEPTION (except);
139 result = PyUnicode_Decode (name, strlen (name), host_charset (), NULL);
149 /* Implementation of gdb.Frame.type (self) -> Integer.
150 Returns the frame type, namely one of the gdb.*_FRAME constants. */
153 frapy_type (PyObject *self, PyObject *args)
155 struct frame_info *frame;
156 enum frame_type type = NORMAL_FRAME;/* Initialize to appease gcc warning. */
157 volatile struct gdb_exception except;
159 TRY_CATCH (except, RETURN_MASK_ALL)
161 FRAPY_REQUIRE_VALID (self, frame);
163 type = get_frame_type (frame);
165 GDB_PY_HANDLE_EXCEPTION (except);
167 return PyInt_FromLong (type);
170 /* Implementation of gdb.Frame.architecture (self) -> gdb.Architecture.
171 Returns the frame's architecture as a gdb.Architecture object. */
174 frapy_arch (PyObject *self, PyObject *args)
176 struct frame_info *frame = NULL; /* Initialize to appease gcc warning. */
177 frame_object *obj = (frame_object *) self;
178 volatile struct gdb_exception except;
180 TRY_CATCH (except, RETURN_MASK_ALL)
182 FRAPY_REQUIRE_VALID (self, frame);
184 GDB_PY_HANDLE_EXCEPTION (except);
186 return gdbarch_to_arch_object (obj->gdbarch);
189 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
190 Returns one of the gdb.FRAME_UNWIND_* constants. */
193 frapy_unwind_stop_reason (PyObject *self, PyObject *args)
195 struct frame_info *frame = NULL; /* Initialize to appease gcc warning. */
196 volatile struct gdb_exception except;
197 enum unwind_stop_reason stop_reason;
199 TRY_CATCH (except, RETURN_MASK_ALL)
201 FRAPY_REQUIRE_VALID (self, frame);
203 GDB_PY_HANDLE_EXCEPTION (except);
205 stop_reason = get_frame_unwind_stop_reason (frame);
207 return PyInt_FromLong (stop_reason);
210 /* Implementation of gdb.Frame.pc (self) -> Long.
211 Returns the frame's resume address. */
214 frapy_pc (PyObject *self, PyObject *args)
216 CORE_ADDR pc = 0; /* Initialize to appease gcc warning. */
217 struct frame_info *frame;
218 volatile struct gdb_exception except;
220 TRY_CATCH (except, RETURN_MASK_ALL)
222 FRAPY_REQUIRE_VALID (self, frame);
224 pc = get_frame_pc (frame);
226 GDB_PY_HANDLE_EXCEPTION (except);
228 return gdb_py_long_from_ulongest (pc);
231 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
232 Returns the frame's code block. */
235 frapy_block (PyObject *self, PyObject *args)
237 struct frame_info *frame;
238 struct block *block = NULL, *fn_block;
239 volatile struct gdb_exception except;
241 TRY_CATCH (except, RETURN_MASK_ALL)
243 FRAPY_REQUIRE_VALID (self, frame);
244 block = get_frame_block (frame, NULL);
246 GDB_PY_HANDLE_EXCEPTION (except);
248 for (fn_block = block;
249 fn_block != NULL && BLOCK_FUNCTION (fn_block) == NULL;
250 fn_block = BLOCK_SUPERBLOCK (fn_block))
253 if (block == NULL || fn_block == NULL || BLOCK_FUNCTION (fn_block) == NULL)
255 PyErr_SetString (PyExc_RuntimeError,
256 _("Cannot locate object file for block."));
264 symt = SYMBOL_SYMTAB (BLOCK_FUNCTION (fn_block));
265 return block_to_block_object (block, symt->objfile);
272 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
273 Returns the symbol for the function corresponding to this frame. */
276 frapy_function (PyObject *self, PyObject *args)
278 struct symbol *sym = NULL;
279 struct frame_info *frame;
280 volatile struct gdb_exception except;
282 TRY_CATCH (except, RETURN_MASK_ALL)
284 FRAPY_REQUIRE_VALID (self, frame);
286 sym = find_pc_function (get_frame_address_in_block (frame));
288 GDB_PY_HANDLE_EXCEPTION (except);
291 return symbol_to_symbol_object (sym);
296 /* Convert a frame_info struct to a Python Frame object.
297 Sets a Python exception and returns NULL on error. */
300 frame_info_to_frame_object (struct frame_info *frame)
302 frame_object *frame_obj;
303 volatile struct gdb_exception except;
305 frame_obj = PyObject_New (frame_object, &frame_object_type);
306 if (frame_obj == NULL)
309 TRY_CATCH (except, RETURN_MASK_ALL)
312 /* Try to get the previous frame, to determine if this is the last frame
313 in a corrupt stack. If so, we need to store the frame_id of the next
314 frame and not of this one (which is possibly invalid). */
315 if (get_prev_frame (frame) == NULL
316 && get_frame_unwind_stop_reason (frame) != UNWIND_NO_REASON
317 && get_next_frame (frame) != NULL)
319 frame_obj->frame_id = get_frame_id (get_next_frame (frame));
320 frame_obj->frame_id_is_next = 1;
324 frame_obj->frame_id = get_frame_id (frame);
325 frame_obj->frame_id_is_next = 0;
327 frame_obj->gdbarch = get_frame_arch (frame);
329 GDB_PY_HANDLE_EXCEPTION (except);
331 return (PyObject *) frame_obj;
334 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
335 Returns the frame immediately older (outer) to this frame, or None if
339 frapy_older (PyObject *self, PyObject *args)
341 struct frame_info *frame, *prev;
342 volatile struct gdb_exception except;
343 PyObject *prev_obj = NULL; /* Initialize to appease gcc warning. */
345 TRY_CATCH (except, RETURN_MASK_ALL)
347 FRAPY_REQUIRE_VALID (self, frame);
349 prev = get_prev_frame (frame);
351 prev_obj = (PyObject *) frame_info_to_frame_object (prev);
358 GDB_PY_HANDLE_EXCEPTION (except);
363 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
364 Returns the frame immediately newer (inner) to this frame, or None if
368 frapy_newer (PyObject *self, PyObject *args)
370 struct frame_info *frame, *next;
371 volatile struct gdb_exception except;
372 PyObject *next_obj = NULL; /* Initialize to appease gcc warning. */
374 TRY_CATCH (except, RETURN_MASK_ALL)
376 FRAPY_REQUIRE_VALID (self, frame);
378 next = get_next_frame (frame);
380 next_obj = (PyObject *) frame_info_to_frame_object (next);
387 GDB_PY_HANDLE_EXCEPTION (except);
392 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
393 Returns the frame's symtab and line. */
396 frapy_find_sal (PyObject *self, PyObject *args)
398 struct frame_info *frame;
399 struct symtab_and_line sal;
400 volatile struct gdb_exception except;
401 PyObject *sal_obj = NULL; /* Initialize to appease gcc warning. */
403 TRY_CATCH (except, RETURN_MASK_ALL)
405 FRAPY_REQUIRE_VALID (self, frame);
407 find_frame_sal (frame, &sal);
408 sal_obj = symtab_and_line_to_sal_object (sal);
410 GDB_PY_HANDLE_EXCEPTION (except);
415 /* Implementation of gdb.Frame.read_var_value (self, variable,
416 [block]) -> gdb.Value. If the optional block argument is provided
417 start the search from that block, otherwise search from the frame's
418 current block (determined by examining the resume address of the
419 frame). The variable argument must be a string or an instance of a
420 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
421 NULL on error, with a python exception set. */
423 frapy_read_var (PyObject *self, PyObject *args)
425 struct frame_info *frame;
426 PyObject *sym_obj, *block_obj = NULL;
427 struct symbol *var = NULL; /* gcc-4.3.2 false warning. */
428 struct value *val = NULL;
429 volatile struct gdb_exception except;
431 if (!PyArg_ParseTuple (args, "O|O", &sym_obj, &block_obj))
434 if (PyObject_TypeCheck (sym_obj, &symbol_object_type))
435 var = symbol_object_to_symbol (sym_obj);
436 else if (gdbpy_is_string (sym_obj))
439 const struct block *block = NULL;
440 struct cleanup *cleanup;
441 volatile struct gdb_exception except;
443 var_name = python_string_to_target_string (sym_obj);
446 cleanup = make_cleanup (xfree, var_name);
450 block = block_object_to_block (block_obj);
453 PyErr_SetString (PyExc_RuntimeError,
454 _("Second argument must be block."));
459 TRY_CATCH (except, RETURN_MASK_ALL)
461 FRAPY_REQUIRE_VALID (self, frame);
464 block = get_frame_block (frame, NULL);
465 var = lookup_symbol (var_name, block, VAR_DOMAIN, NULL);
467 GDB_PY_HANDLE_EXCEPTION (except);
471 PyErr_Format (PyExc_ValueError,
472 _("Variable '%s' not found."), var_name);
473 do_cleanups (cleanup);
478 do_cleanups (cleanup);
482 PyErr_SetString (PyExc_TypeError,
483 _("Argument must be a symbol or string."));
487 TRY_CATCH (except, RETURN_MASK_ALL)
489 FRAPY_REQUIRE_VALID (self, frame);
491 val = read_var_value (var, frame);
493 GDB_PY_HANDLE_EXCEPTION (except);
495 return value_to_value_object (val);
498 /* Select this frame. */
501 frapy_select (PyObject *self, PyObject *args)
503 struct frame_info *fi;
504 volatile struct gdb_exception except;
506 TRY_CATCH (except, RETURN_MASK_ALL)
508 FRAPY_REQUIRE_VALID (self, fi);
512 GDB_PY_HANDLE_EXCEPTION (except);
517 /* Implementation of gdb.newest_frame () -> gdb.Frame.
518 Returns the newest frame object. */
521 gdbpy_newest_frame (PyObject *self, PyObject *args)
523 struct frame_info *frame;
524 PyObject *frame_obj = NULL; /* Initialize to appease gcc warning. */
525 volatile struct gdb_exception except;
527 TRY_CATCH (except, RETURN_MASK_ALL)
529 frame = get_current_frame ();
530 frame_obj = frame_info_to_frame_object (frame);
532 GDB_PY_HANDLE_EXCEPTION (except);
537 /* Implementation of gdb.selected_frame () -> gdb.Frame.
538 Returns the selected frame object. */
541 gdbpy_selected_frame (PyObject *self, PyObject *args)
543 struct frame_info *frame;
544 PyObject *frame_obj = NULL; /* Initialize to appease gcc warning. */
545 volatile struct gdb_exception except;
547 TRY_CATCH (except, RETURN_MASK_ALL)
549 frame = get_selected_frame ("No frame is currently selected.");
550 frame_obj = frame_info_to_frame_object (frame);
552 GDB_PY_HANDLE_EXCEPTION (except);
557 /* Implementation of gdb.stop_reason_string (Integer) -> String.
558 Return a string explaining the unwind stop reason. */
561 gdbpy_frame_stop_reason_string (PyObject *self, PyObject *args)
566 if (!PyArg_ParseTuple (args, "i", &reason))
569 if (reason < UNWIND_FIRST || reason > UNWIND_LAST)
571 PyErr_SetString (PyExc_ValueError,
572 _("Invalid frame stop reason."));
576 str = frame_stop_reason_string (reason);
577 return PyUnicode_Decode (str, strlen (str), host_charset (), NULL);
580 /* Implements the equality comparison for Frame objects.
581 All other comparison operators will throw a TypeError Python exception,
582 as they aren't valid for frames. */
585 frapy_richcompare (PyObject *self, PyObject *other, int op)
589 if (!PyObject_TypeCheck (other, &frame_object_type)
590 || (op != Py_EQ && op != Py_NE))
592 Py_INCREF (Py_NotImplemented);
593 return Py_NotImplemented;
596 if (frame_id_eq (((frame_object *) self)->frame_id,
597 ((frame_object *) other)->frame_id))
607 /* Sets up the Frame API in the gdb module. */
610 gdbpy_initialize_frames (void)
612 frame_object_type.tp_new = PyType_GenericNew;
613 if (PyType_Ready (&frame_object_type) < 0)
616 /* Note: These would probably be best exposed as class attributes of
617 Frame, but I don't know how to do it except by messing with the
618 type's dictionary. That seems too messy. */
619 PyModule_AddIntConstant (gdb_module, "NORMAL_FRAME", NORMAL_FRAME);
620 PyModule_AddIntConstant (gdb_module, "DUMMY_FRAME", DUMMY_FRAME);
621 PyModule_AddIntConstant (gdb_module, "INLINE_FRAME", INLINE_FRAME);
622 PyModule_AddIntConstant (gdb_module, "TAILCALL_FRAME", TAILCALL_FRAME);
623 PyModule_AddIntConstant (gdb_module, "SIGTRAMP_FRAME", SIGTRAMP_FRAME);
624 PyModule_AddIntConstant (gdb_module, "ARCH_FRAME", ARCH_FRAME);
625 PyModule_AddIntConstant (gdb_module, "SENTINEL_FRAME", SENTINEL_FRAME);
627 #define SET(name, description) \
628 PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name);
629 #define FIRST_ERROR(name) \
630 PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name);
631 #include "unwind_stop_reasons.def"
634 Py_INCREF (&frame_object_type);
635 PyModule_AddObject (gdb_module, "Frame", (PyObject *) &frame_object_type);
640 static PyMethodDef frame_object_methods[] = {
641 { "is_valid", frapy_is_valid, METH_NOARGS,
642 "is_valid () -> Boolean.\n\
643 Return true if this frame is valid, false if not." },
644 { "name", frapy_name, METH_NOARGS,
645 "name () -> String.\n\
646 Return the function name of the frame, or None if it can't be determined." },
647 { "type", frapy_type, METH_NOARGS,
648 "type () -> Integer.\n\
649 Return the type of the frame." },
650 { "architecture", frapy_arch, METH_NOARGS,
651 "architecture () -> gdb.Architecture.\n\
652 Return the architecture of the frame." },
653 { "unwind_stop_reason", frapy_unwind_stop_reason, METH_NOARGS,
654 "unwind_stop_reason () -> Integer.\n\
655 Return the reason why it's not possible to find frames older than this." },
656 { "pc", frapy_pc, METH_NOARGS,
658 Return the frame's resume address." },
659 { "block", frapy_block, METH_NOARGS,
660 "block () -> gdb.Block.\n\
661 Return the frame's code block." },
662 { "function", frapy_function, METH_NOARGS,
663 "function () -> gdb.Symbol.\n\
664 Returns the symbol for the function corresponding to this frame." },
665 { "older", frapy_older, METH_NOARGS,
666 "older () -> gdb.Frame.\n\
667 Return the frame that called this frame." },
668 { "newer", frapy_newer, METH_NOARGS,
669 "newer () -> gdb.Frame.\n\
670 Return the frame called by this frame." },
671 { "find_sal", frapy_find_sal, METH_NOARGS,
672 "find_sal () -> gdb.Symtab_and_line.\n\
673 Return the frame's symtab and line." },
674 { "read_var", frapy_read_var, METH_VARARGS,
675 "read_var (variable) -> gdb.Value.\n\
676 Return the value of the variable in this frame." },
677 { "select", frapy_select, METH_NOARGS,
678 "Select this frame as the user's current frame." },
679 {NULL} /* Sentinel */
682 PyTypeObject frame_object_type = {
683 PyVarObject_HEAD_INIT (NULL, 0)
684 "gdb.Frame", /* tp_name */
685 sizeof (frame_object), /* tp_basicsize */
693 0, /* tp_as_number */
694 0, /* tp_as_sequence */
695 0, /* tp_as_mapping */
698 frapy_str, /* tp_str */
701 0, /* tp_as_buffer */
702 Py_TPFLAGS_DEFAULT, /* tp_flags */
703 "GDB frame object", /* tp_doc */
706 frapy_richcompare, /* tp_richcompare */
707 0, /* tp_weaklistoffset */
710 frame_object_methods, /* tp_methods */
715 0, /* tp_descr_get */
716 0, /* tp_descr_set */
717 0, /* tp_dictoffset */