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