gdb/progspace.h

   1 /* Program and address space management, for GDB, the GNU debugger.
   2
   3    Copyright (C) 2009-2020 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
  21 #ifndef PROGSPACE_H
  22 #define PROGSPACE_H
  23
  24 #include "target.h"
  25 #include "gdb_bfd.h"
  26 #include "gdbsupport/gdb_vecs.h"
  27 #include "registry.h"
  28 #include "gdbsupport/next-iterator.h"
  29 #include "gdbsupport/safe-iterator.h"
  30 #include <list>
  31
  32 struct target_ops;
  33 struct bfd;
  34 struct objfile;
  35 struct inferior;
  36 struct exec;
  37 struct address_space;
  38 struct program_space_data;
  39 struct address_space_data;
  40 struct so_list;
  41
  42 typedef std::list<std::shared_ptr<objfile>> objfile_list;
  43
  44 /* An iterator that wraps an iterator over std::shared_ptr<objfile>,
  45    and dereferences the returned object.  This is useful for iterating
  46    over a list of shared pointers and returning raw pointers -- which
  47    helped avoid touching a lot of code when changing how objfiles are
  48    managed.  */
  49
  50 class unwrapping_objfile_iterator
  51 {
  52 public:
  53
  54   typedef unwrapping_objfile_iterator self_type;
  55   typedef typename ::objfile *value_type;
  56   typedef typename ::objfile &reference;
  57   typedef typename ::objfile **pointer;
  58   typedef typename objfile_list::iterator::iterator_category iterator_category;
  59   typedef typename objfile_list::iterator::difference_type difference_type;
  60
  61   unwrapping_objfile_iterator (const objfile_list::iterator &iter)
  62     : m_iter (iter)
  63   {
  64   }
  65
  66   objfile *operator* () const
  67   {
  68     return m_iter->get ();
  69   }
  70
  71   unwrapping_objfile_iterator operator++ ()
  72   {
  73     ++m_iter;
  74     return *this;
  75   }
  76
  77   bool operator!= (const unwrapping_objfile_iterator &other) const
  78   {
  79     return m_iter != other.m_iter;
  80   }
  81
  82 private:
  83
  84   /* The underlying iterator.  */
  85   objfile_list::iterator m_iter;
  86 };
  87
  88
  89 /* A range that returns unwrapping_objfile_iterators.  */
  90
  91 struct unwrapping_objfile_range
  92 {
  93   typedef unwrapping_objfile_iterator iterator;
  94
  95   unwrapping_objfile_range (objfile_list &ol)
  96     : m_list (ol)
  97   {
  98   }
  99
 100   iterator begin () const
 101   {
 102     return iterator (m_list.begin ());
 103   }
 104
 105   iterator end () const
 106   {
 107     return iterator (m_list.end ());
 108   }
 109
 110 private:
 111
 112   objfile_list &m_list;
 113 };
 114
 115 /* A program space represents a symbolic view of an address space.
 116    Roughly speaking, it holds all the data associated with a
 117    non-running-yet program (main executable, main symbols), and when
 118    an inferior is running and is bound to it, includes the list of its
 119    mapped in shared libraries.
 120
 121    In the traditional debugging scenario, there's a 1-1 correspondence
 122    among program spaces, inferiors and address spaces, like so:
 123
 124      pspace1 (prog1) <--> inf1(pid1) <--> aspace1
 125
 126    In the case of debugging more than one traditional unix process or
 127    program, we still have:
 128
 129      |-----------------+------------+---------|
 130      | pspace1 (prog1) | inf1(pid1) | aspace1 |
 131      |----------------------------------------|
 132      | pspace2 (prog1) | no inf yet | aspace2 |
 133      |-----------------+------------+---------|
 134      | pspace3 (prog2) | inf2(pid2) | aspace3 |
 135      |-----------------+------------+---------|
 136
 137    In the former example, if inf1 forks (and GDB stays attached to
 138    both processes), the new child will have its own program and
 139    address spaces.  Like so:
 140
 141      |-----------------+------------+---------|
 142      | pspace1 (prog1) | inf1(pid1) | aspace1 |
 143      |-----------------+------------+---------|
 144      | pspace2 (prog1) | inf2(pid2) | aspace2 |
 145      |-----------------+------------+---------|
 146
 147    However, had inf1 from the latter case vforked instead, it would
 148    share the program and address spaces with its parent, until it
 149    execs or exits, like so:
 150
 151      |-----------------+------------+---------|
 152      | pspace1 (prog1) | inf1(pid1) | aspace1 |
 153      |                 | inf2(pid2) |         |
 154      |-----------------+------------+---------|
 155
 156    When the vfork child execs, it is finally given new program and
 157    address spaces.
 158
 159      |-----------------+------------+---------|
 160      | pspace1 (prog1) | inf1(pid1) | aspace1 |
 161      |-----------------+------------+---------|
 162      | pspace2 (prog1) | inf2(pid2) | aspace2 |
 163      |-----------------+------------+---------|
 164
 165    There are targets where the OS (if any) doesn't provide memory
 166    management or VM protection, where all inferiors share the same
 167    address space --- e.g. uClinux.  GDB models this by having all
 168    inferiors share the same address space, but, giving each its own
 169    program space, like so:
 170
 171      |-----------------+------------+---------|
 172      | pspace1 (prog1) | inf1(pid1) |         |
 173      |-----------------+------------+         |
 174      | pspace2 (prog1) | inf2(pid2) | aspace1 |
 175      |-----------------+------------+         |
 176      | pspace3 (prog2) | inf3(pid3) |         |
 177      |-----------------+------------+---------|
 178
 179    The address space sharing matters for run control and breakpoints
 180    management.  E.g., did we just hit a known breakpoint that we need
 181    to step over?  Is this breakpoint a duplicate of this other one, or
 182    do I need to insert a trap?
 183
 184    Then, there are targets where all symbols look the same for all
 185    inferiors, although each has its own address space, as e.g.,
 186    Ericsson DICOS.  In such case, the model is:
 187
 188      |---------+------------+---------|
 189      |         | inf1(pid1) | aspace1 |
 190      |         +------------+---------|
 191      | pspace  | inf2(pid2) | aspace2 |
 192      |         +------------+---------|
 193      |         | inf3(pid3) | aspace3 |
 194      |---------+------------+---------|
 195
 196    Note however, that the DICOS debug API takes care of making GDB
 197    believe that breakpoints are "global".  That is, although each
 198    process does have its own private copy of data symbols (just like a
 199    bunch of forks), to the breakpoints module, all processes share a
 200    single address space, so all breakpoints set at the same address
 201    are duplicates of each other, even breakpoints set in the data
 202    space (e.g., call dummy breakpoints placed on stack).  This allows
 203    a simplification in the spaces implementation: we avoid caring for
 204    a many-many links between address and program spaces.  Either
 205    there's a single address space bound to the program space
 206    (traditional unix/uClinux), or, in the DICOS case, the address
 207    space bound to the program space is mostly ignored.  */
 208
 209 /* The program space structure.  */
 210
 211 struct program_space
 212 {
 213   /* Constructs a new empty program space, binds it to ASPACE, and
 214      adds it to the program space list.  */
 215   explicit program_space (address_space *aspace);
 216
 217   /* Releases a program space, and all its contents (shared libraries,
 218      objfiles, and any other references to the program space in other
 219      modules).  It is an internal error to call this when the program
 220      space is the current program space, since there should always be
 221      a program space.  */
 222   ~program_space ();
 223
 224   typedef unwrapping_objfile_range objfiles_range;
 225
 226   /* Return an iterable object that can be used to iterate over all
 227      objfiles.  The basic use is in a foreach, like:
 228
 229      for (objfile *objf : pspace->objfiles ()) { ... }  */
 230   objfiles_range objfiles ()
 231   {
 232     return unwrapping_objfile_range (objfiles_list);
 233   }
 234
 235   typedef basic_safe_range<objfiles_range> objfiles_safe_range;
 236
 237   /* An iterable object that can be used to iterate over all objfiles.
 238      The basic use is in a foreach, like:
 239
 240      for (objfile *objf : pspace->objfiles_safe ()) { ... }
 241
 242      This variant uses a basic_safe_iterator so that objfiles can be
 243      deleted during iteration.  */
 244   objfiles_safe_range objfiles_safe ()
 245   {
 246     return objfiles_safe_range (objfiles_list);
 247   }
 248
 249   /* Add OBJFILE to the list of objfiles, putting it just before
 250      BEFORE.  If BEFORE is nullptr, it will go at the end of the
 251      list.  */
 252   void add_objfile (std::shared_ptr<objfile> &&objfile,
 253                     struct objfile *before);
 254
 255   /* Remove OBJFILE from the list of objfiles.  */
 256   void remove_objfile (struct objfile *objfile);
 257
 258   /* Return true if there is more than one object file loaded; false
 259      otherwise.  */
 260   bool multi_objfile_p () const
 261   {
 262     return objfiles_list.size () > 1;
 263   }
 264
 265   /* Free all the objfiles associated with this program space.  */
 266   void free_all_objfiles ();
 267
 268   /* Return a range adapter for iterating over all the solibs in this
 269      program space.  Use it like:
 270
 271      for (so_list *so : pspace->solibs ()) { ... }  */
 272   next_adapter<struct so_list> solibs () const;
 273
 274
 275   /* Pointer to next in linked list.  */
 276   struct program_space *next = NULL;
 277
 278   /* Unique ID number.  */
 279   int num = 0;
 280
 281   /* The main executable loaded into this program space.  This is
 282      managed by the exec target.  */
 283
 284   /* The BFD handle for the main executable.  */
 285   bfd *ebfd = NULL;
 286   /* The last-modified time, from when the exec was brought in.  */
 287   long ebfd_mtime = 0;
 288   /* Similar to bfd_get_filename (exec_bfd) but in original form given
 289      by user, without symbolic links and pathname resolved.
 290      It needs to be freed by xfree.  It is not NULL iff EBFD is not NULL.  */
 291   char *pspace_exec_filename = NULL;
 292
 293   /* Binary file diddling handle for the core file.  */
 294   gdb_bfd_ref_ptr cbfd;
 295
 296   /* The address space attached to this program space.  More than one
 297      program space may be bound to the same address space.  In the
 298      traditional unix-like debugging scenario, this will usually
 299      match the address space bound to the inferior, and is mostly
 300      used by the breakpoints module for address matches.  If the
 301      target shares a program space for all inferiors and breakpoints
 302      are global, then this field is ignored (we don't currently
 303      support inferiors sharing a program space if the target doesn't
 304      make breakpoints global).  */
 305   struct address_space *aspace = NULL;
 306
 307   /* True if this program space's section offsets don't yet represent
 308      the final offsets of the "live" address space (that is, the
 309      section addresses still require the relocation offsets to be
 310      applied, and hence we can't trust the section addresses for
 311      anything that pokes at live memory).  E.g., for qOffsets
 312      targets, or for PIE executables, until we connect and ask the
 313      target for the final relocation offsets, the symbols we've used
 314      to set breakpoints point at the wrong addresses.  */
 315   int executing_startup = 0;
 316
 317   /* True if no breakpoints should be inserted in this program
 318      space.  */
 319   int breakpoints_not_allowed = 0;
 320
 321   /* The object file that the main symbol table was loaded from
 322      (e.g. the argument to the "symbol-file" or "file" command).  */
 323   struct objfile *symfile_object_file = NULL;
 324
 325   /* All known objfiles are kept in a linked list.  */
 326   std::list<std::shared_ptr<objfile>> objfiles_list;
 327
 328   /* The set of target sections matching the sections mapped into
 329      this program space.  Managed by both exec_ops and solib.c.  */
 330   struct target_section_table target_sections {};
 331
 332   /* List of shared objects mapped into this space.  Managed by
 333      solib.c.  */
 334   struct so_list *so_list = NULL;
 335
 336   /* Number of calls to solib_add.  */
 337   unsigned int solib_add_generation = 0;
 338
 339   /* When an solib is added, it is also added to this vector.  This
 340      is so we can properly report solib changes to the user.  */
 341   std::vector<struct so_list *> added_solibs;
 342
 343   /* When an solib is removed, its name is added to this vector.
 344      This is so we can properly report solib changes to the user.  */
 345   std::vector<std::string> deleted_solibs;
 346
 347   /* Per pspace data-pointers required by other GDB modules.  */
 348   REGISTRY_FIELDS {};
 349 };
 350
 351 /* An address space.  It is used for comparing if
 352    pspaces/inferior/threads see the same address space and for
 353    associating caches to each address space.  */
 354 struct address_space
 355 {
 356   int num;
 357
 358   /* Per aspace data-pointers required by other GDB modules.  */
 359   REGISTRY_FIELDS;
 360 };
 361
 362 /* The object file that the main symbol table was loaded from (e.g. the
 363    argument to the "symbol-file" or "file" command).  */
 364
 365 #define symfile_objfile current_program_space->symfile_object_file
 366
 367 /* The set of target sections matching the sections mapped into the
 368    current program space.  */
 369 #define current_target_sections (&current_program_space->target_sections)
 370
 371 /* The list of all program spaces.  There's always at least one.  */
 372 extern struct program_space *program_spaces;
 373
 374 /* The current program space.  This is always non-null.  */
 375 extern struct program_space *current_program_space;
 376
 377 #define ALL_PSPACES(pspace) \
 378   for ((pspace) = program_spaces; (pspace) != NULL; (pspace) = (pspace)->next)
 379
 380 /* Returns the number of program spaces listed.  */
 381 extern int number_of_program_spaces (void);
 382
 383 /* Returns true iff there's no inferior bound to PSPACE.  */
 384 extern int program_space_empty_p (struct program_space *pspace);
 385
 386 /* Copies program space SRC to DEST.  Copies the main executable file,
 387    and the main symbol file.  Returns DEST.  */
 388 extern struct program_space *clone_program_space (struct program_space *dest,
 389                                                 struct program_space *src);
 390
 391 /* Sets PSPACE as the current program space.  This is usually used
 392    instead of set_current_space_and_thread when the current
 393    thread/inferior is not important for the operations that follow.
 394    E.g., when accessing the raw symbol tables.  If memory access is
 395    required, then you should use switch_to_program_space_and_thread.
 396    Otherwise, it is the caller's responsibility to make sure that the
 397    currently selected inferior/thread matches the selected program
 398    space.  */
 399 extern void set_current_program_space (struct program_space *pspace);
 400
 401 /* Save/restore the current program space.  */
 402
 403 class scoped_restore_current_program_space
 404 {
 405 public:
 406   scoped_restore_current_program_space ()
 407     : m_saved_pspace (current_program_space)
 408   {}
 409
 410   ~scoped_restore_current_program_space ()
 411   { set_current_program_space (m_saved_pspace); }
 412
 413   DISABLE_COPY_AND_ASSIGN (scoped_restore_current_program_space);
 414
 415 private:
 416   program_space *m_saved_pspace;
 417 };
 418
 419 /* Create a new address space object, and add it to the list.  */
 420 extern struct address_space *new_address_space (void);
 421
 422 /* Maybe create a new address space object, and add it to the list, or
 423    return a pointer to an existing address space, in case inferiors
 424    share an address space.  */
 425 extern struct address_space *maybe_new_address_space (void);
 426
 427 /* Returns the integer address space id of ASPACE.  */
 428 extern int address_space_num (struct address_space *aspace);
 429
 430 /* Update all program spaces matching to address spaces.  The user may
 431    have created several program spaces, and loaded executables into
 432    them before connecting to the target interface that will create the
 433    inferiors.  All that happens before GDB has a chance to know if the
 434    inferiors will share an address space or not.  Call this after
 435    having connected to the target interface and having fetched the
 436    target description, to fixup the program/address spaces
 437    mappings.  */
 438 extern void update_address_spaces (void);
 439
 440 /* Reset saved solib data at the start of an solib event.  This lets
 441    us properly collect the data when calling solib_add, so it can then
 442    later be printed.  */
 443 extern void clear_program_space_solib_cache (struct program_space *);
 444
 445 /* Keep a registry of per-pspace data-pointers required by other GDB
 446    modules.  */
 447
 448 DECLARE_REGISTRY (program_space);
 449
 450 /* Keep a registry of per-aspace data-pointers required by other GDB
 451    modules.  */
 452
 453 DECLARE_REGISTRY (address_space);
 454
 455 #endif