[Docs] Document DXIL Container and RDAT formats - #8631
[Docs] Document DXIL Container and RDAT formats#8631Chris B (llvm-beanz) wants to merge 2 commits into
Conversation
I've had these docs locally for a while and have reviewed and used them to help reason about and understand aspects of the binary formats that DXC generates. These docs are generated almost entirely by LLMs during iterative chat discussions where I asked repeated clarifying quesitons. I have found them sufficiently useful to keep them around, but thought they're probably worth sharing. Assisted-by: Claude Opus 4.6-4.8
| ``` | ||
| +---------------------------------------------------------------+ | ||
| | DxilContainerHeader | | ||
| | uint32_t HeaderFourCC = 'DXBC' | | ||
| | DxilContainerHash Hash (16 bytes) | | ||
| | DxilContainerVersion Version { uint16 Major, Minor } | | ||
| | uint32_t ContainerSizeInBytes | | ||
| | uint32_t PartCount | | ||
| +---------------------------------------------------------------+ | ||
| | uint32_t PartOffset[PartCount] (absolute, from container start) | | ||
| +---------------------------------------------------------------+ | ||
| | Part 0: DxilPartHeader { uint32 PartFourCC, uint32 PartSize }| | ||
| | uint8_t PartData[PartSize] | | ||
| +---------------------------------------------------------------+ | ||
| | Part 1: DxilPartHeader ... | | ||
| | ... | | ||
| +---------------------------------------------------------------+ | ||
| ``` |
There was a problem hiding this comment.
It'd be nice if these lined up.
| ``` | |
| +---------------------------------------------------------------+ | |
| | DxilContainerHeader | | |
| | uint32_t HeaderFourCC = 'DXBC' | | |
| | DxilContainerHash Hash (16 bytes) | | |
| | DxilContainerVersion Version { uint16 Major, Minor } | | |
| | uint32_t ContainerSizeInBytes | | |
| | uint32_t PartCount | | |
| +---------------------------------------------------------------+ | |
| | uint32_t PartOffset[PartCount] (absolute, from container start) | | |
| +---------------------------------------------------------------+ | |
| | Part 0: DxilPartHeader { uint32 PartFourCC, uint32 PartSize }| | |
| | uint8_t PartData[PartSize] | | |
| +---------------------------------------------------------------+ | |
| | Part 1: DxilPartHeader ... | | |
| | ... | | |
| +---------------------------------------------------------------+ | |
| ``` |
+-------------------------------------------------------------------+
| DxilContainerHeader |
| uint32_t HeaderFourCC = 'DXBC' |
| DxilContainerHash Hash (16 bytes) |
| DxilContainerVersion Version { uint16 Major, Minor } |
| uint32_t ContainerSizeInBytes |
| uint32_t PartCount |
+-------------------------------------------------------------------+
| uint32_t PartOffset[PartCount] (absolute, from container start) |
+-------------------------------------------------------------------+
| Part 0: DxilPartHeader { uint32 PartFourCC, uint32 PartSize } |
| uint8_t PartData[PartSize] |
+-------------------------------------------------------------------+
| Part 1: DxilPartHeader ... |
| ... |
+-------------------------------------------------------------------+
There was a problem hiding this comment.
Pull request overview
Documents DXC’s DXIL container and embedded RDAT binary formats.
Changes:
- Adds DXIL container structure, part, hashing, and encoding documentation.
- Adds detailed RDAT layout, schema, versioning, and validation documentation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
docs/RDAT_Format.md |
Documents RDAT parts, records, references, and validation. |
docs/DxilContainer_Format.md |
Documents DXIL container headers and part encodings. |
Suppressed comments (1)
docs/DxilContainer_Format.md:481
- The type-specific header layout is incomplete here:
AlignedSizeInBytes,Flags,CompressType, andCountare also serialized before the entry bytes. Omitting them prevents this binary-format description from being used to locate or decompress the entries correctly.
- **Source contents** (`DxilSourceInfo_SourceContents` +
`..._SourceContentsEntry[]`): may be **zlib-compressed** (`CompressType`), with
`EntriesSizeInBytes` (compressed) and `UncompressedEntriesSizeInBytes`; each
uncompressed entry is `AlignedSizeInBytes`, `Flags`, `ContentSizeInBytes`, then
the content (null terminated, padded).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - `IndexTableReader::getRow(i)` returns a row starting at `table[i]` with length | ||
| `table[i]`, i.e. it reads the count then exposes the following `count` values. |
| - `RecordDispatchGrid` (inline value): `ByteOffset` (`uint16_t`), | ||
| `ComponentNumAndType` (`uint16_t`, bitfields: bits 0:2 num components, | ||
| bits 2:15 `ComponentType`). |
| - Field accessors resolve handles: string offsets → `StringBuffer.Get`, index | ||
| refs → `IndexTable.getRow`, record refs → `Table<T>().Row`, byte refs → | ||
| `RawBytes.Get` with `Size`. |
| - Debug/reflection/hash parts (`ILDB`, `ILDN`, `HASH`, `STAT`, `SRCI`) are | ||
| gated by flags and validator version. |
| ### Validation (`DxilRuntimeData::Validate`) | ||
|
|
||
| - The string buffer, if present, must end in `'\0'`. | ||
| - Every table is walked; for each record, all references are bounds-checked: |
| `DxilContainerHeader.Hash` is a 16-byte digest. Separately, the `HASH` part | ||
| (`DxilShaderHash`) stores a `Flags` field plus a 16-byte MD5 digest computed | ||
| over either the final program bitcode or the source-inclusive bitcode | ||
| (`DxilShaderHashFlags::IncludesSource` when `-Zss`/`DebugNameDependOnSource`). | ||
| A sentinel `PreviewByPassHash` (all `2`s) is used in some preview scenarios. |
| - **Source names** (`DxilSourceInfo_SourceNames` + `..._SourceNamesEntry[]`): | ||
| `Count`, `EntriesSizeInBytes`, then per-entry `AlignedSizeInBytes`, `Flags`, | ||
| `NameSizeInBytes`, `ContentSizeInBytes`, followed by the UTF-8 name (null | ||
| terminated, padded to 4 bytes). |
I've had these docs locally for a while and have reviewed and used them to help reason about and understand aspects of the binary formats that DXC generates.
These docs are generated almost entirely by LLMs during iterative chat discussions where I asked repeated clarifying quesitons.
I have found them sufficiently useful to keep them around, but thought they're probably worth sharing.
Assisted-by: Claude Opus 4.6-4.8