1 /* Python interface to inferiors.
3 Copyright (C) 2009-2012 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/>. */
21 #include "exceptions.h"
23 #include "gdbthread.h"
27 #include "python-internal.h"
28 #include "arch-utils.h"
30 #include "gdb_signals.h"
32 #include "py-stopevent.h"
34 struct threadlist_entry {
35 thread_object *thread_obj;
36 struct threadlist_entry *next;
43 /* The inferior we represent. */
44 struct inferior *inferior;
46 /* thread_object instances under this inferior. This list owns a
47 reference to each object it contains. */
48 struct threadlist_entry *threads;
50 /* Number of threads in the list. */
54 static PyTypeObject inferior_object_type;
56 static const struct inferior_data *infpy_inf_data_key;
62 /* These are kept just for mbpy_str. */
67 static PyTypeObject membuf_object_type;
69 /* Require that INFERIOR be a valid inferior ID. */
70 #define INFPY_REQUIRE_VALID(Inferior) \
72 if (!Inferior->inferior) \
74 PyErr_SetString (PyExc_RuntimeError, \
75 _("Inferior no longer exists.")); \
81 python_on_normal_stop (struct bpstats *bs, int print_frame)
83 struct cleanup *cleanup;
84 enum target_signal stop_signal;
86 if (!find_thread_ptid (inferior_ptid))
89 stop_signal = inferior_thread ()->suspend.stop_signal;
91 cleanup = ensure_python_env (get_current_arch (), current_language);
93 if (emit_stop_event (bs, stop_signal) < 0)
96 do_cleanups (cleanup);
100 python_on_resume (ptid_t ptid)
102 struct cleanup *cleanup;
104 cleanup = ensure_python_env (target_gdbarch, current_language);
106 if (emit_continue_event (ptid) < 0)
107 gdbpy_print_stack ();
109 do_cleanups (cleanup);
113 python_inferior_exit (struct inferior *inf)
115 struct cleanup *cleanup;
116 const LONGEST *exit_code = NULL;
118 cleanup = ensure_python_env (target_gdbarch, current_language);
120 if (inf->has_exit_code)
121 exit_code = &inf->exit_code;
123 if (emit_exited_event (exit_code, inf) < 0)
124 gdbpy_print_stack ();
126 do_cleanups (cleanup);
129 /* Callback used to notify Python listeners about new objfiles loaded in the
133 python_new_objfile (struct objfile *objfile)
135 struct cleanup *cleanup;
140 cleanup = ensure_python_env (get_objfile_arch (objfile), current_language);
142 if (emit_new_objfile_event (objfile) < 0)
143 gdbpy_print_stack ();
145 do_cleanups (cleanup);
148 /* Return a reference to the Python object of type Inferior
149 representing INFERIOR. If the object has already been created,
150 return it and increment the reference count, otherwise, create it.
151 Return NULL on failure. */
153 inferior_to_inferior_object (struct inferior *inferior)
155 inferior_object *inf_obj;
157 inf_obj = inferior_data (inferior, infpy_inf_data_key);
160 inf_obj = PyObject_New (inferior_object, &inferior_object_type);
164 inf_obj->inferior = inferior;
165 inf_obj->threads = NULL;
166 inf_obj->nthreads = 0;
168 set_inferior_data (inferior, infpy_inf_data_key, inf_obj);
172 Py_INCREF ((PyObject *)inf_obj);
174 return (PyObject *) inf_obj;
177 /* Finds the Python Inferior object for the given PID. Returns a
178 reference, or NULL if PID does not match any inferior object. */
181 find_inferior_object (int pid)
183 struct inflist_entry *p;
184 struct inferior *inf = find_inferior_pid (pid);
187 return inferior_to_inferior_object (inf);
193 find_thread_object (ptid_t ptid)
196 struct threadlist_entry *thread;
198 thread_object *found = NULL;
204 inf_obj = find_inferior_object (pid);
209 for (thread = ((inferior_object *)inf_obj)->threads; thread;
210 thread = thread->next)
211 if (ptid_equal (thread->thread_obj->thread->ptid, ptid))
213 found = thread->thread_obj;
226 add_thread_object (struct thread_info *tp)
228 struct cleanup *cleanup;
229 thread_object *thread_obj;
230 inferior_object *inf_obj;
231 struct threadlist_entry *entry;
233 cleanup = ensure_python_env (python_gdbarch, python_language);
235 thread_obj = create_thread_object (tp);
238 gdbpy_print_stack ();
239 do_cleanups (cleanup);
243 inf_obj = (inferior_object *) thread_obj->inf_obj;
245 entry = xmalloc (sizeof (struct threadlist_entry));
246 entry->thread_obj = thread_obj;
247 entry->next = inf_obj->threads;
249 inf_obj->threads = entry;
252 do_cleanups (cleanup);
256 delete_thread_object (struct thread_info *tp, int ignore)
258 struct cleanup *cleanup;
259 inferior_object *inf_obj;
260 thread_object *thread_obj;
261 struct threadlist_entry **entry, *tmp;
263 cleanup = ensure_python_env (python_gdbarch, python_language);
265 inf_obj = (inferior_object *) find_inferior_object (PIDGET(tp->ptid));
268 do_cleanups (cleanup);
272 /* Find thread entry in its inferior's thread_list. */
273 for (entry = &inf_obj->threads; *entry != NULL; entry =
275 if ((*entry)->thread_obj->thread == tp)
281 do_cleanups (cleanup);
286 tmp->thread_obj->thread = NULL;
288 *entry = (*entry)->next;
291 Py_DECREF (tmp->thread_obj);
295 do_cleanups (cleanup);
299 infpy_threads (PyObject *self, PyObject *args)
302 struct threadlist_entry *entry;
303 inferior_object *inf_obj = (inferior_object *) self;
306 INFPY_REQUIRE_VALID (inf_obj);
308 tuple = PyTuple_New (inf_obj->nthreads);
312 for (i = 0, entry = inf_obj->threads; i < inf_obj->nthreads;
313 i++, entry = entry->next)
315 Py_INCREF (entry->thread_obj);
316 PyTuple_SET_ITEM (tuple, i, (PyObject *) entry->thread_obj);
323 infpy_get_num (PyObject *self, void *closure)
325 inferior_object *inf = (inferior_object *) self;
327 INFPY_REQUIRE_VALID (inf);
329 return PyLong_FromLong (inf->inferior->num);
333 infpy_get_pid (PyObject *self, void *closure)
335 inferior_object *inf = (inferior_object *) self;
337 INFPY_REQUIRE_VALID (inf);
339 return PyLong_FromLong (inf->inferior->pid);
343 infpy_get_was_attached (PyObject *self, void *closure)
345 inferior_object *inf = (inferior_object *) self;
347 INFPY_REQUIRE_VALID (inf);
348 if (inf->inferior->attach_flag)
354 build_inferior_list (struct inferior *inf, void *arg)
356 PyObject *list = arg;
357 PyObject *inferior = inferior_to_inferior_object (inf);
363 success = PyList_Append (list, inferior);
364 Py_DECREF (inferior);
372 /* Implementation of gdb.inferiors () -> (gdb.Inferior, ...).
373 Returns a tuple of all inferiors. */
375 gdbpy_inferiors (PyObject *unused, PyObject *unused2)
377 PyObject *list, *tuple;
379 list = PyList_New (0);
383 if (iterate_over_inferiors (build_inferior_list, list))
389 tuple = PyList_AsTuple (list);
395 /* Membuf and memory manipulation. */
397 /* Implementation of gdb.read_memory (address, length).
398 Returns a Python buffer object with LENGTH bytes of the inferior's
399 memory at ADDRESS. Both arguments are integers. Returns NULL on error,
400 with a python exception set. */
402 infpy_read_memory (PyObject *self, PyObject *args, PyObject *kw)
405 CORE_ADDR addr, length;
407 membuf_object *membuf_obj;
408 PyObject *addr_obj, *length_obj, *result;
409 volatile struct gdb_exception except;
410 static char *keywords[] = { "address", "length", NULL };
412 if (! PyArg_ParseTupleAndKeywords (args, kw, "OO", keywords,
413 &addr_obj, &length_obj))
416 TRY_CATCH (except, RETURN_MASK_ALL)
418 if (!get_addr_from_python (addr_obj, &addr)
419 || !get_addr_from_python (length_obj, &length))
425 buffer = xmalloc (length);
427 read_memory (addr, buffer, length);
429 if (except.reason < 0)
432 GDB_PY_HANDLE_EXCEPTION (except);
441 membuf_obj = PyObject_New (membuf_object, &membuf_object_type);
442 if (membuf_obj == NULL)
445 PyErr_SetString (PyExc_MemoryError,
446 _("Could not allocate memory buffer object."));
450 membuf_obj->buffer = buffer;
451 membuf_obj->addr = addr;
452 membuf_obj->length = length;
454 result = PyBuffer_FromReadWriteObject ((PyObject *) membuf_obj, 0,
456 Py_DECREF (membuf_obj);
460 /* Implementation of gdb.write_memory (address, buffer [, length]).
461 Writes the contents of BUFFER (a Python object supporting the read
462 buffer protocol) at ADDRESS in the inferior's memory. Write LENGTH
463 bytes from BUFFER, or its entire contents if the argument is not
464 provided. The function returns nothing. Returns NULL on error, with
465 a python exception set. */
467 infpy_write_memory (PyObject *self, PyObject *args, PyObject *kw)
472 CORE_ADDR addr, length;
473 PyObject *addr_obj, *length_obj = NULL;
474 volatile struct gdb_exception except;
475 static char *keywords[] = { "address", "buffer", "length", NULL };
478 if (! PyArg_ParseTupleAndKeywords (args, kw, "Os#|O", keywords,
479 &addr_obj, &buffer, &buf_len,
483 TRY_CATCH (except, RETURN_MASK_ALL)
485 if (!get_addr_from_python (addr_obj, &addr))
493 else if (!get_addr_from_python (length_obj, &length))
498 write_memory (addr, buffer, length);
500 GDB_PY_HANDLE_EXCEPTION (except);
508 /* Destructor of Membuf objects. */
510 mbpy_dealloc (PyObject *self)
512 xfree (((membuf_object *) self)->buffer);
513 self->ob_type->tp_free (self);
516 /* Return a description of the Membuf object. */
518 mbpy_str (PyObject *self)
520 membuf_object *membuf_obj = (membuf_object *) self;
522 return PyString_FromFormat (_("Memory buffer for address %s, \
523 which is %s bytes long."),
524 paddress (python_gdbarch, membuf_obj->addr),
525 pulongest (membuf_obj->length));
529 get_read_buffer (PyObject *self, Py_ssize_t segment, void **ptrptr)
531 membuf_object *membuf_obj = (membuf_object *) self;
535 PyErr_SetString (PyExc_SystemError,
536 _("The memory buffer supports only one segment."));
540 *ptrptr = membuf_obj->buffer;
542 return membuf_obj->length;
546 get_write_buffer (PyObject *self, Py_ssize_t segment, void **ptrptr)
548 return get_read_buffer (self, segment, ptrptr);
552 get_seg_count (PyObject *self, Py_ssize_t *lenp)
555 *lenp = ((membuf_object *) self)->length;
561 get_char_buffer (PyObject *self, Py_ssize_t segment, char **ptrptr)
566 ret = get_read_buffer (self, segment, &ptr);
567 *ptrptr = (char *) ptr;
573 gdb.search_memory (address, length, pattern). ADDRESS is the
574 address to start the search. LENGTH specifies the scope of the
575 search from ADDRESS. PATTERN is the pattern to search for (and
576 must be a Python object supporting the buffer protocol).
577 Returns a Python Long object holding the address where the pattern
578 was located, or if the pattern was not found, returns None. Returns NULL
579 on error, with a python exception set. */
581 infpy_search_memory (PyObject *self, PyObject *args, PyObject *kw)
583 CORE_ADDR start_addr, length;
584 static char *keywords[] = { "address", "length", "pattern", NULL };
585 PyObject *pattern, *start_addr_obj, *length_obj;
586 volatile struct gdb_exception except;
587 Py_ssize_t pattern_size;
589 CORE_ADDR found_addr;
592 if (! PyArg_ParseTupleAndKeywords (args, kw, "OOO", keywords,
593 &start_addr_obj, &length_obj,
597 if (get_addr_from_python (start_addr_obj, &start_addr)
598 && get_addr_from_python (length_obj, &length))
602 PyErr_SetString (PyExc_ValueError,
603 _("Search range is empty."));
606 /* Watch for overflows. */
607 else if (length > CORE_ADDR_MAX
608 || (start_addr + length - 1) < start_addr)
610 PyErr_SetString (PyExc_ValueError,
611 _("The search range is too large."));
619 if (!PyObject_CheckReadBuffer (pattern))
621 PyErr_SetString (PyExc_RuntimeError,
622 _("The pattern is not a Python buffer."));
627 if (PyObject_AsReadBuffer (pattern, &buffer, &pattern_size) == -1)
630 TRY_CATCH (except, RETURN_MASK_ALL)
632 found = target_search_memory (start_addr, length,
633 buffer, pattern_size,
636 GDB_PY_HANDLE_EXCEPTION (except);
639 return PyLong_FromLong (found_addr);
644 /* Implementation of gdb.Inferior.is_valid (self) -> Boolean.
645 Returns True if this inferior object still exists in GDB. */
648 infpy_is_valid (PyObject *self, PyObject *args)
650 inferior_object *inf = (inferior_object *) self;
659 infpy_dealloc (PyObject *obj)
661 inferior_object *inf_obj = (inferior_object *) obj;
662 struct inferior *inf = inf_obj->inferior;
667 set_inferior_data (inf, infpy_inf_data_key, NULL);
670 /* Clear the INFERIOR pointer in an Inferior object and clear the
673 py_free_inferior (struct inferior *inf, void *datum)
676 struct cleanup *cleanup;
677 inferior_object *inf_obj = datum;
678 struct threadlist_entry *th_entry, *th_tmp;
680 cleanup = ensure_python_env (python_gdbarch, python_language);
682 inf_obj->inferior = NULL;
684 /* Deallocate threads list. */
685 for (th_entry = inf_obj->threads; th_entry != NULL;)
687 Py_DECREF (th_entry->thread_obj);
690 th_entry = th_entry->next;
694 inf_obj->nthreads = 0;
696 Py_DECREF ((PyObject *) inf_obj);
697 do_cleanups (cleanup);
700 /* Implementation of gdb.selected_inferior() -> gdb.Inferior.
701 Returns the current inferior object. */
704 gdbpy_selected_inferior (PyObject *self, PyObject *args)
708 inf_obj = inferior_to_inferior_object (current_inferior ());
715 gdbpy_initialize_inferior (void)
717 if (PyType_Ready (&inferior_object_type) < 0)
720 Py_INCREF (&inferior_object_type);
721 PyModule_AddObject (gdb_module, "Inferior",
722 (PyObject *) &inferior_object_type);
725 register_inferior_data_with_cleanup (py_free_inferior);
727 observer_attach_new_thread (add_thread_object);
728 observer_attach_thread_exit (delete_thread_object);
729 observer_attach_normal_stop (python_on_normal_stop);
730 observer_attach_target_resumed (python_on_resume);
731 observer_attach_inferior_exit (python_inferior_exit);
732 observer_attach_new_objfile (python_new_objfile);
734 membuf_object_type.tp_new = PyType_GenericNew;
735 if (PyType_Ready (&membuf_object_type) < 0)
738 Py_INCREF (&membuf_object_type);
739 PyModule_AddObject (gdb_module, "Membuf", (PyObject *)
740 &membuf_object_type);
743 static PyGetSetDef inferior_object_getset[] =
745 { "num", infpy_get_num, NULL, "ID of inferior, as assigned by GDB.", NULL },
746 { "pid", infpy_get_pid, NULL, "PID of inferior, as assigned by the OS.",
748 { "was_attached", infpy_get_was_attached, NULL,
749 "True if the inferior was created using 'attach'.", NULL },
753 static PyMethodDef inferior_object_methods[] =
755 { "is_valid", infpy_is_valid, METH_NOARGS,
756 "is_valid () -> Boolean.\n\
757 Return true if this inferior is valid, false if not." },
758 { "threads", infpy_threads, METH_NOARGS,
759 "Return all the threads of this inferior." },
760 { "read_memory", (PyCFunction) infpy_read_memory,
761 METH_VARARGS | METH_KEYWORDS,
762 "read_memory (address, length) -> buffer\n\
763 Return a buffer object for reading from the inferior's memory." },
764 { "write_memory", (PyCFunction) infpy_write_memory,
765 METH_VARARGS | METH_KEYWORDS,
766 "write_memory (address, buffer [, length])\n\
767 Write the given buffer object to the inferior's memory." },
768 { "search_memory", (PyCFunction) infpy_search_memory,
769 METH_VARARGS | METH_KEYWORDS,
770 "search_memory (address, length, pattern) -> long\n\
771 Return a long with the address of a match, or None." },
775 static PyTypeObject inferior_object_type =
777 PyObject_HEAD_INIT (NULL)
779 "gdb.Inferior", /* tp_name */
780 sizeof (inferior_object), /* tp_basicsize */
782 infpy_dealloc, /* tp_dealloc */
788 0, /* tp_as_number */
789 0, /* tp_as_sequence */
790 0, /* tp_as_mapping */
796 0, /* tp_as_buffer */
797 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_ITER, /* tp_flags */
798 "GDB inferior object", /* tp_doc */
801 0, /* tp_richcompare */
802 0, /* tp_weaklistoffset */
805 inferior_object_methods, /* tp_methods */
807 inferior_object_getset, /* tp_getset */
810 0, /* tp_descr_get */
811 0, /* tp_descr_set */
812 0, /* tp_dictoffset */
817 /* Python doesn't provide a decent way to get compatibility here. */
818 #if HAVE_LIBPYTHON2_4
819 #define CHARBUFFERPROC_NAME getcharbufferproc
821 #define CHARBUFFERPROC_NAME charbufferproc
824 static PyBufferProcs buffer_procs = {
828 /* The cast here works around a difference between Python 2.4 and
830 (CHARBUFFERPROC_NAME) get_char_buffer
833 static PyTypeObject membuf_object_type = {
834 PyObject_HEAD_INIT (NULL)
836 "gdb.Membuf", /*tp_name*/
837 sizeof (membuf_object), /*tp_basicsize*/
839 mbpy_dealloc, /*tp_dealloc*/
846 0, /*tp_as_sequence*/
853 &buffer_procs, /*tp_as_buffer*/
854 Py_TPFLAGS_DEFAULT, /*tp_flags*/
855 "GDB memory buffer object", /*tp_doc*/
858 0, /* tp_richcompare */
859 0, /* tp_weaklistoffset */
867 0, /* tp_descr_get */
868 0, /* tp_descr_set */
869 0, /* tp_dictoffset */