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 the static block associated with block.  */
 258
 259   const struct block *global_block () const;
 260
 261   /* Set the compunit of this block, which must be a global block.  */
 262
 263   void set_compunit_symtab (struct compunit_symtab *);
 264
 265   /* Return a property to evaluate the static link associated to this
 266      block.
 267
 268      In the context of nested functions (available in Pascal, Ada and
 269      GNU C, for instance), a static link (as in DWARF's
 270      DW_AT_static_link attribute) for a function is a way to get the
 271      frame corresponding to the enclosing function.
 272
 273      Note that only objfile-owned and function-level blocks can have a
 274      static link.  Return NULL if there is no such property.  */
 275
 276   struct dynamic_prop *static_link () const;
 277
 278   /* Return true if block A is lexically nested within this block, or
 279      if A and this block have the same pc range.  Return false
 280      otherwise.  If ALLOW_NESTED is true, then block A is considered
 281      to be in this block if A is in a nested function in this block's
 282      function.  If ALLOW_NESTED is false (the default), then blocks in
 283      nested functions are not considered to be contained.  */
 284
 285   bool contains (const struct block *a, bool allow_nested = false) const;
 286
 287 private:
 288
 289   /* If the namespace_info is NULL, allocate it via OBSTACK and
 290      initialize its members to zero.  */
 291   void initialize_namespace (struct obstack *obstack);
 292
 293   /* Addresses in the executable code that are in this block.  */
 294
 295   CORE_ADDR m_start = 0;
 296   CORE_ADDR m_end = 0;
 297
 298   /* The symbol that names this block, if the block is the body of a
 299      function (real or inlined); otherwise, zero.  */
 300
 301   struct symbol *m_function = nullptr;
 302
 303   /* The `struct block' for the containing block, or 0 if none.
 304
 305      The superblock of a top-level local block (i.e. a function in the
 306      case of C) is the STATIC_BLOCK.  The superblock of the
 307      STATIC_BLOCK is the GLOBAL_BLOCK.  */
 308
 309   const struct block *m_superblock = nullptr;
 310
 311   /* This is used to store the symbols in the block.  */
 312
 313   struct multidictionary *m_multidict = nullptr;
 314
 315   /* Contains information about namespace-related info relevant to this block:
 316      using directives and the current namespace scope.  */
 317
 318   struct block_namespace_info *m_namespace_info = nullptr;
 319
 320   /* Address ranges for blocks with non-contiguous ranges.  If this
 321      is NULL, then there is only one range which is specified by
 322      startaddr and endaddr above.  */
 323
 324   struct blockranges *m_ranges = nullptr;
 325 };
 326
 327 /* The global block is singled out so that we can provide a back-link
 328    to the compunit symtab.  */
 329
 330 struct global_block : public block
 331 {
 332   /* This holds a pointer to the compunit symtab holding this block.  */
 333
 334   struct compunit_symtab *compunit_symtab = nullptr;
 335 };
 336
 337 struct blockvector
 338 {
 339   /* Return a view on the blocks of this blockvector.  */
 340   gdb::array_view<struct block *> blocks ()
 341   {
 342     return gdb::array_view<struct block *> (m_blocks, m_num_blocks);
 343   }
 344
 345   /* Const version of the above.  */
 346   gdb::array_view<const struct block *const> blocks () const
 347   {
 348     const struct block **blocks = (const struct block **) m_blocks;
 349     return gdb::array_view<const struct block *const> (blocks, m_num_blocks);
 350   }
 351
 352   /* Return the block at index I.  */
 353   struct block *block (size_t i)
 354   { return this->blocks ()[i]; }
 355
 356   /* Const version of the above.  */
 357   const struct block *block (size_t i) const
 358   { return this->blocks ()[i]; }
 359
 360   /* Set the block at index I.  */
 361   void set_block (int i, struct block *block)
 362   { m_blocks[i] = block; }
 363
 364   /* Set the number of blocks of this blockvector.
 365
 366      The storage of blocks is done using a flexible array member, so the number
 367      of blocks set here must agree with what was effectively allocated.  */
 368   void set_num_blocks (int num_blocks)
 369   { m_num_blocks = num_blocks; }
 370
 371   /* Return the number of blocks in this blockvector.  */
 372   int num_blocks () const
 373   { return m_num_blocks; }
 374
 375   /* Return the global block of this blockvector.  */
 376   struct block *global_block ()
 377   { return this->block (GLOBAL_BLOCK); }
 378
 379   /* Const version of the above.  */
 380   const struct block *global_block () const
 381   { return this->block (GLOBAL_BLOCK); }
 382
 383   /* Return the static block of this blockvector.  */
 384   struct block *static_block ()
 385   { return this->block (STATIC_BLOCK); }
 386
 387   /* Const version of the above.  */
 388   const struct block *static_block () const
 389   { return this->block (STATIC_BLOCK); }
 390
 391   /* Return the address -> block map of this blockvector.  */
 392   addrmap *map ()
 393   { return m_map; }
 394
 395   /* Const version of the above.  */
 396   const addrmap *map () const
 397   { return m_map; }
 398
 399   /* Set this blockvector's address -> block map.  */
 400   void set_map (addrmap *map)
 401   { m_map = map; }
 402
 403 private:
 404   /* An address map mapping addresses to blocks in this blockvector.
 405      This pointer is zero if the blocks' start and end addresses are
 406      enough.  */
 407   struct addrmap *m_map;
 408
 409   /* Number of blocks in the list.  */
 410   int m_num_blocks;
 411
 412   /* The blocks themselves.  */
 413   struct block *m_blocks[1];
 414 };
 415
 416 extern const struct blockvector *blockvector_for_pc (CORE_ADDR,
 417                                                const struct block **);
 418
 419 extern const struct blockvector *
 420   blockvector_for_pc_sect (CORE_ADDR, struct obj_section *,
 421                            const struct block **, struct compunit_symtab *);
 422
 423 extern int blockvector_contains_pc (const struct blockvector *bv, CORE_ADDR pc);
 424
 425 extern struct call_site *call_site_for_pc (struct gdbarch *gdbarch,
 426                                            CORE_ADDR pc);
 427
 428 extern const struct block *block_for_pc (CORE_ADDR);
 429
 430 extern const struct block *block_for_pc_sect (CORE_ADDR, struct obj_section *);
 431
 432 /* A block iterator.  This structure should be treated as though it
 433    were opaque; it is only defined here because we want to support
 434    stack allocation of iterators.  */
 435
 436 struct block_iterator
 437 {
 438   /* If we're iterating over a single block, this holds the block.
 439      Otherwise, it holds the canonical compunit.  */
 440
 441   union
 442   {
 443     struct compunit_symtab *compunit_symtab;
 444     const struct block *block;
 445   } d;
 446
 447   /* If we're trying to match a name, this will be non-NULL.  */
 448   const lookup_name_info *name;
 449
 450   /* If we're iterating over a single block, this is always -1.
 451      Otherwise, it holds the index of the current "included" symtab in
 452      the canonical symtab (that is, d.symtab->includes[idx]), with -1
 453      meaning the canonical symtab itself.  */
 454
 455   int idx;
 456
 457   /* Which block, either static or global, to iterate over.  If this
 458      is FIRST_LOCAL_BLOCK, then we are iterating over a single block.
 459      This is used to select which field of 'd' is in use.  */
 460
 461   enum block_enum which;
 462
 463   /* The underlying multidictionary iterator.  */
 464
 465   struct mdict_iterator mdict_iter;
 466 };
 467
 468 /* Initialize ITERATOR to point at the first symbol in BLOCK, and
 469    return that first symbol, or NULL if BLOCK is empty.  If NAME is
 470    not NULL, only return symbols matching that name.  */
 471
 472 extern struct symbol *block_iterator_first
 473      (const struct block *block,
 474       struct block_iterator *iterator,
 475       const lookup_name_info *name = nullptr);
 476
 477 /* Advance ITERATOR, and return the next symbol, or NULL if there are
 478    no more symbols.  Don't call this if you've previously received
 479    NULL from block_iterator_first or block_iterator_next on this
 480    iteration.  */
 481
 482 extern struct symbol *block_iterator_next (struct block_iterator *iterator);
 483
 484 /* An iterator that wraps a block_iterator.  The naming here is
 485    unfortunate, but block_iterator was named before gdb switched to
 486    C++.  */
 487 struct block_iterator_wrapper
 488 {
 489   typedef block_iterator_wrapper self_type;
 490   typedef struct symbol *value_type;
 491
 492   explicit block_iterator_wrapper (const struct block *block,
 493                                    const lookup_name_info *name = nullptr)
 494     : m_sym (block_iterator_first (block, &m_iter, name))
 495   {
 496   }
 497
 498   block_iterator_wrapper ()
 499     : m_sym (nullptr)
 500   {
 501   }
 502
 503   value_type operator* () const
 504   {
 505     return m_sym;
 506   }
 507
 508   bool operator== (const self_type &other) const
 509   {
 510     return m_sym == other.m_sym;
 511   }
 512
 513   bool operator!= (const self_type &other) const
 514   {
 515     return m_sym != other.m_sym;
 516   }
 517
 518   self_type &operator++ ()
 519   {
 520     m_sym = block_iterator_next (&m_iter);
 521     return *this;
 522   }
 523
 524 private:
 525
 526   struct symbol *m_sym;
 527   struct block_iterator m_iter;
 528 };
 529
 530 /* An iterator range for block_iterator_wrapper.  */
 531
 532 typedef iterator_range<block_iterator_wrapper> block_iterator_range;
 533
 534 /* Return true if symbol A is the best match possible for DOMAIN.  */
 535
 536 extern bool best_symbol (struct symbol *a, const domain_enum domain);
 537
 538 /* Return symbol B if it is a better match than symbol A for DOMAIN.
 539    Otherwise return A.  */
 540
 541 extern struct symbol *better_symbol (struct symbol *a, struct symbol *b,
 542                                      const domain_enum domain);
 543
 544 /* Search BLOCK for symbol NAME in DOMAIN.  */
 545
 546 extern struct symbol *block_lookup_symbol (const struct block *block,
 547                                            const char *name,
 548                                            symbol_name_match_type match_type,
 549                                            const domain_enum domain);
 550
 551 /* Search BLOCK for symbol NAME in DOMAIN but only in primary symbol table of
 552    BLOCK.  BLOCK must be STATIC_BLOCK or GLOBAL_BLOCK.  Function is useful if
 553    one iterates all global/static blocks of an objfile.  */
 554
 555 extern struct symbol *block_lookup_symbol_primary (const struct block *block,
 556                                                    const char *name,
 557                                                    const domain_enum domain);
 558
 559 /* The type of the MATCHER argument to block_find_symbol.  */
 560
 561 typedef int (block_symbol_matcher_ftype) (struct symbol *, void *);
 562
 563 /* Find symbol NAME in BLOCK and in DOMAIN that satisfies MATCHER.
 564    DATA is passed unchanged to MATCHER.
 565    BLOCK must be STATIC_BLOCK or GLOBAL_BLOCK.  */
 566
 567 extern struct symbol *block_find_symbol (const struct block *block,
 568                                          const char *name,
 569                                          const domain_enum domain,
 570                                          block_symbol_matcher_ftype *matcher,
 571                                          void *data);
 572
 573 /* A matcher function for block_find_symbol to find only symbols with
 574    non-opaque types.  */
 575
 576 extern int block_find_non_opaque_type (struct symbol *sym, void *data);
 577
 578 /* A matcher function for block_find_symbol to prefer symbols with
 579    non-opaque types.  The way to use this function is as follows:
 580
 581    struct symbol *with_opaque = NULL;
 582    struct symbol *sym
 583      = block_find_symbol (block, name, domain,
 584                           block_find_non_opaque_type_preferred, &with_opaque);
 585
 586    At this point if SYM is non-NULL then a non-opaque type has been found.
 587    Otherwise, if WITH_OPAQUE is non-NULL then an opaque type has been found.
 588    Otherwise, the symbol was not found.  */
 589
 590 extern int block_find_non_opaque_type_preferred (struct symbol *sym,
 591                                                  void *data);
 592
 593 /* Given a vector of pairs, allocate and build an obstack allocated
 594    blockranges struct for a block.  */
 595 struct blockranges *make_blockranges (struct objfile *objfile,
 596                                       const std::vector<blockrange> &rangevec);
 597
 598 #endif /* BLOCK_H */