gdb/python/py-finishbreakpoint.c

   1 /* Python interface to finish breakpoints
   2
   3    Copyright (C) 2011-2025 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   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.
  11
  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.
  16
  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/>.  */
  19
  20
  21
  22 #include "top.h"
  23 #include "python-internal.h"
  24 #include "breakpoint.h"
  25 #include "frame.h"
  26 #include "gdbthread.h"
  27 #include "arch-utils.h"
  28 #include "language.h"
  29 #include "observable.h"
  30 #include "inferior.h"
  31 #include "block.h"
  32 #include "location.h"
  33
  34 /* Function that is called when a Python finish bp is found out of scope.  */
  35 static const char outofscope_func[] = "out_of_scope";
  36
  37 /* struct implementing the gdb.FinishBreakpoint object by extending
  38    the gdb.Breakpoint class.  */
  39 struct finish_breakpoint_object
  40 {
  41   /* gdb.Breakpoint base class.  */
  42   gdbpy_breakpoint_object py_bp;
  43
  44   /* gdb.Symbol object of the function finished by this breakpoint.
  45
  46      nullptr if no debug information was available or return type was VOID.  */
  47   PyObject *func_symbol;
  48
  49   /* gdb.Value object of the function finished by this breakpoint.
  50
  51      nullptr if no debug information was available or return type was VOID.  */
  52   PyObject *function_value;
  53
  54   /* When stopped at this FinishBreakpoint, gdb.Value object returned by
  55      the function; Py_None if the value is not computable; NULL if GDB is
  56      not stopped at a FinishBreakpoint.  */
  57   PyObject *return_value;
  58
  59   /* The initiating frame for this operation, used to decide when we have
  60      left this frame.  */
  61   struct frame_id initiating_frame;
  62 };
  63
  64 extern PyTypeObject finish_breakpoint_object_type
  65     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("finish_breakpoint_object");
  66
  67 /* Python function to get the 'return_value' attribute of
  68    FinishBreakpoint.  */
  69
  70 static PyObject *
  71 bpfinishpy_get_returnvalue (PyObject *self, void *closure)
  72 {
  73   struct finish_breakpoint_object *self_finishbp =
  74       (struct finish_breakpoint_object *) self;
  75
  76   if (!self_finishbp->return_value)
  77     Py_RETURN_NONE;
  78
  79   Py_INCREF (self_finishbp->return_value);
  80   return self_finishbp->return_value;
  81 }
  82
  83 /* Deallocate FinishBreakpoint object.  */
  84
  85 static void
  86 bpfinishpy_dealloc (PyObject *self)
  87 {
  88   struct finish_breakpoint_object *self_bpfinish =
  89         (struct finish_breakpoint_object *) self;
  90
  91   Py_XDECREF (self_bpfinish->func_symbol);
  92   Py_XDECREF (self_bpfinish->function_value);
  93   Py_XDECREF (self_bpfinish->return_value);
  94   Py_TYPE (self)->tp_free (self);
  95 }
  96
  97 /* Triggered when gdbpy_breakpoint_cond_says_stop is about to execute the `stop'
  98    callback of the gdb.FinishBreakpoint object BP_OBJ.  Will compute and cache
  99    the `return_value', if possible.  */
 100
 101 void
 102 bpfinishpy_pre_stop_hook (struct gdbpy_breakpoint_object *bp_obj)
 103 {
 104   struct finish_breakpoint_object *self_finishbp =
 105         (struct finish_breakpoint_object *) bp_obj;
 106
 107   /* Can compute return_value only once.  */
 108   gdb_assert (!self_finishbp->return_value);
 109
 110   if (self_finishbp->func_symbol == nullptr)
 111     return;
 112
 113   try
 114     {
 115       scoped_value_mark free_values;
 116
 117       struct symbol *func_symbol =
 118         symbol_object_to_symbol (self_finishbp->func_symbol);
 119       struct value *function =
 120         value_object_to_value (self_finishbp->function_value);
 121       struct value *ret =
 122         get_return_value (func_symbol, function);
 123
 124       if (ret)
 125         {
 126           self_finishbp->return_value = value_to_value_object (ret);
 127           if (!self_finishbp->return_value)
 128               gdbpy_print_stack ();
 129         }
 130       else
 131         {
 132           Py_INCREF (Py_None);
 133           self_finishbp->return_value = Py_None;
 134         }
 135     }
 136   catch (const gdb_exception &except)
 137     {
 138       gdbpy_convert_exception (except);
 139       gdbpy_print_stack ();
 140     }
 141 }
 142
 143 /* Triggered when gdbpy_breakpoint_cond_says_stop has triggered the `stop'
 144    callback of the gdb.FinishBreakpoint object BP_OBJ.  */
 145
 146 void
 147 bpfinishpy_post_stop_hook (struct gdbpy_breakpoint_object *bp_obj)
 148 {
 149
 150   try
 151     {
 152       /* Can't delete it here, but it will be removed at the next stop.  */
 153       disable_breakpoint (bp_obj->bp);
 154       bp_obj->bp->disposition = disp_del_at_next_stop;
 155     }
 156   catch (const gdb_exception &except)
 157     {
 158       gdbpy_convert_exception (except);
 159       gdbpy_print_stack ();
 160     }
 161 }
 162
 163 /* Python function to create a new breakpoint.  */
 164
 165 static int
 166 bpfinishpy_init (PyObject *self, PyObject *args, PyObject *kwargs)
 167 {
 168   static const char *keywords[] = { "frame", "internal", NULL };
 169   struct finish_breakpoint_object *self_bpfinish =
 170       (struct finish_breakpoint_object *) self;
 171   PyObject *frame_obj = NULL;
 172   int thread;
 173   frame_info_ptr frame = NULL; /* init for gcc -Wall */
 174   frame_info_ptr prev_frame = NULL;
 175   struct frame_id frame_id;
 176   PyObject *internal = NULL;
 177   int internal_bp = 0;
 178   CORE_ADDR pc;
 179
 180   if (!gdb_PyArg_ParseTupleAndKeywords (args, kwargs, "|OO", keywords,
 181                                         &frame_obj, &internal))
 182     return -1;
 183
 184   try
 185     {
 186       /* Default frame to newest frame if necessary.  */
 187       if (frame_obj == NULL)
 188         frame = get_current_frame ();
 189       else
 190         frame = frame_object_to_frame_info (frame_obj);
 191
 192       if (frame == NULL)
 193         {
 194           PyErr_SetString (PyExc_ValueError,
 195                            _("Invalid ID for the `frame' object."));
 196         }
 197       else
 198         {
 199           prev_frame = get_prev_frame (frame);
 200           if (prev_frame == 0)
 201             {
 202               PyErr_SetString (PyExc_ValueError,
 203                                _("\"FinishBreakpoint\" not "
 204                                  "meaningful in the outermost "
 205                                  "frame."));
 206             }
 207           else if (get_frame_type (prev_frame) == DUMMY_FRAME)
 208             {
 209               PyErr_SetString (PyExc_ValueError,
 210                                _("\"FinishBreakpoint\" cannot "
 211                                  "be set on a dummy frame."));
 212             }
 213           else
 214             /* Get the real calling frame ID, ignoring inline frames.  */
 215             frame_id = frame_unwind_caller_id (frame);
 216         }
 217     }
 218   catch (const gdb_exception &except)
 219     {
 220       return gdbpy_handle_gdb_exception (-1, except);
 221     }
 222
 223   if (PyErr_Occurred ())
 224     return -1;
 225
 226   if (inferior_ptid == null_ptid)
 227     {
 228       PyErr_SetString (PyExc_ValueError,
 229                        _("No thread currently selected."));
 230       return -1;
 231     }
 232
 233   thread = inferior_thread ()->global_num;
 234
 235   if (internal)
 236     {
 237       internal_bp = PyObject_IsTrue (internal);
 238       if (internal_bp == -1)
 239         {
 240           PyErr_SetString (PyExc_ValueError,
 241                            _("The value of `internal' must be a boolean."));
 242           return -1;
 243         }
 244     }
 245
 246   /* Find the function we will return from.  */
 247   self_bpfinish->func_symbol = nullptr;
 248   self_bpfinish->function_value = nullptr;
 249
 250   try
 251     {
 252       if (get_frame_pc_if_available (frame, &pc))
 253         {
 254           struct symbol *function = find_pc_function (pc);
 255           if (function != nullptr)
 256             {
 257               struct type *ret_type =
 258                 check_typedef (function->type ()->target_type ());
 259
 260               /* Remember only non-void return types.  */
 261               if (ret_type->code () != TYPE_CODE_VOID)
 262                 {
 263                   scoped_value_mark free_values;
 264
 265                   /* Ignore Python errors at this stage.  */
 266                   value *func_value = read_var_value (function, NULL, frame);
 267                   self_bpfinish->function_value
 268                     = value_to_value_object (func_value);
 269                   PyErr_Clear ();
 270
 271                   self_bpfinish->func_symbol
 272                     = symbol_to_symbol_object (function);
 273                   PyErr_Clear ();
 274                 }
 275             }
 276         }
 277     }
 278   catch (const gdb_exception_forced_quit &except)
 279     {
 280       quit_force (NULL, 0);
 281     }
 282   catch (const gdb_exception &except)
 283     {
 284       /* Just swallow.  Either the return type or the function value
 285          remain NULL.  */
 286     }
 287
 288   if (self_bpfinish->func_symbol == nullptr
 289       || self_bpfinish->function_value == nullptr)
 290     {
 291       /* Won't be able to compute return value.  */
 292       Py_XDECREF (self_bpfinish->func_symbol);
 293       Py_XDECREF (self_bpfinish->function_value);
 294
 295       self_bpfinish->func_symbol = nullptr;
 296       self_bpfinish->function_value = nullptr;
 297     }
 298
 299   bppy_pending_object = &self_bpfinish->py_bp;
 300   bppy_pending_object->number = -1;
 301   bppy_pending_object->bp = NULL;
 302
 303   try
 304     {
 305       /* Set a breakpoint on the return address.  */
 306       location_spec_up locspec
 307         = new_address_location_spec (get_frame_pc (prev_frame), NULL, 0);
 308       create_breakpoint (gdbpy_enter::get_gdbarch (),
 309                          locspec.get (), NULL, thread, -1, NULL, false,
 310                          0,
 311                          1 /*temp_flag*/,
 312                          bp_breakpoint,
 313                          0,
 314                          AUTO_BOOLEAN_TRUE,
 315                          &code_breakpoint_ops,
 316                          0, 1, internal_bp, 0);
 317     }
 318   catch (const gdb_exception &except)
 319     {
 320       return gdbpy_handle_gdb_exception (-1, except);
 321     }
 322
 323   self_bpfinish->py_bp.bp->frame_id = frame_id;
 324   self_bpfinish->py_bp.is_finish_bp = 1;
 325   self_bpfinish->initiating_frame = get_frame_id (frame);
 326
 327   /* Bind the breakpoint with the current program space.  */
 328   self_bpfinish->py_bp.bp->pspace = current_program_space;
 329
 330   return 0;
 331 }
 332
 333 /* Called when GDB notices that the finish breakpoint BP_OBJ is out of
 334    the current callstack.  Triggers the method OUT_OF_SCOPE if implemented,
 335    then delete the breakpoint.  */
 336
 337 static void
 338 bpfinishpy_out_of_scope (struct finish_breakpoint_object *bpfinish_obj)
 339 {
 340   gdbpy_breakpoint_object *bp_obj = (gdbpy_breakpoint_object *) bpfinish_obj;
 341   PyObject *py_obj = (PyObject *) bp_obj;
 342
 343   if (bpfinish_obj->py_bp.bp->enable_state == bp_enabled
 344       && PyObject_HasAttrString (py_obj, outofscope_func))
 345     {
 346       gdbpy_ref<> meth_result = gdbpy_call_method (py_obj, outofscope_func);
 347       if (meth_result == NULL)
 348         gdbpy_print_stack ();
 349     }
 350 }
 351
 352 /* Callback for `bpfinishpy_detect_out_scope'.  Triggers Python's
 353    `B->out_of_scope' function if B is a FinishBreakpoint out of its scope.
 354
 355    When DELETE_BP is true then breakpoint B will be deleted if B is a
 356    FinishBreakpoint and it is out of scope, otherwise B will not be
 357    deleted.  */
 358
 359 static void
 360 bpfinishpy_detect_out_scope_cb (struct breakpoint *b,
 361                                 struct breakpoint *bp_stopped,
 362                                 bool delete_bp)
 363 {
 364   PyObject *py_bp = (PyObject *) b->py_bp_object;
 365
 366   /* Trigger out_of_scope if this is a FinishBreakpoint and its frame is
 367      not anymore in the current callstack.  */
 368   if (py_bp != NULL && b->py_bp_object->is_finish_bp)
 369     {
 370       struct finish_breakpoint_object *finish_bp =
 371           (struct finish_breakpoint_object *) py_bp;
 372
 373       /* Check scope if not currently stopped at the FinishBreakpoint.  */
 374       if (b != bp_stopped)
 375         {
 376           try
 377             {
 378               struct frame_id initiating_frame = finish_bp->initiating_frame;
 379
 380               if (b->pspace == current_inferior ()->pspace
 381                   && (!target_has_registers ()
 382                       || frame_find_by_id (initiating_frame) == NULL))
 383                 {
 384                   bpfinishpy_out_of_scope (finish_bp);
 385                   if (delete_bp)
 386                     delete_breakpoint (finish_bp->py_bp.bp);
 387                 }
 388             }
 389           catch (const gdb_exception &except)
 390             {
 391               gdbpy_convert_exception (except);
 392               gdbpy_print_stack ();
 393             }
 394         }
 395     }
 396 }
 397
 398 /* Called when gdbpy_breakpoint_deleted is about to delete a breakpoint.  A
 399    chance to trigger the out_of_scope callback (if appropriate) for the
 400    associated Python object.  */
 401
 402 void
 403 bpfinishpy_pre_delete_hook (struct gdbpy_breakpoint_object *bp_obj)
 404 {
 405   breakpoint *bp = bp_obj->bp;
 406   bpfinishpy_detect_out_scope_cb (bp, nullptr, false);
 407 }
 408
 409 /* Attached to `stop' notifications, check if the execution has run
 410    out of the scope of any FinishBreakpoint before it has been hit.  */
 411
 412 static void
 413 bpfinishpy_handle_stop (struct bpstat *bs, int print_frame)
 414 {
 415   gdbpy_enter enter_py;
 416
 417   for (breakpoint &bp : all_breakpoints_safe ())
 418     bpfinishpy_detect_out_scope_cb
 419       (&bp, bs == NULL ? NULL : bs->breakpoint_at, true);
 420 }
 421
 422 /* Attached to `exit' notifications, triggers all the necessary out of
 423    scope notifications.  */
 424
 425 static void
 426 bpfinishpy_handle_exit (struct inferior *inf)
 427 {
 428   gdbpy_enter enter_py (current_inferior ()->arch ());
 429
 430   for (breakpoint &bp : all_breakpoints_safe ())
 431     bpfinishpy_detect_out_scope_cb (&bp, nullptr, true);
 432 }
 433
 434 /* Initialize the Python finish breakpoint code.  */
 435
 436 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
 437 gdbpy_initialize_finishbreakpoints (void)
 438 {
 439   if (!gdbpy_breakpoint_init_breakpoint_type ())
 440     return -1;
 441
 442   if (gdbpy_type_ready (&finish_breakpoint_object_type) < 0)
 443     return -1;
 444
 445   gdb::observers::normal_stop.attach (bpfinishpy_handle_stop,
 446                                       "py-finishbreakpoint");
 447   gdb::observers::inferior_exit.attach (bpfinishpy_handle_exit,
 448                                         "py-finishbreakpoint");
 449
 450   return 0;
 451 }
 452
 453 GDBPY_INITIALIZE_FILE (gdbpy_initialize_finishbreakpoints);
 454
 455 \f
 456
 457 static gdb_PyGetSetDef finish_breakpoint_object_getset[] = {
 458   { "return_value", bpfinishpy_get_returnvalue, NULL,
 459   "gdb.Value object representing the return value, if any. \
 460 None otherwise.", NULL },
 461     { NULL }  /* Sentinel.  */
 462 };
 463
 464 PyTypeObject finish_breakpoint_object_type =
 465 {
 466   PyVarObject_HEAD_INIT (NULL, 0)
 467   "gdb.FinishBreakpoint",         /*tp_name*/
 468   sizeof (struct finish_breakpoint_object),  /*tp_basicsize*/
 469   0,                              /*tp_itemsize*/
 470   bpfinishpy_dealloc,             /*tp_dealloc*/
 471   0,                              /*tp_print*/
 472   0,                              /*tp_getattr*/
 473   0,                              /*tp_setattr*/
 474   0,                              /*tp_compare*/
 475   0,                              /*tp_repr*/
 476   0,                              /*tp_as_number*/
 477   0,                              /*tp_as_sequence*/
 478   0,                              /*tp_as_mapping*/
 479   0,                              /*tp_hash */
 480   0,                              /*tp_call*/
 481   0,                              /*tp_str*/
 482   0,                              /*tp_getattro*/
 483   0,                              /*tp_setattro */
 484   0,                              /*tp_as_buffer*/
 485   Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,  /*tp_flags*/
 486   "GDB finish breakpoint object", /* tp_doc */
 487   0,                              /* tp_traverse */
 488   0,                              /* tp_clear */
 489   0,                              /* tp_richcompare */
 490   0,                              /* tp_weaklistoffset */
 491   0,                              /* tp_iter */
 492   0,                              /* tp_iternext */
 493   0,                              /* tp_methods */
 494   0,                              /* tp_members */
 495   finish_breakpoint_object_getset,/* tp_getset */
 496   &breakpoint_object_type,        /* tp_base */
 497   0,                              /* tp_dict */
 498   0,                              /* tp_descr_get */
 499   0,                              /* tp_descr_set */
 500   0,                              /* tp_dictoffset */
 501   bpfinishpy_init,                /* tp_init */
 502   0,                              /* tp_alloc */
 503   0                               /* tp_new */
 504 };