Struct pdb::AddressMap

pub struct AddressMap<'s> { /* fields omitted */ }

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 an Rva in the actual address space.
• SectionOffset: An offset into a section of the actual binary. A section 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 either SectionOffset, or directly to Rva 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");
    }
}

Methods

impl<'s> AddressMap<'s>

Important traits for RvaRangeIter<'_>

impl<'_> Iterator for RvaRangeIter<'_> type Item = Range<Rva>;

pub fn rva_ranges(&self, range: Range<PdbInternalRva>) -> RvaRangeIter

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.

Important traits for PdbInternalRvaRangeIter<'_>

impl<'_> Iterator for PdbInternalRvaRangeIter<'_> type Item = Range<PdbInternalRva>;

pub fn internal_rva_ranges(&self, range: Range<Rva>) -> PdbInternalRvaRangeIter

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

impl<'s> Debug for AddressMap<'s>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.