gdb/python/py-block.c

   1 /* Python interface to blocks.
   2
   3    Copyright (C) 2008-2024 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 #include "block.h"
  21 #include "dictionary.h"
  22 #include "symtab.h"
  23 #include "python-internal.h"
  24 #include "objfiles.h"
  25
  26 struct block_object {
  27   PyObject_HEAD
  28   /* The GDB block structure that represents a frame's code block.  */
  29   const struct block *block;
  30   /* The backing object file.  There is no direct relationship in GDB
  31      between a block and an object file.  When a block is created also
  32      store a pointer to the object file for later use.  */
  33   struct objfile *objfile;
  34 };
  35
  36 struct block_syms_iterator_object {
  37   PyObject_HEAD
  38   /* The block.  */
  39   const struct block *block;
  40   /* The iterator for that block.  */
  41   struct block_iterator iter;
  42   /* Has the iterator been initialized flag.  */
  43   int initialized_p;
  44   /* Pointer back to the original source block object.  Needed to
  45      check if the block is still valid, and has not been invalidated
  46      when an object file has been freed.  */
  47   block_object *source;
  48 };
  49
  50 /* Require a valid block.  All access to block_object->block should be
  51    gated by this call.  */
  52 #define BLPY_REQUIRE_VALID(block_obj, block)            \
  53   do {                                                  \
  54     block = block_object_to_block (block_obj);          \
  55     if (block == NULL)                                  \
  56       {                                                 \
  57         PyErr_SetString (PyExc_RuntimeError,            \
  58                          _("Block is invalid."));       \
  59         return NULL;                                    \
  60       }                                                 \
  61   } while (0)
  62
  63 /* Require a valid block.  This macro is called during block iterator
  64    creation, and at each next call.  */
  65 #define BLPY_ITER_REQUIRE_VALID(block_obj)                              \
  66   do {                                                                  \
  67     if (block_obj->block == NULL)                                       \
  68       {                                                                 \
  69         PyErr_SetString (PyExc_RuntimeError,                            \
  70                          _("Source block for iterator is invalid."));   \
  71         return NULL;                                                    \
  72       }                                                                 \
  73   } while (0)
  74
  75 extern PyTypeObject block_syms_iterator_object_type
  76     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("block_syms_iterator_object");
  77 static const registry<objfile>::key<htab, htab_deleter>
  78      blpy_objfile_data_key;
  79
  80 static PyObject *
  81 blpy_iter (PyObject *self)
  82 {
  83   block_syms_iterator_object *block_iter_obj;
  84   const struct block *block = NULL;
  85
  86   BLPY_REQUIRE_VALID (self, block);
  87
  88   block_iter_obj = PyObject_New (block_syms_iterator_object,
  89                                  &block_syms_iterator_object_type);
  90   if (block_iter_obj == NULL)
  91       return NULL;
  92
  93   block_iter_obj->block = block;
  94   block_iter_obj->initialized_p = 0;
  95   Py_INCREF (self);
  96   block_iter_obj->source = (block_object *) self;
  97
  98   return (PyObject *) block_iter_obj;
  99 }
 100
 101 static PyObject *
 102 blpy_get_start (PyObject *self, void *closure)
 103 {
 104   const struct block *block = NULL;
 105
 106   BLPY_REQUIRE_VALID (self, block);
 107
 108   return gdb_py_object_from_ulongest (block->start ()).release ();
 109 }
 110
 111 static PyObject *
 112 blpy_get_end (PyObject *self, void *closure)
 113 {
 114   const struct block *block = NULL;
 115
 116   BLPY_REQUIRE_VALID (self, block);
 117
 118   return gdb_py_object_from_ulongest (block->end ()).release ();
 119 }
 120
 121 static PyObject *
 122 blpy_get_function (PyObject *self, void *closure)
 123 {
 124   struct symbol *sym;
 125   const struct block *block;
 126
 127   BLPY_REQUIRE_VALID (self, block);
 128
 129   sym = block->function ();
 130   if (sym)
 131     return symbol_to_symbol_object (sym);
 132
 133   Py_RETURN_NONE;
 134 }
 135
 136 static PyObject *
 137 blpy_get_superblock (PyObject *self, void *closure)
 138 {
 139   const struct block *block;
 140   const struct block *super_block;
 141   block_object *self_obj  = (block_object *) self;
 142
 143   BLPY_REQUIRE_VALID (self, block);
 144
 145   super_block = block->superblock ();
 146   if (super_block)
 147     return block_to_block_object (super_block, self_obj->objfile);
 148
 149   Py_RETURN_NONE;
 150 }
 151
 152 /* Return the global block associated to this block.  */
 153
 154 static PyObject *
 155 blpy_get_global_block (PyObject *self, void *closure)
 156 {
 157   const struct block *block;
 158   const struct block *global_block;
 159   block_object *self_obj  = (block_object *) self;
 160
 161   BLPY_REQUIRE_VALID (self, block);
 162
 163   global_block = block->global_block ();
 164
 165   return block_to_block_object (global_block,
 166                                 self_obj->objfile);
 167
 168 }
 169
 170 /* Return the static block associated to this block.  Return None
 171    if we cannot get the static block (this is the global block).  */
 172
 173 static PyObject *
 174 blpy_get_static_block (PyObject *self, void *closure)
 175 {
 176   const struct block *block;
 177   const struct block *static_block;
 178   block_object *self_obj  = (block_object *) self;
 179
 180   BLPY_REQUIRE_VALID (self, block);
 181
 182   if (block->superblock () == NULL)
 183     Py_RETURN_NONE;
 184
 185   static_block = block->static_block ();
 186
 187   return block_to_block_object (static_block, self_obj->objfile);
 188 }
 189
 190 /* Implementation of gdb.Block.is_global (self) -> Boolean.
 191    Returns True if this block object is a global block.  */
 192
 193 static PyObject *
 194 blpy_is_global (PyObject *self, void *closure)
 195 {
 196   const struct block *block;
 197
 198   BLPY_REQUIRE_VALID (self, block);
 199
 200   if (block->superblock ())
 201     Py_RETURN_FALSE;
 202
 203   Py_RETURN_TRUE;
 204 }
 205
 206 /* Implementation of gdb.Block.is_static (self) -> Boolean.
 207    Returns True if this block object is a static block.  */
 208
 209 static PyObject *
 210 blpy_is_static (PyObject *self, void *closure)
 211 {
 212   const struct block *block;
 213
 214   BLPY_REQUIRE_VALID (self, block);
 215
 216   if (block->superblock () != NULL
 217      && block->superblock ()->superblock () == NULL)
 218     Py_RETURN_TRUE;
 219
 220   Py_RETURN_FALSE;
 221 }
 222
 223 /* Given a string, returns the gdb.Symbol representing that symbol in this
 224    block.  If such a symbol does not exist, returns NULL with a Python
 225    exception.  */
 226
 227 static PyObject *
 228 blpy_getitem (PyObject *self, PyObject *key)
 229 {
 230   const struct block *block;
 231
 232   BLPY_REQUIRE_VALID (self, block);
 233
 234   gdb::unique_xmalloc_ptr<char> name = python_string_to_host_string (key);
 235   if (name == nullptr)
 236     return nullptr;
 237
 238   lookup_name_info lookup_name (name.get(), symbol_name_match_type::FULL);
 239
 240   /* We use an iterator instead of block_lookup_symbol so that we can
 241      look up symbols irrespective of the domain, matching the
 242      iterator. It would be confusing if the iterator returns symbols
 243      you can't find via getitem.  */
 244   for (struct symbol *sym : block_iterator_range (block, &lookup_name))
 245     {
 246       /* Just stop at the first match */
 247       return symbol_to_symbol_object (sym);
 248     }
 249
 250   PyErr_SetObject (PyExc_KeyError, key);
 251   return nullptr;
 252 }
 253
 254 /* Deleter function for the hash table.  */
 255
 256 static void
 257 block_object_del (void *obj)
 258 {
 259   block_object *block = (block_object *) obj;
 260   block->block = nullptr;
 261   block->objfile = nullptr;
 262 }
 263
 264 /* Hash function for the hash table.  */
 265
 266 static hashval_t
 267 block_object_hash (const void *obj)
 268 {
 269   const block_object *block = (const block_object *) obj;
 270   return htab_hash_pointer (block->block);
 271 }
 272
 273 /* Equality function for the hash table.  Note that searches must be
 274    done with a plain block.  */
 275
 276 static int
 277 block_object_eq (const void *a, const void *b)
 278 {
 279   const block_object *blocka = (const block_object *) a;
 280   const block *blockb = (const block *) b;
 281   return blocka->block == blockb;
 282 }
 283
 284 /* Called when a gdb.Block is destroyed.  This removes it from the
 285    hash.  */
 286
 287 static void
 288 blpy_dealloc (PyObject *obj)
 289 {
 290   block_object *block = (block_object *) obj;
 291
 292   if (block->objfile != nullptr)
 293     {
 294       htab_t table = blpy_objfile_data_key.get (block->objfile);
 295       hashval_t hash = block_object_hash (block);
 296       /* This will clear the contents of the block as a side
 297          effect.  */
 298       htab_remove_elt_with_hash (table, block->block, hash);
 299     }
 300
 301   Py_TYPE (obj)->tp_free (obj);
 302 }
 303
 304 /* Create a new block object (gdb.Block) that encapsulates the struct
 305    block object from GDB.  */
 306 PyObject *
 307 block_to_block_object (const struct block *block, struct objfile *objfile)
 308 {
 309   htab_t table = blpy_objfile_data_key.get (objfile);
 310   if (table == nullptr)
 311     {
 312       table = htab_create_alloc (10, block_object_hash, block_object_eq,
 313                                  block_object_del, xcalloc, xfree);
 314       blpy_objfile_data_key.set (objfile, table);
 315     }
 316
 317   hashval_t hash = htab_hash_pointer (block);
 318   block_object *result = (block_object *) htab_find_with_hash (table, block,
 319                                                                hash);
 320   if (result != nullptr)
 321     {
 322       PyObject *py_result = (PyObject *) result;
 323       Py_INCREF (py_result);
 324       return py_result;
 325     }
 326
 327   result = PyObject_New (block_object, &block_object_type);
 328   result->block = block;
 329   result->objfile = objfile;
 330
 331   void **slot = htab_find_slot_with_hash (table, block, hash, INSERT);
 332   *slot = result;
 333
 334   return (PyObject *) result;
 335 }
 336
 337 /* Return struct block reference that is wrapped by this object.  */
 338 const struct block *
 339 block_object_to_block (PyObject *obj)
 340 {
 341   if (! PyObject_TypeCheck (obj, &block_object_type))
 342     return NULL;
 343   return ((block_object *) obj)->block;
 344 }
 345
 346 /* Return a reference to the block iterator.  */
 347 static PyObject *
 348 blpy_block_syms_iter (PyObject *self)
 349 {
 350   block_syms_iterator_object *iter_obj = (block_syms_iterator_object *) self;
 351
 352   BLPY_ITER_REQUIRE_VALID (iter_obj->source);
 353
 354   Py_INCREF (self);
 355   return self;
 356 }
 357
 358 /* Return the next symbol in the iteration through the block's
 359    dictionary.  */
 360 static PyObject *
 361 blpy_block_syms_iternext (PyObject *self)
 362 {
 363   block_syms_iterator_object *iter_obj = (block_syms_iterator_object *) self;
 364   struct symbol *sym;
 365
 366   BLPY_ITER_REQUIRE_VALID (iter_obj->source);
 367
 368   if (!iter_obj->initialized_p)
 369     {
 370       sym = block_iterator_first (iter_obj->block,  &(iter_obj->iter));
 371       iter_obj->initialized_p = 1;
 372     }
 373   else
 374     sym = block_iterator_next (&(iter_obj->iter));
 375
 376   if (sym == NULL)
 377     {
 378       PyErr_SetString (PyExc_StopIteration, _("Symbol is null."));
 379       return NULL;
 380     }
 381
 382   return symbol_to_symbol_object (sym);
 383 }
 384
 385 static void
 386 blpy_block_syms_dealloc (PyObject *obj)
 387 {
 388   block_syms_iterator_object *iter_obj = (block_syms_iterator_object *) obj;
 389
 390   Py_XDECREF (iter_obj->source);
 391   Py_TYPE (obj)->tp_free (obj);
 392 }
 393
 394 /* Implementation of gdb.Block.is_valid (self) -> Boolean.
 395    Returns True if this block object still exists in GDB.  */
 396
 397 static PyObject *
 398 blpy_is_valid (PyObject *self, PyObject *args)
 399 {
 400   const struct block *block;
 401
 402   block = block_object_to_block (self);
 403   if (block == NULL)
 404     Py_RETURN_FALSE;
 405
 406   Py_RETURN_TRUE;
 407 }
 408
 409 /* Implementation of gdb.BlockIterator.is_valid (self) -> Boolean.
 410    Returns True if this block iterator object still exists in GDB  */
 411
 412 static PyObject *
 413 blpy_iter_is_valid (PyObject *self, PyObject *args)
 414 {
 415   block_syms_iterator_object *iter_obj =
 416     (block_syms_iterator_object *) self;
 417
 418   if (iter_obj->source->block == NULL)
 419     Py_RETURN_FALSE;
 420
 421   Py_RETURN_TRUE;
 422 }
 423
 424 /* __repr__ implementation for gdb.Block.  */
 425
 426 static PyObject *
 427 blpy_repr (PyObject *self)
 428 {
 429   const auto block = block_object_to_block (self);
 430   if (block == nullptr)
 431     return gdb_py_invalid_object_repr (self);
 432
 433   const auto name = block->function () ?
 434     block->function ()->print_name () : "<anonymous>";
 435
 436   std::string str;
 437   unsigned int written_symbols = 0;
 438   const int len = mdict_size (block->multidict ());
 439   static constexpr int SYMBOLS_TO_SHOW = 5;
 440   for (struct symbol *symbol : block_iterator_range (block))
 441     {
 442       if (written_symbols == SYMBOLS_TO_SHOW)
 443         {
 444           const int remaining = len - SYMBOLS_TO_SHOW;
 445           if (remaining == 1)
 446             str += string_printf ("... (%d more symbol)", remaining);
 447           else
 448             str += string_printf ("... (%d more symbols)", remaining);
 449           break;
 450         }
 451       str += symbol->print_name ();
 452       if (++written_symbols < len)
 453         str += ", ";
 454     }
 455   return PyUnicode_FromFormat ("<%s %s {%s}>", Py_TYPE (self)->tp_name,
 456                                name, str.c_str ());
 457 }
 458
 459 /* Hash function for block objects.  */
 460
 461 static Py_hash_t
 462 blpy_hash (PyObject *self)
 463 {
 464   /* Python doesn't really expose its pointer hash function, so we use
 465      our own.  */
 466   Py_hash_t result = (Py_hash_t) htab_hash_pointer (self);
 467   /* -1 has a special meaning for Python.  */
 468   if (result == -1)
 469     result = -2;
 470   return result;
 471 }
 472
 473 /* Implements the equality comparison for Block objects.  All other
 474    comparison operators will throw NotImplemented, as they aren't
 475    valid for blocks.  */
 476
 477 static PyObject *
 478 blpy_richcompare (PyObject *self, PyObject *other, int op)
 479 {
 480   if (!PyObject_TypeCheck (other, &block_object_type)
 481       || (op != Py_EQ && op != Py_NE))
 482     {
 483       Py_INCREF (Py_NotImplemented);
 484       return Py_NotImplemented;
 485     }
 486
 487   bool expected = self == other;
 488   bool equal = op == Py_EQ;
 489   return PyBool_FromLong (equal == expected);
 490 }
 491
 492 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
 493 gdbpy_initialize_blocks (void)
 494 {
 495   block_object_type.tp_new = PyType_GenericNew;
 496   if (gdbpy_type_ready (&block_object_type) < 0)
 497     return -1;
 498
 499   block_syms_iterator_object_type.tp_new = PyType_GenericNew;
 500   if (gdbpy_type_ready (&block_syms_iterator_object_type) < 0)
 501     return -1;
 502
 503   return 0;
 504 }
 505
 506 GDBPY_INITIALIZE_FILE (gdbpy_initialize_blocks);
 507
 508 \f
 509
 510 static PyMethodDef block_object_methods[] = {
 511   { "is_valid", blpy_is_valid, METH_NOARGS,
 512     "is_valid () -> Boolean.\n\
 513 Return true if this block is valid, false if not." },
 514   {NULL}  /* Sentinel */
 515 };
 516
 517 static gdb_PyGetSetDef block_object_getset[] = {
 518   { "start", blpy_get_start, NULL, "Start address of the block.", NULL },
 519   { "end", blpy_get_end, NULL, "End address of the block.", NULL },
 520   { "function", blpy_get_function, NULL,
 521     "Symbol that names the block, or None.", NULL },
 522   { "superblock", blpy_get_superblock, NULL,
 523     "Block containing the block, or None.", NULL },
 524   { "global_block", blpy_get_global_block, NULL,
 525     "Block containing the global block.", NULL },
 526   { "static_block", blpy_get_static_block, NULL,
 527     "Block containing the static block.", NULL },
 528   { "is_static", blpy_is_static, NULL,
 529     "Whether this block is a static block.", NULL },
 530   { "is_global", blpy_is_global, NULL,
 531     "Whether this block is a global block.", NULL },
 532   { NULL }  /* Sentinel */
 533 };
 534
 535 static PyMappingMethods block_object_as_mapping = {
 536   NULL,
 537   blpy_getitem,
 538   NULL
 539 };
 540
 541 PyTypeObject block_object_type = {
 542   PyVarObject_HEAD_INIT (NULL, 0)
 543   "gdb.Block",                    /*tp_name*/
 544   sizeof (block_object),          /*tp_basicsize*/
 545   0,                              /*tp_itemsize*/
 546   blpy_dealloc,                   /*tp_dealloc*/
 547   0,                              /*tp_print*/
 548   0,                              /*tp_getattr*/
 549   0,                              /*tp_setattr*/
 550   0,                              /*tp_compare*/
 551   blpy_repr,                      /*tp_repr*/
 552   0,                              /*tp_as_number*/
 553   0,                              /*tp_as_sequence*/
 554   &block_object_as_mapping,       /*tp_as_mapping*/
 555   blpy_hash,                      /*tp_hash */
 556   0,                              /*tp_call*/
 557   0,                              /*tp_str*/
 558   0,                              /*tp_getattro*/
 559   0,                              /*tp_setattro*/
 560   0,                              /*tp_as_buffer*/
 561   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 562   "GDB block object",             /* tp_doc */
 563   0,                              /* tp_traverse */
 564   0,                              /* tp_clear */
 565   blpy_richcompare,               /* tp_richcompare */
 566   0,                              /* tp_weaklistoffset */
 567   blpy_iter,                      /* tp_iter */
 568   0,                              /* tp_iternext */
 569   block_object_methods,           /* tp_methods */
 570   0,                              /* tp_members */
 571   block_object_getset             /* tp_getset */
 572 };
 573
 574 static PyMethodDef block_iterator_object_methods[] = {
 575   { "is_valid", blpy_iter_is_valid, METH_NOARGS,
 576     "is_valid () -> Boolean.\n\
 577 Return true if this block iterator is valid, false if not." },
 578   {NULL}  /* Sentinel */
 579 };
 580
 581 PyTypeObject block_syms_iterator_object_type = {
 582   PyVarObject_HEAD_INIT (NULL, 0)
 583   "gdb.BlockIterator",            /*tp_name*/
 584   sizeof (block_syms_iterator_object),        /*tp_basicsize*/
 585   0,                              /*tp_itemsize*/
 586   blpy_block_syms_dealloc,        /*tp_dealloc*/
 587   0,                              /*tp_print*/
 588   0,                              /*tp_getattr*/
 589   0,                              /*tp_setattr*/
 590   0,                              /*tp_compare*/
 591   0,                              /*tp_repr*/
 592   0,                              /*tp_as_number*/
 593   0,                              /*tp_as_sequence*/
 594   0,                              /*tp_as_mapping*/
 595   0,                              /*tp_hash */
 596   0,                              /*tp_call*/
 597   0,                              /*tp_str*/
 598   0,                              /*tp_getattro*/
 599   0,                              /*tp_setattro*/
 600   0,                              /*tp_as_buffer*/
 601   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 602   "GDB block syms iterator object",           /*tp_doc */
 603   0,                              /*tp_traverse */
 604   0,                              /*tp_clear */
 605   0,                              /*tp_richcompare */
 606   0,                              /*tp_weaklistoffset */
 607   blpy_block_syms_iter,           /*tp_iter */
 608   blpy_block_syms_iternext,       /*tp_iternext */
 609   block_iterator_object_methods   /*tp_methods */
 610 };