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 /* PyObject_New initializes the new object with a refcount of 1. This
227 counts for the reference we are keeping in the inferior data. */
228 set_inferior_data (inferior
, infpy_inf_data_key
, inf_obj
);
232 /* We are returning a new reference. */
233 Py_INCREF ((PyObject
*)inf_obj
);
235 return (PyObject
*) inf_obj
;
238 /* Finds the Python Inferior object for the given PID. Returns a
239 reference, or NULL if PID does not match any inferior object. */
242 find_inferior_object (int pid
)
244 struct inferior
*inf
= find_inferior_pid (pid
);
247 return inferior_to_inferior_object (inf
);
253 find_thread_object (ptid_t ptid
)
256 struct threadlist_entry
*thread
;
258 pid
= ptid_get_pid (ptid
);
262 gdbpy_ref
<> inf_obj (find_inferior_object (pid
));
266 for (thread
= ((inferior_object
*)(inf_obj
.get ()))->threads
; thread
;
267 thread
= thread
->next
)
268 if (ptid_equal (thread
->thread_obj
->thread
->ptid
, ptid
))
269 return thread
->thread_obj
;
275 add_thread_object (struct thread_info
*tp
)
277 thread_object
*thread_obj
;
278 inferior_object
*inf_obj
;
279 struct threadlist_entry
*entry
;
281 if (!gdb_python_initialized
)
284 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
286 thread_obj
= create_thread_object (tp
);
289 gdbpy_print_stack ();
293 inf_obj
= (inferior_object
*) thread_obj
->inf_obj
;
295 entry
= XNEW (struct threadlist_entry
);
296 entry
->thread_obj
= thread_obj
;
297 entry
->next
= inf_obj
->threads
;
299 inf_obj
->threads
= entry
;
304 delete_thread_object (struct thread_info
*tp
, int ignore
)
306 struct threadlist_entry
**entry
, *tmp
;
308 if (!gdb_python_initialized
)
311 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
313 gdbpy_ref
<inferior_object
> inf_obj
314 ((inferior_object
*) find_inferior_object (ptid_get_pid (tp
->ptid
)));
318 /* Find thread entry in its inferior's thread_list. */
319 for (entry
= &inf_obj
->threads
; *entry
!= NULL
; entry
=
321 if ((*entry
)->thread_obj
->thread
== tp
)
328 tmp
->thread_obj
->thread
= NULL
;
330 *entry
= (*entry
)->next
;
333 Py_DECREF (tmp
->thread_obj
);
338 infpy_threads (PyObject
*self
, PyObject
*args
)
341 struct threadlist_entry
*entry
;
342 inferior_object
*inf_obj
= (inferior_object
*) self
;
345 INFPY_REQUIRE_VALID (inf_obj
);
349 update_thread_list ();
351 CATCH (except
, RETURN_MASK_ALL
)
353 GDB_PY_HANDLE_EXCEPTION (except
);
357 tuple
= PyTuple_New (inf_obj
->nthreads
);
361 for (i
= 0, entry
= inf_obj
->threads
; i
< inf_obj
->nthreads
;
362 i
++, entry
= entry
->next
)
364 Py_INCREF (entry
->thread_obj
);
365 PyTuple_SET_ITEM (tuple
, i
, (PyObject
*) entry
->thread_obj
);
372 infpy_get_num (PyObject
*self
, void *closure
)
374 inferior_object
*inf
= (inferior_object
*) self
;
376 INFPY_REQUIRE_VALID (inf
);
378 return PyLong_FromLong (inf
->inferior
->num
);
382 infpy_get_pid (PyObject
*self
, void *closure
)
384 inferior_object
*inf
= (inferior_object
*) self
;
386 INFPY_REQUIRE_VALID (inf
);
388 return PyLong_FromLong (inf
->inferior
->pid
);
392 infpy_get_was_attached (PyObject
*self
, void *closure
)
394 inferior_object
*inf
= (inferior_object
*) self
;
396 INFPY_REQUIRE_VALID (inf
);
397 if (inf
->inferior
->attach_flag
)
403 build_inferior_list (struct inferior
*inf
, void *arg
)
405 PyObject
*list
= (PyObject
*) arg
;
406 gdbpy_ref
<> inferior (inferior_to_inferior_object (inf
));
408 if (inferior
== NULL
)
411 return PyList_Append (list
, inferior
.get ()) ? 1 : 0;
414 /* Implementation of gdb.inferiors () -> (gdb.Inferior, ...).
415 Returns a tuple of all inferiors. */
417 gdbpy_inferiors (PyObject
*unused
, PyObject
*unused2
)
419 gdbpy_ref
<> list (PyList_New (0));
423 if (iterate_over_inferiors (build_inferior_list
, list
.get ()))
426 return PyList_AsTuple (list
.get ());
429 /* Membuf and memory manipulation. */
431 /* Implementation of Inferior.read_memory (address, length).
432 Returns a Python buffer object with LENGTH bytes of the inferior's
433 memory at ADDRESS. Both arguments are integers. Returns NULL on error,
434 with a python exception set. */
436 infpy_read_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
438 CORE_ADDR addr
, length
;
439 gdb_byte
*buffer
= NULL
;
440 PyObject
*addr_obj
, *length_obj
, *result
;
441 static const char *keywords
[] = { "address", "length", NULL
};
443 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "OO", keywords
,
444 &addr_obj
, &length_obj
))
447 if (get_addr_from_python (addr_obj
, &addr
) < 0
448 || get_addr_from_python (length_obj
, &length
) < 0)
453 buffer
= (gdb_byte
*) xmalloc (length
);
455 read_memory (addr
, buffer
, length
);
457 CATCH (except
, RETURN_MASK_ALL
)
460 GDB_PY_HANDLE_EXCEPTION (except
);
464 gdbpy_ref
<membuf_object
> membuf_obj (PyObject_New (membuf_object
,
465 &membuf_object_type
));
466 if (membuf_obj
== NULL
)
472 membuf_obj
->buffer
= buffer
;
473 membuf_obj
->addr
= addr
;
474 membuf_obj
->length
= length
;
477 result
= PyMemoryView_FromObject ((PyObject
*) membuf_obj
.get ());
479 result
= PyBuffer_FromReadWriteObject ((PyObject
*) membuf_obj
.get (), 0,
486 /* Implementation of Inferior.write_memory (address, buffer [, length]).
487 Writes the contents of BUFFER (a Python object supporting the read
488 buffer protocol) at ADDRESS in the inferior's memory. Write LENGTH
489 bytes from BUFFER, or its entire contents if the argument is not
490 provided. The function returns nothing. Returns NULL on error, with
491 a python exception set. */
493 infpy_write_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
495 struct gdb_exception except
= exception_none
;
497 const gdb_byte
*buffer
;
498 CORE_ADDR addr
, length
;
499 PyObject
*addr_obj
, *length_obj
= NULL
;
500 static const char *keywords
[] = { "address", "buffer", "length", NULL
};
504 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "Os*|O", keywords
,
505 &addr_obj
, &pybuf
, &length_obj
))
508 buffer
= (const gdb_byte
*) pybuf
.buf
;
511 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "Os#|O", keywords
,
512 &addr_obj
, &buffer
, &buf_len
,
516 buffer
= (const gdb_byte
*) buffer
;
519 if (get_addr_from_python (addr_obj
, &addr
) < 0)
524 else if (get_addr_from_python (length_obj
, &length
) < 0)
529 write_memory_with_notification (addr
, buffer
, length
);
531 CATCH (ex
, RETURN_MASK_ALL
)
538 PyBuffer_Release (&pybuf
);
540 GDB_PY_HANDLE_EXCEPTION (except
);
546 PyBuffer_Release (&pybuf
);
551 /* Destructor of Membuf objects. */
553 mbpy_dealloc (PyObject
*self
)
555 xfree (((membuf_object
*) self
)->buffer
);
556 Py_TYPE (self
)->tp_free (self
);
559 /* Return a description of the Membuf object. */
561 mbpy_str (PyObject
*self
)
563 membuf_object
*membuf_obj
= (membuf_object
*) self
;
565 return PyString_FromFormat (_("Memory buffer for address %s, \
566 which is %s bytes long."),
567 paddress (python_gdbarch
, membuf_obj
->addr
),
568 pulongest (membuf_obj
->length
));
574 get_buffer (PyObject
*self
, Py_buffer
*buf
, int flags
)
576 membuf_object
*membuf_obj
= (membuf_object
*) self
;
579 ret
= PyBuffer_FillInfo (buf
, self
, membuf_obj
->buffer
,
580 membuf_obj
->length
, 0,
583 /* Despite the documentation saying this field is a "const char *",
584 in Python 3.4 at least, it's really a "char *". */
585 buf
->format
= (char *) "c";
593 get_read_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
595 membuf_object
*membuf_obj
= (membuf_object
*) self
;
599 PyErr_SetString (PyExc_SystemError
,
600 _("The memory buffer supports only one segment."));
604 *ptrptr
= membuf_obj
->buffer
;
606 return membuf_obj
->length
;
610 get_write_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
612 return get_read_buffer (self
, segment
, ptrptr
);
616 get_seg_count (PyObject
*self
, Py_ssize_t
*lenp
)
619 *lenp
= ((membuf_object
*) self
)->length
;
625 get_char_buffer (PyObject
*self
, Py_ssize_t segment
, char **ptrptr
)
630 ret
= get_read_buffer (self
, segment
, &ptr
);
631 *ptrptr
= (char *) ptr
;
639 gdb.search_memory (address, length, pattern). ADDRESS is the
640 address to start the search. LENGTH specifies the scope of the
641 search from ADDRESS. PATTERN is the pattern to search for (and
642 must be a Python object supporting the buffer protocol).
643 Returns a Python Long object holding the address where the pattern
644 was located, or if the pattern was not found, returns None. Returns NULL
645 on error, with a python exception set. */
647 infpy_search_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
649 struct gdb_exception except
= exception_none
;
650 CORE_ADDR start_addr
, length
;
651 static const char *keywords
[] = { "address", "length", "pattern", NULL
};
652 PyObject
*start_addr_obj
, *length_obj
;
653 Py_ssize_t pattern_size
;
654 const gdb_byte
*buffer
;
655 CORE_ADDR found_addr
;
660 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "OOs*", keywords
,
661 &start_addr_obj
, &length_obj
,
665 buffer
= (const gdb_byte
*) pybuf
.buf
;
666 pattern_size
= pybuf
.len
;
671 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "OOO", keywords
,
672 &start_addr_obj
, &length_obj
,
676 if (!PyObject_CheckReadBuffer (pattern
))
678 PyErr_SetString (PyExc_RuntimeError
,
679 _("The pattern is not a Python buffer."));
684 if (PyObject_AsReadBuffer (pattern
, &vbuffer
, &pattern_size
) == -1)
687 buffer
= (const gdb_byte
*) vbuffer
;
690 if (get_addr_from_python (start_addr_obj
, &start_addr
) < 0)
693 if (get_addr_from_python (length_obj
, &length
) < 0)
698 PyErr_SetString (PyExc_ValueError
,
699 _("Search range is empty."));
702 /* Watch for overflows. */
703 else if (length
> CORE_ADDR_MAX
704 || (start_addr
+ length
- 1) < start_addr
)
706 PyErr_SetString (PyExc_ValueError
,
707 _("The search range is too large."));
713 found
= target_search_memory (start_addr
, length
,
714 buffer
, pattern_size
,
717 CATCH (ex
, RETURN_MASK_ALL
)
724 PyBuffer_Release (&pybuf
);
726 GDB_PY_HANDLE_EXCEPTION (except
);
729 return PyLong_FromLong (found_addr
);
735 PyBuffer_Release (&pybuf
);
740 /* Implementation of gdb.Inferior.is_valid (self) -> Boolean.
741 Returns True if this inferior object still exists in GDB. */
744 infpy_is_valid (PyObject
*self
, PyObject
*args
)
746 inferior_object
*inf
= (inferior_object
*) self
;
755 infpy_dealloc (PyObject
*obj
)
757 inferior_object
*inf_obj
= (inferior_object
*) obj
;
758 struct inferior
*inf
= inf_obj
->inferior
;
763 set_inferior_data (inf
, infpy_inf_data_key
, NULL
);
766 /* Clear the INFERIOR pointer in an Inferior object and clear the
769 py_free_inferior (struct inferior
*inf
, void *datum
)
771 gdbpy_ref
<inferior_object
> inf_obj ((inferior_object
*) datum
);
772 struct threadlist_entry
*th_entry
, *th_tmp
;
774 if (!gdb_python_initialized
)
777 gdbpy_enter
enter_py (python_gdbarch
, python_language
);
779 inf_obj
->inferior
= NULL
;
781 /* Deallocate threads list. */
782 for (th_entry
= inf_obj
->threads
; th_entry
!= NULL
;)
784 Py_DECREF (th_entry
->thread_obj
);
787 th_entry
= th_entry
->next
;
791 inf_obj
->nthreads
= 0;
794 /* Implementation of gdb.selected_inferior() -> gdb.Inferior.
795 Returns the current inferior object. */
798 gdbpy_selected_inferior (PyObject
*self
, PyObject
*args
)
800 return inferior_to_inferior_object (current_inferior ());
804 gdbpy_initialize_inferior (void)
806 if (PyType_Ready (&inferior_object_type
) < 0)
809 if (gdb_pymodule_addobject (gdb_module
, "Inferior",
810 (PyObject
*) &inferior_object_type
) < 0)
814 register_inferior_data_with_cleanup (NULL
, py_free_inferior
);
816 observer_attach_new_thread (add_thread_object
);
817 observer_attach_thread_exit (delete_thread_object
);
818 observer_attach_normal_stop (python_on_normal_stop
);
819 observer_attach_target_resumed (python_on_resume
);
820 observer_attach_inferior_call_pre (python_on_inferior_call_pre
);
821 observer_attach_inferior_call_post (python_on_inferior_call_post
);
822 observer_attach_memory_changed (python_on_memory_change
);
823 observer_attach_register_changed (python_on_register_change
);
824 observer_attach_inferior_exit (python_inferior_exit
);
825 observer_attach_new_objfile (python_new_objfile
);
827 membuf_object_type
.tp_new
= PyType_GenericNew
;
828 if (PyType_Ready (&membuf_object_type
) < 0)
831 return gdb_pymodule_addobject (gdb_module
, "Membuf", (PyObject
*)
832 &membuf_object_type
);
835 static gdb_PyGetSetDef inferior_object_getset
[] =
837 { "num", infpy_get_num
, NULL
, "ID of inferior, as assigned by GDB.", NULL
},
838 { "pid", infpy_get_pid
, NULL
, "PID of inferior, as assigned by the OS.",
840 { "was_attached", infpy_get_was_attached
, NULL
,
841 "True if the inferior was created using 'attach'.", NULL
},
845 static PyMethodDef inferior_object_methods
[] =
847 { "is_valid", infpy_is_valid
, METH_NOARGS
,
848 "is_valid () -> Boolean.\n\
849 Return true if this inferior is valid, false if not." },
850 { "threads", infpy_threads
, METH_NOARGS
,
851 "Return all the threads of this inferior." },
852 { "read_memory", (PyCFunction
) infpy_read_memory
,
853 METH_VARARGS
| METH_KEYWORDS
,
854 "read_memory (address, length) -> buffer\n\
855 Return a buffer object for reading from the inferior's memory." },
856 { "write_memory", (PyCFunction
) infpy_write_memory
,
857 METH_VARARGS
| METH_KEYWORDS
,
858 "write_memory (address, buffer [, length])\n\
859 Write the given buffer object to the inferior's memory." },
860 { "search_memory", (PyCFunction
) infpy_search_memory
,
861 METH_VARARGS
| METH_KEYWORDS
,
862 "search_memory (address, length, pattern) -> long\n\
863 Return a long with the address of a match, or None." },
867 PyTypeObject inferior_object_type
=
869 PyVarObject_HEAD_INIT (NULL
, 0)
870 "gdb.Inferior", /* tp_name */
871 sizeof (inferior_object
), /* tp_basicsize */
873 infpy_dealloc
, /* tp_dealloc */
879 0, /* tp_as_number */
880 0, /* tp_as_sequence */
881 0, /* tp_as_mapping */
887 0, /* tp_as_buffer */
888 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_HAVE_ITER
, /* tp_flags */
889 "GDB inferior object", /* tp_doc */
892 0, /* tp_richcompare */
893 0, /* tp_weaklistoffset */
896 inferior_object_methods
, /* tp_methods */
898 inferior_object_getset
, /* tp_getset */
901 0, /* tp_descr_get */
902 0, /* tp_descr_set */
903 0, /* tp_dictoffset */
910 static PyBufferProcs buffer_procs
=
917 /* Python doesn't provide a decent way to get compatibility here. */
918 #if HAVE_LIBPYTHON2_4
919 #define CHARBUFFERPROC_NAME getcharbufferproc
921 #define CHARBUFFERPROC_NAME charbufferproc
924 static PyBufferProcs buffer_procs
= {
928 /* The cast here works around a difference between Python 2.4 and
930 (CHARBUFFERPROC_NAME
) get_char_buffer
934 PyTypeObject membuf_object_type
= {
935 PyVarObject_HEAD_INIT (NULL
, 0)
936 "gdb.Membuf", /*tp_name*/
937 sizeof (membuf_object
), /*tp_basicsize*/
939 mbpy_dealloc
, /*tp_dealloc*/
946 0, /*tp_as_sequence*/
953 &buffer_procs
, /*tp_as_buffer*/
954 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
955 "GDB memory buffer object", /*tp_doc*/
958 0, /* tp_richcompare */
959 0, /* tp_weaklistoffset */
967 0, /* tp_descr_get */
968 0, /* tp_descr_set */
969 0, /* tp_dictoffset */