1 /* Python interface to stack frames
3 Copyright (C) 2008, 2009, 2010, 2011 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
= NULL
;
105 volatile struct gdb_exception except
;
107 TRY_CATCH (except
, RETURN_MASK_ALL
)
109 frame
= frame_object_to_frame_info ((frame_object
*) self
);
111 GDB_PY_HANDLE_EXCEPTION (except
);
119 /* Implementation of gdb.Frame.name (self) -> String.
120 Returns the name of the function corresponding to this frame. */
123 frapy_name (PyObject
*self
, PyObject
*args
)
125 struct frame_info
*frame
;
129 volatile struct gdb_exception except
;
131 TRY_CATCH (except
, RETURN_MASK_ALL
)
133 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
135 find_frame_funname (frame
, &name
, &lang
, NULL
);
137 GDB_PY_HANDLE_EXCEPTION (except
);
140 result
= PyUnicode_Decode (name
, strlen (name
), host_charset (), NULL
);
150 /* Implementation of gdb.Frame.type (self) -> Integer.
151 Returns the frame type, namely one of the gdb.*_FRAME constants. */
154 frapy_type (PyObject
*self
, PyObject
*args
)
156 struct frame_info
*frame
;
157 enum frame_type type
= NORMAL_FRAME
;/* Initialize to appease gcc warning. */
158 volatile struct gdb_exception except
;
160 TRY_CATCH (except
, RETURN_MASK_ALL
)
162 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
164 type
= get_frame_type (frame
);
166 GDB_PY_HANDLE_EXCEPTION (except
);
168 return PyInt_FromLong (type
);
171 /* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
172 Returns one of the gdb.FRAME_UNWIND_* constants. */
175 frapy_unwind_stop_reason (PyObject
*self
, PyObject
*args
)
177 struct frame_info
*frame
= NULL
; /* Initialize to appease gcc warning. */
178 volatile struct gdb_exception except
;
179 enum unwind_stop_reason stop_reason
;
181 TRY_CATCH (except
, RETURN_MASK_ALL
)
183 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
185 GDB_PY_HANDLE_EXCEPTION (except
);
187 stop_reason
= get_frame_unwind_stop_reason (frame
);
189 return PyInt_FromLong (stop_reason
);
192 /* Implementation of gdb.Frame.pc (self) -> Long.
193 Returns the frame's resume address. */
196 frapy_pc (PyObject
*self
, PyObject
*args
)
198 CORE_ADDR pc
= 0; /* Initialize to appease gcc warning. */
199 struct frame_info
*frame
;
200 volatile struct gdb_exception except
;
202 TRY_CATCH (except
, RETURN_MASK_ALL
)
204 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
206 pc
= get_frame_pc (frame
);
208 GDB_PY_HANDLE_EXCEPTION (except
);
210 return gdb_py_long_from_ulongest (pc
);
213 /* Implementation of gdb.Frame.block (self) -> gdb.Block.
214 Returns the frame's code block. */
217 frapy_block (PyObject
*self
, PyObject
*args
)
219 struct frame_info
*frame
;
220 struct block
*block
= NULL
, *fn_block
;
221 volatile struct gdb_exception except
;
223 TRY_CATCH (except
, RETURN_MASK_ALL
)
225 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
226 block
= get_frame_block (frame
, NULL
);
228 GDB_PY_HANDLE_EXCEPTION (except
);
230 for (fn_block
= block
;
231 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
232 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
235 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
237 PyErr_SetString (PyExc_RuntimeError
,
238 _("Cannot locate object file for block."));
246 symt
= SYMBOL_SYMTAB (BLOCK_FUNCTION (fn_block
));
247 return block_to_block_object (block
, symt
->objfile
);
254 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
255 Returns the symbol for the function corresponding to this frame. */
258 frapy_function (PyObject
*self
, PyObject
*args
)
260 struct symbol
*sym
= NULL
;
261 struct frame_info
*frame
;
262 volatile struct gdb_exception except
;
264 TRY_CATCH (except
, RETURN_MASK_ALL
)
266 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
268 sym
= find_pc_function (get_frame_address_in_block (frame
));
270 GDB_PY_HANDLE_EXCEPTION (except
);
273 return symbol_to_symbol_object (sym
);
278 /* Convert a frame_info struct to a Python Frame object.
279 Sets a Python exception and returns NULL on error. */
282 frame_info_to_frame_object (struct frame_info
*frame
)
284 frame_object
*frame_obj
;
285 volatile struct gdb_exception except
;
287 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
288 if (frame_obj
== NULL
)
290 PyErr_SetString (PyExc_MemoryError
,
291 _("Could not allocate frame object."));
295 TRY_CATCH (except
, RETURN_MASK_ALL
)
298 /* Try to get the previous frame, to determine if this is the last frame
299 in a corrupt stack. If so, we need to store the frame_id of the next
300 frame and not of this one (which is possibly invalid). */
301 if (get_prev_frame (frame
) == NULL
302 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
303 && get_next_frame (frame
) != NULL
)
305 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
306 frame_obj
->frame_id_is_next
= 1;
310 frame_obj
->frame_id
= get_frame_id (frame
);
311 frame_obj
->frame_id_is_next
= 0;
313 frame_obj
->gdbarch
= get_frame_arch (frame
);
315 GDB_PY_HANDLE_EXCEPTION (except
);
317 return (PyObject
*) frame_obj
;
320 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
321 Returns the frame immediately older (outer) to this frame, or None if
325 frapy_older (PyObject
*self
, PyObject
*args
)
327 struct frame_info
*frame
, *prev
;
328 volatile struct gdb_exception except
;
329 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
331 TRY_CATCH (except
, RETURN_MASK_ALL
)
333 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
335 prev
= get_prev_frame (frame
);
337 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
344 GDB_PY_HANDLE_EXCEPTION (except
);
349 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
350 Returns the frame immediately newer (inner) to this frame, or None if
354 frapy_newer (PyObject
*self
, PyObject
*args
)
356 struct frame_info
*frame
, *next
;
357 volatile struct gdb_exception except
;
358 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
360 TRY_CATCH (except
, RETURN_MASK_ALL
)
362 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
364 next
= get_next_frame (frame
);
366 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
373 GDB_PY_HANDLE_EXCEPTION (except
);
378 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
379 Returns the frame's symtab and line. */
382 frapy_find_sal (PyObject
*self
, PyObject
*args
)
384 struct frame_info
*frame
;
385 struct symtab_and_line sal
;
386 volatile struct gdb_exception except
;
387 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
389 TRY_CATCH (except
, RETURN_MASK_ALL
)
391 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
393 find_frame_sal (frame
, &sal
);
394 sal_obj
= symtab_and_line_to_sal_object (sal
);
396 GDB_PY_HANDLE_EXCEPTION (except
);
401 /* Implementation of gdb.Frame.read_var_value (self, variable,
402 [block]) -> gdb.Value. If the optional block argument is provided
403 start the search from that block, otherwise search from the frame's
404 current block (determined by examining the resume address of the
405 frame). The variable argument must be a string or an instance of a
406 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
407 NULL on error, with a python exception set. */
409 frapy_read_var (PyObject
*self
, PyObject
*args
)
411 struct frame_info
*frame
;
412 PyObject
*sym_obj
, *block_obj
= NULL
;
413 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
414 struct value
*val
= NULL
;
415 volatile struct gdb_exception except
;
417 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
420 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
421 var
= symbol_object_to_symbol (sym_obj
);
422 else if (gdbpy_is_string (sym_obj
))
425 const struct block
*block
= NULL
;
426 struct cleanup
*cleanup
;
427 volatile struct gdb_exception except
;
429 var_name
= python_string_to_target_string (sym_obj
);
432 cleanup
= make_cleanup (xfree
, var_name
);
436 block
= block_object_to_block (block_obj
);
439 PyErr_SetString (PyExc_RuntimeError
,
440 _("Second argument must be block."));
445 TRY_CATCH (except
, RETURN_MASK_ALL
)
447 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
450 block
= get_frame_block (frame
, NULL
);
451 var
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
453 GDB_PY_HANDLE_EXCEPTION (except
);
457 PyErr_Format (PyExc_ValueError
,
458 _("Variable '%s' not found."), var_name
);
459 do_cleanups (cleanup
);
464 do_cleanups (cleanup
);
468 PyErr_SetString (PyExc_TypeError
,
469 _("Argument must be a symbol or string."));
473 TRY_CATCH (except
, RETURN_MASK_ALL
)
475 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
477 val
= read_var_value (var
, frame
);
479 GDB_PY_HANDLE_EXCEPTION (except
);
481 return value_to_value_object (val
);
484 /* Select this frame. */
487 frapy_select (PyObject
*self
, PyObject
*args
)
489 struct frame_info
*fi
;
490 frame_object
*frame
= (frame_object
*) self
;
491 volatile struct gdb_exception except
;
493 TRY_CATCH (except
, RETURN_MASK_ALL
)
495 FRAPY_REQUIRE_VALID (frame
, fi
);
499 GDB_PY_HANDLE_EXCEPTION (except
);
504 /* Implementation of gdb.newest_frame () -> gdb.Frame.
505 Returns the newest frame object. */
508 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
510 struct frame_info
*frame
;
511 PyObject
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
512 volatile struct gdb_exception except
;
514 TRY_CATCH (except
, RETURN_MASK_ALL
)
516 frame
= get_current_frame ();
517 frame_obj
= frame_info_to_frame_object (frame
);
519 GDB_PY_HANDLE_EXCEPTION (except
);
524 /* Implementation of gdb.selected_frame () -> gdb.Frame.
525 Returns the selected frame object. */
528 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
530 struct frame_info
*frame
;
531 PyObject
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
532 volatile struct gdb_exception except
;
534 TRY_CATCH (except
, RETURN_MASK_ALL
)
536 frame
= get_selected_frame ("No frame is currently selected.");
537 frame_obj
= frame_info_to_frame_object (frame
);
539 GDB_PY_HANDLE_EXCEPTION (except
);
544 /* Implementation of gdb.stop_reason_string (Integer) -> String.
545 Return a string explaining the unwind stop reason. */
548 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
553 if (!PyArg_ParseTuple (args
, "i", &reason
))
556 if (reason
< UNWIND_FIRST
|| reason
> UNWIND_LAST
)
558 PyErr_SetString (PyExc_ValueError
,
559 _("Invalid frame stop reason."));
563 str
= frame_stop_reason_string (reason
);
564 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
567 /* Implements the equality comparison for Frame objects.
568 All other comparison operators will throw a TypeError Python exception,
569 as they aren't valid for frames. */
572 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
576 if (!PyObject_TypeCheck (other
, &frame_object_type
)
577 || (op
!= Py_EQ
&& op
!= Py_NE
))
579 Py_INCREF (Py_NotImplemented
);
580 return Py_NotImplemented
;
583 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
584 ((frame_object
*) other
)->frame_id
))
594 /* Sets up the Frame API in the gdb module. */
597 gdbpy_initialize_frames (void)
599 frame_object_type
.tp_new
= PyType_GenericNew
;
600 if (PyType_Ready (&frame_object_type
) < 0)
603 /* Note: These would probably be best exposed as class attributes of
604 Frame, but I don't know how to do it except by messing with the
605 type's dictionary. That seems too messy. */
606 PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
);
607 PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
);
608 PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
);
609 PyModule_AddIntConstant (gdb_module
, "TAILCALL_FRAME", TAILCALL_FRAME
);
610 PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME", SIGTRAMP_FRAME
);
611 PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
);
612 PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME", SENTINEL_FRAME
);
614 #define SET(name, description) \
615 PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name);
616 #define FIRST_ERROR(name) \
617 PyModule_AddIntConstant (gdb_module, "FRAME_"#name, name);
618 #include "unwind_stop_reasons.def"
621 Py_INCREF (&frame_object_type
);
622 PyModule_AddObject (gdb_module
, "Frame", (PyObject
*) &frame_object_type
);
627 static PyMethodDef frame_object_methods
[] = {
628 { "is_valid", frapy_is_valid
, METH_NOARGS
,
629 "is_valid () -> Boolean.\n\
630 Return true if this frame is valid, false if not." },
631 { "name", frapy_name
, METH_NOARGS
,
632 "name () -> String.\n\
633 Return the function name of the frame, or None if it can't be determined." },
634 { "type", frapy_type
, METH_NOARGS
,
635 "type () -> Integer.\n\
636 Return the type of the frame." },
637 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
638 "unwind_stop_reason () -> Integer.\n\
639 Return the reason why it's not possible to find frames older than this." },
640 { "pc", frapy_pc
, METH_NOARGS
,
642 Return the frame's resume address." },
643 { "block", frapy_block
, METH_NOARGS
,
644 "block () -> gdb.Block.\n\
645 Return the frame's code block." },
646 { "function", frapy_function
, METH_NOARGS
,
647 "function () -> gdb.Symbol.\n\
648 Returns the symbol for the function corresponding to this frame." },
649 { "older", frapy_older
, METH_NOARGS
,
650 "older () -> gdb.Frame.\n\
651 Return the frame that called this frame." },
652 { "newer", frapy_newer
, METH_NOARGS
,
653 "newer () -> gdb.Frame.\n\
654 Return the frame called by this frame." },
655 { "find_sal", frapy_find_sal
, METH_NOARGS
,
656 "find_sal () -> gdb.Symtab_and_line.\n\
657 Return the frame's symtab and line." },
658 { "read_var", frapy_read_var
, METH_VARARGS
,
659 "read_var (variable) -> gdb.Value.\n\
660 Return the value of the variable in this frame." },
661 { "select", frapy_select
, METH_NOARGS
,
662 "Select this frame as the user's current frame." },
663 {NULL
} /* Sentinel */
666 static PyTypeObject frame_object_type
= {
667 PyObject_HEAD_INIT (NULL
)
669 "gdb.Frame", /* tp_name */
670 sizeof (frame_object
), /* tp_basicsize */
678 0, /* tp_as_number */
679 0, /* tp_as_sequence */
680 0, /* tp_as_mapping */
683 frapy_str
, /* tp_str */
686 0, /* tp_as_buffer */
687 Py_TPFLAGS_DEFAULT
, /* tp_flags */
688 "GDB frame object", /* tp_doc */
691 frapy_richcompare
, /* tp_richcompare */
692 0, /* tp_weaklistoffset */
695 frame_object_methods
, /* tp_methods */
700 0, /* tp_descr_get */
701 0, /* tp_descr_set */
702 0, /* tp_dictoffset */