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 ()) { ... } */
210 {
211 return objfiles_range
214 }
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. */
226 {
231 }
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 a range adapter for iterating over all the solibs in this
253 program space. Use it like:
254
255 for (so_list *so : pspace->solibs ()) { ... } */
257 { return so_list_range (this->so_list); }
258
259 /* Close and clear exec_bfd. If we end up with no target sections
260 to read memory from, this unpushes the exec_ops target. */
261 void exec_close ();
262
263 /* Return the exec BFD for this program space. */
264 bfd *exec_bfd () const
265 {
266 return ebfd.get ();
267 }
268
269 /* Set the exec BFD for this program space to ABFD. */
271 {
272 ebfd = std::move (abfd);
273 }
274
275 /* Reset saved solib data at the start of an solib event. This lets
276 us properly collect the data when calling solib_add, so it can then
277 later be printed. */
278 void clear_solib_cache ();
279
280 /* Returns true iff there's no inferior bound to this program
281 space. */
282 bool empty ();
283
284 /* Remove all target sections owned by OWNER. */
285 void remove_target_sections (void *owner);
286
287 /* Add the sections array defined by SECTIONS to the
288 current set of target sections. */
289 void add_target_sections (void *owner,
290 const target_section_table &sections);
291
292 /* Add the sections of OBJFILE to the current set of target
293 sections. They are given OBJFILE as the "owner". */
294 void add_target_sections (struct objfile *objfile);
295
296 /* Clear all target sections from M_TARGET_SECTIONS table. */
298 {
299 m_target_sections.clear ();
300 }
301
302 /* Return a reference to the M_TARGET_SECTIONS table. */
304 {
305 return m_target_sections;
306 }
307
308 /* Unique ID number. */
309 int num = 0;
310
311 /* The main executable loaded into this program space. This is
312 managed by the exec target. */
313
314 /* The BFD handle for the main executable. */
316 /* The last-modified time, from when the exec was brought in. */
317 long ebfd_mtime = 0;
318 /* Similar to bfd_get_filename (exec_bfd) but in original form given
319 by user, without symbolic links and pathname resolved. It is not
320 NULL iff EBFD is not NULL. */
321 gdb::unique_xmalloc_ptr<char> exec_filename;
322
323 /* Binary file diddling handle for the core file. */
325
326 /* The address space attached to this program space. More than one
327 program space may be bound to the same address space. In the
328 traditional unix-like debugging scenario, this will usually
329 match the address space bound to the inferior, and is mostly
330 used by the breakpoints module for address matches. If the
331 target shares a program space for all inferiors and breakpoints
332 are global, then this field is ignored (we don't currently
333 support inferiors sharing a program space if the target doesn't
334 make breakpoints global). */
335 struct address_space *aspace = NULL;
336
337 /* True if this program space's section offsets don't yet represent
338 the final offsets of the "live" address space (that is, the
339 section addresses still require the relocation offsets to be
340 applied, and hence we can't trust the section addresses for
341 anything that pokes at live memory). E.g., for qOffsets
342 targets, or for PIE executables, until we connect and ask the
343 target for the final relocation offsets, the symbols we've used
344 to set breakpoints point at the wrong addresses. */
346
347 /* True if no breakpoints should be inserted in this program
348 space. */
350
351 /* The object file that the main symbol table was loaded from
352 (e.g. the argument to the "symbol-file" or "file" command). */
354
355 /* All known objfiles are kept in a linked list. */
356 std::list<std::unique_ptr<objfile>> objfiles_list;
357
358 /* List of shared objects mapped into this space. Managed by
359 solib.c. */
360 struct so_list *so_list = NULL;
361
362 /* Number of calls to solib_add. */
363 unsigned int solib_add_generation = 0;
364
365 /* When an solib is added, it is also added to this vector. This
366 is so we can properly report solib changes to the user. */
367 std::vector<struct so_list *> added_solibs;
368
369 /* When an solib is removed, its name is added to this vector.
370 This is so we can properly report solib changes to the user. */
371 std::vector<std::string> deleted_solibs;
372
373 /* Per pspace data-pointers required by other GDB modules. */
375
376private:
377 /* The set of target sections matching the sections mapped into
378 this program space. Managed by both exec_ops and solib.c. */
380};
381
382/* An address space. It is used for comparing if
383 pspaces/inferior/threads see the same address space and for
384 associating caches to each address space. */
386{
387 /* Create a new address space object, and add it to the list. */
388 address_space ();
390
391 /* Returns the integer address space id of this address space. */
392 int num () const
393 {
394 return m_num;
395 }
396
397 /* Per aspace data-pointers required by other GDB modules. */
399
400private:
401 int m_num;
402};
403
404/* The list of all program spaces. There's always at least one. */
405extern std::vector<struct program_space *>program_spaces;
406
407/* The current program space. This is always non-null. */
409
410/* Copies program space SRC to DEST. Copies the main executable file,
411 and the main symbol file. Returns DEST. */
412extern struct program_space *clone_program_space (struct program_space *dest,
413 struct program_space *src);
414
415/* Sets PSPACE as the current program space. This is usually used
416 instead of set_current_space_and_thread when the current
417 thread/inferior is not important for the operations that follow.
418 E.g., when accessing the raw symbol tables. If memory access is
419 required, then you should use switch_to_program_space_and_thread.
420 Otherwise, it is the caller's responsibility to make sure that the
421 currently selected inferior/thread matches the selected program
422 space. */
423extern void set_current_program_space (struct program_space *pspace);
424
425/* Save/restore the current program space. */
426
428{
429public:
432 {}
433
436
438
439private:
441};
442
443/* Maybe create a new address space object, and add it to the list, or
444 return a pointer to an existing address space, in case inferiors
445 share an address space. */
446extern struct address_space *maybe_new_address_space (void);
447
448/* Update all program spaces matching to address spaces. The user may
449 have created several program spaces, and loaded executables into
450 them before connecting to the target interface that will create the
451 inferiors. All that happens before GDB has a chance to know if the
452 inferiors will share an address space or not. Call this after
453 having connected to the target interface and having fetched the
454 target description, to fixup the program/address spaces
455 mappings. */
456extern void update_address_spaces (void);
457
458#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:78
Definition aarch64.h:50
struct program_space * current_program_space
Definition progspace.c:39
void set_current_program_space(struct program_space *pspace)
Definition progspace.c:224
struct program_space * clone_program_space(struct program_space *dest, struct program_space *src)
Definition progspace.c:203
struct address_space * maybe_new_address_space(void)
Definition progspace.c:58
std::list< std::unique_ptr< objfile > > objfile_list
Definition progspace.h:43
void update_address_spaces(void)
Definition progspace.c:384
std::vector< struct program_space * > program_spaces
Definition progspace.c:36
iterator_range< unwrapping_objfile_iterator > unwrapping_objfile_range
Definition progspace.h:92
next_range< so_list > so_list_range
Definition solist.h:166
int num() const
Definition progspace.h:392
DISABLE_COPY_AND_ASSIGN(address_space)
registry< address_space > registry_fields
Definition progspace.h:398
objfiles_safe_range objfiles_safe()
Definition progspace.h:225
void remove_target_sections(void *owner)
Definition exec.c:647
void add_target_sections(void *owner, const target_section_table &sections)
Definition exec.c:593
registry< program_space > registry_fields
Definition progspace.h:374
objfiles_range objfiles()
Definition progspace.h:209
void remove_objfile(struct objfile *objfile)
Definition progspace.c:161
gdb_bfd_ref_ptr ebfd
Definition progspace.h:315
target_section_table m_target_sections
Definition progspace.h:379
std::vector< std::string > deleted_solibs
Definition progspace.h:371
void exec_close()
Definition progspace.c:184
std::vector< struct so_list * > added_solibs
Definition progspace.h:367
void add_objfile(std::unique_ptr< objfile > &&objfile, struct objfile *before)
Definition progspace.c:141
int executing_startup
Definition progspace.h:345
unsigned int solib_add_generation
Definition progspace.h:363
bool multi_objfile_p() const
Definition progspace.h:244
target_section_table & target_sections()
Definition progspace.h:303
int breakpoints_not_allowed
Definition progspace.h:349
bfd * exec_bfd() const
Definition progspace.h:264
void set_exec_bfd(gdb_bfd_ref_ptr &&abfd)
Definition progspace.h:270
struct address_space * aspace
Definition progspace.h:335
basic_safe_range< objfiles_range > objfiles_safe_range
Definition progspace.h:216
void clear_target_sections()
Definition progspace.h:297
gdb::unique_xmalloc_ptr< char > exec_filename
Definition progspace.h:321
struct objfile * symfile_object_file
Definition progspace.h:353
gdb_bfd_ref_ptr cbfd
Definition progspace.h:324
std::list< std::unique_ptr< objfile > > objfiles_list
Definition progspace.h:356
unwrapping_objfile_range objfiles_range
Definition progspace.h:203
void free_all_objfiles()
Definition progspace.c:128
void clear_solib_cache()
Definition progspace.c:417
so_list_range solibs() const
Definition progspace.h:256
std::vector< target_section > target_section_table