1 /* Python interface to inferiors.
3 Copyright (C) 2009-2015 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 struct cleanup
*cleanup
;
85 enum gdb_signal stop_signal
;
87 if (!gdb_python_initialized
)
90 if (!find_thread_ptid (inferior_ptid
))
93 stop_signal
= inferior_thread ()->suspend
.stop_signal
;
95 cleanup
= ensure_python_env (get_current_arch (), current_language
);
97 if (emit_stop_event (bs
, stop_signal
) < 0)
100 do_cleanups (cleanup
);
104 python_on_resume (ptid_t ptid
)
106 struct cleanup
*cleanup
;
108 if (!gdb_python_initialized
)
111 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
113 if (emit_continue_event (ptid
) < 0)
114 gdbpy_print_stack ();
116 do_cleanups (cleanup
);
119 /* Callback, registered as an observer, that notifies Python listeners
120 when an inferior function call is about to be made. */
123 python_on_inferior_call_pre (ptid_t thread
, CORE_ADDR address
)
125 struct cleanup
*cleanup
;
127 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
129 if (emit_inferior_call_event (INFERIOR_CALL_PRE
, thread
, address
) < 0)
130 gdbpy_print_stack ();
132 do_cleanups (cleanup
);
135 /* Callback, registered as an observer, that notifies Python listeners
136 when an inferior function call has completed. */
139 python_on_inferior_call_post (ptid_t thread
, CORE_ADDR address
)
141 struct cleanup
*cleanup
;
143 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
145 if (emit_inferior_call_event (INFERIOR_CALL_POST
, thread
, address
) < 0)
146 gdbpy_print_stack ();
148 do_cleanups (cleanup
);
151 /* Callback, registered as an observer, that notifies Python listeners
152 when a part of memory has been modified by user action (eg via a
156 python_on_memory_change (struct inferior
*inferior
, CORE_ADDR addr
, ssize_t len
, const bfd_byte
*data
)
158 struct cleanup
*cleanup
;
160 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
162 if (emit_memory_changed_event (addr
, len
) < 0)
163 gdbpy_print_stack ();
165 do_cleanups (cleanup
);
168 /* Callback, registered as an observer, that notifies Python listeners
169 when a register has been modified by user action (eg via a 'set'
173 python_on_register_change (struct frame_info
*frame
, int regnum
)
175 struct cleanup
*cleanup
;
177 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
179 if (emit_register_changed_event (frame
, regnum
) < 0)
180 gdbpy_print_stack ();
182 do_cleanups (cleanup
);
186 python_inferior_exit (struct inferior
*inf
)
188 struct cleanup
*cleanup
;
189 const LONGEST
*exit_code
= NULL
;
191 if (!gdb_python_initialized
)
194 cleanup
= ensure_python_env (target_gdbarch (), current_language
);
196 if (inf
->has_exit_code
)
197 exit_code
= &inf
->exit_code
;
199 if (emit_exited_event (exit_code
, inf
) < 0)
200 gdbpy_print_stack ();
202 do_cleanups (cleanup
);
205 /* Callback used to notify Python listeners about new objfiles loaded in the
206 inferior. OBJFILE may be NULL which means that the objfile list has been
207 cleared (emptied). */
210 python_new_objfile (struct objfile
*objfile
)
212 struct cleanup
*cleanup
;
214 if (!gdb_python_initialized
)
217 cleanup
= ensure_python_env (objfile
!= NULL
218 ? get_objfile_arch (objfile
)
224 if (emit_clear_objfiles_event () < 0)
225 gdbpy_print_stack ();
229 if (emit_new_objfile_event (objfile
) < 0)
230 gdbpy_print_stack ();
233 do_cleanups (cleanup
);
236 /* Return a reference to the Python object of type Inferior
237 representing INFERIOR. If the object has already been created,
238 return it and increment the reference count, otherwise, create it.
239 Return NULL on failure. */
241 inferior_to_inferior_object (struct inferior
*inferior
)
243 inferior_object
*inf_obj
;
245 inf_obj
= inferior_data (inferior
, infpy_inf_data_key
);
248 inf_obj
= PyObject_New (inferior_object
, &inferior_object_type
);
252 inf_obj
->inferior
= inferior
;
253 inf_obj
->threads
= NULL
;
254 inf_obj
->nthreads
= 0;
256 set_inferior_data (inferior
, infpy_inf_data_key
, inf_obj
);
260 Py_INCREF ((PyObject
*)inf_obj
);
262 return (PyObject
*) inf_obj
;
265 /* Finds the Python Inferior object for the given PID. Returns a
266 reference, or NULL if PID does not match any inferior object. */
269 find_inferior_object (int pid
)
271 struct inferior
*inf
= find_inferior_pid (pid
);
274 return inferior_to_inferior_object (inf
);
280 find_thread_object (ptid_t ptid
)
283 struct threadlist_entry
*thread
;
285 thread_object
*found
= NULL
;
287 pid
= ptid_get_pid (ptid
);
291 inf_obj
= find_inferior_object (pid
);
296 for (thread
= ((inferior_object
*)inf_obj
)->threads
; thread
;
297 thread
= thread
->next
)
298 if (ptid_equal (thread
->thread_obj
->thread
->ptid
, ptid
))
300 found
= thread
->thread_obj
;
313 add_thread_object (struct thread_info
*tp
)
315 struct cleanup
*cleanup
;
316 thread_object
*thread_obj
;
317 inferior_object
*inf_obj
;
318 struct threadlist_entry
*entry
;
320 if (!gdb_python_initialized
)
323 cleanup
= ensure_python_env (python_gdbarch
, python_language
);
325 thread_obj
= create_thread_object (tp
);
328 gdbpy_print_stack ();
329 do_cleanups (cleanup
);
333 inf_obj
= (inferior_object
*) thread_obj
->inf_obj
;
335 entry
= xmalloc (sizeof (struct threadlist_entry
));
336 entry
->thread_obj
= thread_obj
;
337 entry
->next
= inf_obj
->threads
;
339 inf_obj
->threads
= entry
;
342 do_cleanups (cleanup
);
346 delete_thread_object (struct thread_info
*tp
, int ignore
)
348 struct cleanup
*cleanup
;
349 inferior_object
*inf_obj
;
350 struct threadlist_entry
**entry
, *tmp
;
352 if (!gdb_python_initialized
)
355 cleanup
= ensure_python_env (python_gdbarch
, python_language
);
358 = (inferior_object
*) find_inferior_object (ptid_get_pid (tp
->ptid
));
361 do_cleanups (cleanup
);
365 /* Find thread entry in its inferior's thread_list. */
366 for (entry
= &inf_obj
->threads
; *entry
!= NULL
; entry
=
368 if ((*entry
)->thread_obj
->thread
== tp
)
374 do_cleanups (cleanup
);
379 tmp
->thread_obj
->thread
= NULL
;
381 *entry
= (*entry
)->next
;
384 Py_DECREF (tmp
->thread_obj
);
388 do_cleanups (cleanup
);
392 infpy_threads (PyObject
*self
, PyObject
*args
)
395 struct threadlist_entry
*entry
;
396 inferior_object
*inf_obj
= (inferior_object
*) self
;
399 INFPY_REQUIRE_VALID (inf_obj
);
403 update_thread_list ();
405 CATCH (except
, RETURN_MASK_ALL
)
407 GDB_PY_HANDLE_EXCEPTION (except
);
411 tuple
= PyTuple_New (inf_obj
->nthreads
);
415 for (i
= 0, entry
= inf_obj
->threads
; i
< inf_obj
->nthreads
;
416 i
++, entry
= entry
->next
)
418 Py_INCREF (entry
->thread_obj
);
419 PyTuple_SET_ITEM (tuple
, i
, (PyObject
*) entry
->thread_obj
);
426 infpy_get_num (PyObject
*self
, void *closure
)
428 inferior_object
*inf
= (inferior_object
*) self
;
430 INFPY_REQUIRE_VALID (inf
);
432 return PyLong_FromLong (inf
->inferior
->num
);
436 infpy_get_pid (PyObject
*self
, void *closure
)
438 inferior_object
*inf
= (inferior_object
*) self
;
440 INFPY_REQUIRE_VALID (inf
);
442 return PyLong_FromLong (inf
->inferior
->pid
);
446 infpy_get_was_attached (PyObject
*self
, void *closure
)
448 inferior_object
*inf
= (inferior_object
*) self
;
450 INFPY_REQUIRE_VALID (inf
);
451 if (inf
->inferior
->attach_flag
)
457 build_inferior_list (struct inferior
*inf
, void *arg
)
459 PyObject
*list
= arg
;
460 PyObject
*inferior
= inferior_to_inferior_object (inf
);
466 success
= PyList_Append (list
, inferior
);
467 Py_DECREF (inferior
);
475 /* Implementation of gdb.inferiors () -> (gdb.Inferior, ...).
476 Returns a tuple of all inferiors. */
478 gdbpy_inferiors (PyObject
*unused
, PyObject
*unused2
)
480 PyObject
*list
, *tuple
;
482 list
= PyList_New (0);
486 if (iterate_over_inferiors (build_inferior_list
, list
))
492 tuple
= PyList_AsTuple (list
);
498 /* Membuf and memory manipulation. */
500 /* Implementation of Inferior.read_memory (address, length).
501 Returns a Python buffer object with LENGTH bytes of the inferior's
502 memory at ADDRESS. Both arguments are integers. Returns NULL on error,
503 with a python exception set. */
505 infpy_read_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
507 CORE_ADDR addr
, length
;
509 membuf_object
*membuf_obj
;
510 PyObject
*addr_obj
, *length_obj
, *result
;
511 static char *keywords
[] = { "address", "length", NULL
};
513 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OO", keywords
,
514 &addr_obj
, &length_obj
))
517 if (get_addr_from_python (addr_obj
, &addr
) < 0
518 || get_addr_from_python (length_obj
, &length
) < 0)
523 buffer
= xmalloc (length
);
525 read_memory (addr
, buffer
, length
);
527 CATCH (except
, RETURN_MASK_ALL
)
530 GDB_PY_HANDLE_EXCEPTION (except
);
534 membuf_obj
= PyObject_New (membuf_object
, &membuf_object_type
);
535 if (membuf_obj
== NULL
)
541 membuf_obj
->buffer
= buffer
;
542 membuf_obj
->addr
= addr
;
543 membuf_obj
->length
= length
;
546 result
= PyMemoryView_FromObject ((PyObject
*) membuf_obj
);
548 result
= PyBuffer_FromReadWriteObject ((PyObject
*) membuf_obj
, 0,
551 Py_DECREF (membuf_obj
);
556 /* Implementation of Inferior.write_memory (address, buffer [, length]).
557 Writes the contents of BUFFER (a Python object supporting the read
558 buffer protocol) at ADDRESS in the inferior's memory. Write LENGTH
559 bytes from BUFFER, or its entire contents if the argument is not
560 provided. The function returns nothing. Returns NULL on error, with
561 a python exception set. */
563 infpy_write_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
565 struct gdb_exception except
= exception_none
;
568 CORE_ADDR addr
, length
;
569 PyObject
*addr_obj
, *length_obj
= NULL
;
570 static char *keywords
[] = { "address", "buffer", "length", NULL
};
574 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "Os*|O", keywords
,
582 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "Os#|O", keywords
,
583 &addr_obj
, &buffer
, &buf_len
,
588 if (get_addr_from_python (addr_obj
, &addr
) < 0)
593 else if (get_addr_from_python (length_obj
, &length
) < 0)
598 write_memory_with_notification (addr
, (gdb_byte
*) buffer
, length
);
600 CATCH (ex
, RETURN_MASK_ALL
)
607 PyBuffer_Release (&pybuf
);
609 GDB_PY_HANDLE_EXCEPTION (except
);
615 PyBuffer_Release (&pybuf
);
620 /* Destructor of Membuf objects. */
622 mbpy_dealloc (PyObject
*self
)
624 xfree (((membuf_object
*) self
)->buffer
);
625 Py_TYPE (self
)->tp_free (self
);
628 /* Return a description of the Membuf object. */
630 mbpy_str (PyObject
*self
)
632 membuf_object
*membuf_obj
= (membuf_object
*) self
;
634 return PyString_FromFormat (_("Memory buffer for address %s, \
635 which is %s bytes long."),
636 paddress (python_gdbarch
, membuf_obj
->addr
),
637 pulongest (membuf_obj
->length
));
643 get_buffer (PyObject
*self
, Py_buffer
*buf
, int flags
)
645 membuf_object
*membuf_obj
= (membuf_object
*) self
;
648 ret
= PyBuffer_FillInfo (buf
, self
, membuf_obj
->buffer
,
649 membuf_obj
->length
, 0,
659 get_read_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
661 membuf_object
*membuf_obj
= (membuf_object
*) self
;
665 PyErr_SetString (PyExc_SystemError
,
666 _("The memory buffer supports only one segment."));
670 *ptrptr
= membuf_obj
->buffer
;
672 return membuf_obj
->length
;
676 get_write_buffer (PyObject
*self
, Py_ssize_t segment
, void **ptrptr
)
678 return get_read_buffer (self
, segment
, ptrptr
);
682 get_seg_count (PyObject
*self
, Py_ssize_t
*lenp
)
685 *lenp
= ((membuf_object
*) self
)->length
;
691 get_char_buffer (PyObject
*self
, Py_ssize_t segment
, char **ptrptr
)
696 ret
= get_read_buffer (self
, segment
, &ptr
);
697 *ptrptr
= (char *) ptr
;
705 gdb.search_memory (address, length, pattern). ADDRESS is the
706 address to start the search. LENGTH specifies the scope of the
707 search from ADDRESS. PATTERN is the pattern to search for (and
708 must be a Python object supporting the buffer protocol).
709 Returns a Python Long object holding the address where the pattern
710 was located, or if the pattern was not found, returns None. Returns NULL
711 on error, with a python exception set. */
713 infpy_search_memory (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
715 struct gdb_exception except
= exception_none
;
716 CORE_ADDR start_addr
, length
;
717 static char *keywords
[] = { "address", "length", "pattern", NULL
};
718 PyObject
*start_addr_obj
, *length_obj
;
719 Py_ssize_t pattern_size
;
721 CORE_ADDR found_addr
;
726 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OOs*", keywords
,
727 &start_addr_obj
, &length_obj
,
732 pattern_size
= pybuf
.len
;
736 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "OOO", keywords
,
737 &start_addr_obj
, &length_obj
,
741 if (!PyObject_CheckReadBuffer (pattern
))
743 PyErr_SetString (PyExc_RuntimeError
,
744 _("The pattern is not a Python buffer."));
749 if (PyObject_AsReadBuffer (pattern
, &buffer
, &pattern_size
) == -1)
753 if (get_addr_from_python (start_addr_obj
, &start_addr
) < 0)
756 if (get_addr_from_python (length_obj
, &length
) < 0)
761 PyErr_SetString (PyExc_ValueError
,
762 _("Search range is empty."));
765 /* Watch for overflows. */
766 else if (length
> CORE_ADDR_MAX
767 || (start_addr
+ length
- 1) < start_addr
)
769 PyErr_SetString (PyExc_ValueError
,
770 _("The search range is too large."));
776 found
= target_search_memory (start_addr
, length
,
777 buffer
, pattern_size
,
780 CATCH (ex
, RETURN_MASK_ALL
)
787 PyBuffer_Release (&pybuf
);
789 GDB_PY_HANDLE_EXCEPTION (except
);
792 return PyLong_FromLong (found_addr
);
798 PyBuffer_Release (&pybuf
);
803 /* Implementation of gdb.Inferior.is_valid (self) -> Boolean.
804 Returns True if this inferior object still exists in GDB. */
807 infpy_is_valid (PyObject
*self
, PyObject
*args
)
809 inferior_object
*inf
= (inferior_object
*) self
;
818 infpy_dealloc (PyObject
*obj
)
820 inferior_object
*inf_obj
= (inferior_object
*) obj
;
821 struct inferior
*inf
= inf_obj
->inferior
;
826 set_inferior_data (inf
, infpy_inf_data_key
, NULL
);
829 /* Clear the INFERIOR pointer in an Inferior object and clear the
832 py_free_inferior (struct inferior
*inf
, void *datum
)
835 struct cleanup
*cleanup
;
836 inferior_object
*inf_obj
= datum
;
837 struct threadlist_entry
*th_entry
, *th_tmp
;
839 if (!gdb_python_initialized
)
842 cleanup
= ensure_python_env (python_gdbarch
, python_language
);
844 inf_obj
->inferior
= NULL
;
846 /* Deallocate threads list. */
847 for (th_entry
= inf_obj
->threads
; th_entry
!= NULL
;)
849 Py_DECREF (th_entry
->thread_obj
);
852 th_entry
= th_entry
->next
;
856 inf_obj
->nthreads
= 0;
858 Py_DECREF ((PyObject
*) inf_obj
);
859 do_cleanups (cleanup
);
862 /* Implementation of gdb.selected_inferior() -> gdb.Inferior.
863 Returns the current inferior object. */
866 gdbpy_selected_inferior (PyObject
*self
, PyObject
*args
)
868 return inferior_to_inferior_object (current_inferior ());
872 gdbpy_initialize_inferior (void)
874 if (PyType_Ready (&inferior_object_type
) < 0)
877 if (gdb_pymodule_addobject (gdb_module
, "Inferior",
878 (PyObject
*) &inferior_object_type
) < 0)
882 register_inferior_data_with_cleanup (NULL
, py_free_inferior
);
884 observer_attach_new_thread (add_thread_object
);
885 observer_attach_thread_exit (delete_thread_object
);
886 observer_attach_normal_stop (python_on_normal_stop
);
887 observer_attach_target_resumed (python_on_resume
);
888 observer_attach_inferior_call_pre (python_on_inferior_call_pre
);
889 observer_attach_inferior_call_post (python_on_inferior_call_post
);
890 observer_attach_memory_changed (python_on_memory_change
);
891 observer_attach_register_changed (python_on_register_change
);
892 observer_attach_inferior_exit (python_inferior_exit
);
893 observer_attach_new_objfile (python_new_objfile
);
895 membuf_object_type
.tp_new
= PyType_GenericNew
;
896 if (PyType_Ready (&membuf_object_type
) < 0)
899 return gdb_pymodule_addobject (gdb_module
, "Membuf", (PyObject
*)
900 &membuf_object_type
);
903 static PyGetSetDef inferior_object_getset
[] =
905 { "num", infpy_get_num
, NULL
, "ID of inferior, as assigned by GDB.", NULL
},
906 { "pid", infpy_get_pid
, NULL
, "PID of inferior, as assigned by the OS.",
908 { "was_attached", infpy_get_was_attached
, NULL
,
909 "True if the inferior was created using 'attach'.", NULL
},
913 static PyMethodDef inferior_object_methods
[] =
915 { "is_valid", infpy_is_valid
, METH_NOARGS
,
916 "is_valid () -> Boolean.\n\
917 Return true if this inferior is valid, false if not." },
918 { "threads", infpy_threads
, METH_NOARGS
,
919 "Return all the threads of this inferior." },
920 { "read_memory", (PyCFunction
) infpy_read_memory
,
921 METH_VARARGS
| METH_KEYWORDS
,
922 "read_memory (address, length) -> buffer\n\
923 Return a buffer object for reading from the inferior's memory." },
924 { "write_memory", (PyCFunction
) infpy_write_memory
,
925 METH_VARARGS
| METH_KEYWORDS
,
926 "write_memory (address, buffer [, length])\n\
927 Write the given buffer object to the inferior's memory." },
928 { "search_memory", (PyCFunction
) infpy_search_memory
,
929 METH_VARARGS
| METH_KEYWORDS
,
930 "search_memory (address, length, pattern) -> long\n\
931 Return a long with the address of a match, or None." },
935 PyTypeObject inferior_object_type
=
937 PyVarObject_HEAD_INIT (NULL
, 0)
938 "gdb.Inferior", /* tp_name */
939 sizeof (inferior_object
), /* tp_basicsize */
941 infpy_dealloc
, /* tp_dealloc */
947 0, /* tp_as_number */
948 0, /* tp_as_sequence */
949 0, /* tp_as_mapping */
955 0, /* tp_as_buffer */
956 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_HAVE_ITER
, /* tp_flags */
957 "GDB inferior object", /* tp_doc */
960 0, /* tp_richcompare */
961 0, /* tp_weaklistoffset */
964 inferior_object_methods
, /* tp_methods */
966 inferior_object_getset
, /* tp_getset */
969 0, /* tp_descr_get */
970 0, /* tp_descr_set */
971 0, /* tp_dictoffset */
978 static PyBufferProcs buffer_procs
=
985 /* Python doesn't provide a decent way to get compatibility here. */
986 #if HAVE_LIBPYTHON2_4
987 #define CHARBUFFERPROC_NAME getcharbufferproc
989 #define CHARBUFFERPROC_NAME charbufferproc
992 static PyBufferProcs buffer_procs
= {
996 /* The cast here works around a difference between Python 2.4 and
998 (CHARBUFFERPROC_NAME
) get_char_buffer
1000 #endif /* IS_PY3K */
1002 PyTypeObject membuf_object_type
= {
1003 PyVarObject_HEAD_INIT (NULL
, 0)
1004 "gdb.Membuf", /*tp_name*/
1005 sizeof (membuf_object
), /*tp_basicsize*/
1007 mbpy_dealloc
, /*tp_dealloc*/
1014 0, /*tp_as_sequence*/
1015 0, /*tp_as_mapping*/
1018 mbpy_str
, /*tp_str*/
1021 &buffer_procs
, /*tp_as_buffer*/
1022 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
1023 "GDB memory buffer object", /*tp_doc*/
1024 0, /* tp_traverse */
1026 0, /* tp_richcompare */
1027 0, /* tp_weaklistoffset */
1029 0, /* tp_iternext */
1035 0, /* tp_descr_get */
1036 0, /* tp_descr_set */
1037 0, /* tp_dictoffset */