BC file format: bitstream

LLVM bitcode is stored in a generic container, the LLVM bitstream, which also carries Clang’s serialised ASTs and other LLVM data. The bitstream is a sequence of bits, not bytes: fields take as many bits as they need and are packed one after another. This page describes the container, following LLVM’s Bitcode File Format document. What the blocks and records mean for LLVM IR is on the module blocks, functions and constants and metadata and summaries pages.

Magic number

A bitstream starts with a 32-bit magic number chosen by the application. The LLVM document asks tools not to reject a stream because they do not recognise its magic. LLVM IR uses the characters B and C as two 8-bit fields followed by the four 4-bit fields 0x0, 0xC, 0xE, 0xD. Because fields are packed from the least significant bit, those nibbles land as the bytes C0 DE, so the file starts:

42 43 C0 DE        "BC" then 0xC0DE

After the magic, the stream is read with an abbreviation-ID width of 2 bits and no abbreviations defined.

Bitcode wrapper header

A file may instead start with a wrapper, which lets other data sit beside the bitcode. It is five little-endian 32-bit fields:

Offset	Size	Name	Meaning
`0`	4	Magic	`0x0B17C0DE`, stored `DE C0 17 0B`.
`4`	4	Version	Always 0.
`8`	4	Offset	Byte offset of the bitcode (its `42 43 C0 DE`) from the start of the file.
`12`	4	Size	Size of the bitcode in bytes.
`16`	4	CPUType	A target-specific value for the processor the bitcode was built for.

Bitcode can also be embedded in a native object file: in a section named __LLVM,__bitcode in Mach-O, and .llvmbc in ELF, COFF and others. ELF files built for “fat” link-time optimisation also use a .llvm.lto section.

Primitives

Bits are taken from each byte starting at its least significant bit, and the bytes in file order.

Primitive	Encoding
Fixed(`N`)	The value’s low `N` bits, least significant first. A Fixed(1) is a Boolean.
VBR(`N`)	Variable-width: chunks of `N` bits, each holding `N`−1 bits of the value (lowest first) and, in its top bit, 1 if another chunk follows. In VBR6 the value 100 (`0b1100100`) is the chunk `100100` (low five bits `00100` plus the continuation bit) then `000011`.
Char6	A 6-bit character: `a`–`z` are 0–25, `A`–`Z` 26–51, `0`–`9` 52–61, `.` 62 and `_` 63. No other character can be written this way.
Align32	Zero bits up to the next multiple of 32 bits.
Signed VBR	Used by LLVM IR for signed integers: a value `n` ≥ 0 is written as `n` << 1; a negative one as (−`n` << 1) \| 1, so the low bit is the sign.

Abbreviation IDs

Everything in the stream after the magic starts with an abbreviation ID, a Fixed field whose width is set by the enclosing block (2 bits at the top level). IDs 0 to 3 are fixed by the bitstream; 4 and up name abbreviations defined in the current block or for its block ID in the BLOCKINFO block.

ID	Name	Meaning
`0`	`END_BLOCK`	Ends the current block.
`1`	`ENTER_SUBBLOCK`	Starts a nested block.
`2`	`DEFINE_ABBREV`	Defines a new abbreviation.
`3`	`UNABBREV_RECORD`	A record written in the general, unabbreviated form.
`4`+	—	A record written with the abbreviation of that number.

Blocks

A block groups records and other blocks. Each has a block ID; IDs 0 to 7 are reserved for the bitstream (only 0, BLOCKINFO, is defined) and 8 and up belong to the application. Abbreviations defined inside a block belong to that block.

ENTER_SUBBLOCK

Field	Encoding	Meaning
abbrev ID	Fixed(current width)	`1`.
blockid	VBR8	The block ID.
newabbrevlen	VBR4	The abbreviation-ID width inside the new block.
—	Align32	Padding to a 32-bit boundary.
blocklen	Fixed(32)	Length of the block body in 32-bit words, so a reader can skip the block without parsing it.

END_BLOCK

Field	Encoding	Meaning
abbrev ID	Fixed(current width)	`0`.
—	Align32	Padding to a 32-bit boundary. The width of the outer block applies again.

Data records

A record is a code (an unsigned number giving the kind of record within its block) and a list of unsigned integer operands. Strings are records whose operands are character codes.

UNABBREV_RECORD

Field	Encoding	Meaning
abbrev ID	Fixed(current width)	`3`.
code	VBR6	The record code.
numops	VBR6	Number of operands.
op0, op1, …	VBR6 each	The operands.

This form can hold any record but is not compact, so writers define abbreviations for common records.

Abbreviated records

A record written with an abbreviation ID of 4 or more has no code or count of its own: the abbreviation lists the fields, and each field is either a literal (not written at all) or read with the encoding the abbreviation gives. The first field is the record code.

DEFINE_ABBREV

Field	Encoding	Meaning
abbrev ID	Fixed(current width)	`2`.
numabbrevops	VBR5	Number of operand definitions that follow. An Array and its element type count as two.
operand definitions	see below	One per field of the record.

Each operand definition starts with a 1-bit flag:

Flag	Then	Meaning
`1`	value: VBR8	A literal: the field always has this value and takes no bits in the records.
`0`	encoding: Fixed(3), then, for Fixed and VBR only, a VBR5 width	An encoded field.

Encoding	Name	Has width	Meaning
`1`	Fixed	yes	Fixed(`width`).
`2`	VBR	yes	VBR(`width`).
`3`	Array	no	A VBR6 element count, then that many elements, each encoded as the next operand definition says. Must be the second-to-last operand.
`4`	Char6	no	One 6-bit character.
`5`	Blob	no	A VBR6 byte count, Align32, the bytes, then zero bytes to a multiple of 4. Must be the last operand.

Encodings 0, 6 and 7 are not defined.

BLOCKINFO block (ID 0)

BLOCKINFO holds information about other blocks, chiefly abbreviations that apply to every block with a given ID wherever it appears. Its records:

Code	Name	Operands	Meaning
`1`	`SETBID`	[blockid]	Selects the block ID that the following records and DEFINE_ABBREVs describe. Must come before the others.
`2`	`BLOCKNAME`	[name chars…]	A name for the block, for tools such as `llvm-bcanalyzer`. Optional.
`3`	`SETRECORDNAME`	[code, name chars…]	A name for one record code of the block. Optional.

A DEFINE_ABBREV inside BLOCKINFO does not define an abbreviation for BLOCKINFO itself: it adds one to the selected block ID.

Example

The bytes 42 43 C0 DE 35 14 00 00 05 00 00 00 62 0C 30 24 decoded with the rules above. (They were chosen to show how a file can begin; block ID 13 is the identification block and record code 1 its string record, from LLVM’s LLVMBitCodes.h.)

42 43 C0 DE    magic "BC" 0xC0DE
35             bits 0-1   01        abbrev ID 1 = ENTER_SUBBLOCK (width 2)
               bits 2-9   00001101  blockid VBR8 = 13 (IDENTIFICATION_BLOCK)
14             bits 10-13 0101      newabbrevlen VBR4 = 5
00 00          align to 32 bits
05 00 00 00    blocklen = 5 words
62             bits 0-4   00010     abbrev ID 2 = DEFINE_ABBREV (width 5)
               bits 5-9   00011     numabbrevops VBR5 = 3
0C             bit 10     1         literal
               bits 11-18 00000001  value VBR8 = 1 (the record code, IDENTIFICATION_CODE_STRING)
30             bit 19     0         encoded
               bits 20-22 011       encoding 3 = Array
               bit 23     0         encoded
24             bits 24-26 100       encoding 4 = Char6, the array's element type

So the block’s first abbreviation (ID 4) writes record code 1 with its characters as an array of 6-bit characters. Bit numbers count from the start of each 32-bit word (bytes 35 and 62 each begin one), bits are taken from the least significant end of each byte, and the binary is shown with the most significant bit on the left.

Sources

Everything on this page is from LLVM’s LLVM Bitcode File Format: “Bitstream Format” (magic, primitives, abbreviation IDs, blocks, data records, abbreviations, BLOCKINFO), “Bitcode Wrapper Format”, “Native Object File Wrapper Format” and “Signed VBRs”. The decoded example applies those rules; the block and record numbers in it are from llvm/include/llvm/Bitcode/LLVMBitCodes.h.

.BC File Format – Bitstream