path: root/docs/BitCodeFormat.rst

.. _bitcode_format:

.. role:: raw-html(raw)
   :format: html

========================
LLVM Bitcode File Format
========================

.. contents::
   :local:

Abstract
========

This document describes the LLVM bitstream file format and the encoding of the
LLVM IR into it.

Overview
========

What is commonly known as the LLVM bitcode file format (also, sometimes
anachronistically known as bytecode) is actually two things: a `bitstream
container format`_ and an `encoding of LLVM IR`_ into the container format.

The bitstream format is an abstract encoding of structured data, very similar to
XML in some ways.  Like XML, bitstream files contain tags, and nested
structures, and you can parse the file without having to understand the tags.
Unlike XML, the bitstream format is a binary encoding, and unlike XML it
provides a mechanism for the file to self-describe "abbreviations", which are
effectively size optimizations for the content.

LLVM IR files may be optionally embedded into a `wrapper`_ structure that makes
it easy to embed extra data along with LLVM IR files.

This document first describes the LLVM bitstream format, describes the wrapper
format, then describes the record structure used by LLVM IR files.

.. _bitstream container format:

Bitstream Format
================

The bitstream format is literally a stream of bits, with a very simple
structure.  This structure consists of the following concepts:

* A "`magic number`_" that identifies the contents of the stream.

* Encoding `primitives`_ like variable bit-rate integers.

* `Blocks`_, which define nested content.

* `Data Records`_, which describe entities within the file.

* Abbreviations, which specify compression optimizations for the file.

Note that the `llvm-bcanalyzer <CommandGuide/html/llvm-bcanalyzer.html>`_ tool
can be used to dump and inspect arbitrary bitstreams, which is very useful for
understanding the encoding.

.. _magic number:

Magic Numbers
-------------

The first two bytes of a bitcode file are 'BC' (``0x42``, ``0x43``).  The second
two bytes are an application-specific magic number.  Generic bitcode tools can
look at only the first two bytes to verify the file is bitcode, while
application-specific programs will want to look at all four.

.. _primitives:

Primitives
----------

A bitstream literally consists of a stream of bits, which are read in order
starting with the least significant bit of each byte.  The stream is made up of
a number of primitive values that encode a stream of unsigned integer values.
These integers are encoded in two ways: either as `Fixed Width Integers`_ or as
`Variable Width Integers`_.

.. _Fixed Width Integers:
.. _fixed-width value:

Fixed Width Integers
^^^^^^^^^^^^^^^^^^^^

Fixed-width integer values have their low bits emitted directly to the file.
For example, a 3-bit integer value encodes 1 as 001.  Fixed width integers are
used when there are a well-known number of options for a field.  For example,
boolean values are usually encoded with a 1-bit wide integer.

.. _Variable Width Integers:
.. _Variable Width Integer:
.. _variable-width value:

Variable Width Integers
^^^^^^^^^^^^^^^^^^^^^^^

Variable-width integer (VBR) values encode values of arbitrary size, optimizing
for the case where the values are small.  Given a 4-bit VBR field, any 3-bit
value (0 through 7) is encoded directly, with the high bit set to zero.  Values
larger than N-1 bits emit their bits in a series of N-1 bit chunks, where all
but the last set the high bit.

For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a vbr4
value.  The first set of four bits indicates the value 3 (011) with a
continuation piece (indicated by a high bit of 1).  The next word indicates a
value of 24 (011 << 3) with no continuation.  The sum (3+24) yields the value
27.

.. _char6-encoded value:

6-bit characters
^^^^^^^^^^^^^^^^

6-bit characters encode common characters into a fixed 6-bit field.  They
represent the following characters with the following 6-bit values:

::

  'a' .. 'z' ---  0 .. 25
  'A' .. 'Z' --- 26 .. 51
  '0' .. '9' --- 52 .. 61
         '.' --- 62
         '_' --- 63

This encoding is only suitable for encoding characters and strings that consist
only of the above characters.  It is completely incapable of encoding characters
not in the set.

Word Alignment
^^^^^^^^^^^^^^

Occasionally, it is useful to emit zero bits until the bitstream is a multiple
of 32 bits.  This ensures that the bit position in the stream can be represented
as a multiple of 32-bit words.

Abbreviation IDs
----------------

A bitstream is a sequential series of `Blocks`_ and `Data Records`_.  Both of
these start with an abbreviation ID encoded as a fixed-bitwidth field.  The
width is specified by the current block, as described below.  The value of the
abbreviation ID specifies either a builtin ID (which have special meanings,
defined below) or one of the abbreviation IDs defined for the current block by
the stream itself.

The set of builtin abbrev IDs is:

* 0 - `END_BLOCK`_ --- This abbrev ID marks the end of the current block.

* 1 - `ENTER_SUBBLOCK`_ --- This abbrev ID marks the beginning of a new
  block.

* 2 - `DEFINE_ABBREV`_ --- This defines a new abbreviation.

* 3 - `UNABBREV_RECORD`_ --- This ID specifies the definition of an
  unabbreviated record.

Abbreviation IDs 4 and above are defined by the stream itself, and specify an
`abbreviated record encoding`_.

.. _Blocks:

Blocks
------

Blocks in a bitstream denote nested regions of the stream, and are identified by
a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
function bodies).  Block IDs 0-7 are reserved for `standard blocks`_ whose
meaning is defined by Bitcode; block IDs 8 and greater are application
specific. Nested blocks capture the hierarchical structure of the data encoded
in it, and various properties are associated with blocks as the file is parsed.
Block definitions allow the reader to efficiently skip blocks in constant time
if the reader wants a summary of blocks, or if it wants to efficiently skip data
it does not understand.  The LLVM IR reader uses this mechanism to skip function
bodies, lazily reading them on demand.

When reading and encoding the stream, several properties are maintained for the
block.  In particular, each block maintains:

#. A current abbrev id width.  This value starts at 2 at the beginning of the
   stream, and is set every time a block record is entered.  The block entry
   specifies the abbrev id width for the body of the block.

#. A set of abbreviations.  Abbreviations may be defined within a block, in
   which case they are only defined in that block (neither subblocks nor
   enclosing blocks see the abbreviation).  Abbreviations can also be defined
   inside a `BLOCKINFO`_ block, in which case they are defined in all blocks
   that match the ID that the ``BLOCKINFO`` block is describing.

As sub blocks are entered, these properties are saved and the new sub-block has
its own set of abbreviations, and its own abbrev id width.  When a sub-block is
popped, the saved values are restored.

.. _ENTER_SUBBLOCK:

ENTER_SUBBLOCK Encoding
^^^^^^^^^^^^^^^^^^^^^^^

:raw-html:`<tt>`
[ENTER_SUBBLOCK, blockid\ :sub:`vbr8`, newabbrevlen\ :sub:`vbr4`, <align32bits>, blocklen_32]
:raw-html:`</tt>`

The ``ENTER_SUBBLOCK`` abbreviation ID specifies the start of a new block
record.  The ``blockid`` value is encoded as an 8-bit VBR identifier, and
indicates the type of block being entered, which can be a `standard block`_ or
an application-specific block.  The ``newabbrevlen`` value is a 4-bit VBR, which
specifies the abbrev id width for the sub-block.  The ``blocklen`` value is a
32-bit aligned value that specifies the size of the subblock in 32-bit
words. This value allows the reader to skip over the entire block in one jump.

.. _END_BLOCK:

END_BLOCK Encoding
^^^^^^^^^^^^^^^^^^

``[END_BLOCK, <align32bits>]``

The ``END_BLOCK`` abbreviation ID specifies the end of the current block record.
Its end is aligned to 32-bits to ensure that the size of the block is an even
multiple of 32-bits.

.. _Data Records:

Data Records
------------

Data records consist of a record code and a number of (up to) 64-bit integer
values.  The interpretation of the code and values is application specific and
may vary between different block types.  Records can be encoded either using an
unabbrev record, or with an abbreviation.  In the LLVM IR format, for example,
there is a record which encodes the target triple of a module.  The code is
``MODULE_CODE_TRIPLE``, and the values of the record are the ASCII codes for the
characters in the string.

.. _UNABBREV_RECORD:

UNABBREV_RECORD Encoding
^^^^^^^^^^^^^^^^^^^^^^^^

:raw-html:`<tt>`
[UNABBREV_RECORD, code\ :sub:`vbr6`, numops\ :sub:`vbr6`, op0\ :sub:`vbr6`, op1\ :sub:`vbr6`, ...]
:raw-html:`</tt>`

An ``UNABBREV_RECORD`` provides a default fallback encoding, which is both
completely general and extremely inefficient.  It can describe an arbitrary
record by emitting the code and operands as VBRs.

For example, emitting an LLVM IR target triple as an unabbreviated record
requires emitting the ``UNABBREV_RECORD`` abbrevid, a vbr6 for the
``MODULE_CODE_TRIPLE`` code, a vbr6 for the length of the string, which is equal
to the number of operands, and a vbr6 for each character.  Because there are no
letters with values less than 32, each letter would need to be emitted as at
least a two-part VBR, which means that each letter would require at least 12
bits.  This is not an efficient encoding, but it is fully general.

.. _abbreviated record encoding:

Abbreviated Record Encoding
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``[<abbrevid>, fields...]``

An abbreviated record is a abbreviation id followed by a set of fields that are
encoded according to the `abbreviation definition`_.  This allows records to be
encoded significantly more densely than records encoded with the
`UNABBREV_RECORD`_ type, and allows the abbreviation types to be specified in
the stream itself, which allows the files to be completely self describing.  The
actual encoding of abbreviations is defined below.

The record code, which is the first field of an abbreviated record, may be
encoded in the abbreviation definition (as a literal operand) or supplied in the
abbreviated record (as a Fixed or VBR operand value).

.. _abbreviation definition:

Abbreviations
-------------

Abbreviations are an important form of compression for bitstreams.  The idea is
to specify a dense encoding for a class of records once, then use that encoding
to emit many records.  It takes space to emit the encoding into the file, but
the space is recouped (hopefully plus some) when the records that use it are
emitted.

Abbreviations can be determined dynamically per client, per file. Because the
abbreviations are stored in the bitstream itself, different streams of the same
format can contain different sets of abbreviations according to the needs of the
specific stream.  As a concrete example, LLVM IR files usually emit an
abbreviation for binary operators.  If a specific LLVM module contained no or
few binary operators, the abbreviation does not need to be emitted.

.. _DEFINE_ABBREV:

DEFINE_ABBREV Encoding
^^^^^^^^^^^^^^^^^^^^^^

:raw-html:`<tt>`
[DEFINE_ABBREV, numabbrevops\ :sub:`vbr5`, abbrevop0, abbrevop1, ...]
:raw-html:`</tt>`

A ``DEFINE_ABBREV`` record adds an abbreviation to the list of currently defined
abbreviations in the scope of this block.  This definition only exists inside
this immediate block --- it is not visible in subblocks or enclosing blocks.
Abbreviations are implicitly assigned IDs sequentially starting from 4 (the
first application-defined abbreviation ID).  Any abbreviations defined in a
``BLOCKINFO`` record for the particular block type receive IDs first, in order,
followed by any abbreviations defined within the block itself.  Abbreviated data
records reference this ID to indicate what abbreviation they are invoking.

An abbreviation definition consists of the ``DEFINE_ABBREV`` abbrevid followed
by a VBR that specifies the number of abbrev operands, then the abbrev operands
themselves.  Abbreviation operands come in three forms.  They all start with a
single bit that indicates whether the abbrev operand is a literal operand (when
the bit is 1) or an encoding operand (when the bit is 0).

#. Literal operands --- :raw-html:`<tt>` [1\ :sub:`1`, litvalue\
   :sub:`vbr8`] :raw-html:`</tt>` --- Literal operands specify that the value in
   the result is always a single specific value.  This specific value is emitted
   as a vbr8 after the bit indicating that it is a literal operand.

#. Encoding info without data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
   :sub:`3`] :raw-html:`</tt>` --- Operand encodings that do not have extra data
   are just emitted as their code.

#. Encoding info with data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
   :sub:`3`, value\ :sub:`vbr5`] :raw-html:`</tt>` --- Operand encodings that do
   have extra data are emitted as their code, followed by the extra data.

The possible operand encodings are:

* Fixed (code 1): The field should be emitted as a `fixed-width value`_, whose
  width is specified by the operand's extra data.

* VBR (code 2): The field should be emitted as a `variable-width value`_, whose
  width is specified by the operand's extra data.

* Array (code 3): This field is an array of values.  The array operand has no
  extra data, but expects another operand to follow it, indicating the element
  type of the array.  When reading an array in an abbreviated record, the first
  integer is a vbr6 that indicates the array length, followed by the encoded
  elements of the array.  An array may only occur as the last operand of an
  abbreviation (except for the one final operand that gives the array's
  type).

* Char6 (code 4): This field should be emitted as a `char6-encoded value`_.
  This operand type takes no extra data. Char6 encoding is normally used as an
  array element type.

* Blob (code 5): This field is emitted as a vbr6, followed by padding to a
  32-bit boundary (for alignment) and an array of 8-bit objects.  The array of
  bytes is further followed by tail padding to ensure that its total length is a
  multiple of 4 bytes.  This makes it very efficient for the reader to decode
  the data without having to make a copy of it: it can use a pointer to the data
  in the mapped in file and poke directly at it.  A blob may only occur as the
  last operand of an abbreviation.

For example, target triples in LLVM modules are encoded as a record of the form
``[TRIPLE, 'a', 'b', 'c', 'd']``.  Consider if the bitstream emitted the
following abbrev entry:

::

  [0, Fixed, 4]
  [0, Array]
  [0, Char6]

When emitting a record with this abbreviation, the above entry would be emitted
as:

:raw-html:`<tt><blockquote>`
[4\ :sub:`abbrevwidth`, 2\ :sub:`4`, 4\ :sub:`vbr6`, 0\ :sub:`6`, 1\ :sub:`6`, 2\ :sub:`6`, 3\ :sub:`6`]
:raw-html:`</blockquote></tt>`

These values are:

#. The first value, 4, is the abbreviation ID for this abbreviation.

#. The second value, 2, is the record code for ``TRIPLE`` records within LLVM IR
   file ``MODULE_BLOCK`` blocks.

#. The third value, 4, is the length of the array.

#. The rest of the values are the char6 encoded values for ``"abcd"``.

With this abbreviation, the triple is emitted with only 37 bits (assuming a
abbrev id width of 3).  Without the abbreviation, significantly more space would
be required to emit the target triple.  Also, because the ``TRIPLE`` value is
not emitted as a literal in the abbreviation, the abbreviation can also be used
for any other string value.

.. _standard blocks:
.. _standard block:

Standard Blocks