Written by Reid Spencer and Chris Lattner

This document is an (after the fact) specification of the LLVM bytecode file format. It documents the binary encoding rules of the bytecode file format so that equivalent systems can encode bytecode files correctly. The LLVM bytecode representation is used to store the intermediate representation on disk in compacted form.

This section describes the general concepts of the bytecode file format without getting into bit and byte level specifics.

LLVM bytecode files consist simply of a sequence of blocks of bytes. Each block begins with an identification value that determines the type of the next block. The possible types of blocks are described below in the section Block Types. The block identifier is used because it is possible for entire blocks to be omitted from the file if they are empty. The block identifier helps the reader determine which kind of block is next in the file.

The following block identifiers are currently in use (from llvm/Bytecode/Format.h):

1. Module (0x01).
2. Function (0x11).
3. ConstantPool (0x12).
4. SymbolTable (0x13).
5. ModuleGlobalInfo (0x14).
6. GlobalTypePlane (0x15).
7. BasicBlock (0x31).
8. InstructionList (0x32).
9. CompactionTable (0x33).

Except for the Header Block all blocks are variable length. They consume just enough bytes to express their contents.

Most blocks are constructed of lists of information. Lists can be constructed of other lists, etc. This decomposition of information follows the containment hierarchy of the LLVM Intermediate Representation. For example, a function is composed of a list of basic blocks. Each basic block is composed of a set of instructions. This list of list nesting and hierarchy is maintained in the bytecode file.

A list is encoded into the file simply by encoding the number of entries as an integer followed by each of the entries. The reader knows when the list is done because it will have filled the list with the required numbe of entries.

Fields are units of information that LLVM knows how to write atomically. Most fields have a uniform length or some kind of length indication built into their encoding. For example, a constant string (array of SByte or UByte) is written simply as the length followed by the characters. Although this is similar to a list, constant strings are treated atomically and are thus fields.

Fields use a condensed bit format specific to the type of information they must contain. As few bits as possible are written for each field. The sections that follow will provide the details on how these fields are written and how the bits are to be interpreted.

To support cross-platform differences, the bytecode file is aligned on certain boundaries. This means that a small amount of padding (at most 3 bytes) will be added to ensure that the next entry is aligned to a 32-bit boundary.

This section provides the detailed layout of the LLVM bytecode file format. bit and byte level specifics.

The descriptions of the bytecode format that follow describe the bit fields in detail. These descriptions are provided in tabular form. Each table has four columns that specify:

1. Byte(s). The offset in bytes of the field from the start of its container (block, list, other field).
3. Bit(s). The offset in bits of the field from the start of the byte field. Bits are always little endian. That is, bit addresses with smaller values have smaller address (i.e. 2^0 is at bit 0, 2^1 at 1, etc.)
4. Align? Indicates if this field is aligned to 32 bits or not. This indicates where the next field starts, always on a 32 bit boundary.
5. Type. The basic type of information contained in the field.
6. Description. Descripts the contents of the field.

The bytecode format encodes the intermediate representation into groups of bytes known as blocks. The blocks are written sequentially to the file in the following order:

1. Header. This block contains the file signature (magic number), machine description and file format version (not LLVM version).
2. Global Type Pool. This block contains all the global (module) level types.
3. Module Info. This block contains the types of the global variables and functions in the module as well as the constant initializers for the global variables
4. Constants. This block contains all the global constants except function arguments, global values and constant strings.
5. Functions. One function block is written for each function in the module.
6. Symbol Table. The module level symbol table that provides names for the various other entries in the file is the final block written.

The Header Block occurs in every LLVM bytecode file and is always first. It simply provides a few bytes of data to identify the file, its format, and the bytecode version. This block is fixed length and always eight bytes, as follows:

The module symbol table is a list of