# dxil-reader
A bounded reader of DXIL, the Direct3D Shader Model 6 program format: it decodes the LLVM bitcode inside a `DXBC`
container into a module (types, constants, metadata, function bodies) and reads the reflection records DXIL keeps in its
metadata and in its signature and runtime-data parts.
```rust
let container = std::fs::read("shader.dxil")?;
let parts = dxil_reader::parts(&container)?;
let module = dxil_reader::module(&parts, b"DXIL")?.expect("a DXIL part");
println!("{} functions", module.functions.len());
// The records the file stores for its entry point:
let (inputs, outputs) = dxil_reader::reflection::elements(&module)?;
println!("{} input and {} output signature elements", inputs.len(), outputs.len());
for (range, name, _) in dxil_reader::reflection::ranges(&module)? {
println!("{name}: class {} register {}", range.class, range.lower);
}
```
Run it with `cargo run -p dxil-reader --example inspect_dxil -- <files>`; the source is [`examples/inspect_dxil.rs`](examples/inspect_dxil.rs).
## What it reads
- **Container** (`parts`, over the `dxcontainer` crate): the DXBC directory; Shader Model 6 parts are not 4-byte aligned.
- **Program part** (`program`, `part`): the `DXIL` part's header (program version, size, `DXIL` magic, DXIL version,
bitcode offset and size); the `STAT` reflection part has the same header (`module(&parts, b"STAT")`).
- **Bitstream** (`bitstream`): LLVM's bitstream container: abbreviations (literal, fixed, VBR, array, char6, blob),
BLOCKINFO, nesting up to 32 blocks, at most 4096 abbreviations per block and 2^26 record operands, every length checked
against the bits that remain before anything is allocated. The `llvm-bitcode` crate was considered and not used: it sizes
allocations from untrusted lengths.
- **Module** (`module`): LLVM 3.7 IR as DXIL stores it, with relative value ids (module version 1): types, globals and
functions, constants (no constant expressions), metadata (strings, values, nodes, named nodes, kind names), the attribute
groups and lists (a function names its list; `function_attributes`, `string_attribute`), value names and function
bodies; the metadata attached to each instruction (`Instruction::attachments`, with `dx.precise` also as `precise`) and
to a function. Instructions: binary operators, casts, comparisons, select, extractvalue and insertvalue, vector element and
shuffle operations, call, phi, ret, branches, switch, unreachable, alloca, load and store. Any other record is refused by
name.
- **Texture reads** (`sampling::texture_reads`): every `sample`, `sampleBias`, `sampleLevel`, `sampleGrad`, `sampleCmp`,
`sampleCmpLevelZero`, `textureGather`, `textureGatherCmp`, `calculateLOD`, `textureLoad`, `bufferLoad` and
`rawBufferLoad` call, with the class, space and register of its resource's handle and of its sampler's (the handle is
followed through `annotateHandle` to its `createHandle` or `createHandleFromBinding` call), and whether the call
compares. In Elden Ring's 12,754 distinct programs a texture register is read with exactly one sampler register in all
but 15 of 103,299 sampled slots. `cargo run -p dxil-reader --example pairs_dxil -- <files or folders>` prints the pairs
of each program.
- **Reflection records** (`reflection`): the entry point and what its properties state (`num_threads`, `geometry_state`,
`mesh_state`, `hull_state`, `domain_state`; a library's `library_kind`); signature elements and their packing
(`elements`, `patch_elements`); the bound resource ranges of `dx.resources` (`ranges`: class, range id, register, count,
shape, space, element type and stride tags, counter); the field annotations of `dx.typeAnnotations` (`fields`); and the
rows of an `ISG1`/`OSG1`/`PSG1` part (`signature`); the entry properties' shader flags (`shader_flags`) and each
signature element's usage mask (`usage_masks`). Every entry property as stored (`entry_properties`) and the typed ones
beside the earlier states: the ray payload and attribute sizes, the auto binding space of the entry and of a library's
resource record, a required wave size, an amplification program's payload size (its thread group is read by
`num_threads` too). Each signature element's tail tags (`element_tags`: the geometry stream, the dynamically indexed
components, the usage mask), the optional fields of each resource record (`resource_extras`: an SRV's sample count, a
UAV's coherence, rasterizer order and 64-bit atomic use, the tag list), and the string attribute of the entry function
that states the denormal mode (`fp32_denorm_mode`).
- **Pipeline state** (`psv`): the `PSV0` part the validator writes: runtime information (36, 48 or 52 bytes), resource
records, strings, semantic indices, signature elements and the dependency words.
- **Runtime data** (`rdat`): a library's subobjects as its `RDAT` part stores them (state object and pipeline configuration,
root signatures, associations, hit groups), and a function's export name from its decorated name.
- `operations`: the `dx.op` operations a container's module calls, by name, for surveying shaders.
## What it guarantees
- **Bounded.** Every length, count and reference is checked against what exists before allocation; a crafted file produces
an `Error` naming the bit offset (in the bitcode, or eight times a byte of the container or part), never a panic or an
unbounded allocation.
- **Function bodies are self-consistent.** Every value an instruction reads is one of the function's (an earlier one, or a
later one a phi or a loop reads), every branch target and phi predecessor is a block of it, every instruction is in a
block, and a call has as many arguments as its callee has parameters.
- **Records as stored.** Resource classes, kinds and shapes keep DXIL's and D3D's own numbers.
## What it does not do
It does not execute, optimise or translate programs, does not write bitcode, and does not read LLVM modules that are not
DXIL's dialect (LLVM 3.7 IR as dxc emits it). The container digest is not verified. Reflection helpers that are given a
module without the metadata they look for return an error naming what is missing; some of those errors report bit 0,
because a metadata node has no position of its own.
## Tests
`cargo test -p dxil-reader`: every committed fixture in `tests/fixtures` (129 `.dxil` files compiled by dxc 1.7 from the
HLSL beside each, with the command in each file; `.od` files with `-Od`) is read, control-flow and memory fixtures are checked
in detail, and `RDAT` data laid out by hand exercises every subobject kind and the refusals. No game files are needed.
License: GPL-3.0-or-later.