1 /* Python interface to inferiors.
3 Copyright (C) 2009-2017 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/>. */
22 #include "gdbthread.h"
26 #include "python-internal.h"
27 #include "arch-utils.h"
29 #include "gdb_signals.h"
31 #include "py-stopevent.h"
33 struct threadlist_entry
{
34 thread_object
*thread_obj
;
35 struct threadlist_entry
*next
;
42 /* The inferior we represent. */
43 struct inferior
*inferior
;
45 /* thread_object instances under this inferior. This list owns a
46 reference to each object it contains. */
47 struct threadlist_entry
*threads
;
49 /* Number of threads in the list. */
53 extern PyTypeObject inferior_object_type
54 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("inferior_object");
56 static const struct inferior_data
*infpy_inf_data_key
;
62 /* These are kept just for mbpy_str. */
67 extern PyTypeObject membuf_object_type
68 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("membuf_object");
70 /* Require that INFERIOR be a valid inferior ID. */
71 #define INFPY_REQUIRE_VALID(Inferior) \
73 if (!Inferior->inferior) \
75 PyErr_SetString (PyExc_RuntimeError, \
76 _("Inferior no longer exists.")); \
82 python_on_normal_stop (struct bpstats
*bs
, int print_frame
)
84 enum gdb_signal stop_signal
;
86 if (!gdb_python_initialized
)
89 if (!find_thread_ptid (inferior_ptid
))
92 stop_signal
= inferior_thread ()->suspend
.stop_signal
;
94 gdbpy_enter
enter_py (get_current_arch (), current_language
);
96 if (emit_stop_event (bs
, stop_signal
) < 0)
101 python_on_resume (ptid_t ptid
)
103 if (!gdb_python_initialized
)
106 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
108 if (emit_continue_event (ptid
) < 0)
109 gdbpy_print_stack ();
112 /* Callback, registered as an observer, that notifies Python listeners
113 when an inferior function call is about to be made. */
116 python_on_inferior_call_pre (ptid_t thread
, CORE_ADDR address
)
118 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
120 if (emit_inferior_call_event (INFERIOR_CALL_PRE
, thread
, address
) < 0)
121 gdbpy_print_stack ();
124 /* Callback, registered as an observer, that notifies Python listeners
125 when an inferior function call has completed. */
128 python_on_inferior_call_post (ptid_t thread
, CORE_ADDR address
)
130 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
132 if (emit_inferior_call_event (INFERIOR_CALL_POST
, thread
, address
) < 0)
133 gdbpy_print_stack ();
136 /* Callback, registered as an observer, that notifies Python listeners
137 when a part of memory has been modified by user action (eg via a
141 python_on_memory_change (struct inferior
*inferior
, CORE_ADDR addr
, ssize_t len
, const bfd_byte
*data
)
143 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
145 if (emit_memory_changed_event (addr
, len
) < 0)
146 gdbpy_print_stack ();
149 /* Callback, registered as an observer, that notifies Python listeners
150 when a register has been modified by user action (eg via a 'set'
154 python_on_register_change (struct frame_info
*frame
, int regnum
)
156 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
158 if (emit_register_changed_event (frame
, regnum
) < 0)
159 gdbpy_print_stack ();
163 python_inferior_exit (struct inferior
*inf
)
165 const LONGEST
*exit_code
= NULL
;
167 if (!gdb_python_initialized
)
170 gdbpy_enter
enter_py (target_gdbarch (), current_language
);
172 if (inf
->has_exit_code
)
173 exit_code
= &inf
->exit_code
;
175 if (emit_exited_event (exit_code
, inf
) < 0)
176 gdbpy_print_stack ();
179 /* Callback used to notify Python listeners about new objfiles loaded in the
180 inferior. OBJFILE may be NULL which means that the objfile list has been
181 cleared (emptied). */
184 python_new_objfile (struct objfile
*objfile
)
186 if (!gdb_python_initialized
)
189 gdbpy_enter
enter_py (objfile
!= NULL
190 ? get_objfile_arch (objfile
)
196 if (emit_clear_objfiles_event () < 0)
197 gdbpy_print_stack ();
201 if (emit_new_objfile_event (objfile
) < 0)
202 gdbpy_print_stack ();
206 /* Return a reference to the Python object of type Inferior
207 representing INFERIOR. If the object has already been created,
208 return it and increment the reference count, otherwise, create it.
209 Return NULL on failure. */
211 inferior_to_inferior_object (struct inferior
*inferior
)
213 inferior_object
*inf_obj
;
215 inf_obj
= (inferior_object
*) inferior_data (inferior
, infpy_inf_data_key
);
218 inf_obj
= PyObject_New (inferior_object
, &inferior_object_type
);
222 inf_obj
->inferior
= inferior
;
223 inf_obj
->threads
= NULL
;
224 inf_obj
->nthreads
= 0;
226 set_inferior_data (inferior
, infpy_inf_data_key
, inf_obj
);
230 Py_INCREF ((PyObject
*)inf_obj
);
232 return (PyObject
*) inf_obj
;
235 /* Finds the Python Inferior object for the given PID. Returns a
236 reference, or NULL if PID does not match any inferior object. */
239 find_inferior_object (int pid
)
241 struct inferior
*inf
= find_inferior_pid (pid
);
244 return inferior_to_inferior_object (inf
);
250 find_thread_object (ptid_t ptid
)
253 struct threadlist_entry
*thread
;
255 thread_object
*found
= NULL
;
257 pid
= ptid_get_pid (ptid
);
261 inf_obj
= find_inferior_object (pid
);
266 for (thread
= ((inferior_object
*)inf_obj
)->threads
; thread
;
267 thread
= thread
->next
)
268 if (ptid_equal (thread
->thread_obj
->thread
->ptid
, ptid
))
270 found
= thread
->thread_obj
;
283 add_thread_object (struct thread_info
*tp
)
285 thread_object
*thread_obj
;
286 inferior_object
*inf_obj
;
287 struct threadlist_entry
*entry
;
289 if (!gdb_python_initialized
)
292 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
294 thread_obj
= create_thread_object (tp
);
297 gdbpy_print_stack ();
301 inf_obj
= (inferior_object
*) thread_obj
->inf_obj
;
303 entry
= XNEW (struct threadlist_entry
);
304 entry
->thread_obj
= thread_obj
;
305 entry
->next
= inf_obj
->threads
;
307 inf_obj
->threads
= entry
;
312 delete_thread_object (struct thread_info
*tp
, int ignore
)
314 inferior_object
*inf_obj
;
315 struct threadlist_entry
**entry
, *tmp
;
317 if (!gdb_python_initialized
)
320 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
323 = (inferior_object
*) find_inferior_object (ptid_get_pid (tp
->ptid
));
327 /* Find thread entry in its inferior's thread_list. */
328 for (entry
= &inf_obj
->threads
; *entry
!= NULL
; entry
=
330 if ((*entry
)->thread_obj
->thread
== tp
)
340 tmp
->thread_obj
->thread
= NULL
;
342 *entry
= (*entry
)->next
;
345 Py_DECREF (tmp
->thread_obj
);
351 infpy_threads (PyObject
*self
, PyObject
*args
)
354 struct threadlist_entry
*entry
;
355 inferior_object
*inf_obj
= (inferior_object
*) self
;
358 INFPY_REQUIRE_VALID (inf_obj
);
362 update_thread_list ();
364 CATCH (except
, RETURN_MASK_ALL
)
366 GDB_PY_HANDLE_EXCEPTION (except
);
370 tuple
= PyTuple_New (inf_obj
->nthreads
);
374 for (i
= 0, entry
= inf_obj
->threads
; i
< inf_obj
->nthreads
;
375 i
++, entry
= entry
->next
)
377 Py_INCREF (entry
->thread_obj
);
378 PyTuple_SET_ITEM (tuple
, i
, (PyObject
*) entry
->thread_obj
);
385 infpy_get_num (PyObject
*self
, void *closure
)
387 inferior_object
*inf
= (inferior_object
*) self
;
389 INFPY_REQUIRE_VALID (inf
);
391 return PyLong_FromLong (inf
->inferior
->num
);
395 infpy_get_pid (PyObject
*self
, void *closure
)
397 inferior_object
*inf
= (inferior_object
*) self
;
399 INFPY_REQUIRE_VALID (inf
);
401 return PyLong_FromLong (inf
->inferior
->pid
);
405 infpy_get_was_attached (PyObject
*self
, void *closure
)
407 inferior_object
*inf
= (inferior_object
*) self
;
409 INFPY_REQUIRE_VALID (inf
);
410 if (inf
->inferior
->attach_flag
)
416 build_inferior_list (struct inferior
*inf
, void *arg
)
418 PyObject
*list
= (PyObject
*) arg
;
419 PyObject
*inferior
= inferior_to_inferior_object (inf
);
425 success
= PyList_Append (list
, inferior
);
426 Py_DECREF (inferior
);
434 /* Implementation of gdb.inferiors () -> (gdb.Inferior, ...).
435 Returns a tuple of all inferiors. */
437 gdbpy_inferiors (PyObject
*unused
, PyObject
*unused2
)
439 gdbpy_ref
list (PyList_New (0));
443 if (iterate_over_inferiors (build_inferior_list
, list
.get ()))
446 return PyList_AsTuple (list
.get ());
449 /* Membuf and memory manipulation. */
451 /* Implementation of Inferior.read_memory (address, length).
452 Returns a Python buffer object with LENGTH bytes of the inferior's
453 memory at ADDRESS. Both arguments are integers. Returns NULL on error,
454 with a python exception set. */
456 infpy_read_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
458 CORE_ADDR addr
, length
;
459 gdb_byte
*buffer
= NULL
;
460 membuf_object
*membuf_obj
;
461 PyObject
*addr_obj
, *length_obj
, *result
;
462 static char *keywords
[] = { "address", "length", NULL
};
464 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OO", keywords
,
465 &addr_obj
, &length_obj
))
468 if (get_addr_from_python (addr_obj
, &addr
) < 0
469 || get_addr_from_python (length_obj
, &length
) < 0)
474 buffer
= (gdb_byte
*) xmalloc (length
);
476 read_memory (addr
, buffer
, length
);
478 CATCH (except
, RETURN_MASK_ALL
)
481 GDB_PY_HANDLE_EXCEPTION (except
);
485 membuf_obj
= PyObject_New (membuf_object
, &membuf_object_type
);
486 if (membuf_obj
== NULL
)
492 membuf_obj
->buffer
= buffer
;
493 membuf_obj
->addr
= addr
;
494 membuf_obj
->length
= length
;
497 result
= PyMemoryView_FromObject ((PyObject
*) membuf_obj
);
499 result
= PyBuffer_FromReadWriteObject ((PyObject
*) membuf_obj
, 0,
502 Py_DECREF (membuf_obj
);
507 /* Implementation of Inferior.write_memory (address, buffer [, length]).
508 Writes the contents of BUFFER (a Python object supporting the read
509 buffer protocol) at ADDRESS in the inferior's memory. Write LENGTH
510 bytes from BUFFER, or its entire contents if the argument is not
511 provided. The function returns nothing. Returns NULL on error, with
512 a python exception set. */
514 infpy_write_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
516 struct gdb_exception except
= exception_none
;
518 const gdb_byte
*buffer
;
519 CORE_ADDR addr
, length
;
520 PyObject
*addr_obj
, *length_obj
= NULL
;
521 static char *keywords
[] = { "address", "buffer", "length", NULL
};
525 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "Os*|O", keywords
,
530 buffer
= (const gdb_byte
*) pybuf
.buf
;
533 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "Os#|O", keywords
,
534 &addr_obj
, &buffer
, &buf_len
,
538 buffer
= (const gdb_byte
*) buffer
;
541 if (get_addr_from_python (addr_obj
, &addr
) < 0)
546 else if (get_addr_from_python (length_obj
, &length
) < 0)
551 write_memory_with_notification (addr
, buffer
, length
);
553 CATCH (ex
, RETURN_MASK_ALL
)
560 PyBuffer_Release (&pybuf
);
562 GDB_PY_HANDLE_EXCEPTION (except
);
568 PyBuffer_Release (&pybuf
);
573 /* Destructor of Membuf objects. */
575 mbpy_dealloc (PyObject
*self
)
577 xfree (((membuf_object
*) self
)->buffer
);
578 Py_TYPE (self
)->tp_free (self
);
581 /* Return a description of the Membuf object. */
583 mbpy_str (PyObject
*self
)
585 membuf_object
*membuf_obj
= (membuf_object
*) self
;
587 return PyString_FromFormat (_("Memory buffer for address %s, \
588 which is %s bytes long."),
589 paddress (python_gdbarch
, membuf_obj
->addr
),
590 pulongest (membuf_obj
->length
));
596 get_buffer (PyObject
*self
, Py_buffer
*buf
, int flags
)
598 membuf_object
*membuf_obj
= (membuf_object
*) self
;
601 ret
= PyBuffer_FillInfo (buf
, self
, membuf_obj
->buffer
,
602 membuf_obj
->length
, 0,
612 get_read_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
614 membuf_object
*membuf_obj
= (membuf_object
*) self
;
618 PyErr_SetString (PyExc_SystemError
,
619 _("The memory buffer supports only one segment."));
623 *ptrptr
= membuf_obj
->buffer
;
625 return membuf_obj
->length
;
629 get_write_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
631 return get_read_buffer (self
, segment
, ptrptr
);
635 get_seg_count (PyObject
*self
, Py_ssize_t
*lenp
)
638 *lenp
= ((membuf_object
*) self
)->length
;
644 get_char_buffer (PyObject
*self
, Py_ssize_t segment
, char **ptrptr
)
649 ret
= get_read_buffer (self
, segment
, &ptr
);
650 *ptrptr
= (char *) ptr
;
658 gdb.search_memory (address, length, pattern). ADDRESS is the
659 address to start the search. LENGTH specifies the scope of the
660 search from ADDRESS. PATTERN is the pattern to search for (and
661 must be a Python object supporting the buffer protocol).
662 Returns a Python Long object holding the address where the pattern
663 was located, or if the pattern was not found, returns None. Returns NULL
664 on error, with a python exception set. */
666 infpy_search_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
668 struct gdb_exception except
= exception_none
;
669 CORE_ADDR start_addr
, length
;
670 static char *keywords
[] = { "address", "length", "pattern", NULL
};
671 PyObject
*start_addr_obj
, *length_obj
;
672 Py_ssize_t pattern_size
;
673 const gdb_byte
*buffer
;
674 CORE_ADDR found_addr
;
679 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OOs*", keywords
,
680 &start_addr_obj
, &length_obj
,
684 buffer
= (const gdb_byte
*) pybuf
.buf
;
685 pattern_size
= pybuf
.len
;
690 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OOO", keywords
,
691 &start_addr_obj
, &length_obj
,
695 if (!PyObject_CheckReadBuffer (pattern
))
697 PyErr_SetString (PyExc_RuntimeError
,
698 _("The pattern is not a Python buffer."));
703 if (PyObject_AsReadBuffer (pattern
, &vbuffer
, &pattern_size
) == -1)
706 buffer
= (const gdb_byte
*) vbuffer
;
709 if (get_addr_from_python (start_addr_obj
, &start_addr
) < 0)
712 if (get_addr_from_python (length_obj
, &length
) < 0)
717 PyErr_SetString (PyExc_ValueError
,
718 _("Search range is empty."));
721 /* Watch for overflows. */
722 else if (length
> CORE_ADDR_MAX
723 || (start_addr
+ length
- 1) < start_addr
)
725 PyErr_SetString (PyExc_ValueError
,
726 _("The search range is too large."));
732 found
= target_search_memory (start_addr
, length
,
733 buffer
, pattern_size
,
736 CATCH (ex
, RETURN_MASK_ALL
)
743 PyBuffer_Release (&pybuf
);
745 GDB_PY_HANDLE_EXCEPTION (except
);
748 return PyLong_FromLong (found_addr
);
754 PyBuffer_Release (&pybuf
);
759 /* Implementation of gdb.Inferior.is_valid (self) -> Boolean.
760 Returns True if this inferior object still exists in GDB. */
763 infpy_is_valid (PyObject
*self
, PyObject
*args
)
765 inferior_object
*inf
= (inferior_object
*) self
;
774 infpy_dealloc (PyObject
*obj
)
776 inferior_object
*inf_obj
= (inferior_object
*) obj
;
777 struct inferior
*inf
= inf_obj
->inferior
;
782 set_inferior_data (inf
, infpy_inf_data_key
, NULL
);
785 /* Clear the INFERIOR pointer in an Inferior object and clear the
788 py_free_inferior (struct inferior
*inf
, void *datum
)
790 inferior_object
*inf_obj
= (inferior_object
*) datum
;
791 struct threadlist_entry
*th_entry
, *th_tmp
;
793 if (!gdb_python_initialized
)
796 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
798 inf_obj
->inferior
= NULL
;
800 /* Deallocate threads list. */
801 for (th_entry
= inf_obj
->threads
; th_entry
!= NULL
;)
803 Py_DECREF (th_entry
->thread_obj
);
806 th_entry
= th_entry
->next
;
810 inf_obj
->nthreads
= 0;
812 Py_DECREF ((PyObject
*) inf_obj
);
815 /* Implementation of gdb.selected_inferior() -> gdb.Inferior.
816 Returns the current inferior object. */
819 gdbpy_selected_inferior (PyObject
*self
, PyObject
*args
)
821 return inferior_to_inferior_object (current_inferior ());
825 gdbpy_initialize_inferior (void)
827 if (PyType_Ready (&inferior_object_type
) < 0)
830 if (gdb_pymodule_addobject (gdb_module
, "Inferior",
831 (PyObject
*) &inferior_object_type
) < 0)
835 register_inferior_data_with_cleanup (NULL
, py_free_inferior
);
837 observer_attach_new_thread (add_thread_object
);
838 observer_attach_thread_exit (delete_thread_object
);
839 observer_attach_normal_stop (python_on_normal_stop
);
840 observer_attach_target_resumed (python_on_resume
);
841 observer_attach_inferior_call_pre (python_on_inferior_call_pre
);
842 observer_attach_inferior_call_post (python_on_inferior_call_post
);
843 observer_attach_memory_changed (python_on_memory_change
);
844 observer_attach_register_changed (python_on_register_change
);
845 observer_attach_inferior_exit (python_inferior_exit
);
846 observer_attach_new_objfile (python_new_objfile
);
848 membuf_object_type
.tp_new
= PyType_GenericNew
;
849 if (PyType_Ready (&membuf_object_type
) < 0)
852 return gdb_pymodule_addobject (gdb_module
, "Membuf", (PyObject
*)
853 &membuf_object_type
);
856 static PyGetSetDef inferior_object_getset
[] =
858 { "num", infpy_get_num
, NULL
, "ID of inferior, as assigned by GDB.", NULL
},
859 { "pid", infpy_get_pid
, NULL
, "PID of inferior, as assigned by the OS.",
861 { "was_attached", infpy_get_was_attached
, NULL
,
862 "True if the inferior was created using 'attach'.", NULL
},
866 static PyMethodDef inferior_object_methods
[] =
868 { "is_valid", infpy_is_valid
, METH_NOARGS
,
869 "is_valid () -> Boolean.\n\
870 Return true if this inferior is valid, false if not." },
871 { "threads", infpy_threads
, METH_NOARGS
,
872 "Return all the threads of this inferior." },
873 { "read_memory", (PyCFunction
) infpy_read_memory
,
874 METH_VARARGS
| METH_KEYWORDS
,
875 "read_memory (address, length) -> buffer\n\
876 Return a buffer object for reading from the inferior's memory." },
877 { "write_memory", (PyCFunction
) infpy_write_memory
,
878 METH_VARARGS
| METH_KEYWORDS
,
879 "write_memory (address, buffer [, length])\n\
880 Write the given buffer object to the inferior's memory." },
881 { "search_memory", (PyCFunction
) infpy_search_memory
,
882 METH_VARARGS
| METH_KEYWORDS
,
883 "search_memory (address, length, pattern) -> long\n\
884 Return a long with the address of a match, or None." },
888 PyTypeObject inferior_object_type
=
890 PyVarObject_HEAD_INIT (NULL
, 0)
891 "gdb.Inferior", /* tp_name */
892 sizeof (inferior_object
), /* tp_basicsize */
894 infpy_dealloc
, /* tp_dealloc */
900 0, /* tp_as_number */
901 0, /* tp_as_sequence */
902 0, /* tp_as_mapping */
908 0, /* tp_as_buffer */
909 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_HAVE_ITER
, /* tp_flags */
910 "GDB inferior object", /* tp_doc */
913 0, /* tp_richcompare */
914 0, /* tp_weaklistoffset */
917 inferior_object_methods
, /* tp_methods */
919 inferior_object_getset
, /* tp_getset */
922 0, /* tp_descr_get */
923 0, /* tp_descr_set */
924 0, /* tp_dictoffset */
931 static PyBufferProcs buffer_procs
=
938 /* Python doesn't provide a decent way to get compatibility here. */
939 #if HAVE_LIBPYTHON2_4
940 #define CHARBUFFERPROC_NAME getcharbufferproc
942 #define CHARBUFFERPROC_NAME charbufferproc
945 static PyBufferProcs buffer_procs
= {
949 /* The cast here works around a difference between Python 2.4 and
951 (CHARBUFFERPROC_NAME
) get_char_buffer
955 PyTypeObject membuf_object_type
= {
956 PyVarObject_HEAD_INIT (NULL
, 0)
957 "gdb.Membuf", /*tp_name*/
958 sizeof (membuf_object
), /*tp_basicsize*/
960 mbpy_dealloc
, /*tp_dealloc*/
967 0, /*tp_as_sequence*/
974 &buffer_procs
, /*tp_as_buffer*/
975 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
976 "GDB memory buffer object", /*tp_doc*/
979 0, /* tp_richcompare */
980 0, /* tp_weaklistoffset */
988 0, /* tp_descr_get */
989 0, /* tp_descr_set */
990 0, /* tp_dictoffset */