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
, "Could not allocate frame object.");
280 /* Try to get the previous frame, to determine if this is the last frame
281 in a corrupt stack. If so, we need to store the frame_id of the next
282 frame and not of this one (which is possibly invalid). */
283 if (get_prev_frame (frame
) == NULL
284 && get_frame_unwind_stop_reason (frame
) != UNWIND_NO_REASON
285 && get_next_frame (frame
) != NULL
)
287 frame_obj
->frame_id
= get_frame_id (get_next_frame (frame
));
288 frame_obj
->frame_id_is_next
= 1;
292 frame_obj
->frame_id
= get_frame_id (frame
);
293 frame_obj
->frame_id_is_next
= 0;
296 frame_obj
->gdbarch
= get_frame_arch (frame
);
301 /* Implementation of gdb.Frame.older (self) -> gdb.Frame.
302 Returns the frame immediately older (outer) to this frame, or None if
306 frapy_older (PyObject
*self
, PyObject
*args
)
308 struct frame_info
*frame
, *prev
;
309 volatile struct gdb_exception except
;
310 PyObject
*prev_obj
= NULL
; /* Initialize to appease gcc warning. */
312 TRY_CATCH (except
, RETURN_MASK_ALL
)
314 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
316 prev
= get_prev_frame (frame
);
318 prev_obj
= (PyObject
*) frame_info_to_frame_object (prev
);
325 GDB_PY_HANDLE_EXCEPTION (except
);
330 /* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
331 Returns the frame immediately newer (inner) to this frame, or None if
335 frapy_newer (PyObject
*self
, PyObject
*args
)
337 struct frame_info
*frame
, *next
;
338 volatile struct gdb_exception except
;
339 PyObject
*next_obj
= NULL
; /* Initialize to appease gcc warning. */
341 TRY_CATCH (except
, RETURN_MASK_ALL
)
343 FRAPY_REQUIRE_VALID ((frame_object
*) self
, frame
);
345 next
= get_next_frame (frame
);
347 next_obj
= (PyObject
*) frame_info_to_frame_object (next
);
354 GDB_PY_HANDLE_EXCEPTION (except
);
359 /* Implementation of gdb.Frame.find_sal (self) -> gdb.Symtab_and_line.
360 Returns the frame's symtab and line. */
363 frapy_find_sal (PyObject
*self
, PyObject
*args
)
365 struct frame_info
*frame
;
366 struct symtab_and_line sal
;
367 struct objfile
*objfile
= NULL
;
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 frame_object
*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
);
510 return (PyObject
*) frame_obj
;
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
, "Invalid frame stop reason.");
531 str
= frame_stop_reason_string (reason
);
532 return PyUnicode_Decode (str
, strlen (str
), host_charset (), NULL
);
535 /* Implements the equality comparison for Frame objects.
536 All other comparison operators will throw a TypeError Python exception,
537 as they aren't valid for frames. */
540 frapy_richcompare (PyObject
*self
, PyObject
*other
, int op
)
544 if (!PyObject_TypeCheck (other
, &frame_object_type
)
545 || (op
!= Py_EQ
&& op
!= Py_NE
))
547 Py_INCREF (Py_NotImplemented
);
548 return Py_NotImplemented
;
551 if (frame_id_eq (((frame_object
*) self
)->frame_id
,
552 ((frame_object
*) other
)->frame_id
))
562 /* Sets up the Frame API in the gdb module. */
565 gdbpy_initialize_frames (void)
567 if (PyType_Ready (&frame_object_type
) < 0)
570 /* Note: These would probably be best exposed as class attributes of Frame,
571 but I don't know how to do it except by messing with the type's dictionary.
572 That seems too messy. */
573 PyModule_AddIntConstant (gdb_module
, "NORMAL_FRAME", NORMAL_FRAME
);
574 PyModule_AddIntConstant (gdb_module
, "DUMMY_FRAME", DUMMY_FRAME
);
575 PyModule_AddIntConstant (gdb_module
, "SIGTRAMP_FRAME", SIGTRAMP_FRAME
);
576 PyModule_AddIntConstant (gdb_module
, "SENTINEL_FRAME", SENTINEL_FRAME
);
577 PyModule_AddIntConstant (gdb_module
,
578 "FRAME_UNWIND_NO_REASON", UNWIND_NO_REASON
);
579 PyModule_AddIntConstant (gdb_module
,
580 "FRAME_UNWIND_NULL_ID", UNWIND_NULL_ID
);
581 PyModule_AddIntConstant (gdb_module
,
582 "FRAME_UNWIND_FIRST_ERROR", UNWIND_FIRST_ERROR
);
583 PyModule_AddIntConstant (gdb_module
,
584 "FRAME_UNWIND_INNER_ID", UNWIND_INNER_ID
);
585 PyModule_AddIntConstant (gdb_module
,
586 "FRAME_UNWIND_SAME_ID", UNWIND_SAME_ID
);
587 PyModule_AddIntConstant (gdb_module
,
588 "FRAME_UNWIND_NO_SAVED_PC", UNWIND_NO_SAVED_PC
);
590 Py_INCREF (&frame_object_type
);
591 PyModule_AddObject (gdb_module
, "Frame", (PyObject
*) &frame_object_type
);
596 static PyMethodDef frame_object_methods
[] = {
597 { "is_valid", frapy_is_valid
, METH_NOARGS
,
598 "is_valid () -> Boolean.\n\
599 Return true if this frame is valid, false if not." },
600 { "name", frapy_name
, METH_NOARGS
,
601 "name () -> String.\n\
602 Return the function name of the frame, or None if it can't be determined." },
603 { "type", frapy_type
, METH_NOARGS
,
604 "type () -> Integer.\n\
605 Return the type of the frame." },
606 { "unwind_stop_reason", frapy_unwind_stop_reason
, METH_NOARGS
,
607 "unwind_stop_reason () -> Integer.\n\
608 Return the reason why it's not possible to find frames older than this." },
609 { "pc", frapy_pc
, METH_NOARGS
,
611 Return the frame's resume address." },
612 { "block", frapy_block
, METH_NOARGS
,
613 "block () -> gdb.Block.\n\
614 Return the frame's code block." },
615 { "function", frapy_function
, METH_NOARGS
,
616 "function () -> gdb.Symbol.\n\
617 Returns the symbol for the function corresponding to this frame." },
618 { "older", frapy_older
, METH_NOARGS
,
619 "older () -> gdb.Frame.\n\
620 Return the frame that called this frame." },
621 { "newer", frapy_newer
, METH_NOARGS
,
622 "newer () -> gdb.Frame.\n\
623 Return the frame called by this frame." },
624 { "find_sal", frapy_find_sal
, METH_NOARGS
,
625 "find_sal () -> gdb.Symtab_and_line.\n\
626 Return the frame's symtab and line." },
627 { "read_var", frapy_read_var
, METH_VARARGS
,
628 "read_var (variable) -> gdb.Value.\n\
629 Return the value of the variable in this frame." },
630 { "select", frapy_select
, METH_NOARGS
,
631 "Select this frame as the user's current frame." },
632 {NULL
} /* Sentinel */
635 static PyTypeObject frame_object_type
= {
636 PyObject_HEAD_INIT (NULL
)
638 "gdb.Frame", /* tp_name */
639 sizeof (frame_object
), /* tp_basicsize */
647 0, /* tp_as_number */
648 0, /* tp_as_sequence */
649 0, /* tp_as_mapping */
652 frapy_str
, /* tp_str */
655 0, /* tp_as_buffer */
656 Py_TPFLAGS_DEFAULT
, /* tp_flags */
657 "GDB frame object", /* tp_doc */
660 frapy_richcompare
, /* tp_richcompare */
661 0, /* tp_weaklistoffset */
664 frame_object_methods
, /* tp_methods */
669 0, /* tp_descr_get */
670 0, /* tp_descr_set */
671 0, /* tp_dictoffset */
674 PyType_GenericNew
/* tp_new */