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