DirectX Container

Overview

The DirectX Container (DXContainer) file format is the binary file format for compiled shaders targeting the DirectX runtime. The file format is also called the DXIL Container or DXBC file format. Because the file format can be used to include either DXIL or DXBC compiled shaders, the nomenclature in LLVM is simply DirectX Container.

DirectX Container files are read by the compiler and associated tools as well as the DirectX runtime, profiling tools and other users. This document serves as a companion to the implementation in LLVM to more completely document the file format for its many users.

Basic Structure

A DXContainer file begins with a header, and is then followed by a sequence of “parts”, which are analogous to object file sections. Each part contains a part header, and some number of bytes of data after the header in a defined format.

DX Container data structures are encoded little-endian in the binary file.

The LLVM versions of all data structures described and/or referenced in this file are defined in llvm/include/llvm/BinaryFormat/DXContainer.h. Some pseudo code is provided in blocks below to ease understanding of this document, but reading it with the header available will provide the most clarity.

File Header

struct Header {
  uint8_t Magic[4];
  uint8_t Digest[16];
  uint16_t MajorVersion;
  uint16_t MinorVersion;
  uint32_t FileSize;
  uint32_t PartCount;
};

The DXContainer header matches the pseudo-definition above. It begins with a four character code (magic number) with the value DXBC to denote the file format.

The Digest is a 128bit hash digest computed with a proprietary algorithm and encoded in the binary by the bytecode validator.

The MajorVersion and MinorVersion encode the file format version 1.0.

The remaining fields encode 32-bit unsigned integers for the file size and number of parts.

Following the part header is an array of PartCount 32-bit unsigned integers specifying the offsets of each part header.

Part Data

struct PartHeader {
  uint8_t Name[4];
  uint32_t Size;
}

Each part begins with a part header. A part header includes the 4-character part name, and a 32-bit unsigned integer specifying the size of the part data. The part header is followed by Size bytes of data comprising the part. The format does not explicitly require 32-bit alignment of parts, although LLVM does implement this restriction in the writer code (because it’s a good idea). The LLVM object reader code does not assume inputs are correctly aligned to avoid undefined behavior caused by misaligned inputs generated by other compilers.

Part Formats

The part name indicates the format of the part data. There are 24 part headers used by DXC and FXC. Not all compiled shaders contain all parts. In the list below parts generated only by DXC are marked with †, and parts generated only by FXC are marked with *.

  1. DXIL† - Stores the DXIL bytecode.

  2. HASH† - Stores the shader MD5 hash.

  3. ILDB† - Stores the DXIL bytecode with LLVM Debug Information embedded in the module.

  4. ILDN† - Stores shader debug name for external debug information.

  5. ISG1 - Stores the input signature for Shader Model 5.1+.

  6. ISGN* - Stores the input signature for Shader Model 4 and earlier.

  7. OSG1 - Stores the output signature for Shader Model 5.1+.

  8. OSG5* - Stores the output signature for Shader Model 5.

  9. OSGN* - Stores the output signature for Shader Model 4 and earlier.

  10. PCSG* - Stores the patch constant signature for Shader Model 5.1 and earlier.

  11. PDBI† - Stores PDB information.

  12. PRIV - Stores arbitrary private data (Not encoded by either FXC or DXC).

  13. PSG1 - Stores the patch constant signature for Shader Model 6+.

  14. PSV0 - Stores Pipeline State Validation data.

  15. RDAT† - Stores Runtime Data.

  16. RDEF* - Stores resource definitions.

  17. RTS0 - Stores compiled root signature.

  18. SFI0 - Stores shader feature flags.

  19. SHDR* - Stores compiled DXBC bytecode.

  20. SHEX* - Stores compiled DXBC bytecode.

  21. DXBC* - Stores compiled DXBC bytecode.

  22. SRCI† - Stores shader source information.

  23. STAT† - Stores shader statistics.

  24. VERS† - Stores shader compiler version information.

DXIL Part

The DXIL part is comprised of three data structures: the ProgramHeader, the BitcodeHeader and the bitcode serialized LLVM 3.7 IR Module.

The ProgramHeader contains the shader model version and pipeline stage enumeration value. This identifies the target profile of the contained shader bitcode.

The BitcodeHeader contains the DXIL version information and refers to the start of the bitcode data.

HASH Part

The HASH part contains a 32-bit unsigned integer with the shader hash flags, and a 128-bit MD5 hash digest. The flags field can either have the value 0 to indicate no flags, or 1 to indicate that the file hash was computed including the source code that produced the binary.

Program Signature (SG1) Parts