Commit | Line | Data |
---|---|---|
801e3a5b JB |
1 | /* addrmap.h --- interface to address map data structure. |
2 | ||
3666a048 | 3 | Copyright (C) 2007-2021 Free Software Foundation, Inc. |
801e3a5b JB |
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 | |
2fff4d11 | 9 | the Free Software Foundation; either version 3 of the License, or |
801e3a5b JB |
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 | |
2fff4d11 | 18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
801e3a5b JB |
19 | |
20 | #ifndef ADDRMAP_H | |
21 | #define ADDRMAP_H | |
22 | ||
50a6759f TT |
23 | #include "gdbsupport/function-view.h" |
24 | ||
801e3a5b JB |
25 | /* An address map is essentially a table mapping CORE_ADDRs onto GDB |
26 | data structures, like blocks, symtabs, partial symtabs, and so on. | |
27 | An address map uses memory proportional to the number of | |
28 | transitions in the map, where a CORE_ADDR N is mapped to one | |
29 | object, and N+1 is mapped to a different object. | |
30 | ||
31 | Address maps come in two flavors: fixed, and mutable. Mutable | |
32 | address maps consume more memory, but can be changed and extended. | |
33 | A fixed address map, once constructed (from a mutable address map), | |
34 | can't be edited. Both kinds of map are allocated in obstacks. */ | |
35 | ||
36 | /* The opaque type representing address maps. */ | |
37 | struct addrmap; | |
38 | ||
39 | /* Create a mutable address map which maps every address to NULL. | |
40 | Allocate entries in OBSTACK. */ | |
41 | struct addrmap *addrmap_create_mutable (struct obstack *obstack); | |
42 | ||
43 | /* In the mutable address map MAP, associate the addresses from START | |
44 | to END_INCLUSIVE that are currently associated with NULL with OBJ | |
45 | instead. Addresses mapped to an object other than NULL are left | |
46 | unchanged. | |
47 | ||
48 | As the name suggests, END_INCLUSIVE is also mapped to OBJ. This | |
49 | convention is unusual, but it allows callers to accurately specify | |
50 | ranges that abut the top of the address space, and ranges that | |
51 | cover the entire address space. | |
52 | ||
53 | This operation seems a bit complicated for a primitive: if it's | |
54 | needed, why not just have a simpler primitive operation that sets a | |
55 | range to a value, wiping out whatever was there before, and then | |
56 | let the caller construct more complicated operations from that, | |
57 | along with some others for traversal? | |
58 | ||
59 | It turns out this is the mutation operation we want to use all the | |
60 | time, at least for now. Our immediate use for address maps is to | |
61 | represent lexical blocks whose address ranges are not contiguous. | |
62 | We walk the tree of lexical blocks present in the debug info, and | |
63 | only create 'struct block' objects after we've traversed all a | |
64 | block's children. If a lexical block declares no local variables | |
65 | (and isn't the lexical block for a function's body), we omit it | |
66 | from GDB's data structures entirely. | |
67 | ||
0fb0cc75 | 68 | However, this means that we don't decide to create a block (and |
801e3a5b JB |
69 | thus record it in the address map) until after we've traversed its |
70 | children. If we do decide to create the block, we do so at a time | |
71 | when all its children have already been recorded in the map. So | |
72 | this operation --- change only those addresses left unset --- is | |
73 | actually the operation we want to use every time. | |
74 | ||
75 | It seems simpler to let the code which operates on the | |
76 | representation directly deal with the hair of implementing these | |
77 | semantics than to provide an interface which allows it to be | |
78 | implemented efficiently, but doesn't reveal too much of the | |
79 | representation. */ | |
80 | void addrmap_set_empty (struct addrmap *map, | |
dda83cd7 SM |
81 | CORE_ADDR start, CORE_ADDR end_inclusive, |
82 | void *obj); | |
801e3a5b JB |
83 | |
84 | /* Return the object associated with ADDR in MAP. */ | |
85 | void *addrmap_find (struct addrmap *map, CORE_ADDR addr); | |
86 | ||
87 | /* Create a fixed address map which is a copy of the mutable address | |
88 | map ORIGINAL. Allocate entries in OBSTACK. */ | |
89 | struct addrmap *addrmap_create_fixed (struct addrmap *original, | |
dda83cd7 | 90 | struct obstack *obstack); |
801e3a5b JB |
91 | |
92 | /* Relocate all the addresses in MAP by OFFSET. (This can be applied | |
93 | to either mutable or immutable maps.) */ | |
94 | void addrmap_relocate (struct addrmap *map, CORE_ADDR offset); | |
95 | ||
855c153f DE |
96 | /* The type of a function used to iterate over the map. |
97 | OBJ is NULL for unmapped regions. */ | |
50a6759f TT |
98 | typedef gdb::function_view<int (CORE_ADDR start_addr, void *obj)> |
99 | addrmap_foreach_fn; | |
100 | ||
101 | /* Call FN for every address in MAP, following an in-order traversal. | |
102 | If FN ever returns a non-zero value, the iteration ceases | |
103 | immediately, and the value is returned. Otherwise, this function | |
104 | returns 0. */ | |
105 | int addrmap_foreach (struct addrmap *map, addrmap_foreach_fn fn); | |
855c153f | 106 | |
801e3a5b | 107 | #endif /* ADDRMAP_H */ |