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
;
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 gdb_py_long_from_ulongest (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
, *fn_block
;
215 volatile struct gdb_exception except
;
217 TRY_CATCH (except
, RETURN_MASK_ALL
)
219 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
220 block
= get_frame_block (frame
, NULL
);
222 GDB_PY_HANDLE_EXCEPTION (except
);
224 for (fn_block
= block
;
225 fn_block
!= NULL
&& BLOCK_FUNCTION (fn_block
) == NULL
;
226 fn_block
= BLOCK_SUPERBLOCK (fn_block
))
229 if (block
== NULL
|| fn_block
== NULL
|| BLOCK_FUNCTION (fn_block
) == NULL
)
231 PyErr_SetString (PyExc_RuntimeError
,
232 _("Cannot locate object file for block."));
240 symt
= SYMBOL_SYMTAB (BLOCK_FUNCTION (fn_block
));
241 return block_to_block_object (block
, symt
->objfile
);
248 /* Implementation of gdb.Frame.function (self) -> gdb.Symbol.
249 Returns the symbol for the function corresponding to this frame. */
252 frapy_function (PyObject
*self
, PyObject
*args
)
254 struct symbol
*sym
= NULL
;
255 struct frame_info
*frame
;
256 volatile struct gdb_exception except
;
258 TRY_CATCH (except
, RETURN_MASK_ALL
)
260 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
262 sym
= find_pc_function (get_frame_address_in_block (frame
));
264 GDB_PY_HANDLE_EXCEPTION (except
);
267 return symbol_to_symbol_object (sym
);
272 /* Convert a frame_info struct to a Python Frame object.
273 Sets a Python exception and returns NULL on error. */
276 frame_info_to_frame_object (struct frame_info
*frame
)
278 frame_object
*frame_obj
;
280 frame_obj
= PyObject_New (frame_object
, &frame_object_type
);
281 if (frame_obj
== NULL
)
283 PyErr_SetString (PyExc_MemoryError
,
284 _("Could not allocate frame object."));
288 /* Try to get the previous frame, to determine if this is the last frame
289 in a corrupt stack. If so, we need to store the frame_id of the next
290 frame and not of this one (which is possibly invalid). */
291 if (get_prev_frame (frame
) == NULL
292 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
293 && get_next_frame (frame
) != NULL
)
295 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
296 frame_obj
->frame_id_is_next
= 1;
300 frame_obj
->frame_id
= get_frame_id (frame
);
301 frame_obj
->frame_id_is_next
= 0;
304 frame_obj
->gdbarch
= get_frame_arch (frame
);
306 return (PyObject
*) frame_obj
;
309 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
310 Returns the frame immediately older (outer) to this frame, or None if
314 frapy_older (PyObject
*self
, PyObject
*args
)
316 struct frame_info
*frame
, *prev
;
317 volatile struct gdb_exception except
;
318 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
320 TRY_CATCH (except
, RETURN_MASK_ALL
)
322 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
324 prev
= get_prev_frame (frame
);
326 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
333 GDB_PY_HANDLE_EXCEPTION (except
);
338 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
339 Returns the frame immediately newer (inner) to this frame, or None if
343 frapy_newer (PyObject
*self
, PyObject
*args
)
345 struct frame_info
*frame
, *next
;
346 volatile struct gdb_exception except
;
347 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
349 TRY_CATCH (except
, RETURN_MASK_ALL
)
351 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
353 next
= get_next_frame (frame
);
355 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
362 GDB_PY_HANDLE_EXCEPTION (except
);
367 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
368 Returns the frame's symtab and line. */
371 frapy_find_sal (PyObject
*self
, PyObject
*args
)
373 struct frame_info
*frame
;
374 struct symtab_and_line sal
;
375 volatile struct gdb_exception except
;
376 PyObject
*sal_obj
= NULL
; /* Initialize to appease gcc warning. */
378 TRY_CATCH (except
, RETURN_MASK_ALL
)
380 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
382 find_frame_sal (frame
, &sal
);
383 sal_obj
= symtab_and_line_to_sal_object (sal
);
385 GDB_PY_HANDLE_EXCEPTION (except
);
390 /* Implementation of gdb.Frame.read_var_value (self, variable,
391 [block]) -> gdb.Value. If the optional block argument is provided
392 start the search from that block, otherwise search from the frame's
393 current block (determined by examining the resume address of the
394 frame). The variable argument must be a string or an instance of a
395 gdb.Symbol. The block argument must be an instance of gdb.Block. Returns
396 NULL on error, with a python exception set. */
398 frapy_read_var (PyObject
*self
, PyObject
*args
)
400 struct frame_info
*frame
;
401 PyObject
*sym_obj
, *block_obj
= NULL
;
402 struct symbol
*var
= NULL
; /* gcc-4.3.2 false warning. */
403 struct value
*val
= NULL
;
404 volatile struct gdb_exception except
;
406 if (!PyArg_ParseTuple (args
, "O|O", &sym_obj
, &block_obj
))
409 if (PyObject_TypeCheck (sym_obj
, &symbol_object_type
))
410 var
= symbol_object_to_symbol (sym_obj
);
411 else if (gdbpy_is_string (sym_obj
))
414 struct block
*block
= NULL
;
415 struct cleanup
*cleanup
;
416 volatile struct gdb_exception except
;
418 var_name
= python_string_to_target_string (sym_obj
);
421 cleanup
= make_cleanup (xfree
, var_name
);
425 block
= block_object_to_block (block_obj
);
428 PyErr_SetString (PyExc_RuntimeError
,
429 _("Second argument must be block."));
434 TRY_CATCH (except
, RETURN_MASK_ALL
)
436 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
439 block
= block_for_pc (get_frame_address_in_block (frame
));
440 var
= lookup_symbol (var_name
, block
, VAR_DOMAIN
, NULL
);
442 GDB_PY_HANDLE_EXCEPTION (except
);
446 PyErr_Format (PyExc_ValueError
,
447 _("Variable '%s' not found."), var_name
);
448 do_cleanups (cleanup
);
453 do_cleanups (cleanup
);
457 PyErr_SetString (PyExc_TypeError
,
458 _("Argument must be a symbol or string."));
462 TRY_CATCH (except
, RETURN_MASK_ALL
)
464 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
466 val
= read_var_value (var
, frame
);
468 GDB_PY_HANDLE_EXCEPTION (except
);
472 PyErr_Format (PyExc_ValueError
,
473 _("Variable cannot be found for symbol '%s'."),
474 SYMBOL_NATURAL_NAME (var
));
478 return value_to_value_object (val
);
481 /* Select this frame. */
484 frapy_select (PyObject
*self
, PyObject
*args
)
486 struct frame_info
*fi
;
487 frame_object
*frame
= (frame_object
*) self
;
488 volatile struct gdb_exception except
;
490 TRY_CATCH (except
, RETURN_MASK_ALL
)
492 FRAPY_REQUIRE_VALID (frame
, fi
);
496 GDB_PY_HANDLE_EXCEPTION (except
);
501 /* Implementation of gdb.newest_frame () -> gdb.Frame.
502 Returns the newest frame object. */
505 gdbpy_newest_frame (PyObject
*self
, PyObject
*args
)
507 struct frame_info
*frame
;
508 PyObject
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
509 volatile struct gdb_exception except
;
511 TRY_CATCH (except
, RETURN_MASK_ALL
)
513 frame
= get_current_frame ();
514 frame_obj
= frame_info_to_frame_object (frame
);
516 GDB_PY_HANDLE_EXCEPTION (except
);
521 /* Implementation of gdb.selected_frame () -> gdb.Frame.
522 Returns the selected frame object. */
525 gdbpy_selected_frame (PyObject
*self
, PyObject
*args
)
527 struct frame_info
*frame
;
528 PyObject
*frame_obj
= NULL
; /* Initialize to appease gcc warning. */
529 volatile struct gdb_exception except
;
531 TRY_CATCH (except
, RETURN_MASK_ALL
)
533 frame
= get_selected_frame ("No frame is currently selected.");
534 frame_obj
= frame_info_to_frame_object (frame
);
536 GDB_PY_HANDLE_EXCEPTION (except
);
541 /* Implementation of gdb.stop_reason_string (Integer) -> String.
542 Return a string explaining the unwind stop reason. */
545 gdbpy_frame_stop_reason_string (PyObject
*self
, PyObject
*args
)
550 if (!PyArg_ParseTuple (args
, "i", &reason
))
553 if (reason
< 0 || reason
> UNWIND_NO_SAVED_PC
)
555 PyErr_SetString (PyExc_ValueError
,
556 _("Invalid frame stop reason."));
560 str
= frame_stop_reason_string (reason
);
561 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
564 /* Implements the equality comparison for Frame objects.
565 All other comparison operators will throw a TypeError Python exception,
566 as they aren't valid for frames. */
569 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
573 if (!PyObject_TypeCheck (other
, &frame_object_type
)
574 || (op
!= Py_EQ
&& op
!= Py_NE
))
576 Py_INCREF (Py_NotImplemented
);
577 return Py_NotImplemented
;
580 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
581 ((frame_object
*) other
)->frame_id
))
591 /* Sets up the Frame API in the gdb module. */
594 gdbpy_initialize_frames (void)
596 if (PyType_Ready (&frame_object_type
) < 0)
599 /* Note: These would probably be best exposed as class attributes of
600 Frame, but I don't know how to do it except by messing with the
601 type's dictionary. That seems too messy. */
602 PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
);
603 PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
);
604 PyModule_AddIntConstant (gdb_module
, "INLINE_FRAME", INLINE_FRAME
);
605 PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME", SIGTRAMP_FRAME
);
606 PyModule_AddIntConstant (gdb_module
, "ARCH_FRAME", ARCH_FRAME
);
607 PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME", SENTINEL_FRAME
);
608 PyModule_AddIntConstant (gdb_module
,
609 "FRAME_UNWIND_NO_REASON", UNWIND_NO_REASON
);
610 PyModule_AddIntConstant (gdb_module
,
611 "FRAME_UNWIND_NULL_ID", UNWIND_NULL_ID
);
612 PyModule_AddIntConstant (gdb_module
,
613 "FRAME_UNWIND_FIRST_ERROR", UNWIND_FIRST_ERROR
);
614 PyModule_AddIntConstant (gdb_module
,
615 "FRAME_UNWIND_INNER_ID", UNWIND_INNER_ID
);
616 PyModule_AddIntConstant (gdb_module
,
617 "FRAME_UNWIND_SAME_ID", UNWIND_SAME_ID
);
618 PyModule_AddIntConstant (gdb_module
,
619 "FRAME_UNWIND_NO_SAVED_PC", UNWIND_NO_SAVED_PC
);
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 */
705 PyType_GenericNew
/* tp_new */