Skip to main content

pdb_bindgen/
lib.rs

1#![no_std]
2
3//! `pdb-bindgen` is the `no_std` facade for bindings generated from Microsoft PDBs.
4//!
5//! Depend on this crate normally for the [`pdb`] proc macro. Enable `codegen` only
6//! for the build dependency, where [`Builder::generate`] discovers active source
7//! markers, acquires configured PDBs, and writes the fragments the macro consumes.
8//! The proc macro does not scan PDBs or source and does not write files.
9//!
10//! # Safety
11//!
12//! Generated addresses are the source-side base provider result plus a PDB RVA.
13//! The provider must return the base of the currently loaded image that exactly
14//! matches its configured PDB identity and must remain valid during the operation.
15//! Loaded-image identity is not validated at runtime. A generated safe wrapper is
16//! sound only for a source `safe fn` whose foreign contract is safe for all declared
17//! inputs under those invariants; unsafe declarations retain caller obligations.
18//! Global accessors return raw pointers, and callers are responsible for validity,
19//! aliasing, lifetime, and mutability when dereferencing them.
20
21#![cfg_attr(
22    feature = "codegen",
23    doc = r#"
24# Build-script generation
25
26Configure each image in `build.rs` with an exact logical PDB filename, GUID, and
27age, then call [`Builder::generate`]. Runtime base providers belong only to the
28source-side `#[pdb(image = "kernel", base = crate::kernel_base)]` declaration.
29
30```rust,no_run
31use pdb_bindgen::{Builder, Image, PdbGuid, PdbIdentity};
32
33fn main() -> Result<(), Box<dyn std::error::Error>> {
34    let guid: PdbGuid = "12345678-9abc-def0-1234-56789abcdef0".parse()?;
35    let identity = PdbIdentity::new("ntkrnlmp.pdb", guid, 1)?;
36    let image = Image::new("kernel", identity)?.local_pdb("symbols/ntkrnlmp.pdb")?;
37
38    let mut builder = Builder::new();
39    builder.offline(true).disable_symbol_server();
40    builder.image(image)?;
41    builder.generate()?;
42    Ok(())
43}
44```
45
46`generate` reads Cargo's package and output directories, evaluates active `cfg` and
47`cfg_attr` declarations, acquires only their referenced images, and publishes
48rendered fragments deterministically. Relative local-PDB and cache paths are package
49relative; the default cache is `OUT_DIR/pdb-bindgen/cache`. Offline mode forbids
50network access, and `disable_symbol_server` disables server acquisition.
51
52# Source marker shape
53
54The marker requires generated fragments, so this is not a compiled example. Use an
55inline image module.
56
57```text
58#[pdb_bindgen::pdb(image = "kernel", base = crate::kernel_base)]
59mod kernel {
60    #[pdb_bindgen::pdb(type_name = "EPROCESS")]
61    pub struct Process {
62        #[pdb_bindgen::pdb(field_name = "UniqueProcessId")]
63        pub pid: usize,
64    }
65
66    #[pdb_bindgen::pdb(symbols)]
67    unsafe extern "system" {
68        pub safe fn PsGetCurrentProcessId() -> usize;
69        pub static mut PsInitialSystemProcess: *mut Process;
70    }
71}
72```
73"#
74)]
75
76#[doc(inline)]
77pub use pdb_bindgen_macro::pdb;
78
79#[cfg(feature = "codegen")]
80#[doc(inline)]
81pub use pdb_bindgen_codegen::{
82    Builder, CachePolicy, ConfigError, GenerateError, GenerateErrorKind, GuidErrorKind, Image,
83    ParsePdbGuidError, PdbFilenameErrorKind, PdbGuid, PdbIdentity, SymbolServer,
84    SymbolServerErrorKind,
85};