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
, NULL
);
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. */
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
);
299 return (PyObject
*) frame_obj
;
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 volatile struct gdb_exception except
;
369 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
371 TRY_CATCH (except
, RETURN_MASK_ALL
)
373 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
375 find_frame_sal (frame
, &sal
);
376 sal_obj
= symtab_and_line_to_sal_object (sal
);
378 GDB_PY_HANDLE_EXCEPTION (except
);
383 /* Implementation of gdb.Frame.read_var_value (self, variable,
384 [block]) -> gdb.Value. If the optional block argument is provided
385 start the search from that block, otherwise search from the frame's
386 current block (determined by examining the resume address of the
387 frame). The variable argument must be a string or an instance of a
388 gdb.Symbol. The block argument must be an instance of gdb.Block. */
390 frapy_read_var (PyObject
*self
, PyObject
*args
)
392 struct frame_info
*frame
;
393 PyObject
*sym_obj
, *block_obj
= NULL
;
394 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
395 struct value
*val
= NULL
;
396 volatile struct gdb_exception except
;
398 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
401 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
402 var
= symbol_object_to_symbol (sym_obj
);
403 else if (gdbpy_is_string (sym_obj
))
406 struct block
*block
= NULL
;
407 struct cleanup
*cleanup
;
408 volatile struct gdb_exception except
;
410 var_name
= python_string_to_target_string (sym_obj
);
413 cleanup
= make_cleanup (xfree
, var_name
);
417 block
= block_object_to_block (block_obj
);
420 PyErr_SetString (PyExc_RuntimeError
,
421 _("Second argument must be block."));
426 TRY_CATCH (except
, RETURN_MASK_ALL
)
428 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
431 block
= block_for_pc (get_frame_address_in_block (frame
));
432 var
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
434 GDB_PY_HANDLE_EXCEPTION (except
);
438 PyErr_Format (PyExc_ValueError
,
439 _("Variable '%s' not found."), var_name
);
440 do_cleanups (cleanup
);
445 do_cleanups (cleanup
);
449 PyErr_SetString (PyExc_TypeError
,
450 _("Argument must be a symbol or string."));
454 TRY_CATCH (except
, RETURN_MASK_ALL
)
456 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
458 val
= read_var_value (var
, frame
);
460 GDB_PY_HANDLE_EXCEPTION (except
);
464 PyErr_Format (PyExc_ValueError
,
465 _("Variable cannot be found for symbol '%s'."),
466 SYMBOL_NATURAL_NAME (var
));
470 return value_to_value_object (val
);
473 /* Select this frame. */
476 frapy_select (PyObject
*self
, PyObject
*args
)
478 struct frame_info
*fi
;
479 frame_object
*frame
= (frame_object
*) self
;
480 volatile struct gdb_exception except
;
482 TRY_CATCH (except
, RETURN_MASK_ALL
)
484 FRAPY_REQUIRE_VALID (frame
, fi
);
488 GDB_PY_HANDLE_EXCEPTION (except
);
493 /* Implementation of gdb.selected_frame () -> gdb.Frame.
494 Returns the selected frame object. */
497 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
499 struct frame_info
*frame
;
500 PyObject
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
501 volatile struct gdb_exception except
;
503 TRY_CATCH (except
, RETURN_MASK_ALL
)
505 frame
= get_selected_frame ("No frame is currently selected.");
506 frame_obj
= frame_info_to_frame_object (frame
);
508 GDB_PY_HANDLE_EXCEPTION (except
);
513 /* Implementation of gdb.stop_reason_string (Integer) -> String.
514 Return a string explaining the unwind stop reason. */
517 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
522 if (!PyArg_ParseTuple (args
, "i", &reason
))
525 if (reason
< 0 || reason
> UNWIND_NO_SAVED_PC
)
527 PyErr_SetString (PyExc_ValueError
,
528 _("Invalid frame stop reason."));
532 str
= frame_stop_reason_string (reason
);
533 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
536 /* Implements the equality comparison for Frame objects.
537 All other comparison operators will throw a TypeError Python exception,
538 as they aren't valid for frames. */
541 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
545 if (!PyObject_TypeCheck (other
, &frame_object_type
)
546 || (op
!= Py_EQ
&& op
!= Py_NE
))
548 Py_INCREF (Py_NotImplemented
);
549 return Py_NotImplemented
;
552 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
553 ((frame_object
*) other
)->frame_id
))
563 /* Sets up the Frame API in the gdb module. */
566 gdbpy_initialize_frames (void)
568 if (PyType_Ready (&frame_object_type
) < 0)
571 /* Note: These would probably be best exposed as class attributes of Frame,
572 but I don't know how to do it except by messing with the type's dictionary.
573 That seems too messy. */
574 PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
);
575 PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
);
576 PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME", SIGTRAMP_FRAME
);
577 PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME", SENTINEL_FRAME
);
578 PyModule_AddIntConstant (gdb_module
,
579 "FRAME_UNWIND_NO_REASON", UNWIND_NO_REASON
);
580 PyModule_AddIntConstant (gdb_module
,
581 "FRAME_UNWIND_NULL_ID", UNWIND_NULL_ID
);
582 PyModule_AddIntConstant (gdb_module
,
583 "FRAME_UNWIND_FIRST_ERROR", UNWIND_FIRST_ERROR
);
584 PyModule_AddIntConstant (gdb_module
,
585 "FRAME_UNWIND_INNER_ID", UNWIND_INNER_ID
);
586 PyModule_AddIntConstant (gdb_module
,
587 "FRAME_UNWIND_SAME_ID", UNWIND_SAME_ID
);
588 PyModule_AddIntConstant (gdb_module
,
589 "FRAME_UNWIND_NO_SAVED_PC", UNWIND_NO_SAVED_PC
);
591 Py_INCREF (&frame_object_type
);
592 PyModule_AddObject (gdb_module
, "Frame", (PyObject
*) &frame_object_type
);
597 static PyMethodDef frame_object_methods
[] = {
598 { "is_valid", frapy_is_valid
, METH_NOARGS
,
599 "is_valid () -> Boolean.\n\
600 Return true if this frame is valid, false if not." },
601 { "name", frapy_name
, METH_NOARGS
,
602 "name () -> String.\n\
603 Return the function name of the frame, or None if it can't be determined." },
604 { "type", frapy_type
, METH_NOARGS
,
605 "type () -> Integer.\n\
606 Return the type of the frame." },
607 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
608 "unwind_stop_reason () -> Integer.\n\
609 Return the reason why it's not possible to find frames older than this." },
610 { "pc", frapy_pc
, METH_NOARGS
,
612 Return the frame's resume address." },
613 { "block", frapy_block
, METH_NOARGS
,
614 "block () -> gdb.Block.\n\
615 Return the frame's code block." },
616 { "function", frapy_function
, METH_NOARGS
,
617 "function () -> gdb.Symbol.\n\
618 Returns the symbol for the function corresponding to this frame." },
619 { "older", frapy_older
, METH_NOARGS
,
620 "older () -> gdb.Frame.\n\
621 Return the frame that called this frame." },
622 { "newer", frapy_newer
, METH_NOARGS
,
623 "newer () -> gdb.Frame.\n\
624 Return the frame called by this frame." },
625 { "find_sal", frapy_find_sal
, METH_NOARGS
,
626 "find_sal () -> gdb.Symtab_and_line.\n\
627 Return the frame's symtab and line." },
628 { "read_var", frapy_read_var
, METH_VARARGS
,
629 "read_var (variable) -> gdb.Value.\n\
630 Return the value of the variable in this frame." },
631 { "select", frapy_select
, METH_NOARGS
,
632 "Select this frame as the user's current frame." },
633 {NULL
} /* Sentinel */
636 static PyTypeObject frame_object_type
= {
637 PyObject_HEAD_INIT (NULL
)
639 "gdb.Frame", /* tp_name */
640 sizeof (frame_object
), /* tp_basicsize */
648 0, /* tp_as_number */
649 0, /* tp_as_sequence */
650 0, /* tp_as_mapping */
653 frapy_str
, /* tp_str */
656 0, /* tp_as_buffer */
657 Py_TPFLAGS_DEFAULT
, /* tp_flags */
658 "GDB frame object", /* tp_doc */
661 frapy_richcompare
, /* tp_richcompare */
662 0, /* tp_weaklistoffset */
665 frame_object_methods
, /* tp_methods */
670 0, /* tp_descr_get */
671 0, /* tp_descr_set */
672 0, /* tp_dictoffset */
675 PyType_GenericNew
/* tp_new */