1 /* Python interface to stack frames
3 Copyright (C) 2008, 2009, 2010 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 static PyTypeObject frame_object_type
;
59 /* Returns the frame_info object corresponding to the given Python Frame
60 object. If the frame doesn't exist anymore (the frame id doesn't
61 correspond to any frame in the inferior), returns NULL. */
63 static struct frame_info
*
64 frame_object_to_frame_info (frame_object
*frame_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 struct ui_file
*strfile
;
88 strfile
= mem_fileopen ();
89 fprint_frame_id (strfile
, ((frame_object
*) self
)->frame_id
);
90 s
= ui_file_xstrdup (strfile
, NULL
);
91 result
= PyString_FromString (s
);
97 /* Implementation of gdb.Frame.is_valid (self) -> Boolean.
98 Returns True if the frame corresponding to the frame_id of this
99 object still exists in the inferior. */
102 frapy_is_valid (PyObject
*self
, PyObject
*args
)
104 struct frame_info
*frame
;
106 frame
= frame_object_to_frame_info ((frame_object
*) self
);
113 /* Implementation of gdb.Frame.name (self) -> String.
114 Returns the name of the function corresponding to this frame. */
117 frapy_name (PyObject
*self
, PyObject
*args
)
119 struct frame_info
*frame
;
123 volatile struct gdb_exception except
;
125 TRY_CATCH (except
, RETURN_MASK_ALL
)
127 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
129 find_frame_funname (frame
, &name
, &lang
);
131 GDB_PY_HANDLE_EXCEPTION (except
);
134 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
144 /* Implementation of gdb.Frame.type (self) -> Integer.
145 Returns the frame type, namely one of the gdb.*_FRAME constants. */
148 frapy_type (PyObject
*self
, PyObject
*args
)
150 struct frame_info
*frame
;
151 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
152 volatile struct gdb_exception except
;
154 TRY_CATCH (except
, RETURN_MASK_ALL
)
156 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
158 type
= get_frame_type (frame
);
160 GDB_PY_HANDLE_EXCEPTION (except
);
162 return PyInt_FromLong (type
);
165 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
166 Returns one of the gdb.FRAME_UNWIND_* constants. */
169 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
171 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
172 volatile struct gdb_exception except
;
173 enum unwind_stop_reason stop_reason
;
175 TRY_CATCH (except
, RETURN_MASK_ALL
)
177 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
179 GDB_PY_HANDLE_EXCEPTION (except
);
181 stop_reason
= get_frame_unwind_stop_reason (frame
);
183 return PyInt_FromLong (stop_reason
);
186 /* Implementation of gdb.Frame.pc (self) -> Long.
187 Returns the frame's resume address. */
190 frapy_pc (PyObject
*self
, PyObject
*args
)
192 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
193 struct frame_info
*frame
;
194 volatile struct gdb_exception except
;
196 TRY_CATCH (except
, RETURN_MASK_ALL
)
198 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
200 pc
= get_frame_pc (frame
);
202 GDB_PY_HANDLE_EXCEPTION (except
);
204 return PyLong_FromUnsignedLongLong (pc
);
207 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
208 Returns the frame's code block. */
211 frapy_block (PyObject
*self
, PyObject
*args
)
213 struct frame_info
*frame
;
214 struct block
*block
= NULL
;
215 volatile struct gdb_exception except
;
216 struct symtab_and_line sal
;
218 TRY_CATCH (except
, RETURN_MASK_ALL
)
220 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
222 find_frame_sal (frame
, &sal
);
223 block
= block_for_pc (get_frame_address_in_block (frame
));
225 GDB_PY_HANDLE_EXCEPTION (except
);
227 if (!sal
.symtab
|| !sal
.symtab
->objfile
)
229 PyErr_SetString (PyExc_RuntimeError
,
230 _("Cannot locate object file for block."));
235 return block_to_block_object (block
, sal
.symtab
->objfile
);
241 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
242 Returns the symbol for the function corresponding to this frame. */
245 frapy_function (PyObject
*self
, PyObject
*args
)
247 struct symbol
*sym
= NULL
;
248 struct frame_info
*frame
;
249 volatile struct gdb_exception except
;
251 TRY_CATCH (except
, RETURN_MASK_ALL
)
253 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
255 sym
= find_pc_function (get_frame_address_in_block (frame
));
257 GDB_PY_HANDLE_EXCEPTION (except
);
260 return symbol_to_symbol_object (sym
);
265 /* Convert a frame_info struct to a Python Frame object.
266 Sets a Python exception and returns NULL on error. */
268 static frame_object
*
269 frame_info_to_frame_object (struct frame_info
*frame
)
271 frame_object
*frame_obj
;
273 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
274 if (frame_obj
== NULL
)
276 PyErr_SetString (PyExc_MemoryError
,
277 _("Could not allocate frame object."));
281 /* Try to get the previous frame, to determine if this is the last frame
282 in a corrupt stack. If so, we need to store the frame_id of the next
283 frame and not of this one (which is possibly invalid). */
284 if (get_prev_frame (frame
) == NULL
285 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
286 && get_next_frame (frame
) != NULL
)
288 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
289 frame_obj
->frame_id_is_next
= 1;
293 frame_obj
->frame_id
= get_frame_id (frame
);
294 frame_obj
->frame_id_is_next
= 0;
297 frame_obj
->gdbarch
= get_frame_arch (frame
);
302 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
303 Returns the frame immediately older (outer) to this frame, or None if
307 frapy_older (PyObject
*self
, PyObject
*args
)
309 struct frame_info
*frame
, *prev
;
310 volatile struct gdb_exception except
;
311 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
313 TRY_CATCH (except
, RETURN_MASK_ALL
)
315 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
317 prev
= get_prev_frame (frame
);
319 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
326 GDB_PY_HANDLE_EXCEPTION (except
);
331 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
332 Returns the frame immediately newer (inner) to this frame, or None if
336 frapy_newer (PyObject
*self
, PyObject
*args
)
338 struct frame_info
*frame
, *next
;
339 volatile struct gdb_exception except
;
340 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
342 TRY_CATCH (except
, RETURN_MASK_ALL
)
344 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
346 next
= get_next_frame (frame
);
348 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
355 GDB_PY_HANDLE_EXCEPTION (except
);
360 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
361 Returns the frame's symtab and line. */
364 frapy_find_sal (PyObject
*self
, PyObject
*args
)
366 struct frame_info
*frame
;
367 struct symtab_and_line sal
;
368 struct objfile
*objfile
= NULL
;
369 volatile struct gdb_exception except
;
370 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
372 TRY_CATCH (except
, RETURN_MASK_ALL
)
374 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
376 find_frame_sal (frame
, &sal
);
377 sal_obj
= symtab_and_line_to_sal_object (sal
);
379 GDB_PY_HANDLE_EXCEPTION (except
);
384 /* Implementation of gdb.Frame.read_var_value (self, variable,
385 [block]) -> gdb.Value. If the optional block argument is provided
386 start the search from that block, otherwise search from the frame's
387 current block (determined by examining the resume address of the
388 frame). The variable argument must be a string or an instance of a
389 gdb.Symbol. The block argument must be an instance of gdb.Block. */
391 frapy_read_var (PyObject
*self
, PyObject
*args
)
393 struct frame_info
*frame
;
394 PyObject
*sym_obj
, *block_obj
= NULL
;
395 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
396 struct value
*val
= NULL
;
397 volatile struct gdb_exception except
;
399 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
402 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
403 var
= symbol_object_to_symbol (sym_obj
);
404 else if (gdbpy_is_string (sym_obj
))
407 struct block
*block
= NULL
;
408 struct cleanup
*cleanup
;
409 volatile struct gdb_exception except
;
411 var_name
= python_string_to_target_string (sym_obj
);
414 cleanup
= make_cleanup (xfree
, var_name
);
418 block
= block_object_to_block (block_obj
);
421 PyErr_SetString (PyExc_RuntimeError
,
422 _("Second argument must be block."));
427 TRY_CATCH (except
, RETURN_MASK_ALL
)
429 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
432 block
= block_for_pc (get_frame_address_in_block (frame
));
433 var
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
435 GDB_PY_HANDLE_EXCEPTION (except
);
439 PyErr_Format (PyExc_ValueError
,
440 _("Variable '%s' not found."), var_name
);
441 do_cleanups (cleanup
);
446 do_cleanups (cleanup
);
450 PyErr_SetString (PyExc_TypeError
,
451 _("Argument must be a symbol or string."));
455 TRY_CATCH (except
, RETURN_MASK_ALL
)
457 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
459 val
= read_var_value (var
, frame
);
461 GDB_PY_HANDLE_EXCEPTION (except
);
465 PyErr_Format (PyExc_ValueError
,
466 _("Variable cannot be found for symbol '%s'."),
467 SYMBOL_NATURAL_NAME (var
));
471 return value_to_value_object (val
);
474 /* Select this frame. */
477 frapy_select (PyObject
*self
, PyObject
*args
)
479 struct frame_info
*fi
;
480 frame_object
*frame
= (frame_object
*) self
;
481 volatile struct gdb_exception except
;
483 TRY_CATCH (except
, RETURN_MASK_ALL
)
485 FRAPY_REQUIRE_VALID (frame
, fi
);
489 GDB_PY_HANDLE_EXCEPTION (except
);
494 /* Implementation of gdb.selected_frame () -> gdb.Frame.
495 Returns the selected frame object. */
498 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
500 struct frame_info
*frame
;
501 frame_object
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
502 volatile struct gdb_exception except
;
504 TRY_CATCH (except
, RETURN_MASK_ALL
)
506 frame
= get_selected_frame ("No frame is currently selected.");
507 frame_obj
= frame_info_to_frame_object (frame
);
509 GDB_PY_HANDLE_EXCEPTION (except
);
511 return (PyObject
*) frame_obj
;
514 /* Implementation of gdb.stop_reason_string (Integer) -> String.
515 Return a string explaining the unwind stop reason. */
518 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
523 if (!PyArg_ParseTuple (args
, "i", &reason
))
526 if (reason
< 0 || reason
> UNWIND_NO_SAVED_PC
)
528 PyErr_SetString (PyExc_ValueError
,
529 _("Invalid frame stop reason."));
533 str
= frame_stop_reason_string (reason
);
534 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
537 /* Implements the equality comparison for Frame objects.
538 All other comparison operators will throw a TypeError Python exception,
539 as they aren't valid for frames. */
542 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
546 if (!PyObject_TypeCheck (other
, &frame_object_type
)
547 || (op
!= Py_EQ
&& op
!= Py_NE
))
549 Py_INCREF (Py_NotImplemented
);
550 return Py_NotImplemented
;
553 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
554 ((frame_object
*) other
)->frame_id
))
564 /* Sets up the Frame API in the gdb module. */
567 gdbpy_initialize_frames (void)
569 if (PyType_Ready (&frame_object_type
) < 0)
572 /* Note: These would probably be best exposed as class attributes of Frame,
573 but I don't know how to do it except by messing with the type's dictionary.
574 That seems too messy. */
575 PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
);
576 PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
);
577 PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME", SIGTRAMP_FRAME
);
578 PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME", SENTINEL_FRAME
);
579 PyModule_AddIntConstant (gdb_module
,
580 "FRAME_UNWIND_NO_REASON", UNWIND_NO_REASON
);
581 PyModule_AddIntConstant (gdb_module
,
582 "FRAME_UNWIND_NULL_ID", UNWIND_NULL_ID
);
583 PyModule_AddIntConstant (gdb_module
,
584 "FRAME_UNWIND_FIRST_ERROR", UNWIND_FIRST_ERROR
);
585 PyModule_AddIntConstant (gdb_module
,
586 "FRAME_UNWIND_INNER_ID", UNWIND_INNER_ID
);
587 PyModule_AddIntConstant (gdb_module
,
588 "FRAME_UNWIND_SAME_ID", UNWIND_SAME_ID
);
589 PyModule_AddIntConstant (gdb_module
,
590 "FRAME_UNWIND_NO_SAVED_PC", UNWIND_NO_SAVED_PC
);
592 Py_INCREF (&frame_object_type
);
593 PyModule_AddObject (gdb_module
, "Frame", (PyObject
*) &frame_object_type
);
598 static PyMethodDef frame_object_methods
[] = {
599 { "is_valid", frapy_is_valid
, METH_NOARGS
,
600 "is_valid () -> Boolean.\n\
601 Return true if this frame is valid, false if not." },
602 { "name", frapy_name
, METH_NOARGS
,
603 "name () -> String.\n\
604 Return the function name of the frame, or None if it can't be determined." },
605 { "type", frapy_type
, METH_NOARGS
,
606 "type () -> Integer.\n\
607 Return the type of the frame." },
608 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
609 "unwind_stop_reason () -> Integer.\n\
610 Return the reason why it's not possible to find frames older than this." },
611 { "pc", frapy_pc
, METH_NOARGS
,
613 Return the frame's resume address." },
614 { "block", frapy_block
, METH_NOARGS
,
615 "block () -> gdb.Block.\n\
616 Return the frame's code block." },
617 { "function", frapy_function
, METH_NOARGS
,
618 "function () -> gdb.Symbol.\n\
619 Returns the symbol for the function corresponding to this frame." },
620 { "older", frapy_older
, METH_NOARGS
,
621 "older () -> gdb.Frame.\n\
622 Return the frame that called this frame." },
623 { "newer", frapy_newer
, METH_NOARGS
,
624 "newer () -> gdb.Frame.\n\
625 Return the frame called by this frame." },
626 { "find_sal", frapy_find_sal
, METH_NOARGS
,
627 "find_sal () -> gdb.Symtab_and_line.\n\
628 Return the frame's symtab and line." },
629 { "read_var", frapy_read_var
, METH_VARARGS
,
630 "read_var (variable) -> gdb.Value.\n\
631 Return the value of the variable in this frame." },
632 { "select", frapy_select
, METH_NOARGS
,
633 "Select this frame as the user's current frame." },
634 {NULL
} /* Sentinel */
637 static PyTypeObject frame_object_type
= {
638 PyObject_HEAD_INIT (NULL
)
640 "gdb.Frame", /* tp_name */
641 sizeof (frame_object
), /* tp_basicsize */
649 0, /* tp_as_number */
650 0, /* tp_as_sequence */
651 0, /* tp_as_mapping */
654 frapy_str
, /* tp_str */
657 0, /* tp_as_buffer */
658 Py_TPFLAGS_DEFAULT
, /* tp_flags */
659 "GDB frame object", /* tp_doc */
662 frapy_richcompare
, /* tp_richcompare */
663 0, /* tp_weaklistoffset */
666 frame_object_methods
, /* tp_methods */
671 0, /* tp_descr_get */
672 0, /* tp_descr_set */
673 0, /* tp_dictoffset */
676 PyType_GenericNew
/* tp_new */