gdb/block.h

   1 /* Code dealing with blocks for GDB.
   2
   3    Copyright (C) 2003-2023 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 #ifndef BLOCK_H
  21 #define BLOCK_H
  22
  23 #include "dictionary.h"
  24 #include "gdbsupport/array-view.h"
  25
  26 /* Opaque declarations.  */
  27
  28 struct symbol;
  29 struct compunit_symtab;
  30 struct block_namespace_info;
  31 struct using_direct;
  32 struct obstack;
  33 struct addrmap;
  34
  35 /* Blocks can occupy non-contiguous address ranges.  When this occurs,
  36    startaddr and endaddr within struct block (still) specify the lowest
  37    and highest addresses of all ranges, but each individual range is
  38    specified by the addresses in struct blockrange.  */
  39
  40 struct blockrange
  41 {
  42   blockrange (CORE_ADDR start, CORE_ADDR end)
  43     : m_start (start),
  44       m_end (end)
  45   {
  46   }
  47
  48   /* Return this blockrange's start address.  */
  49   CORE_ADDR start () const
  50   { return m_start; }
  51
  52   /* Set this blockrange's start address.  */
  53   void set_start (CORE_ADDR start)
  54   { m_start = start; }
  55
  56   /* Return this blockrange's end address.  */
  57   CORE_ADDR end () const
  58   { return m_end; }
  59
  60   /* Set this blockrange's end address.  */
  61   void set_end (CORE_ADDR end)
  62   { m_end = end; }
  63
  64   /* Lowest address in this range.  */
  65
  66   CORE_ADDR m_start;
  67
  68   /* One past the highest address in the range.  */
  69
  70   CORE_ADDR m_end;
  71 };
  72
  73 /* Two or more non-contiguous ranges in the same order as that provided
  74    via the debug info.  */
  75
  76 struct blockranges
  77 {
  78   int nranges;
  79   struct blockrange range[1];
  80 };
  81
  82 /* All of the name-scope contours of the program
  83    are represented by `struct block' objects.
  84    All of these objects are pointed to by the blockvector.
  85
  86    Each block represents one name scope.
  87    Each lexical context has its own block.
  88
  89    The blockvector begins with some special blocks.
  90    The GLOBAL_BLOCK contains all the symbols defined in this compilation
  91    whose scope is the entire program linked together.
  92    The STATIC_BLOCK contains all the symbols whose scope is the
  93    entire compilation excluding other separate compilations.
  94    Blocks starting with the FIRST_LOCAL_BLOCK are not special.
  95
  96    Each block records a range of core addresses for the code that
  97    is in the scope of the block.  The STATIC_BLOCK and GLOBAL_BLOCK
  98    give, for the range of code, the entire range of code produced
  99    by the compilation that the symbol segment belongs to.
 100
 101    The blocks appear in the blockvector
 102    in order of increasing starting-address,
 103    and, within that, in order of decreasing ending-address.
 104
 105    This implies that within the body of one function
 106    the blocks appear in the order of a depth-first tree walk.  */
 107
 108 struct block
 109 {
 110   /* Return this block's start address.  */
 111   CORE_ADDR start () const
 112   { return m_start; }
 113
 114   /* Set this block's start address.  */
 115   void set_start (CORE_ADDR start)
 116   { m_start = start; }
 117
 118   /* Return this block's end address.  */
 119   CORE_ADDR end () const
 120   { return m_end; }
 121
 122   /* Set this block's end address.  */
 123   void set_end (CORE_ADDR end)
 124   { m_end = end; }
 125
 126   /* Return this block's function symbol.  */
 127   symbol *function () const
 128   { return m_function; }
 129
 130   /* Set this block's function symbol.  */
 131   void set_function (symbol *function)
 132   { m_function = function; }
 133
 134   /* Return this block's superblock.  */
 135   const block *superblock () const
 136   { return m_superblock; }
 137
 138   /* Set this block's superblock.  */
 139   void set_superblock (const block *superblock)
 140   { m_superblock = superblock; }
 141
 142   /* Return this block's multidict.  */
 143   multidictionary *multidict () const
 144   { return m_multidict; }
 145
 146   /* Set this block's multidict.  */
 147   void set_multidict (multidictionary *multidict)
 148   { m_multidict = multidict; }
 149
 150   /* Return this block's namespace info.  */
 151   block_namespace_info *namespace_info () const
 152   { return m_namespace_info; }
 153
 154   /* Set this block's namespace info.  */
 155   void set_namespace_info (block_namespace_info *namespace_info)
 156   { m_namespace_info = namespace_info; }
 157
 158   /* Return a view on this block's ranges.  */
 159   gdb::array_view<blockrange> ranges ()
 160   {
 161     if (m_ranges == nullptr)
 162       return {};
 163     else
 164       return gdb::make_array_view (m_ranges->range, m_ranges->nranges);
 165   }
 166
 167   /* Const version of the above.  */
 168   gdb::array_view<const blockrange> ranges () const
 169   {
 170     if (m_ranges == nullptr)
 171       return {};
 172     else
 173       return gdb::make_array_view (m_ranges->range, m_ranges->nranges);
 174   }
 175
 176   /* Set this block's ranges array.  */
 177   void set_ranges (blockranges *ranges)
 178   { m_ranges = ranges; }
 179
 180   /* Return true if all addresses within this block are contiguous.  */
 181   bool is_contiguous () const
 182   { return this->ranges ().size () <= 1; }
 183
 184   /* Return the "entry PC" of this block.
 185
 186      The entry PC is the lowest (start) address for the block when all addresses
 187      within the block are contiguous.  If non-contiguous, then use the start
 188      address for the first range in the block.
 189
 190      At the moment, this almost matches what DWARF specifies as the entry
 191      pc.  (The missing bit is support for DW_AT_entry_pc which should be
 192      preferred over range data and the low_pc.)
 193
 194      Once support for DW_AT_entry_pc is added, I expect that an entry_pc
 195      field will be added to one of these data structures.  Once that's done,
 196      the entry_pc field can be set from the dwarf reader (and other readers
 197      too).  ENTRY_PC can then be redefined to be less DWARF-centric.  */
 198
 199   CORE_ADDR entry_pc () const
 200   {
 201     if (this->is_contiguous ())
 202       return this->start ();
 203     else
 204       return this->ranges ()[0].start ();
 205   }
 206
 207   /* Addresses in the executable code that are in this block.  */
 208
 209   CORE_ADDR m_start;
 210   CORE_ADDR m_end;
 211
 212   /* The symbol that names this block, if the block is the body of a
 213      function (real or inlined); otherwise, zero.  */
 214
 215   struct symbol *m_function;
 216
 217   /* The `struct block' for the containing block, or 0 if none.
 218
 219      The superblock of a top-level local block (i.e. a function in the
 220      case of C) is the STATIC_BLOCK.  The superblock of the
 221      STATIC_BLOCK is the GLOBAL_BLOCK.  */
 222
 223   const struct block *m_superblock;
 224
 225   /* This is used to store the symbols in the block.  */
 226
 227   struct multidictionary *m_multidict;
 228
 229   /* Contains information about namespace-related info relevant to this block:
 230      using directives and the current namespace scope.  */
 231
 232   struct block_namespace_info *m_namespace_info;
 233
 234   /* Address ranges for blocks with non-contiguous ranges.  If this
 235      is NULL, then there is only one range which is specified by
 236      startaddr and endaddr above.  */
 237
 238   struct blockranges *m_ranges;
 239 };
 240
 241 /* The global block is singled out so that we can provide a back-link
 242    to the compunit symtab.  */
 243
 244 struct global_block
 245 {
 246   /* The block.  */
 247
 248   struct block block;
 249
 250   /* This holds a pointer to the compunit symtab holding this block.  */
 251
 252   struct compunit_symtab *compunit_symtab;
 253 };
 254
 255 struct blockvector
 256 {
 257   /* Return a view on the blocks of this blockvector.  */
 258   gdb::array_view<struct block *> blocks ()
 259   {
 260     return gdb::array_view<struct block *> (m_blocks, m_num_blocks);
 261   }
 262
 263   /* Const version of the above.  */
 264   gdb::array_view<const struct block *const> blocks () const
 265   {
 266     const struct block **blocks = (const struct block **) m_blocks;
 267     return gdb::array_view<const struct block *const> (blocks, m_num_blocks);
 268   }
 269
 270   /* Return the block at index I.  */
 271   struct block *block (size_t i)
 272   { return this->blocks ()[i]; }
 273
 274   /* Const version of the above.  */
 275   const struct block *block (size_t i) const
 276   { return this->blocks ()[i]; }
 277
 278   /* Set the block at index I.  */
 279   void set_block (int i, struct block *block)
 280   { m_blocks[i] = block; }
 281
 282   /* Set the number of blocks of this blockvector.
 283
 284      The storage of blocks is done using a flexible array member, so the number
 285      of blocks set here must agree with what was effectively allocated.  */
 286   void set_num_blocks (int num_blocks)
 287   { m_num_blocks = num_blocks; }
 288
 289   /* Return the number of blocks in this blockvector.  */
 290   int num_blocks () const
 291   { return m_num_blocks; }
 292
 293   /* Return the global block of this blockvector.  */
 294   struct block *global_block ()
 295   { return this->block (GLOBAL_BLOCK); }
 296
 297   /* Const version of the above.  */
 298   const struct block *global_block () const
 299   { return this->block (GLOBAL_BLOCK); }
 300
 301   /* Return the static block of this blockvector.  */
 302   struct block *static_block ()
 303   { return this->block (STATIC_BLOCK); }
 304
 305   /* Const version of the above.  */
 306   const struct block *static_block () const
 307   { return this->block (STATIC_BLOCK); }
 308
 309   /* Return the address -> block map of this blockvector.  */
 310   addrmap *map ()
 311   { return m_map; }
 312
 313   /* Const version of the above.  */
 314   const addrmap *map () const
 315   { return m_map; }
 316
 317   /* Set this blockvector's address -> block map.  */
 318   void set_map (addrmap *map)
 319   { m_map = map; }
 320
 321 private:
 322   /* An address map mapping addresses to blocks in this blockvector.
 323      This pointer is zero if the blocks' start and end addresses are
 324      enough.  */
 325   struct addrmap *m_map;
 326
 327   /* Number of blocks in the list.  */
 328   int m_num_blocks;
 329
 330   /* The blocks themselves.  */
 331   struct block *m_blocks[1];
 332 };
 333
 334 /* Return the objfile of BLOCK, which must be non-NULL.  */
 335
 336 extern struct objfile *block_objfile (const struct block *block);
 337
 338 /* Return the architecture of BLOCK, which must be non-NULL.  */
 339
 340 extern struct gdbarch *block_gdbarch (const struct block *block);
 341
 342 extern struct symbol *block_linkage_function (const struct block *);
 343
 344 extern struct symbol *block_containing_function (const struct block *);
 345
 346 extern int block_inlined_p (const struct block *block);
 347
 348 /* Return true if block A is lexically nested within block B, or if a
 349    and b have the same pc range.  Return false otherwise.  If
 350    ALLOW_NESTED is true, then block A is considered to be in block B
 351    if A is in a nested function in B's function.  If ALLOW_NESTED is
 352    false (the default), then blocks in nested functions are not
 353    considered to be contained.  */
 354
 355 extern bool contained_in (const struct block *a, const struct block *b,
 356                           bool allow_nested = false);
 357
 358 extern const struct blockvector *blockvector_for_pc (CORE_ADDR,
 359                                                const struct block **);
 360
 361 extern const struct blockvector *
 362   blockvector_for_pc_sect (CORE_ADDR, struct obj_section *,
 363                            const struct block **, struct compunit_symtab *);
 364
 365 extern int blockvector_contains_pc (const struct blockvector *bv, CORE_ADDR pc);
 366
 367 extern struct call_site *call_site_for_pc (struct gdbarch *gdbarch,
 368                                            CORE_ADDR pc);
 369
 370 extern const struct block *block_for_pc (CORE_ADDR);
 371
 372 extern const struct block *block_for_pc_sect (CORE_ADDR, struct obj_section *);
 373
 374 extern const char *block_scope (const struct block *block);
 375
 376 extern void block_set_scope (struct block *block, const char *scope,
 377                              struct obstack *obstack);
 378
 379 extern struct using_direct *block_using (const struct block *block);
 380
 381 extern void block_set_using (struct block *block,
 382                              struct using_direct *using_decl,
 383                              struct obstack *obstack);
 384
 385 extern const struct block *block_static_block (const struct block *block);
 386
 387 extern const struct block *block_global_block (const struct block *block);
 388
 389 extern struct block *allocate_block (struct obstack *obstack);
 390
 391 extern struct block *allocate_global_block (struct obstack *obstack);
 392
 393 extern void set_block_compunit_symtab (struct block *,
 394                                        struct compunit_symtab *);
 395
 396 /* Return a property to evaluate the static link associated to BLOCK.
 397
 398    In the context of nested functions (available in Pascal, Ada and GNU C, for
 399    instance), a static link (as in DWARF's DW_AT_static_link attribute) for a
 400    function is a way to get the frame corresponding to the enclosing function.
 401
 402    Note that only objfile-owned and function-level blocks can have a static
 403    link.  Return NULL if there is no such property.  */
 404
 405 extern struct dynamic_prop *block_static_link (const struct block *block);
 406
 407 /* A block iterator.  This structure should be treated as though it
 408    were opaque; it is only defined here because we want to support
 409    stack allocation of iterators.  */
 410
 411 struct block_iterator
 412 {
 413   /* If we're iterating over a single block, this holds the block.
 414      Otherwise, it holds the canonical compunit.  */
 415
 416   union
 417   {
 418     struct compunit_symtab *compunit_symtab;
 419     const struct block *block;
 420   } d;
 421
 422   /* If we're iterating over a single block, this is always -1.
 423      Otherwise, it holds the index of the current "included" symtab in
 424      the canonical symtab (that is, d.symtab->includes[idx]), with -1
 425      meaning the canonical symtab itself.  */
 426
 427   int idx;
 428
 429   /* Which block, either static or global, to iterate over.  If this
 430      is FIRST_LOCAL_BLOCK, then we are iterating over a single block.
 431      This is used to select which field of 'd' is in use.  */
 432
 433   enum block_enum which;
 434
 435   /* The underlying multidictionary iterator.  */
 436
 437   struct mdict_iterator mdict_iter;
 438 };
 439
 440 /* Initialize ITERATOR to point at the first symbol in BLOCK, and
 441    return that first symbol, or NULL if BLOCK is empty.  */
 442
 443 extern struct symbol *block_iterator_first (const struct block *block,
 444                                             struct block_iterator *iterator);
 445
 446 /* Advance ITERATOR, and return the next symbol, or NULL if there are
 447    no more symbols.  Don't call this if you've previously received
 448    NULL from block_iterator_first or block_iterator_next on this
 449    iteration.  */
 450
 451 extern struct symbol *block_iterator_next (struct block_iterator *iterator);
 452
 453 /* Initialize ITERATOR to point at the first symbol in BLOCK whose
 454    search_name () matches NAME, and return that first symbol, or
 455    NULL if there are no such symbols.  */
 456
 457 extern struct symbol *block_iter_match_first (const struct block *block,
 458                                               const lookup_name_info &name,
 459                                               struct block_iterator *iterator);
 460
 461 /* Advance ITERATOR to point at the next symbol in BLOCK whose
 462    search_name () matches NAME, or NULL if there are no more such
 463    symbols.  Don't call this if you've previously received NULL from
 464    block_iterator_match_first or block_iterator_match_next on this
 465    iteration.  And don't call it unless ITERATOR was created by a
 466    previous call to block_iter_match_first with the same NAME.  */
 467
 468 extern struct symbol *block_iter_match_next
 469   (const lookup_name_info &name, struct block_iterator *iterator);
 470
 471 /* Return true if symbol A is the best match possible for DOMAIN.  */
 472
 473 extern bool best_symbol (struct symbol *a, const domain_enum domain);
 474
 475 /* Return symbol B if it is a better match than symbol A for DOMAIN.
 476    Otherwise return A.  */
 477
 478 extern struct symbol *better_symbol (struct symbol *a, struct symbol *b,
 479                                      const domain_enum domain);
 480
 481 /* Search BLOCK for symbol NAME in DOMAIN.  */
 482
 483 extern struct symbol *block_lookup_symbol (const struct block *block,
 484                                            const char *name,
 485                                            symbol_name_match_type match_type,
 486                                            const domain_enum domain);
 487
 488 /* Search BLOCK for symbol NAME in DOMAIN but only in primary symbol table of
 489    BLOCK.  BLOCK must be STATIC_BLOCK or GLOBAL_BLOCK.  Function is useful if
 490    one iterates all global/static blocks of an objfile.  */
 491
 492 extern struct symbol *block_lookup_symbol_primary (const struct block *block,
 493                                                    const char *name,
 494                                                    const domain_enum domain);
 495
 496 /* The type of the MATCHER argument to block_find_symbol.  */
 497
 498 typedef int (block_symbol_matcher_ftype) (struct symbol *, void *);
 499
 500 /* Find symbol NAME in BLOCK and in DOMAIN that satisfies MATCHER.
 501    DATA is passed unchanged to MATCHER.
 502    BLOCK must be STATIC_BLOCK or GLOBAL_BLOCK.  */
 503
 504 extern struct symbol *block_find_symbol (const struct block *block,
 505                                          const char *name,
 506                                          const domain_enum domain,
 507                                          block_symbol_matcher_ftype *matcher,
 508                                          void *data);
 509
 510 /* A matcher function for block_find_symbol to find only symbols with
 511    non-opaque types.  */
 512
 513 extern int block_find_non_opaque_type (struct symbol *sym, void *data);
 514
 515 /* A matcher function for block_find_symbol to prefer symbols with
 516    non-opaque types.  The way to use this function is as follows:
 517
 518    struct symbol *with_opaque = NULL;
 519    struct symbol *sym
 520      = block_find_symbol (block, name, domain,
 521                           block_find_non_opaque_type_preferred, &with_opaque);
 522
 523    At this point if SYM is non-NULL then a non-opaque type has been found.
 524    Otherwise, if WITH_OPAQUE is non-NULL then an opaque type has been found.
 525    Otherwise, the symbol was not found.  */
 526
 527 extern int block_find_non_opaque_type_preferred (struct symbol *sym,
 528                                                  void *data);
 529
 530 /* Macro to loop through all symbols in BLOCK, in no particular
 531    order.  ITER helps keep track of the iteration, and must be a
 532    struct block_iterator.  SYM points to the current symbol.  */
 533
 534 #define ALL_BLOCK_SYMBOLS(block, iter, sym)             \
 535   for ((sym) = block_iterator_first ((block), &(iter)); \
 536        (sym);                                           \
 537        (sym) = block_iterator_next (&(iter)))
 538
 539 /* Macro to loop through all symbols in BLOCK with a name that matches
 540    NAME, in no particular order.  ITER helps keep track of the
 541    iteration, and must be a struct block_iterator.  SYM points to the
 542    current symbol.  */
 543
 544 #define ALL_BLOCK_SYMBOLS_WITH_NAME(block, name, iter, sym)             \
 545   for ((sym) = block_iter_match_first ((block), (name), &(iter));       \
 546        (sym) != NULL;                                                   \
 547        (sym) = block_iter_match_next ((name), &(iter)))
 548
 549 /* Given a vector of pairs, allocate and build an obstack allocated
 550    blockranges struct for a block.  */
 551 struct blockranges *make_blockranges (struct objfile *objfile,
 552                                       const std::vector<blockrange> &rangevec);
 553
 554 #endif /* BLOCK_H */