gdb/psympriv.h

   1 /* Private partial symbol table definitions.
   2
   3    Copyright (C) 2009-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 PSYMPRIV_H
  21 #define PSYMPRIV_H
  22
  23 #include "psymtab.h"
  24 #include "objfiles.h"
  25 #include "gdbsupport/gdb_string_view.h"
  26
  27 /* A partial_symbol records the name, domain, and address class of
  28    symbols whose types we have not parsed yet.  For functions, it also
  29    contains their memory address, so we can find them from a PC value.
  30    Each partial_symbol sits in a partial_symtab, all of which are chained
  31    on a  partial symtab list and which points to the corresponding
  32    normal symtab once the partial_symtab has been referenced.  */
  33
  34 /* This structure is space critical.  See space comments at the top of
  35    symtab.h.  */
  36
  37 struct partial_symbol
  38 {
  39   /* Return the section for this partial symbol, or nullptr if no
  40      section has been set.  */
  41   struct obj_section *obj_section (struct objfile *objfile) const
  42   {
  43     return ginfo.obj_section (objfile);
  44   }
  45
  46   /* Return the unrelocated address of this partial symbol.  */
  47   unrelocated_addr unrelocated_address () const
  48   {
  49     return ginfo.unrelocated_address ();
  50   }
  51
  52   /* Return the address of this partial symbol, relocated according to
  53      the offsets provided in OBJFILE.  */
  54   CORE_ADDR address (const struct objfile *objfile) const
  55   {
  56     return (CORE_ADDR (ginfo.unrelocated_address ())
  57             + objfile->section_offsets[ginfo.section_index ()]);
  58   }
  59
  60   /* Set the address of this partial symbol.  The address must be
  61      unrelocated.  */
  62   void set_unrelocated_address (unrelocated_addr addr)
  63   {
  64     ginfo.set_unrelocated_address (addr);
  65   }
  66
  67   /* Note that partial_symbol does not derive from general_symbol_info
  68      due to the bcache.  See add_psymbol_to_bcache.  */
  69
  70   struct general_symbol_info ginfo;
  71
  72   /* Name space code.  */
  73
  74   ENUM_BITFIELD(domain_enum) domain : SYMBOL_DOMAIN_BITS;
  75
  76   /* Address class (for info_symbols).  Note that we don't allow
  77      synthetic "aclass" values here at present, simply because there's
  78      no need.  */
  79
  80   ENUM_BITFIELD(address_class) aclass : SYMBOL_ACLASS_BITS;
  81 };
  82
  83 /* A convenience enum to give names to some constants used when
  84    searching psymtabs.  This is internal to psymtab and should not be
  85    used elsewhere.  */
  86
  87 enum psymtab_search_status
  88   {
  89     PST_NOT_SEARCHED,
  90     PST_SEARCHED_AND_FOUND,
  91     PST_SEARCHED_AND_NOT_FOUND
  92   };
  93
  94 /* Specify whether a partial psymbol should be allocated on the global
  95    list or the static list.  */
  96
  97 enum class psymbol_placement
  98 {
  99   STATIC,
 100   GLOBAL
 101 };
 102
 103 /* Each source file that has not been fully read in is represented by
 104    a partial_symtab.  This contains the information on where in the
 105    executable the debugging symbols for a specific file are, and a
 106    list of names of global symbols which are located in this file.
 107    They are all chained on partial symtab lists.
 108
 109    Even after the source file has been read into a symtab, the
 110    partial_symtab remains around.  */
 111
 112 struct partial_symtab
 113 {
 114   /* Allocate a new partial symbol table.
 115
 116      FILENAME (which must be non-NULL) is the filename of this partial
 117      symbol table; it is copied into the appropriate storage.  The
 118      partial symtab will also be installed using
 119      psymtab_storage::install.  */
 120
 121   partial_symtab (const char *filename,
 122                   psymtab_storage *partial_symtabs,
 123                   objfile_per_bfd_storage *objfile_per_bfd)
 124     ATTRIBUTE_NONNULL (2) ATTRIBUTE_NONNULL (3);
 125
 126   /* Like the above, but also sets the initial text low and text high
 127      from the ADDR argument, and sets the global- and
 128      static-offsets.  */
 129
 130   partial_symtab (const char *filename,
 131                   psymtab_storage *partial_symtabs,
 132                   objfile_per_bfd_storage *objfile_per_bfd,
 133                   unrelocated_addr addr)
 134     ATTRIBUTE_NONNULL (2) ATTRIBUTE_NONNULL (3);
 135
 136   virtual ~partial_symtab ()
 137   {
 138   }
 139
 140   /* Psymtab expansion is done in two steps:
 141      - a call to read_symtab
 142      - while that call is in progress, calls to expand_psymtab can be made,
 143        both for this psymtab, and its dependencies.
 144      This makes a distinction between a toplevel psymtab (for which both
 145      read_symtab and expand_psymtab will be called) and a non-toplevel
 146      psymtab (for which only expand_psymtab will be called). The
 147      distinction can be used f.i. to do things before and after all
 148      dependencies of a top-level psymtab have been expanded.
 149
 150      Read the full symbol table corresponding to this partial symbol
 151      table.  Typically calls expand_psymtab.  */
 152   virtual void read_symtab (struct objfile *) = 0;
 153
 154   /* Expand the full symbol table for this partial symbol table.  Typically
 155      calls expand_dependencies.  */
 156   virtual void expand_psymtab (struct objfile *) = 0;
 157
 158   /* Ensure that all the dependencies are read in.  Calls
 159      expand_psymtab for each non-shared dependency.  */
 160   void expand_dependencies (struct objfile *);
 161
 162   /* Return true if the symtab corresponding to this psymtab has been
 163      read in in the context of this objfile.  */
 164   virtual bool readin_p (struct objfile *) const = 0;
 165
 166   /* Return a pointer to the compunit allocated for this source file
 167      in the context of this objfile.
 168
 169      Return nullptr if the compunit was not read in or if there was no
 170      symtab.  */
 171   virtual struct compunit_symtab *get_compunit_symtab
 172     (struct objfile *) const = 0;
 173
 174   /* Return the unrelocated low text address of this
 175      partial_symtab.  */
 176   unrelocated_addr raw_text_low () const
 177   {
 178     return m_text_low;
 179   }
 180
 181   /* Return the unrelocated_addr high text address of this
 182      partial_symtab.  */
 183   unrelocated_addr raw_text_high () const
 184   {
 185     return m_text_high;
 186   }
 187
 188   /* Return the relocated low text address of this partial_symtab.  */
 189   CORE_ADDR text_low (struct objfile *objfile) const
 190   {
 191     return CORE_ADDR (m_text_low) + objfile->text_section_offset ();
 192   }
 193
 194   /* Return the relocated high text address of this partial_symtab.  */
 195   CORE_ADDR text_high (struct objfile *objfile) const
 196   {
 197     return CORE_ADDR (m_text_high) + objfile->text_section_offset ();
 198   }
 199
 200   /* Set the low text address of this partial_symtab.  */
 201   void set_text_low (unrelocated_addr addr)
 202   {
 203     m_text_low = addr;
 204     text_low_valid = 1;
 205   }
 206
 207   /* Set the high text address of this partial_symtab.  */
 208   void set_text_high (unrelocated_addr addr)
 209   {
 210     m_text_high = addr;
 211     text_high_valid = 1;
 212   }
 213
 214   /* Return true if this symtab is empty -- meaning that it contains
 215      no symbols.  It may still have dependencies.  */
 216   bool empty () const
 217   {
 218     return global_psymbols.empty () && static_psymbols.empty ();
 219   }
 220
 221   /* Add a symbol to this partial symbol table of OBJFILE.
 222
 223      If COPY_NAME is true, make a copy of NAME, otherwise use the passed
 224      reference.
 225
 226      THECLASS is the type of symbol.
 227
 228      SECTION is the index of the section of OBJFILE in which the symbol is found.
 229
 230      WHERE determines whether the symbol goes in the list of static or global
 231      partial symbols.
 232
 233      COREADDR is the address of the symbol.  For partial symbols that don't have
 234      an address, zero is passed.
 235
 236      LANGUAGE is the language from which the symbol originates.  This will
 237      influence, amongst other things, how the symbol name is demangled. */
 238
 239   void add_psymbol (gdb::string_view name,
 240                     bool copy_name, domain_enum domain,
 241                     enum address_class theclass,
 242                     short section,
 243                     psymbol_placement where,
 244                     unrelocated_addr coreaddr,
 245                     enum language language,
 246                     psymtab_storage *partial_symtabs,
 247                     struct objfile *objfile);
 248
 249   /* Add a symbol to this partial symbol table of OBJFILE.  The psymbol
 250      must be fully constructed, and the names must be set and intern'd
 251      as appropriate.  */
 252
 253   void add_psymbol (const partial_symbol &psym,
 254                     psymbol_placement where,
 255                     psymtab_storage *partial_symtabs,
 256                     struct objfile *objfile);
 257
 258
 259   /* Indicate that this partial symtab is complete.  */
 260
 261   void end ();
 262
 263   /* Chain of all existing partial symtabs.  */
 264
 265   struct partial_symtab *next = nullptr;
 266
 267   /* Name of the source file which this partial_symtab defines,
 268      or if the psymtab is anonymous then a descriptive name for
 269      debugging purposes, or "".  It must not be NULL.  */
 270
 271   const char *filename = nullptr;
 272
 273   /* Full path of the source file.  NULL if not known.  */
 274
 275   char *fullname = nullptr;
 276
 277   /* Directory in which it was compiled, or NULL if we don't know.  */
 278
 279   const char *dirname = nullptr;
 280
 281   /* Range of text addresses covered by this file; texthigh is the
 282      beginning of the next section.  Do not refer directly to these
 283      fields.  Instead, use the accessors.  The validity of these
 284      fields is determined by the text_low_valid and text_high_valid
 285      fields; these are located later in this structure for better
 286      packing.  */
 287
 288   unrelocated_addr m_text_low {};
 289   unrelocated_addr m_text_high {};
 290
 291   /* If NULL, this is an ordinary partial symbol table.
 292
 293      If non-NULL, this holds a single includer of this partial symbol
 294      table, and this partial symbol table is a shared one.
 295
 296      A shared psymtab is one that is referenced by multiple other
 297      psymtabs, and which conceptually has its contents directly
 298      included in those.
 299
 300      Shared psymtabs have special semantics.  When a search finds a
 301      symbol in a shared table, we instead return one of the non-shared
 302      tables that include this one.
 303
 304      A shared psymtabs can be referred to by other shared ones.
 305
 306      The psymtabs that refer to a shared psymtab will list the shared
 307      psymtab in their 'dependencies' array.
 308
 309      In DWARF terms, a shared psymtab is a DW_TAG_partial_unit; but
 310      of course using a name based on that would be too confusing, so
 311      "shared" was chosen instead.
 312
 313      Only a single user is needed because, when expanding a shared
 314      psymtab, we only need to expand its "canonical" non-shared user.
 315      The choice of which one should be canonical is left to the
 316      debuginfo reader; it can be arbitrary.  */
 317
 318   struct partial_symtab *user = nullptr;
 319
 320   /* Array of pointers to all of the partial_symtab's which this one
 321      depends on.  Since this array can only be set to previous or
 322      the current (?) psymtab, this dependency tree is guaranteed not
 323      to have any loops.  "depends on" means that symbols must be read
 324      for the dependencies before being read for this psymtab; this is
 325      for type references in stabs, where if foo.c includes foo.h, declarations
 326      in foo.h may use type numbers defined in foo.c.  For other debugging
 327      formats there may be no need to use dependencies.  */
 328
 329   struct partial_symtab **dependencies = nullptr;
 330
 331   int number_of_dependencies = 0;
 332
 333   /* Global symbol list.  This list will be sorted after readin to
 334      improve access.  Binary search will be the usual method of
 335      finding a symbol within it.  */
 336
 337   std::vector<partial_symbol *> global_psymbols;
 338
 339   /* Static symbol list.  This list will *not* be sorted after readin;
 340      to find a symbol in it, exhaustive search must be used.  This is
 341      reasonable because searches through this list will eventually
 342      lead to either the read in of a files symbols for real (assumed
 343      to take a *lot* of time; check) or an error (and we don't care
 344      how long errors take).  */
 345
 346   std::vector<partial_symbol *> static_psymbols;
 347
 348   /* True if the name of this partial symtab is not a source file name.  */
 349
 350   bool anonymous = false;
 351
 352   /* A flag that is temporarily used when searching psymtabs.  */
 353
 354   ENUM_BITFIELD (psymtab_search_status) searched_flag : 2;
 355
 356   /* Validity of the m_text_low and m_text_high fields.  */
 357
 358   unsigned int text_low_valid : 1;
 359   unsigned int text_high_valid : 1;
 360 };
 361
 362 /* A partial symtab that tracks the "readin" and "compunit_symtab"
 363    information in the ordinary way -- by storing it directly in this
 364    object.  */
 365 struct standard_psymtab : public partial_symtab
 366 {
 367   standard_psymtab (const char *filename,
 368                     psymtab_storage *partial_symtabs,
 369                     objfile_per_bfd_storage *objfile_per_bfd)
 370     : partial_symtab (filename, partial_symtabs, objfile_per_bfd)
 371   {
 372   }
 373
 374   standard_psymtab (const char *filename,
 375                     psymtab_storage *partial_symtabs,
 376                     objfile_per_bfd_storage *objfile_per_bfd,
 377                     unrelocated_addr addr)
 378     : partial_symtab (filename, partial_symtabs, objfile_per_bfd, addr)
 379   {
 380   }
 381
 382   bool readin_p (struct objfile *) const override
 383   {
 384     return readin;
 385   }
 386
 387   struct compunit_symtab *get_compunit_symtab (struct objfile *) const override
 388   {
 389     return compunit_symtab;
 390   }
 391
 392   /* True if the symtab corresponding to this psymtab has been
 393      readin.  */
 394
 395   bool readin = false;
 396
 397   /* Pointer to compunit eventually allocated for this source file, 0 if
 398      !readin or if we haven't looked for the symtab after it was readin.  */
 399
 400   struct compunit_symtab *compunit_symtab = nullptr;
 401 };
 402
 403 /* A partial_symtab that works in the historical db way.  This should
 404    not be used in new code, but exists to transition the somewhat
 405    unmaintained "legacy" debug formats.  */
 406
 407 struct legacy_psymtab : public standard_psymtab
 408 {
 409   legacy_psymtab (const char *filename,
 410                   psymtab_storage *partial_symtabs,
 411                   objfile_per_bfd_storage *objfile_per_bfd)
 412     : standard_psymtab (filename, partial_symtabs, objfile_per_bfd)
 413   {
 414   }
 415
 416   legacy_psymtab (const char *filename,
 417                   psymtab_storage *partial_symtabs,
 418                   objfile_per_bfd_storage *objfile_per_bfd,
 419                   unrelocated_addr addr)
 420     : standard_psymtab (filename, partial_symtabs, objfile_per_bfd, addr)
 421   {
 422   }
 423
 424   void read_symtab (struct objfile *objf) override
 425   {
 426     if (legacy_read_symtab)
 427       (*legacy_read_symtab) (this, objf);
 428   }
 429
 430   void expand_psymtab (struct objfile *objf) override
 431   {
 432     (*legacy_expand_psymtab) (this, objf);
 433   }
 434
 435   /* Pointer to function which will read in the symtab corresponding to
 436      this psymtab.  */
 437
 438   void (*legacy_read_symtab) (legacy_psymtab *, struct objfile *) = nullptr;
 439
 440   /* Pointer to function which will actually expand this psymtab into
 441      a full symtab.  */
 442
 443   void (*legacy_expand_psymtab) (legacy_psymtab *, struct objfile *) = nullptr;
 444
 445   /* Information that lets read_symtab() locate the part of the symbol table
 446      that this psymtab corresponds to.  This information is private to the
 447      format-dependent symbol reading routines.  For further detail examine
 448      the various symbol reading modules.  */
 449
 450   void *read_symtab_private = nullptr;
 451 };
 452
 453 /* Used when recording partial symbol tables.  On destruction,
 454    discards any partial symbol tables that have been built.  However,
 455    the tables can be kept by calling the "keep" method.  */
 456 class psymtab_discarder
 457 {
 458  public:
 459
 460   psymtab_discarder (psymtab_storage *partial_symtabs)
 461     : m_partial_symtabs (partial_symtabs),
 462       m_psymtab (partial_symtabs->psymtabs)
 463   {
 464   }
 465
 466   ~psymtab_discarder ()
 467   {
 468     if (m_partial_symtabs != nullptr)
 469       m_partial_symtabs->discard_psymtabs_to (m_psymtab);
 470   }
 471
 472   /* Keep any partial symbol tables that were built.  */
 473   void keep ()
 474   {
 475     m_partial_symtabs = nullptr;
 476   }
 477
 478  private:
 479
 480   /* The partial symbol storage object.  */
 481   psymtab_storage *m_partial_symtabs;
 482   /* How far back to free.  */
 483   struct partial_symtab *m_psymtab;
 484 };
 485
 486 /* An implementation of quick_symbol_functions, specialized for
 487    partial symbols.  */
 488 struct psymbol_functions : public quick_symbol_functions
 489 {
 490   explicit psymbol_functions (const std::shared_ptr<psymtab_storage> &storage)
 491     : m_partial_symtabs (storage)
 492   {
 493   }
 494
 495   psymbol_functions ()
 496     : m_partial_symtabs (new psymtab_storage)
 497   {
 498   }
 499
 500   bool has_symbols (struct objfile *objfile) override;
 501
 502   bool has_unexpanded_symtabs (struct objfile *objfile) override;
 503
 504   struct symtab *find_last_source_symtab (struct objfile *objfile) override;
 505
 506   void forget_cached_source_info (struct objfile *objfile) override;
 507
 508   enum language lookup_global_symbol_language (struct objfile *objfile,
 509                                                const char *name,
 510                                                domain_enum domain,
 511                                                bool *symbol_found_p) override;
 512
 513   void print_stats (struct objfile *objfile, bool print_bcache) override;
 514
 515   void dump (struct objfile *objfile) override;
 516
 517   void expand_all_symtabs (struct objfile *objfile) override;
 518
 519   void expand_matching_symbols
 520     (struct objfile *,
 521      const lookup_name_info &lookup_name,
 522      domain_enum domain,
 523      int global,
 524      symbol_compare_ftype *ordered_compare) override;
 525
 526   bool expand_symtabs_matching
 527     (struct objfile *objfile,
 528      gdb::function_view<expand_symtabs_file_matcher_ftype> file_matcher,
 529      const lookup_name_info *lookup_name,
 530      gdb::function_view<expand_symtabs_symbol_matcher_ftype> symbol_matcher,
 531      gdb::function_view<expand_symtabs_exp_notify_ftype> expansion_notify,
 532      block_search_flags search_flags,
 533      domain_enum domain,
 534      enum search_domain kind) override;
 535
 536   struct compunit_symtab *find_pc_sect_compunit_symtab
 537     (struct objfile *objfile, struct bound_minimal_symbol msymbol,
 538      CORE_ADDR pc, struct obj_section *section, int warn_if_readin) override;
 539
 540   struct compunit_symtab *find_compunit_symtab_by_address
 541     (struct objfile *objfile, CORE_ADDR address) override
 542   {
 543     return nullptr;
 544   }
 545
 546   void map_symbol_filenames (struct objfile *objfile,
 547                              gdb::function_view<symbol_filename_ftype> fun,
 548                              bool need_fullname) override;
 549
 550   /* Return a range adapter for the psymtabs.  */
 551   psymtab_storage::partial_symtab_range partial_symbols
 552        (struct objfile *objfile);
 553
 554   /* Return the partial symbol storage associated with this
 555      object.  */
 556   const std::shared_ptr<psymtab_storage> &get_partial_symtabs () const
 557   {
 558     return m_partial_symtabs;
 559   }
 560
 561   /* Replace the partial symbol table storage in this object with
 562      SYMS.  */
 563   void set_partial_symtabs (const std::shared_ptr<psymtab_storage> &syms)
 564   {
 565     m_partial_symtabs = syms;
 566   }
 567
 568   /* Find which partial symtab contains PC and SECTION.  Return NULL if
 569      none.  We return the psymtab that contains a symbol whose address
 570      exactly matches PC, or, if we cannot find an exact match, the
 571      psymtab that contains a symbol whose address is closest to PC.  */
 572
 573   struct partial_symtab *find_pc_sect_psymtab
 574        (struct objfile *objfile,
 575         CORE_ADDR pc,
 576         struct obj_section *section,
 577         struct bound_minimal_symbol msymbol);
 578
 579 private:
 580
 581   /* Count the number of partial symbols in *THIS.  */
 582   int count_psyms ();
 583
 584   /* Storage for the partial symbols.  */
 585   std::shared_ptr<psymtab_storage> m_partial_symtabs;
 586 };
 587
 588 #endif /* PSYMPRIV_H */