Five small blocks give names to things: the value symbol table (block 14) names values
and basic blocks, the string table (23) holds the names of global values, the symbol table
(25) is a ready-made index of symbols for linkers, and the operand bundle tags (21) and
synchronisation scope names (26) are lists that other records refer to by position. The
record codes are on module blocks; this page gives
operands, offsets and the reader’s checks from BitcodeReader.cpp, the writer
from BitcodeWriter.cpp and the symbol table’s layout from
IRSymtab.h.
VALUE_SYMTAB (14)
| Code | Record | Operands | Where, and the reader’s checks |
|---|---|---|---|
1 | ENTRY | [value ID, name chars…] | In a function’s table, and in a module-level table of module version 1 or lower. Names the value (an argument, an instruction, or a global). The ID must be an existing value: Invalid record if it is outside the value list, refers to a value not yet defined, or if the name cannot be read; Invalid value name if the name contains a zero byte. |
2 | BBENTRY | [block number, name chars…] | In a function’s table. Names a basic block, counted from 0. A block number that does not exist, or an unreadable name: Invalid bbentry record. |
3 | FNENTRY | [value ID, offset, name chars…] | The position of a function body. With module version 2 the module-level table holds only [value ID, offset] records and no names; an ID that is not a defined value is Invalid value reference in symbol table (lines 3105–3144). In an older module the record carries the name too (lines 3229–3241; function offsets for aliases written by old LLVM are ignored). |
5 | COMBINED_ENTRY | [value ID, GUID] | In a combined summary index, read by the summary reader (ModuleSummaryIndexBitcodeReader::parseValueSymbolTable, lines 7614–7623): it ties a value ID to the 64-bit GUID of the symbol. The ordinary reader has no case for it. A per-module summary reader skips the table when the module uses a string table. |
Any other code in the block is ignored. A sub-block or a stream error is
Malformed block.
Function offsets
The module-level table is written after all the function blocks, and the module record
VSTOFFSET says where it starts.
Both numbers are words (4 bytes) counted from one word before the
IDENTIFICATION block, which is where a plain bitcode file’s magic number used to put the
start, so every offset is the real word offset plus 1. The writer stores
bit position / 32 + 1 (lines 3793 and 3818). The reader takes the value minus
1, multiplies by 32, and adds the width of the abbreviation ID plus the block ID width, so
that it lands on the start of the function block’s ENTER_SUBBLOCK record
(setDeferredFunctionInfo, lines 3088–3102). VSTOFFSET must point at a
VALUE_SYMTAB block, or the reader says Expected value symbol table subblock.
What the writer emits
- The module-level table has one abbreviated FNENTRY record (value ID and offset, both VBR8) for each function that has a body; nothing else.
- A function’s table has an ENTRY for every named argument and instruction and a BBENTRY for every named block, in the table’s own order, each with an abbreviation chosen by the name’s characters: Char6, 7-bit or 8-bit (lines 3827–3869). It is left out when nothing in the function has a name.
STRTAB (23)
One record, BLOB (code 1), whose single operand is a blob: all the names of
the module’s globals, functions, aliases, ifuncs, COMDATs and partitions, run together with
no separators and no terminators. A record refers to a name by offset and
size in bytes. The reader keeps the last BLOB record of the block (lines
8763–8799) and treats a reference that runs outside it as absent (lines 477–489).
- The block comes after the module, normally at the end of the file. It serves every module before it that has not got its own string table. A file made by joining bitcode files can hold several modules and several string tables (lines 8871–8891).
- The writer adds names in the order it writes them and finalises the table in that
order (
finalizeInOrder, line 5787), so the names are in record order. Names of the symbol table (below) are added to the same table. - A module of version 0 or 1 has no string table; its names are in the value symbol table.
SYMTAB (25)
One record, BLOB (code 1), whose blob is a symbol table in LLVM’s
irsymtab format (llvm/Object/IRSymtab.h), so that a linker can read
the symbols of a bitcode file without building a module. The writer puts the block before
the string table and builds the table with the string table builder, so every
Str in it points into the STRTAB block. The reader of a bitcode file keeps the first
symbol table only and expects the client to rebuild it if the number of modules does not
match (lines 8893–8908). A file is valid without it; the writer leaves it out when a module
has inline assembly and no assembly parser is available (writeSymtab, lines
5751–5781).
All fields are 32-bit little-endian words (ulittle32_t) unless said
otherwise. A Str is two words, [offset, size] into the string table. A
Range is two words, [byte offset into this blob, number of elements].
Header (19 words, 76 bytes)
| Word | Field | Meaning |
|---|---|---|
| 0 | Version | The format version; kCurrentVersion is 4. |
| 1–2 | Producer (Str) | The producer’s version string. A consumer should rebuild the table from IR when it differs from its own. |
| 3–4 | Modules (Range) | Array of Module. |
| 5–6 | Comdats (Range) | Array of Comdat. |
| 7–8 | Symbols (Range) | Array of Symbol. |
| 9–10 | Uncommons (Range) | Array of Uncommon. |
| 11–12 | TargetTriple (Str) | The target triple. |
| 13–14 | SourceFileName (Str) | The source file name. |
| 15–16 | COFFLinkerOpts (Str) | COFF-specific linker directives. |
| 17–18 | DependentLibraries (Range) | Array of Str: dependent library specifiers. |
Entries
| Entry | Size | Fields |
|---|---|---|
| Module | 12 bytes | Begin, End (indices of the module’s first symbol and the one after the last), UncBegin (the index of the first Uncommon of this module). |
| Comdat | 12 bytes | Name (Str), SelectionKind (the value of LLVM’s in-memory Comdat::SelectionKind, not the numbering of the MODULE record’s COMDAT kinds). |
| Symbol | 24 bytes | Name (Str, the mangled name), IRName (Str, the name in the IR, empty for a symbol that is not an IR global), ComdatIndex (into the Comdats array, or −1), Flags. |
| Uncommon | 28 bytes | CommonSize (a 64-bit little-endian number), CommonAlign (word), COFFWeakExternFallbackName (Str), SectionName (Str). |
Symbol flags
| Bits | Name | Meaning |
|---|---|---|
| 0–1 | visibility | 0 default, 1 hidden, 2 protected |
| 2 | has_uncommon | The symbol has an entry in the Uncommons array; the reader takes these entries in symbol order (SymbolRef::read, lines 323–340). |
| 3 | undefined | |
| 4 | weak | |
| 5 | common | CommonSize and CommonAlign are valid. |
| 6 | indirect | |
| 7 | used | |
| 8 | tls | |
| 9 | may_omit | The symbol can be left out of the symbol table (canBeOmittedFromSymbolTable). |
| 10 | global | |
| 11 | format_specific | |
| 12 | unnamed_addr | |
| 13 | executable |
How the writer sets the flags
irsymtab::build (IRSymtab.cpp, Builder::addSymbol)
makes one Symbol for each entry of the module’s ModuleSymbolTable: every global
value, in the module’s order, and then the symbols that the module’s inline assembly defines
or uses. It first asks ModuleSymbolTable::getSymbolFlags for the generic
symbol flags and copies seven of them, then sets the others from the global itself.
| Flag | Set when |
|---|---|
| undefined | The global is a declaration for the linker (isDeclarationForLinker: a declaration, or available-externally linkage); for an assembly symbol, one that is only declared global or only used, or a weak one never defined. |
| weak | Linkonce, weak or extern_weak linkage (linkonce, linkonce_odr, weak, weak_odr, extern_weak); an assembly symbol that is weak. |
| common | Common linkage. Only a variable may have it (the build fails with “Only variables can have common linkage!”), and then the symbol gets an Uncommon entry with the variable’s size in bytes (getGlobalSize) and its alignment (0 when it has none). |
| indirect | The global is an alias (GlobalAlias); an ifunc is not. |
| global | The linkage is not local (not internal and not private); an assembly symbol that is declared .globl. |
| format_specific | Private linkage, or a name that starts with llvm., or a variable in the section llvm.metadata. |
| executable | What the global ends up at (getAliaseeObject) is a function or an ifunc; every assembly symbol (the source says “for now we just assume that all asm symbols are executable”). |
| used | The global is in llvm.used or llvm.compiler.used (both lists count, so a linker keeps it); an assembly symbol that is only referenced and undefined. |
| tls | The global is thread-local (any model). |
| unnamed_addr | The global has unnamed_addr (not local_unnamed_addr). |
| may_omit | canBeOmittedFromSymbolTable (Globals.cpp): the linkage is linkonce_odr, and the global is unnamed_addr, or is not a non-constant variable (a function, alias or constant) and is at least local_unnamed_addr. |
| visibility (bits 0–1) | The global’s visibility, 0 default, 1 hidden, 2 protected. A symbol from assembly has 0. |
| has_uncommon | The symbol needed an Uncommon entry: it is common, or has a section (its object’s section name goes to SectionName), or on COFF it is a weak external alias (the fallback name goes to COFFWeakExternFallbackName). |
The Name is the mangled name (the target’s global prefix, and __imp_ in front
for a DLL-import global); the IRName is the name in the IR, empty for an assembly symbol.
The ComdatIndex is that of the comdat of the global, or, for an alias or ifunc, of the object it
resolves to (an alias whose target cannot be found fails with “Unable to determine comdat of alias!”);
on COFF a comdat whose leader has local linkage gets −1 and no entry, and a Comdat’s Name is
then the leader’s mangled name. Other building rules: the build fails when a module has no data
layout; on an ELF target the llvm.dependent-libraries strings become the
DependentLibraries; on COFF the llvm.linker.options strings and the linker flags of each
global are put in COFFLinkerOpts; for x86 ELF with a 32-bit target or a medium or large code model
the undefined, global assembly symbol _GLOBAL_OFFSET_TABLE_ is added.
A consumer rebuilds the table from the modules when its version or producer differs from its own,
when it has no string table, or when the number of modules in it differs from the file’s
(readBitcode).
The rules for the generic flags are those of ModuleSymbolTable.cpp
(getSymbolFlags, CollectAsmSymbols) and Globals.cpp, also read from the main branch on
2026-11-19. The asm-symbol rules come from the assembler’s symbol states, which the table above gives only in outline.
BLOCKINFO abbreviations (writeBlockInfo)
A module written by LLVM starts its module block with a BLOCKINFO block (ID 0) that defines
abbreviations for the three blocks that occur many times: the value symbol table, the
constants and the function block. Every other block (types, metadata, attributes) defines its
abbreviations inline. A reader needs none of this, because the stream always says what each abbreviation is; the table is
what ModuleBitcodeWriter::writeBlockInfo in BitcodeWriter.cpp emits.
Abbreviation IDs start at 4 in each block (the first application ID).
Type is Fixed(n) with n the number of bits needed for a type index of the module
(computeBitsRequiredForTypeIndices), Val is VBR6. A first operand written as a number is a literal record code.
| Block | ID | Abbreviation (operands) | Used for |
|---|---|---|---|
| VALUE_SYMTAB (14) | 4 | Fixed(3), VBR8, Array, Fixed(8) | an ENTRY or BBENTRY name with a character over 127 (the code is in the first operand) |
| 5 | 1 (ENTRY), VBR8, Array, Fixed(7) | an entry whose name is 7-bit | |
| 6 | 1 (ENTRY), VBR8, Array, Char6 | an entry whose name is all char6 characters | |
| 7 | 2 (BBENTRY), VBR8, Array, Char6 | a basic block whose name is all char6 | |
| CONSTANTS (11) | 4 | 1 (SETTYPE), Type | SETTYPE |
| 5 | 4 (INTEGER), VBR8 | INTEGER | |
| 6 | 35 (BYTE), VBR8 | BYTE (a recent record, as the byte type) | |
| 7 | 11 (CE_CAST), Fixed(4), Type, VBR8 | CE_CAST: opcode, type, value | |
| 8 | 2 (NULL) | NULL | |
| FUNCTION (12) | 4 | 20 (INST_LOAD), Val, Type, VBR4, Fixed(1) | LOAD: pointer, type, alignment, volatile |
| 5 | 44 (INST_STORE), Val, Val, VBR4, Fixed(1) | STORE: pointer, value, alignment, volatile | |
| 6 | 56 (INST_UNOP), Val, Fixed(4) | UNOP without flags | |
| 7 | 56 (INST_UNOP), Val, Fixed(4), Fixed(8) | UNOP with fast-math flags | |
| 8 | 2 (INST_BINOP), Val, Val, Fixed(4) | BINOP without flags | |
| 9 | 2 (INST_BINOP), Val, Val, Fixed(4), Fixed(8) | BINOP with flags | |
| 10 | 3 (INST_CAST), Val, Type, Fixed(4) | CAST without flags | |
| 11 | 3 (INST_CAST), Val, Type, Fixed(4), Fixed(9) | CAST with flags (nneg, nuw, nsw …) | |
| 12 | 10 (INST_RET) | ret void | |
| 13 | 10 (INST_RET), Val | ret with a value | |
| 14 | 11 (INST_BR), Val | unconditional br | |
| 15 | 11 (INST_BR), Val, Val, Val | conditional br: true block, false block, condition | |
| 16 | 15 (INST_UNREACHABLE) | unreachable | |
| 17 | 43 (INST_GEP), Fixed(3), Type, Array, Val | GEP: flags, source element type, operands | |
| 18 | 28 (INST_CMP2), Val, Val, Fixed(6) | CMP2 without flags | |
| 19 | 28 (INST_CMP2), Val, Val, Fixed(6), Fixed(8) | CMP2 with flags | |
| 20 | 64 (DEBUG_RECORD_VALUE_SIMPLE), VBR7, VBR7, VBR7, Val | #dbg_value with a value operand: location, variable, expression, value | |
| 21 | 35 (DEBUG_LOC), VBR6, VBR8, VBR6, VBR6, Fixed(1), VBR6, VBR3 | DEBUG_LOC: line, column, scope, inlined-at, implicit code, atom group, atom rank | |
| 22 | as 21, then VBR6 | DEBUG_LOC with an IR-layers operand (main branch only; the writer picks the abbreviation for each record, so a location without layers does not spend a chunk on a zero) |
The enumeration that gives the IDs (VST_ENTRY_8_ABBREV … FUNCTION_DEBUG_LOC_LAYERS_ABBREV)
is at the top of BitcodeWriter.cpp and is checked in each definition (an
llvm_unreachable if the ID that EmitBlockInfoAbbrev returns differs). LLVM 22 writes
the same table up to abbreviation 21 (debug-O1-linux.bc has it: DEBUG_LOC as abbreviation 21),
without the BYTE abbreviation and without 22; the IDs of the constants abbreviations after SETTYPE and
INTEGER therefore differ by one in a file from LLVM 22 (CE_CAST is 6, NULL 7) and the function block’s are the same.
Record-code numbers used above
The codes are those of LLVMBitCodes.h: VST ENTRY 1 and BBENTRY 2; CONSTANTS SETTYPE 1, NULL 2, INTEGER 4, CE_CAST 11, BYTE 35; FUNCTION
INST_BINOP 2, INST_CAST 3, INST_RET 10, INST_BR 11, INST_UNREACHABLE 15, INST_LOAD 20, INST_CMP2 28, DEBUG_LOC 35, INST_GEP 43,
INST_STORE 44, INST_UNOP 56, DEBUG_RECORD_VALUE_SIMPLE 64.
SYNC_SCOPE_NAMES (26)
| Code | Record | Operands | Meaning |
|---|---|---|---|
1 | SYNC_SCOPE_NAME | [chars…] | One synchronisation scope name. Its number is its position in the block, from 0. |
The sync scope operand of fence, atomic load, atomic store, compare-exchange
and read-modify-write records is a number. The two predefined scopes (single thread and
system) keep their own numbers; for any other number, the reader uses the name at that
position in this block and maps a number past the end to system
(getDecodedSyncScopeID, lines 7279–7285). A second block is Invalid
multiple synchronization scope names blocks; an empty block is Invalid empty
synchronization scope names block; another record code or an unreadable name is
Invalid sync scope record (lines 3004–3047). The writer leaves the block out
when the context has no names (lines 2932–2948).
Sources
- llvm/lib/Bitcode/Reader/BitcodeReader.cpp – lines 477–489, 2962–3047, 3072–3255, 7279–7285, 7538–7626, 8763–8920
- llvm/lib/Bitcode/Writer/BitcodeWriter.cpp – lines 2905–2948, 3782–3869, 5738–5800
- llvm/include/llvm/Object/IRSymtab.h – lines 47–161
- llvm/lib/Object/IRSymtab.cpp, ModuleSymbolTable.cpp and llvm/lib/IR/Globals.cpp – the flag rules (main branch, read 2026-11-19)
- BitcodeWriter.cpp
writeBlockInfo(main branch, 2026-11-19) – the BLOCKINFO abbreviations - llvm/include/llvm/Bitcode/LLVMBitCodes.h – lines 189–204, 850–856
- llvm/docs/BitCodeFormat.md – STRTAB_BLOCK Contents