Struct pdb::AddressMap
source · [−]pub struct AddressMap<'s> { /* private fields */ }
Expand description
A mapping between addresses and offsets used in the PDB and PE file.
To obtain an instace of this address map, call PDB::address_map
. It will determine the correct
translation mode and read all internal state from the PDB. Then use the conversion methods on
the address and offset types to translate addresses.
Background
Addresses in PDBs are stored as offsets into sections of the PE file. The AddressMap
contains
the PE’s section headers to translate between the offsets and virtual addresses relative to the
image base (RVAs).
Additionally, Microsoft has been reordering the Windows system and application binaries to
optimize them for paging reduction, using a toolset reported to be derived from and/or built on
top of the Vulcan research project. Relatively little else is known about the tools or the
methods they use. Looking at Windows system binaries like ntoskrnl.exe
, it is apparent that
their layout has been rearranged, and their respective symbol files contain OMAP re-mapping
information. The Microsoft Binary Technologies Projects may be involved in this.
The internals of this transformation are not well understood. According to 1997 reference material:
Yet another form of debug information is relatively new and undocumented, except for a few obscure references in
WINNT.H
and the Win32 SDK help. This type of information is known as OMAP. Apparently, as part of Microsoft’s internal build procedure, small fragments of code in EXEs and DLLs are moved around to put the most commonly used code at the beginning of the code section. This presumably keeps the process memory working set as small as possible. However, when shifting around the blocks of code, the corresponding debug information isn’t updated. Instead, OMAP information is created. It lets symbol table code translate between the original address in a symbol table and the modified address where the variable or line of code really exists in memory.
Usage
To aid with translating addresses and offsets, this module exposes AddressMap
, a helper that
contains all information to apply the correct translation of any kind of address or offset to
another. Due to the rearranging optimizations, there are four types involved:
Rva
: A Relative Virtual Address in the actual binary. This address directly corresponds to instruction pointers seen in stack traces and symbol addresses reported by debuggers.PdbInternalRva
: An RVA as it would have appeared before the optimization. These RVAs are used in some places and can be converted to anRva
in the actual address space.SectionOffset
: An offset into a section of the actual binary. Asection
member of n refers to section n - 1, which makes a section number of 0 a null pointer.PdbInternalSectionOffset
: An offset into a section of the original binary. These offsets are used throughout the PDB and can be converted to eitherSectionOffset
, or directly toRva
in the actual address space.
For binaries that have not been optimized that way, the PdbInternal*
values are effectively
equal to their regular counterparts and the conversion between the two are no-ops. Address
translation still has to assume different address spaces, which is why there is no direct
conversion without an AddressMap
.
Example
let mut pdb = pdb::PDB::open(source)?;
// Compute the address map once and reuse it
let address_map = pdb.address_map()?;
// Obtain some section offset, eg from a symbol, and convert it
match pubsym.offset.to_rva(&address_map) {
Some(rva) => {
println!("symbol is at {}", rva);
}
None => {
println!("symbol refers to eliminated code");
}
}
Implementations
sourceimpl<'s> AddressMap<'s>
impl<'s> AddressMap<'s>
sourcepub fn rva_ranges(&self, range: Range<PdbInternalRva>) -> RvaRangeIter<'_>ⓘNotable traits for RvaRangeIter<'_>impl Iterator for RvaRangeIter<'_> type Item = Range<Rva>;
pub fn rva_ranges(&self, range: Range<PdbInternalRva>) -> RvaRangeIter<'_>ⓘNotable traits for RvaRangeIter<'_>impl Iterator for RvaRangeIter<'_> type Item = Range<Rva>;
Resolves actual ranges in the executable’s address space.
The given internal address range might be split up into multiple ranges in the executable. This iterator traverses all mapped ranges in the order of the PDB-internal mapping. All empty or eliminated ranges are skipped. Thus, the iterator might be empty even for non-empty ranges.
sourcepub fn internal_rva_ranges(
&self,
range: Range<Rva>
) -> PdbInternalRvaRangeIter<'_>ⓘNotable traits for PdbInternalRvaRangeIter<'_>impl Iterator for PdbInternalRvaRangeIter<'_> type Item = Range<PdbInternalRva>;
pub fn internal_rva_ranges(
&self,
range: Range<Rva>
) -> PdbInternalRvaRangeIter<'_>ⓘNotable traits for PdbInternalRvaRangeIter<'_>impl Iterator for PdbInternalRvaRangeIter<'_> type Item = Range<PdbInternalRva>;
Resolves actual ranges in the executable’s address space.
The given address range might correspond to multiple ranges in the PDB-internal address space. This iterator traverses all mapped ranges in the order of the actual RVA mapping. This iterator might be empty even for non-empty ranges if no corresponding original range can be found.
Trait Implementations
sourceimpl<'s> Debug for AddressMap<'s>
impl<'s> Debug for AddressMap<'s>
sourceimpl<'s> Default for AddressMap<'s>
impl<'s> Default for AddressMap<'s>
sourcefn default() -> AddressMap<'s>
fn default() -> AddressMap<'s>
Returns the “default value” for a type. Read more
Auto Trait Implementations
impl<'s> !RefUnwindSafe for AddressMap<'s>
impl<'s> !Send for AddressMap<'s>
impl<'s> !Sync for AddressMap<'s>
impl<'s> Unpin for AddressMap<'s>
impl<'s> !UnwindSafe for AddressMap<'s>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more