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 : public allocate_on_obstack
 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   /* Return an iterator range for this block's multidict.  */
 147   iterator_range<mdict_iterator_wrapper> multidict_symbols () const
 148   { return iterator_range<mdict_iterator_wrapper> (m_multidict); }
 149
 150   /* Set this block's multidict.  */
 151   void set_multidict (multidictionary *multidict)
 152   { m_multidict = multidict; }
 153
 154   /* Return a view on this block's ranges.  */
 155   gdb::array_view<blockrange> ranges ()
 156   {
 157     if (m_ranges == nullptr)
 158       return {};
 159     else
 160       return gdb::make_array_view (m_ranges->range, m_ranges->nranges);
 161   }
 162
 163   /* Const version of the above.  */
 164   gdb::array_view<const blockrange> ranges () const
 165   {
 166     if (m_ranges == nullptr)
 167       return {};
 168     else
 169       return gdb::make_array_view (m_ranges->range, m_ranges->nranges);
 170   }
 171
 172   /* Set this block's ranges array.  */
 173   void set_ranges (blockranges *ranges)
 174   { m_ranges = ranges; }
 175
 176   /* Return true if all addresses within this block are contiguous.  */
 177   bool is_contiguous () const
 178   { return this->ranges ().size () <= 1; }
 179
 180   /* Return the "entry PC" of this block.
 181
 182      The entry PC is the lowest (start) address for the block when all addresses
 183      within the block are contiguous.  If non-contiguous, then use the start
 184      address for the first range in the block.
 185
 186      At the moment, this almost matches what DWARF specifies as the entry
 187      pc.  (The missing bit is support for DW_AT_entry_pc which should be
 188      preferred over range data and the low_pc.)
 189
 190      Once support for DW_AT_entry_pc is added, I expect that an entry_pc
 191      field will be added to one of these data structures.  Once that's done,
 192      the entry_pc field can be set from the dwarf reader (and other readers
 193      too).  ENTRY_PC can then be redefined to be less DWARF-centric.  */
 194
 195   CORE_ADDR entry_pc () const
 196   {
 197     if (this->is_contiguous ())
 198       return this->start ();
 199     else
 200       return this->ranges ()[0].start ();
 201   }
 202
 203   /* Return the objfile of this block.  */
 204
 205   struct objfile *objfile () const;
 206
 207   /* Return the architecture of this block.  */
 208
 209   struct gdbarch *gdbarch () const;
 210
 211   /* Return true if BL represents an inlined function.  */
 212
 213   bool inlined_p () const;
 214
 215   /* This returns the namespace that this block is enclosed in, or ""
 216      if it isn't enclosed in a namespace at all.  This travels the
 217      chain of superblocks looking for a scope, if necessary.  */
 218
 219   const char *scope () const;
 220
 221   /* Set this block's scope member to SCOPE; if needed, allocate
 222      memory via OBSTACK.  (It won't make a copy of SCOPE, however, so
 223      that already has to be allocated correctly.)  */
 224
 225   void set_scope (const char *scope, struct obstack *obstack);
 226
 227   /* This returns the using directives list associated with this
 228      block, if any.  */
 229
 230   struct using_direct *get_using () const;
 231
 232   /* Set this block's using member to USING; if needed, allocate
 233      memory via OBSTACK.  (It won't make a copy of USING, however, so
 234      that already has to be allocated correctly.)  */
 235
 236   void set_using (struct using_direct *using_decl, struct obstack *obstack);
 237
 238   /* Return the symbol for the function which contains a specified
 239      lexical block, described by a struct block.  The return value
 240      will not be an inlined function; the containing function will be
 241      returned instead.  */
 242
 243   struct symbol *linkage_function () const;
 244
 245   /* Return the symbol for the function which contains a specified
 246      block, described by a struct block.  The return value will be the
 247      closest enclosing function, which might be an inline
 248      function.  */
 249
 250   struct symbol *containing_function () const;
 251
 252   /* Return the static block associated with this block.  Return NULL
 253      if block is a global block.  */
 254
 255   const struct block *static_block () const;
 256
 257   /* Return true if this block is a static block.  */
 258
 259   bool is_static_block () const
 260   {
 261     const block *sup = superblock ();
 262     if (sup == nullptr)
 263       return false;
 264     return sup->is_global_block ();
 265   }
 266
 267   /* Return the static block associated with block.  */
 268
 269   const struct block *global_block () const;
 270
 271   /* Return true if this block is a global block.  */
 272
 273   bool is_global_block () const
 274   { return superblock () == nullptr; }
 275
 276   /* Return the function block for this block.  Returns nullptr if
 277      there is no enclosing function, i.e., if this block is a static
 278      or global block.  */
 279
 280   const struct block *function_block () const;
 281
 282   /* Set the compunit of this block, which must be a global block.  */
 283
 284   void set_compunit_symtab (struct compunit_symtab *);
 285
 286   /* Return a property to evaluate the static link associated to this
 287      block.
 288
 289      In the context of nested functions (available in Pascal, Ada and
 290      GNU C, for instance), a static link (as in DWARF's
 291      DW_AT_static_link attribute) for a function is a way to get the
 292      frame corresponding to the enclosing function.
 293
 294      Note that only objfile-owned and function-level blocks can have a
 295      static link.  Return NULL if there is no such property.  */
 296
 297   struct dynamic_prop *static_link () const;
 298
 299   /* Return true if block A is lexically nested within this block, or
 300      if A and this block have the same pc range.  Return false
 301      otherwise.  If ALLOW_NESTED is true, then block A is considered
 302      to be in this block if A is in a nested function in this block's
 303      function.  If ALLOW_NESTED is false (the default), then blocks in
 304      nested functions are not considered to be contained.  */
 305
 306   bool contains (const struct block *a, bool allow_nested = false) const;
 307
 308 private:
 309
 310   /* If the namespace_info is NULL, allocate it via OBSTACK and
 311      initialize its members to zero.  */
 312   void initialize_namespace (struct obstack *obstack);
 313
 314   /* Addresses in the executable code that are in this block.  */
 315
 316   CORE_ADDR m_start = 0;
 317   CORE_ADDR m_end = 0;
 318
 319   /* The symbol that names this block, if the block is the body of a
 320      function (real or inlined); otherwise, zero.  */
 321
 322   struct symbol *m_function = nullptr;
 323
 324   /* The `struct block' for the containing block, or 0 if none.
 325
 326      The superblock of a top-level local block (i.e. a function in the
 327      case of C) is the STATIC_BLOCK.  The superblock of the
 328      STATIC_BLOCK is the GLOBAL_BLOCK.  */
 329
 330   const struct block *m_superblock = nullptr;
 331
 332   /* This is used to store the symbols in the block.  */
 333
 334   struct multidictionary *m_multidict = nullptr;
 335
 336   /* Contains information about namespace-related info relevant to this block:
 337      using directives and the current namespace scope.  */
 338
 339   struct block_namespace_info *m_namespace_info = nullptr;
 340
 341   /* Address ranges for blocks with non-contiguous ranges.  If this
 342      is NULL, then there is only one range which is specified by
 343      startaddr and endaddr above.  */
 344
 345   struct blockranges *m_ranges = nullptr;
 346 };
 347
 348 /* The global block is singled out so that we can provide a back-link
 349    to the compunit symtab.  */
 350
 351 struct global_block : public block
 352 {
 353   /* This holds a pointer to the compunit symtab holding this block.  */
 354
 355   struct compunit_symtab *compunit_symtab = nullptr;
 356 };
 357
 358 struct blockvector
 359 {
 360   /* Return a view on the blocks of this blockvector.  */
 361   gdb::array_view<struct block *> blocks ()
 362   {
 363     return gdb::array_view<struct block *> (m_blocks, m_num_blocks);
 364   }
 365
 366   /* Const version of the above.  */
 367   gdb::array_view<const struct block *const> blocks () const
 368   {
 369     const struct block **blocks = (const struct block **) m_blocks;
 370     return gdb::array_view<const struct block *const> (blocks, m_num_blocks);
 371   }
 372
 373   /* Return the block at index I.  */
 374   struct block *block (size_t i)
 375   { return this->blocks ()[i]; }
 376
 377   /* Const version of the above.  */
 378   const struct block *block (size_t i) const
 379   { return this->blocks ()[i]; }
 380
 381   /* Set the block at index I.  */
 382   void set_block (int i, struct block *block)
 383   { m_blocks[i] = block; }
 384
 385   /* Set the number of blocks of this blockvector.
 386
 387      The storage of blocks is done using a flexible array member, so the number
 388      of blocks set here must agree with what was effectively allocated.  */
 389   void set_num_blocks (int num_blocks)
 390   { m_num_blocks = num_blocks; }
 391
 392   /* Return the number of blocks in this blockvector.  */
 393   int num_blocks () const
 394   { return m_num_blocks; }
 395
 396   /* Return the global block of this blockvector.  */
 397   struct block *global_block ()
 398   { return this->block (GLOBAL_BLOCK); }
 399
 400   /* Const version of the above.  */
 401   const struct block *global_block () const
 402   { return this->block (GLOBAL_BLOCK); }
 403
 404   /* Return the static block of this blockvector.  */
 405   struct block *static_block ()
 406   { return this->block (STATIC_BLOCK); }
 407
 408   /* Const version of the above.  */
 409   const struct block *static_block () const
 410   { return this->block (STATIC_BLOCK); }
 411
 412   /* Return the address -> block map of this blockvector.  */
 413   addrmap *map ()
 414   { return m_map; }
 415
 416   /* Const version of the above.  */
 417   const addrmap *map () const
 418   { return m_map; }
 419
 420   /* Set this blockvector's address -> block map.  */
 421   void set_map (addrmap *map)
 422   { m_map = map; }
 423
 424 private:
 425   /* An address map mapping addresses to blocks in this blockvector.
 426      This pointer is zero if the blocks' start and end addresses are
 427      enough.  */
 428   struct addrmap *m_map;
 429
 430   /* Number of blocks in the list.  */
 431   int m_num_blocks;
 432
 433   /* The blocks themselves.  */
 434   struct block *m_blocks[1];
 435 };
 436
 437 extern const struct blockvector *blockvector_for_pc (CORE_ADDR,
 438                                                const struct block **);
 439
 440 extern const struct blockvector *
 441   blockvector_for_pc_sect (CORE_ADDR, struct obj_section *,
 442                            const struct block **, struct compunit_symtab *);
 443
 444 extern int blockvector_contains_pc (const struct blockvector *bv, CORE_ADDR pc);
 445
 446 extern struct call_site *call_site_for_pc (struct gdbarch *gdbarch,
 447                                            CORE_ADDR pc);
 448
 449 extern const struct block *block_for_pc (CORE_ADDR);
 450
 451 extern const struct block *block_for_pc_sect (CORE_ADDR, struct obj_section *);
 452
 453 /* A block iterator.  This structure should be treated as though it
 454    were opaque; it is only defined here because we want to support
 455    stack allocation of iterators.  */
 456
 457 struct block_iterator
 458 {
 459   /* If we're iterating over a single block, this holds the block.
 460      Otherwise, it holds the canonical compunit.  */
 461
 462   union
 463   {
 464     struct compunit_symtab *compunit_symtab;
 465     const struct block *block;
 466   } d;
 467
 468   /* If we're trying to match a name, this will be non-NULL.  */
 469   const lookup_name_info *name;
 470
 471   /* If we're iterating over a single block, this is always -1.
 472      Otherwise, it holds the index of the current "included" symtab in
 473      the canonical symtab (that is, d.symtab->includes[idx]), with -1
 474      meaning the canonical symtab itself.  */
 475
 476   int idx;
 477
 478   /* Which block, either static or global, to iterate over.  If this
 479      is FIRST_LOCAL_BLOCK, then we are iterating over a single block.
 480      This is used to select which field of 'd' is in use.  */
 481
 482   enum block_enum which;
 483
 484   /* The underlying multidictionary iterator.  */
 485
 486   struct mdict_iterator mdict_iter;
 487 };
 488
 489 /* Initialize ITERATOR to point at the first symbol in BLOCK, and
 490    return that first symbol, or NULL if BLOCK is empty.  If NAME is
 491    not NULL, only return symbols matching that name.  */
 492
 493 extern struct symbol *block_iterator_first
 494      (const struct block *block,
 495       struct block_iterator *iterator,
 496       const lookup_name_info *name = nullptr);
 497
 498 /* Advance ITERATOR, and return the next symbol, or NULL if there are
 499    no more symbols.  Don't call this if you've previously received
 500    NULL from block_iterator_first or block_iterator_next on this
 501    iteration.  */
 502
 503 extern struct symbol *block_iterator_next (struct block_iterator *iterator);
 504
 505 /* An iterator that wraps a block_iterator.  The naming here is
 506    unfortunate, but block_iterator was named before gdb switched to
 507    C++.  */
 508 struct block_iterator_wrapper
 509 {
 510   typedef block_iterator_wrapper self_type;
 511   typedef struct symbol *value_type;
 512
 513   explicit block_iterator_wrapper (const struct block *block,
 514                                    const lookup_name_info *name = nullptr)
 515     : m_sym (block_iterator_first (block, &m_iter, name))
 516   {
 517   }
 518
 519   block_iterator_wrapper ()
 520     : m_sym (nullptr)
 521   {
 522   }
 523
 524   value_type operator* () const
 525   {
 526     return m_sym;
 527   }
 528
 529   bool operator== (const self_type &other) const
 530   {
 531     return m_sym == other.m_sym;
 532   }
 533
 534   bool operator!= (const self_type &other) const
 535   {
 536     return m_sym != other.m_sym;
 537   }
 538
 539   self_type &operator++ ()
 540   {
 541     m_sym = block_iterator_next (&m_iter);
 542     return *this;
 543   }
 544
 545 private:
 546
 547   struct symbol *m_sym;
 548   struct block_iterator m_iter;
 549 };
 550
 551 /* An iterator range for block_iterator_wrapper.  */
 552
 553 typedef iterator_range<block_iterator_wrapper> block_iterator_range;
 554
 555 /* Return true if symbol A is the best match possible for DOMAIN.  */
 556
 557 extern bool best_symbol (struct symbol *a, const domain_enum domain);
 558
 559 /* Return symbol B if it is a better match than symbol A for DOMAIN.
 560    Otherwise return A.  */
 561
 562 extern struct symbol *better_symbol (struct symbol *a, struct symbol *b,
 563                                      const domain_enum domain);
 564
 565 /* Search BLOCK for symbol NAME in DOMAIN.  */
 566
 567 extern struct symbol *block_lookup_symbol (const struct block *block,
 568                                            const char *name,
 569                                            symbol_name_match_type match_type,
 570                                            const domain_enum domain);
 571
 572 /* Search BLOCK for symbol NAME in DOMAIN but only in primary symbol table of
 573    BLOCK.  BLOCK must be STATIC_BLOCK or GLOBAL_BLOCK.  Function is useful if
 574    one iterates all global/static blocks of an objfile.  */
 575
 576 extern struct symbol *block_lookup_symbol_primary (const struct block *block,
 577                                                    const char *name,
 578                                                    const domain_enum domain);
 579
 580 /* Find symbol NAME in BLOCK and in DOMAIN.  This will return a
 581    matching symbol whose type is not a "opaque", see TYPE_IS_OPAQUE.
 582    If STUB is non-NULL, an otherwise matching symbol whose type is a
 583    opaque will be stored here.  */
 584
 585 extern struct symbol *block_find_symbol (const struct block *block,
 586                                          const lookup_name_info &name,
 587                                          const domain_enum domain,
 588                                          struct symbol **stub);
 589
 590 /* Given a vector of pairs, allocate and build an obstack allocated
 591    blockranges struct for a block.  */
 592 struct blockranges *make_blockranges (struct objfile *objfile,
 593                                       const std::vector<blockrange> &rangevec);
 594
 595 #endif /* BLOCK_H */