Skip to main content

Crate pdb_bindgen

Crate pdb_bindgen 

Source
Expand description

pdb-bindgen is the no_std facade for bindings generated from Microsoft PDBs.

Depend on this crate normally for the pdb proc macro. Enable codegen only for the build dependency, where Builder::generate discovers active source markers, acquires configured PDBs, and writes the fragments the macro consumes. The proc macro does not scan PDBs or source and does not write files.

§Safety

Generated addresses are the source-side base provider result plus a PDB RVA. The provider must return the base of the currently loaded image that exactly matches its configured PDB identity and must remain valid during the operation. Loaded-image identity is not validated at runtime. A generated safe wrapper is sound only for a source safe fn whose foreign contract is safe for all declared inputs under those invariants; unsafe declarations retain caller obligations. Global accessors return raw pointers, and callers are responsible for validity, aliasing, lifetime, and mutability when dereferencing them.

§Build-script generation

Configure each image in build.rs with an exact logical PDB filename, GUID, and age, then call Builder::generate. Runtime base providers belong only to the source-side #[pdb(image = "kernel", base = crate::kernel_base)] declaration.

use pdb_bindgen::{Builder, Image, PdbGuid, PdbIdentity};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let guid: PdbGuid = "12345678-9abc-def0-1234-56789abcdef0".parse()?;
    let identity = PdbIdentity::new("ntkrnlmp.pdb", guid, 1)?;
    let image = Image::new("kernel", identity)?.local_pdb("symbols/ntkrnlmp.pdb")?;

    let mut builder = Builder::new();
    builder.offline(true).disable_symbol_server();
    builder.image(image)?;
    builder.generate()?;
    Ok(())
}

generate reads Cargo’s package and output directories, evaluates active cfg and cfg_attr declarations, acquires only their referenced images, and publishes rendered fragments deterministically. Relative local-PDB and cache paths are package relative; the default cache is OUT_DIR/pdb-bindgen/cache. Offline mode forbids network access, and disable_symbol_server disables server acquisition.

§Source marker shape

The marker requires generated fragments, so this is not a compiled example. Use an inline image module.

#[pdb_bindgen::pdb(image = "kernel", base = crate::kernel_base)]
mod kernel {
    #[pdb_bindgen::pdb(type_name = "EPROCESS")]
    pub struct Process {
        #[pdb_bindgen::pdb(field_name = "UniqueProcessId")]
        pub pid: usize,
    }

    #[pdb_bindgen::pdb(symbols)]
    unsafe extern "system" {
        pub safe fn PsGetCurrentProcessId() -> usize;
        pub static mut PsInitialSystemProcess: *mut Process;
    }
}

Structs§

Builder
Collects image configuration and builder-wide PDB acquisition policy.
CachePolicy
Describes where PDB acquisition keeps cached files.
GenerateError
An error from Builder::generate.
Image
A logical image and its authoritative PDB configuration.
ParsePdbGuidError
An error returned when canonical PDB GUID text is malformed.
PdbGuid
A PDB GUID represented by its conventional GUID fields.
PdbIdentity
An explicit Symbol Server PDB identity.
SymbolServer
Describes the configured Symbol Server source.

Enums§

ConfigError
Describes a configuration validation failure.
GenerateErrorKind
The category of a GenerateError.
GuidErrorKind
Describes why canonical PDB GUID text could not be parsed.
PdbFilenameErrorKind
Describes why a logical PDB filename is invalid.
SymbolServerErrorKind
Describes why a Symbol Server URL is invalid.

Attribute Macros§

pdb
Replaces a named struct marker with its generated item fragment.