Initial draft of PNaCl bitcode files.

native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst

Index: native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
diff --git a/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst b/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3fafe15960d135cb694a55f424bb6fd1f084926e
--- /dev/null
+++ b/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
@@ -0,0 +1,6091 @@
+===============================
+Contents Of PNaCl Bitcode Files
+===============================
+
+.. contents::
+   :local:
+   :backlinks: none
+   :depth: 3
+
+
+Introduction
+============
+
+This document is a reference manual for the contents of PNaCl bitcode files. We
+define bitcode files via three layers. The first layer is presented using
+assembly language *PNaClAsm*, and defines the textual form of the bitcode
+file. The textual form is then lowered to a sequence of :ref:`PNaCl
+records<link_for_pnacl_records>`. The final layer applies abbreviations that
+convert each PNaCl record into a corresponding sequence of bits.
+
+.. image:: /images/PNaClBitcodeFlow.png
+
+PNaClAsm uses a *static single assignment* (SSA) based representation that
+requires generated results to have a single (assignment) source.
+
+PNaClAsm focuses on the semantic content of the file, not the bit-encoding of
+that content. However, it does provide annotations that allow one to specify how
+the :ref:`abbreviations<link_for_abbreviations_section>` are used to convert
+PNaCl records into the sequence of bits.
+
+Each construct in PNaClAsm defines a corresponding :ref:`PNaCl
+record<link_for_pnacl_records>`.  A PNaCl bitcode file is simply a sequence of
+PNaCl records. The goal of PNaClAsm is to make records easier to read, and not
+to define a high-level user programming language.
+
+PNaCl records are an abstract encoding of structured data, similar to XML. Like
+XML, A PNaCl record has a notion of a tag (i.e. the first element in a record,
+called a *code*). PNaCl records can be nested. Nesting is defined by a
+corresponding :ref:`enter<link_for_enter_block_record_section>` and
+:ref:`exit<link_for_exit_block_record_section>` block record.
+
+These block records must be used like balanced parentheses to define the block
+structure that is imposed on top of records. Each exit record must be preceded
+by a corresponding enter record. Blocks can be nested by nesting enter/exit
+records appropriately.
+
+The *PNaCl bitcode writer* takes the sequence of records, defined by a PNaClAsm
+program, and converts each record into a (variable-length) sequence of bits. The
+output of each bit sequence is appended together. The resulting generated
+sequence of bits is the contents of the PNaCl bitcode file.
+
+For every kind of record, there is a method for converting records into bit
+sequences. These methods correspond to a notion of
+:ref:`abbreviations<link_for_abbreviations_section>`.  Each abbreviation defines
+a specific bit sequence conversion to be applied.
+
+Abbreviations can be user defined, but there are also predefined defaults.  All
+user-specified abbreviations are included in the generated bitcode
+file. Predefined defaults are not.
+
+Each abbreviation defines how a record is converted to a bit sequence. The
+:ref:`PNaCl translator<link_for_pnacl_translator>` uses these abbreviations
+to convert the bit sequence back to the corresponding sequence of PNaCl records.
+As a result, all records have an abbreviation (user or default) associated with
+them.
+
+Conceptually, abbreviations are used to define how to pack the contents of
+records into bit sequences.  The main reason for defining abbreviations is to
+save space. The default abbreviations are simplistic and are intended to handle
+all possible records. The default abbreviations do not really worry about being
+efficient, in terms of the number of bits generated.
+
+By separating the concepts of PNaCl records and abbreviations, the notion of
+data compression is cleanly separated from semantic content. This allows
+different use cases to decide how much effort should be spent on compressing
+records.
+
+For a JIT compiler that produces bitcode, little (if any) compression should be
+applied. In fact, the API to the JIT may just be the records themselves.  The
+goal of a JIT is to perform the final translation to machine code as quickly as
+possible.
+
+On the other hand, when delivering across the web, one may want to compress the
+sequence of bits considerably, to reduce costs in delivering web pages. Note
+that :ref:`pnacl-compress<pnacl_compress>` is provided as part of the SDK to do
+this job.
+
+Data Model
+==========
+
+The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are
+32 bits in size. 64-bit integer types are also supported natively via the i64
+type (for example, a front-end can generate these from the C/C++ type ``long
+long``).
+
+Integers are assumed to be modeled using two's complement.  Floating point
+support is fixed at :ref:`IEEE 754<c_cpp_floating_point>` 32-bit and 64-bit
+values (float and double, respectively).
+
+PNaCl Blocks
+============
+
+Blocks are used to organize records in the bitcode file.  The kinds of blocks
+defined in PNaClAsm are:
+
+Module block
+  A top-level block defining the program. The :ref:`module
+  block<link_for_module_block>` defines global information used by the program,
+  followed by function blocks defining the implementation of functions within
+  the program. All other blocks (listed below) must appear within a module
+  block.
+
+Types block
+  The :ref:`types block<link_for_types_block_section>` defines the set of types
+  used by the program. All types used in the program must be defined in the
+  types block.  These types consist of primitive types as well as high level
+  constructs such as vectors and function signatures.
+
+Globals block
+  The :ref:`globals block<link_for_globals_block_section>` defines the set of
+  global addresses of global variables and constants used by the program. It

[Jim Stichnoth, 2014/11/18 02:24:42]

"global addresses of global variables" - is the first "global" supposed to be
there?

[Karl, 2014/11/19 20:28:53]

Yes. All global variables and addresses must appear in this block. However, this
doesn't appear to be the right place to bring this up. This is a high-level
overview. Details should be further down.

[Jim Stichnoth, 2014/11/19 21:12:00]

Per our offline discussion, I think we both agree this should read "the set of
addresses of global variables".

+  also defines how each global (associated with the global address) is
+  initialized.
+
+Valuesymtab block
+  The :ref:`valuesymtab block<link_for_valuesymtab_block_section>` defines
+  textual names for external function addresses.
+
+Function block
+  Each function (implemented) in a program has its own :ref:`function
+  block<link_for_function_blocks_section>` that defines the implementation of
+  the corresponding function.
+
+Constants block
+  Each implemented function that uses constants in its instructions defines a
+  :ref:`constants block<link_for_constants_block_section>`. Constants blocks
+  appear within the corresponding function block of the implemented function.
+
+Abbreviations block
+  Defines global abbreviations that are used to compress PNaCl records. The
+  :ref:`abbreviations block<link_for_abbreviations_block_section>` is segmented
+  into multiple sections, one section for each kind of block. This block appears
+  at the beginning of the module block.
+
+This section is only intended as a high-level discussion of blocks. Later
+sections will dive more deeply into the constraints on how blocks must be laid
+out. This section only presents the overall concepts of what kinds of data are
+stored in each of the blocks.
+
+A PNaCl program consists of a :ref:`header
+record<link_for_header_record_section>` and a :ref:`module
+block<link_for_module_block>`. The header record defines a sequence of bytes
+uniquely identifying the file as a bitcode file. The module block defines the
+program to run.
+
+Each block, within a bitcode file, defines values. These values are associated
+with IDs. Each type of block defines different kinds of IDs.  The
+:ref:`module<link_for_module_block>`,
+:ref:`types<link_for_types_block_section>`,
+:ref:`globals<link_for_globals_block_section>`, and
+:ref:`abbreviations<link_for_abbreviations_block_section>` blocks define global
+identifiers, and only a single instance can appear.  The
+:ref:`function<link_for_function_blocks_section>` and
+:ref:`constant<link_for_constants_block_section>` blocks define local
+identifiers, and can have multiple instances (one for each implemented
+function).
+
+The only records in the module block that define values, are :ref:`function
+address<link_for_function_address_section>` records.  Each function address
+record defines a different function address, and the :ref:`type
+signature<link_for_function_type>` associated with that function address.
+
+Each :ref:`function block<link_for_function_blocks_section>` defines the
+implementation of a single function. Each function block defines the
+intermediate representation of the function, consisting of basic blocks and
+instructions. If constants are used within instructions, they are defined in a
+:ref:`constants block<link_for_constants_block_section>`, nested within the
+corresponding function block.
+
+All function blocks are associated with a corresponding function address. This
+association is positional rather than explicit. That is, the Nth function block
+in a module block corresponds to the Nth
+:ref:`defining<link_for_function_address_section>` (rather than declared)
+function address record in the module block.
+
+Hence, within a function block, there is no explicit reference to the function
+address the block defines. For readability, PNaClAsm uses the corresponding
+function signature, associated with the corresponding function address record,
+even though that data does not appear in the corresponding records.
+
+.. _link_for_pnacl_records:
+
+PNaCl Records
+=============
+
+A PNaCl record is a non-empty sequence of unsigned, 64-bit, integers. A record
+is identified by the record *code*, which is the first element in the
+sequence. Record codes are unique within a specific kind of block, but are not
+necessarily unique across different kinds of blocks. The record code acts as the
+variant discriminator (i.e. tag) within a block, to identify what kind of record
+it is.
+
+Record codes that are local to a specific kind of block are small values
+(starting from zero). In an ideal world, they would be a consecutive sequence of
+integers, starting at zero. However, the reality is that PNaCl records evolved
+over time (and actually started as `LLVM records
+<http://llvm.org/docs/BitCodeFormat.html>`_).  For backward compatibility,
+obsolete numbers have not been reused, leaving gaps in the actual record code
+values used.
+
+Global record codes are record codes that have the same meaning in multiple
+kinds of blocks. To separate global record codes from local record codes, large
+values are used.  Currently there are four :ref:`global record
+codes<link_for_global_record_codes>`.  To make these cases clear, and to leave
+ample room for future growth in PNaClAsm, these special records have record
+codes close to the value 2\ :sup:`16`\ . Note: Well-formed PNaCl bitcode files
+do not have record codes >= 2\ :sup:`16`\ .
+ 
+A PNaCl record is denoted as follows: ::
+
+  a: <v0, v1, ... , vN>
+
+The value ``v0`` is the record code. The remaining values, ``v1`` through
+``vN``, are parameters that fill in additional information needed by the
+construct it represents. All records must have a record code. Hence, empty PNaCl
+records are not allowed. ``a`` is the index to the abbreviation used to convert
+the record to a bit sequence.
+
+While most records (for a given record code) have the same length, it is not
+true of all record codes. Some record codes can have arbitrary length. In
+particular, function type signatures, call instructions, phi nodes, switch

[Jim Stichnoth, 2014/11/18 02:24:42]

phi instructions? (instead of nodes)

[Karl, 2014/11/19 20:28:53]

Done.

+instructions, and global variable initialization records all have variable
+length. The expected length is predefined and part of the PNaClAsm language. See
+the corresponding construct (associated with the record) to determine the
+expected length.
+
+The ``PNaCl bitstream writer``, which converts records to bit sequences, does

[Jim Stichnoth, 2014/11/18 02:24:43]

The `` `` formatting doesn't look right in the html file.  Should it be *...* ?

[Karl, 2014/11/19 20:28:53]

Done.

+this by writing out the abbreviation index used to encode the record, followed
+by the contents of the record. The details of this are left to the section on
+:ref:`abbreviations<link_for_abbreviations_section>`. However, at the record
+level, one important aspect of this appears in ::ref:`block

[Jim Stichnoth, 2014/11/18 02:24:42]

::ref: ==> :ref:

[Karl, 2014/11/19 20:28:52]

Done.

+enter<link_for_enter_block_record_section>` records.  These records must define
+how many bits are required to hold abbreviation indices associated with records
+of that block.
+
+.. _link_for_default_abbreviations:
+
+Default Abbreviations
+=====================
+
+There are 4 predefined (default) abbreviation indices, used as the default
+abbreviations for PNaCl records. They are:
+
+0
+  Abbreviation index for the abbreviation used to bit-encode an exit block
+  record.
+
+1
+  Abbreviation index for the abbreviation used to bit-encode an enter block
+  record.
+
+2
+  Abbreviation index for the abbreviation used to bit-encode a user-defined
+  abbreviation. Note: User defined abbreviations are also encoded as records,

[Jim Stichnoth, 2014/11/18 02:24:42]

"User defined" ==> "User-defined"

[Karl, 2014/11/19 20:28:52]

Done.

+  and hence need an abbreviation index to bit-encode them.
+
+3
+  Abbreviation index for the default abbreviation to bit-encode all other
+  records in the bitcode file.
+
+A block may, in addition, define a list of block specific, user-defined,
+abbreviations (of length ``U``). The number of bits ``B`` specified for an enter
+record must be sufficiently large such that::
+
+   2**B >= U + 4
+
+In addition, the upper limit for ``B`` is ``16``.
+
+PNaClAsm requires specifying the number of bits needed to read abbreviations as
+part of the enter block record. This allows the PNaCl bitcode reader/writer to
+use the specified number of bits to encode abbreviation indices.
+
+PNaCl Identifiers
+=================
+
+A program is defined by a :ref:`module block<link_for_module_block>`. Blocks can
+be nested within other blocks, including the module block. Each block defines a
+sequence of records.
+
+Most of the records, within a block, also define unique values.  Each unique
+value is given a corresponding unique identifier (i.e. *ID*). In PNaClAsm, each
+kind of block defines its own kind of identifiers. The names of these
+identifiers are defined by concatenating a prefix character (``'@'`` or
+``'%'``), the kind of block (a single character), and a suffix index. The suffix
+index is defined by the positional location of the defined value within the
+records of the corresponding block. The indices are all zero based, meaning that
+the first defined value (within a block) is defined using index 0.
+
+Identifiers are categorized into two types, *local* and *global*.  Local
+identifiers are identifiers that are associated with the implementation of a
+single function. In that sense, they are local to the block they appear in.
+
+All other identifiers are global, and can appear in multiple blocks. This split
+is intentional. Global identifiers are used by multiple functions, and therefore
+must be known in all function implementations. Local identifiers only apply to a
+single function, and can be reused between functions.  The :ref:`PNaCl
+translator<link_for_pnacl_translator>` uses this separation to parallelize the
+compilation of functions.
+
+Note that local abbreviation identifiers are unique to the block they appear
+in. Global abbreviation identifiers are only unique to the block type they are
+defined for. Different block types can reuse global abbreviation identifiers.
+
+Global identifiers use the prefix character ``'@'`` while local identifiers use
+the prefix character ``'%'``.
+
+Note that by using positional location to define identifiers (within a block),
+the values defined in PNaCl bitcode files need not be explicitly included in the
+bitcode file. Rather, they are inferred by the (ordered) position of the record
+in the block.  This is also intentional. It is used to reduce the amount of data
+that must be (explicitly) passed to the :ref:`PNaCl
+translator<link_for_pnacl_translator>`, and downloaded from the cloud.

[Jim Stichnoth, 2014/11/18 02:24:42]

"the cloud"? yuck...

[Karl, 2014/11/19 20:28:52]

How about simply "when downloaded into Chrome".

+
+In general, most of the records within blocks are assumed to be topologically
+sorted, putting value definitions before their uses.  This implies that records
+do not need to encode data if they can deduce the corresponding information from
+their uses.
+
+The most common use of this is that many instructions use the type of their
+operands to determine the type of the instruction. Again, this is
+intentional. It allows less information to be stored.
+
+However, for function blocks (which define instructions), a topological sort may
+not exist. Loop carried value dependencies simply do not allow topologically
+sorting. To deal with this, function blocks have a notion of (instruction value)
+:ref:`forward type
+declarations<link_for_forward_type_declaration_section>`. These declarations
+must appear before any of the uses of that value, if the (instruction) value is
+defined later in the function than its first use.
+
+The kinds of identifiers used in PNaClAsm are:
+
+@a
+  Global abbreviation identifier.
+
+%a
+  Local abbreviation identifier.
+
+%b
+  Function basic block identifier.
+
+%c
+  Function constant identifier.
+
+@f
+  Global function address identifier.
+
+@g
+  Global variable/constant address identifier.
+
+%p
+  Function parameter identifier.
+
+@t
+  Global type identifier.
+
+%v
+  Value generated by an instruction in a function block.
+
+
+Conventions For Describing Records
+==================================
+
+PNaClAsm is the textual representation of :ref:`PNaCl
+records<link_for_pnacl_records>`.  Each PNaCl record is described by a
+corresponding PNaClAsm construct. These constructs are described using syntax
+rules, and semantics on how they are converted to records. Along with the rules,
+is a notion of :ref:`global state<link_for_global_state_section>`. The global
+state is updated by syntax rules.  The purpose of the global state is to track
+positional dependencies between records.
+
+For each PNaCl construct, we define multiple subsections. The **Syntax**
+subsection defines a syntax rule for the construct. The **Record** subsection

[Jim Stichnoth, 2014/11/18 02:24:42]

I think most instances of "subsection" can be changed to "section", because the
word subsection is a bit clumsy and section nesting levels are probably hard to
discern in the formatted online docs.

[Karl, 2014/11/19 20:28:52]

Done.

+defines the corresponding record associated with the syntax rule. The
+**Semantics** subsection describes the semantics associated with the record, in
+terms of data within the global state and the corresponding syntax. It also
+includes other high-level semantics, when appropriate.
+
+The **Constraints** subsection (if present) defines any constraints associated
+with the construct, including the global state. The **Updates** subsection (if
+present) defines how the global state is updated when the construct is
+processed.  The **Examples** subsection gives one or more examples of using the
+corresponding PNaClAsm construct.
+
+Some semantics subsections use functions to compute values. The meaning of
+functions can be found in :ref:`support
+functions<link_for_support_functions_section>`.
+
+The syntax rule may include the
+:ref:`abbreviation<link_for_abbreviations_section>` to use, when converting to a
+bit-sequence.  These abbreviations, if allowed, are at the end of the construct,
+and enclosed in ``<`` and ``>`` brackets. These abbreviations are optional in
+the syntax, and can be omitted. If they are used, the abbreviation brackets are
+part of the actual syntax of the construct. If the abbreviation is omitted, the
+default abbreviation index is used. To make it clear that abbreviations are
+optional, syntax rules separate abbreviations using plenty of whitespace.
+
+Within a syntax rule, lowercase characters are literal values. Sequences of

[Jim Stichnoth, 2014/11/18 02:24:42]

"lower case" for consistency with other uses, including "upper case"

[Karl, 2014/11/19 20:28:52]

Done.

+upper case alphanumeric characters are named values.  If we mix lower and upper
+case letters within a name appearing in a syntax rule, the lower case letters
+are literal while the upper case sequence of alphanumeric characters denote rule
+specific values.  The valid values for each of these names will be defined in
+the corresponding semantics and constraints subsections.
+
+For example, consider the following syntax rule::
+
+   %vN = add T O1, O2;                            <A>
+
+This rule defines a PNaClAsm add instruction.  This construct defines an
+instruction that adds two values (``O1`` and ``O2``) to generate instruction
+value ``%vN``. The types of the arguments, and the result, are all of type
+``T``. If abbreviation ID ``A`` is present, the record is encoded using that
+abbreviation. Otherwise the corresponding default abbreviation (3) is used.

[Jim Stichnoth, 2014/11/18 02:24:42]

Can you briefly where the "3" comes from?  E.g.

  default abbreviation (which happens to be 3 for the add instruction)

(or whatever the actual explanation is)

[Karl, 2014/11/19 20:28:53]

Replaces with reference to "default abbreviation index", and did not bother with
actual value (which is defined at the reference as 3).

+
+To be concrete, the syntactic rule above defines the structure of the following
+PNaClAsm examples::
+
+  %v10 = add i32 %v1, %v2;  <@a5>
+  %v11 = add i32 %v10, %v3;
+
+In addition to specifying the syntax, each syntax rule can also also specify the
+contents of the corresponding record in the corresponding record subsection. In
+simple cases, the elements of the corresponding record are predefined (literal)
+constants. Otherwise the record element is an identifier from another subsection
+associated with the construct.
+
+Factorial Example
+=================
+
+This section provides a simple example of a PNaCl bitcode file. Its contents
+describe a bitcode file that only defines a function to compute the factorial
+value of a number.
+
+In C, the factorial function can be defined as::
+
+  int fact(int n) {
+    if (n == 1) return 1;
+    return n * fact(n-1);
+  }
+
+Compiling this into a PNaCl bitcode file, and dumping out its contents with
+utility :ref:`pnacl-bcdis<pnacl-bcdis>`, the corresponding output is::
+
+    0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69)
+       | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2
+       | 0>                          |
+   16:0|1: <65535, 8, 2>             |module {  // BlockID = 8
+   24:0|  3: <1, 1>                  |  version 1;
+   26:4|  1: <65535, 0, 2>           |  abbreviations {  // BlockID = 0
+   36:0|  0: <65534>                 |  }
+   40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+   48:0|    3: <1, 4>                |    count 4;
+   50:4|    3: <7, 32>               |    @t0 = i32;
+   53:6|    3: <2>                   |    @t1 = void;
+   55:4|    3: <21, 0, 0, 0>         |    @t2 = i32 (i32);
+   59:4|    3: <7, 1>                |    @t3 = i1;
+   62:0|  0: <65534>                 |  }
+   64:0|  3: <8, 2, 0, 0, 0>         |  define external i32 @f0(i32);
+   68:6|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+   76:0|    3: <5, 0>                |    count 0;
+   78:4|  0: <65534>                 |  }
+   80:0|  1: <65535, 14, 2>          |  valuesymtab {  // BlockID = 14
+   88:0|    3: <1, 0, 102, 97, 99,   |    @f0 : "fact";
+       |        116>                 |
+   96:4|  0: <65534>                 |  }
+  100:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0) {  
+       |                             |                   // BlockID = 12
+  108:0|    3: <1, 3>                |    blocks 3;
+  110:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+  120:0|      3: <1, 0>              |      i32:
+  122:4|      3: <4, 2>              |        %c0 = i32 1;
+  125:0|    0: <65534>               |      }
+       |                             |  %b0:
+  128:0|    3: <28, 2, 1, 32>        |    %v0 = icmp eq i32 %p0, %c0;
+  132:6|    3: <11, 1, 2, 1>         |    br i1 %v0, label %b1, label %b2;
+       |                             |  %b1:
+  136:6|    3: <10, 2>               |    ret i32 %c0;
+       |                             |  %b2:
+  139:2|    3: <2, 3, 2, 1>          |    %v1 = sub i32 %p0, %c0;
+  143:2|    3: <34, 0, 5, 1>         |    %v2 = call i32 @f0(i32 %v1);
+  148:0|    3: <2, 5, 1, 2>          |    %v3 = mul i32 %p0, %v2;
+  152:0|    3: <10, 1>               |    ret i32 %v3;
+  154:4|  0: <65534>                 |  }
+  156:0|0: <65534>                   |}
+
+Note that there are three columns in this output. The first column contains the
+bit positions of the records within the bitcode file. The second column contains
+the sequence of records within the bitcode file. The third column contains the
+corresponding PNaClAsm program.
+
+Bit positions are defined by a pair ``B:N``. ``B`` is the number of bytes, while
+``N`` is the bit offset within the ``B``-th byte. Hence, the bit position (in
+bits) is::
+
+  B*8 + N
+
+Hence, the first record is at bit offset ``0`` (``0*8+0``). The second record is
+at bit offset ``128`` (``16*8+0``).  The third record is at bit offset ``192``
+(``24*8+0``).  The fourth record is at bit offset ``212`` (``26*8+4``).
+
+The :ref:`header record<link_for_header_record_section>` is a sequence of 16
+bytes, defining the contents of the first 16 bytes of the bitcode file. These
+bytes never change, and are expected for all version 2, PNaCl bitcode files. The
+first four bytes define the magic number of the file, i.e. 'PEXE'. All PEXE
+bitcode files begin with these four bytes.
+
+All but the header record has an abbreviation index associated with it. Since no
+user-defined abbreviations are provided, all records were converted to
+bit sequences using default abbreviations.
+
+The types block (starting at bit address ``40:0``), defines 4 types: ``i1``,
+``i32``, ``void``, and function signature ``i32 (i32)``.
+
+Bit address ``64:0`` declares the factorial function address ``@f0``, and its
+corresponding type signature. Bit address ``88:0`` associates the name ``fact``
+with function address ``@f0``.
+
+Bit address ``100:0`` defines the function block that implements function
+``fact``. The entry point is ``%b0`` (at bit address ``128:0``). It uses the
+32-bit integer constant ``1`` (defined at bit addresses ``122:4``). Bit address
+``128:0`` defines an equality comparison of the argument ``%p0`` with ``1``
+(constant ``%c0``). Bit address ``132:6`` defines a conditional branch. If the
+result of the previous comparison (``%v0``) is true, the program will branch to
+block ``%b1``. Otherwise it will branch to block ``%b2``.
+
+Bit address ``136:6`` returns constant ``1`` (``%c0``) when the input parameter
+is 1.  Instructions between bit address ``139:2`` and ``154:4`` compute and
+return ``n * fact(n-1)``.
+
+Road Map
+========
+
+At this point, this document transitions from basic concepts to the details
+of how records should be formatted. This section defines the road map to
+the remaining sections in this document.
+
+Many records have implicit information associated with them, and must be
+maintained across records. :ref:`Global state<link_for_global_state_section>`
+describes how this implicit information is modeled. In addition, there are
+various :ref:`support functions<link_for_support_functions_section>` that are
+used to define the semantics of records, and how they update the global state.
+
+There are just a handful of global records (records that either don't appear in
+any block, or can appear in all blocks).  :ref:`Global
+records<link_for_global_record_codes>` describes these records. This includes
+the block delimiter records :ref:`enter<link_for_enter_block_record_section>`
+and :ref:`exit<link_for_exit_block_record_section>` that define block
+boundaries.
+
+PNaClAsm is a strongly typed language, and most block values are typed.
+:ref:`types<link_for_types_block_section>` describes the set of legal types, and
+how to define types.
+
+Global variables and their initializers are presented in the :ref:`globals
+block<link_for_globals_block_section>`. :ref:`Function
+addresses<link_for_function_address_section>` are part of the :ref:`module
+block<link_for_module_block>`, but must be defined before any global variables.
+
+Names to be associated with global variables and function addresses, are defined
+in the :ref:`valuesymtab block<link_for_valuesymtab_block_section>`, and must
+appear after the :ref:`globals block<link_for_globals_block_section>`, but
+before any :ref:`function definition<link_for_function_blocks_section>`.
+
+The :ref:`module block<link_for_module_block>` is the top-most block, and all
+other blocks must appear within the module block. The module block defines the
+executable in the bitcode file.
+
+Constants used within a :ref:`function
+definition<link_for_function_blocks_section>` must be defined using a
+:ref:`constants block<link_for_constants_block_section>`.  Each function
+definition is defined by a :ref:`function
+block<link_for_function_blocks_section>` and constant blocks can only appear
+within function blocks. Constants defined within a constant block can only be
+used in the enclosing function block.
+
+Function definitions are defined by a sequence of instructions. There are
+several types of instructions.
+
+A :ref:`terminator instruction<link_for_terminator_instruction_section>` is the
+last instruction in a :ref:`basic block<link_for_function_blocks_section>`, and
+is a branch/return instruction.

[Jim Stichnoth, 2014/11/18 02:24:42]

What about unreachable?  That's kind of distinct from branch and return.

[Karl, 2014/11/19 20:28:52]

Done.

+
+There are :ref:`integer<link_for_integer_binary_instructions>` and
+:ref:`floating point<link_for_floating_point_binary_instructions>` binary
+operations.  Integer binary instructions include both arithmetic and logical
+operations. Floating point instructions define arithmetic operations.
+
+There are also :ref:`memory
+access<link_for_memory_creation_and_access_instructions>` instructions that
+allow one to load and store values. That section also includes how to define
+local variables using the :ref:`alloca
+instruction<link_for_alloca_instruction>`.
+
+One can also convert integer and floating point values using :ref:`conversion
+instructions<link_for_conversion_instructions>`.
+
+:ref:`Comparison instructions<link_for_compare_instructions>`
+allow you to compare values.
+
+:ref:`Vector instructions<link_for_vector_instructions>` allow you to build and
+update vectors. Corresponding :ref:`intrinsic
+functions<link_for_intrinsic_functions_section>`, as well as
+:ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating
+point<link_for_floating_point_binary_instructions>` binary instructions allow
+you to apply operations to vectors.
+
+In addition, :ref:`other instructions<link_for_other_pnaclasm_instructions>` are
+available. This includes function and procedure calls.
+
+There are also :ref:`memory
+alignment<link_for_memory_blocks_and_alignment_section>` issues that should be
+considered for global and local variables, as well as load and store
+instructions.
+
+Finally, how to pack records is described in the
+:ref:`abbreviations<link_for_abbreviations_section>` section.
+
+.. _link_for_global_state_section:
+
+Global State
+============
+
+This section describes the global state associated with PNaClAsm. It is used to
+define contextual data that is carried between records.
+
+In particular, PNaClAsm is a strongly typed language, and hence, we must track
+the type associated with values. Subsection :ref:`link_to_typing_functions`
+describes the functions used to maintain typing information associated with
+values.
+
+Values are implicitly ordered within a block, and the indices associated with
+the values do not appear in records.  Rather, ID counters are used to figure out
+what corresponding ID name is associated with a value generating record.
+Subsection :ref:`link_to_ID_Counters` defines counters maintained in the global
+state.
+
+In several blocks, one of the first records in the block defines how many values
+are defined in in the block. The main purpose of these counts is to communicate
+to the :ref:`PNaCl translator<link_for_pnacl_translator>` space requirements, or
+a limit so that it can detect bad references to values. Subsection
+:ref:`link_for_Size_Variables` defines variables that hold size definitions in
+the corresponding records.
+
+Finally, the function and constants block contain implicit context between
+records in those blocks. Subsection :ref:`link_to_Other_Variables` defines the
+variables that contain this implicit context.
+
+.. _link_to_typing_functions:
+
+Typing Functions
+----------------
+
+Associated with most identifiers is a type. This type defines what type the
+corresponding value has. It is defined by the (initially empty) map::
+
+  TypeOf: ID -> Type
+
+For each type in the :ref:`types block<link_for_types_block_section>`, a
+corresponding inverse map::
+
+  TypeID: Type -> ID
+
+is maintained to convert syntactic types to the corresponding type ID.
+
+Note: This document assumes that map ``TypeID`` is automatically maintained
+during updates to map ``TypeOf`` (when given a type ``ID``). Hence, *Updates*
+subsections will not contain assignments to this map.
+
+Associated with each function identifier is its :ref:`type
+signature<link_for_function_type>`. This is different than the type of the
+function identifier, since function identifiers represent the function address
+which is a pointer (and pointers are always implemented as a 32-bit integer
+following the ILP32 data model).
+
+Function type signatures are maintained using::
+
+  TypeOfFcn: ID -> Type
+
+In addition, if a function address has an implementing block, there is a
+corresponding implementation associated with the function address.  To indicate
+which function addresses have implementations, we use the set::
+
+  DefiningFcnIDs: set(ID)
+
+.. _link_to_ID_Counters:
+
+ID Counters
+-----------
+
+Each block defines one or more kinds of values.  Value indices are generated
+sequentially, starting at zero. To capture this, the following counters are
+defined:
+
+NumTypes
+  The number of types defined so far (in the :ref:`types
+  block<link_for_types_block_section>`).
+
+NumFuncAddresses
+  The number of function addresses defined so far (in the :ref:`module
+  block<link_for_module_block>`).
+
+NumGlobalAddresses
+  The number of global variable/constant addresses defined so far (in the
+  :ref:`globals block<link_for_globals_block_section>`).
+
+NumParams
+  The number of parameters defined for a function. Note: Unlike other counters,
+  this value is set once, at the beginning of the corresponding :ref:`function
+  block<link_for_function_blocks_section>`, based on the type signature
+  associated with the function.
+
+NumFcnConsts
+  The number of constants defined in a function so far (in the corresponding
+  nested :ref:`constants block<link_for_constants_block_section>`).
+
+NumBasicBlocks
+  The number of basic blocks defined so far (within a :ref:`function
+  block<link_for_function_blocks_section>`).
+
+NumValuedInsts
+  The number of instructions, generating values, defined so far (within a
+  :ref:`function block<link_for_function_blocks_section>`).
+
+.. _link_for_Size_Variables:
+
+Size Variables
+--------------
+
+A number of blocks define expected sizes of constructs. These sizes are recorded
+in the following size variables:
+
+ExpectedBasicBlocks
+  The expected :ref:`number of basic blocks<link_for_basic_blocks_count>` within
+  a function implementation.
+
+ExpectedTypes
+  The expected :ref:`number of types<link_for_types_count_record>` defined in
+  the types block.
+
+ExpectedGlobals
+  The expected :ref:`number of global variable/constant
+  addresses<link_for_globals_count_record>` in the globals block.
+
+ExpectedInitializers
+  The expected :ref:`number of initializers<link_for_compound_initializer>` for
+  a global variable/constant address in the globals block.
+
+It is assumed that the corresponding :ref:`ID counters<link_to_ID_counters>` are
+always smaller than the corresponding size variables (except
+ExpectedInitializers). That is:
+
+  NumBasicBlocks < ExpectedBasicBlocks

[Jim Stichnoth, 2014/11/18 02:24:42]

Maybe this paragraph should have some special formatting, like Courier?

[Karl, 2014/11/19 20:28:53]

Oops, I forgot the "::" after "That is". Fixing.

+  NumTypes < ExpectedTypes
+  NumGlobalAddresses < ExpectedGlobals
+
+.. _link_to_Other_Variables:
+
+Other Variables
+---------------
+
+EnclosingFcnID
+  The function ID of the function block being processed.
+

[Jim Stichnoth, 2014/11/18 02:24:42]

Remove this blank line for consistency

[Karl, 2014/11/19 20:28:52]

Actually, the consistent form is to leave a blank line between each (labeled)
case.

+ConstantsSetType
+

[Jim Stichnoth, 2014/11/18 02:24:42]

Remove this blank line

[Karl, 2014/11/19 20:28:53]

Done.

+  Holds the type associated with the last :ref:`set type
+  record<link_for_constants_set_type_record>` in the constants block. Note: at
+  the beginning of each constants block, this variable is set to type void.
+
+.. _link_for_global_record_codes:
+
+Global Records
+==============
+
+Global records are records that can appear in any block. These records have
+the same meaning in multiple kinds of blocks.
+
+There are four global PNaCl records, each having its own record code. These
+global records are:
+
+Header
+  The :ref:`header record<link_for_header_record_section>` is the first record
+  of a PNaCl bitcode file, and identifies the file's magic number, as well as
+  the bitcode version it uses. The record defines the sequence of bytes that
+  make up the header and uniquely identifies the file as a PNaCl bitcode file.
+
+Enter
+  An :ref:`enter record<link_for_enter_block_record_section>` defines the
+  beginning of a block. Since blocks can be nested, one can appear inside other
+  blocks, as well as at the top level.
+
+Exit
+  An :ref:`exit record<link_for_exit_block_record_section>` defines the end of a
+  block. Hence, it must appear in every block, to end the block.
+
+Abbreviation
+  An :ref:`abbreviation record<link_for_abbreviation_record>` defines a
+  user-defined abbreviation to be applied to records within blocks.
+  Abbreviation records appearing in the abbreviations block define global
+  abbreviations. All other abbreviations are local to the block they appear in,
+  and can only be used in that block.
+
+All global records can't have user-defined abbreviations associated with
+them. The :ref:`default abbreviation<link_for_default_abbreviations>` is always
+used.
+
+.. _link_for_header_record_section:
+
+Header Record
+-------------
+
+The header record must be the first record in the file. It is the only record in
+the bitcode file that doesn't have a corresponding construct in PNaClAsm.  In
+addition, no abbreviation index is associated with it.
+
+**Syntax**:
+
+There is no syntax for header records in PNaClAsm.
+
+**Record**::
+
+   <65532, 80, 69, 88, 69, 1, 0, 8, 0, 17, 0, 4, 0, 2, 0, 0, 0>
+
+**Semantics**:
+
+The header record defines the initial sequence of bytes that must appear at the
+beginning of all (PNaCl bitcode version 2) files. That sequence is the list of
+bytes inside the record (excluding the record code). As such, it uniquely
+identifies all PNaCl bitcode files.
+
+**Examples**::
+
+    0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69)
+       | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2
+       | 0>                          |
+
+.. _link_for_enter_block_record_section:
+
+Enter Block Record
+------------------
+
+Block records can be top-level, as well as nested in other blocks. Blocks must
+begin with an *enter* record, and end with an
+:ref:`exit<link_for_exit_block_record_section>` record.
+
+**Syntax**::
+
+  N {                                             <B>
+
+**Record**::
+
+  1: <65535, ID, B>
+
+**Semantics**:
+
+Enter block records define the beginning of a block.  ``B``, if present, is the
+number of bits needed to represent all possible abbreviation indices used within
+the block. If omitted, ``B=2`` is assumed.
+
+The block ``ID`` value is dependent on the name ``N``. Valid names and corresponding

[Jim Stichnoth, 2014/11/17 18:54:56]

Find all 80-char violations:
  grep -n '^.\{81\}' pnacl-bitcode-manual.rst

[Karl, 2014/11/17 20:17:28]

Done.

+``BlockID`` values are defined as follows:
+
+============= ========
+N             Block ID
+============= ========
+abbreviations 0
+constants     11
+function      12
+globals       19
+module        8
+types         17
+valuesymtab   14
+============= ========
+
+Note: For readability, PNaClAsm defines a more readable form of a function block
+enter record.  See :ref:`function blocks<link_for_function_blocks_section>` for
+more details.
+
+**Examples**::
+
+   16:0|1: <65535, 8, 2>             |module {  // BlockID = 8
+   24:0|  3: <1, 1>                  |  version 1;
+   26:4|  1: <65535, 0, 2>           |  abbreviations {  // BlockID = 0
+   36:0|  0: <65534>                 |  }
+   40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+   48:0|    3: <1, 2>                |    count 2;
+   50:4|    3: <2>                   |    @t0 = void;
+   52:2|    3: <21, 0, 0>            |    @t1 = void ();
+   55:4|  0: <65534>                 |  }
+   56:0|  3: <8, 1, 0, 1, 0>         |  declare external void @f0();
+   60:6|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+   68:0|    3: <5, 0>                |    count 0;
+   70:4|  0: <65534>                 |  }
+   72:0|0: <65534>                   |}
+
+.. _link_for_exit_block_record_section:
+
+Exit Block Record
+-----------------
+
+Block records can be top-level, as well as nested, records. Blocks must begin
+with an :ref:`enter<link_for_enter_block_record_section>` record, and end with an
+*exit* record.
+
+**Syntax**::
+
+  }
+
+**Record**::
+
+  0: <65534>
+
+**Semantics**:
+
+All exit records are identical, no matter what block they are ending. An exit
+record defines the end of the block.
+
+**Examples**::
+
+   16:0|1: <65535, 8, 2>             |module {  // BlockID = 8
+   24:0|  3: <1, 1>                  |  version 1;
+   26:4|  1: <65535, 0, 2>           |  abbreviations {  // BlockID = 0
+   36:0|  0: <65534>                 |  }
+   40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+   48:0|    3: <1, 2>                |    count 2;
+   50:4|    3: <2>                   |    @t0 = void;
+   52:2|    3: <21, 0, 0>            |    @t1 = void ();
+   55:4|  0: <65534>                 |  }
+   56:0|  3: <8, 1, 0, 1, 0>         |  declare external void @f0();
+   60:6|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+   68:0|    3: <5, 0>                |    count 0;
+   70:4|  0: <65534>                 |  }
+   72:0|0: <65534>                   |}
+
+.. _link_for_abbreviation_record:
+
+Abbreviation Record
+-------------------
+
+Abbreviation records define abbreviations. See
+:ref:`abbreviations<link_for_abbreviations_section>` for details on how abbreviations should be
+written. This section only presents the mechanical details for converting
+an abbreviation into a PNaCl record.
+
+**Syntax**::
+
+  A = abbrev <E1, ... , EM>;
+
+**Record**::
+
+  2: <65533, M, EE1, ... , EEM>
+
+**Semantics**:
+
+Defines an abbreviation ``A`` as the sequence of encodings ``E1`` through
+``EM``.  If the abbreviation appears within the :ref:`abbreviations
+block<link_for_abbreviations_block_section>`, ``A`` must be a global
+abbreviation. Otherwise, ``A`` must be a local abbreviation.
+
+Abbreviations within a block (or a section within the abbreviations block), must
+be enumerated in order, starting at index ``0``.
+
+Valid encodings ``Ei``, and the corresponding sequence of (unsigned) integers
+``EEi``, ( for ``1 <= i <= M``) are defined by the following table:
+
+========= ======= ===============================================================
+Ei        EEi     Form
+========= ======= ===============================================================
+C         1, C    Literal C in corresponding position in record.
+fixed(N)  0, 1, N Encode value as a fixed sequence of N bits.
+vbr(N)    0, 2, N Encode value using a variable bit rate of N.
+char6     0, 4    Encode value as 6-bit char containing characters [a-zA-Z0-9._].
+array(EM) 0, 3    Allow zero or more of the enclosed encoding.
+========= ======= ===============================================================
+
+Notationally, Array(EM) encloses the encoding EM, and must appear at the end of

[Jim Stichnoth, 2014/11/18 02:24:42]

Should Array(EM) be formatted consistently with ``array(EM), array and EM`` in
the next line?

[Karl, 2014/11/19 20:28:52]

Done.

+the abbreviation. When encoding ``array(EM), array and EM`` are the last two
+entries in an abbreviation, the trailing EM is omitted from the syntax, since it
+is redundant.
+
+**Examples**::
+
+    0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69)
+       | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2
+       | 0>                          |
+   16:0|1: <65535, 8, 2>             |module {  // BlockID = 8
+   24:0|  3: <1, 1>                  |  version 1;
+   26:4|  1: <65535, 0, 2>           |  abbreviations {  // BlockID = 0
+   36:0|    1: <1, 14>               |    valuesymtab:
+   38:4|    2: <65533, 4, 0, 1, 3, 0,|      @a0 = abbrev <fixed(3), vbr(8), 
+       |        2, 8, 0, 3, 0, 1, 8> |                   array(fixed(8))>;
+   43:2|    2: <65533, 4, 1, 1, 0, 2,|      @a1 = abbrev <1, vbr(8), 
+       |        8, 0, 3, 0, 1, 7>    |                   array(fixed(7))>;
+   48:0|    2: <65533, 4, 1, 1, 0, 2,|      @a2 = abbrev <1, vbr(8), 
+       |        8, 0, 3, 0, 4>       |                   array(char6)>;
+   52:1|    2: <65533, 4, 1, 2, 0, 2,|      @a3 = abbrev <2, vbr(8), 
+       |        8, 0, 3, 0, 4>       |                   array(char6)>;
+   56:2|    1: <1, 11>               |    constants:
+   58:6|    2: <65533, 2, 1, 1, 0, 1,|      @a0 = abbrev <1, fixed(2)>;
+       |        2>                   |
+   61:7|    2: <65533, 2, 1, 4, 0, 2,|      @a1 = abbrev <4, vbr(8)>;
+       |        8>                   |
+   65:0|    2: <65533, 2, 1, 4, 1, 0>|      @a2 = abbrev <4, 0>;
+   68:1|    2: <65533, 2, 1, 6, 0, 2,|      @a3 = abbrev <6, vbr(8)>;
+       |        8>                   |
+   71:2|    1: <1, 12>               |    function:
+   73:6|    2: <65533, 4, 1, 20, 0,  |      @a0 = abbrev <20, vbr(6), vbr(4),
+       |        2, 6, 0, 2, 4, 0, 2, |                   vbr(4)>;
+       |        4>                   |
+   79:1|    2: <65533, 4, 1, 2, 0, 2,|      @a1 = abbrev <2, vbr(6), vbr(6), 
+       |        6, 0, 2, 6, 0, 1, 4> |                   fixed(4)>;
+   84:4|    2: <65533, 4, 1, 3, 0, 2,|      @a2 = abbrev <3, vbr(6), 
+       |        6, 0, 1, 2, 0, 1, 4> |                   fixed(2), fixed(4)>;
+   89:7|    2: <65533, 1, 1, 10>     |      @a3 = abbrev <10>;
+   91:7|    2: <65533, 2, 1, 10, 0,  |      @a4 = abbrev <10, vbr(6)>;
+       |        2, 6>                |
+   95:0|    2: <65533, 1, 1, 15>     |      @a5 = abbrev <15>;
+   97:0|    2: <65533, 3, 1, 43, 0,  |      @a6 = abbrev <43, vbr(6), 
+       |        2, 6, 0, 1, 2>       |                   fixed(2)>;
+  101:2|    2: <65533, 4, 1, 24, 0,  |      @a7 = abbrev <24, vbr(6), vbr(6),
+       |        2, 6, 0, 2, 6, 0, 2, |                   vbr(4)>;
+       |        4>                   |
+  106:5|    1: <1, 19>               |    globals:
+  109:1|    2: <65533, 3, 1, 0, 0, 2,|      @a0 = abbrev <0, vbr(6), 
+       |        6, 0, 1, 1>          |                   fixed(1)>;
+  113:3|    2: <65533, 2, 1, 1, 0, 2,|      @a1 = abbrev <1, vbr(8)>;
+       |        8>                   |
+  116:4|    2: <65533, 2, 1, 2, 0, 2,|      @a2 = abbrev <2, vbr(8)>;
+       |        8>                   |
+  119:5|    2: <65533, 3, 1, 3, 0, 3,|      @a3 = abbrev <3, array(fixed(8))>
+       |        0, 1, 8>             |          ;
+  123:2|    2: <65533, 2, 1, 4, 0, 2,|      @a4 = abbrev <4, vbr(6)>;
+       |        6>                   |
+  126:3|    2: <65533, 3, 1, 4, 0, 2,|      @a5 = abbrev <4, vbr(6), vbr(6)>;
+       |        6, 0, 2, 6>          |
+  130:5|  0: <65534>                 |  }
+  132:0|  1: <65535, 17, 3>          |  types {  // BlockID = 17
+  140:0|    2: <65533, 4, 1, 21, 0,  |    %a0 = abbrev <21, fixed(1), 
+       |        1, 1, 0, 3, 0, 1, 2> |                  array(fixed(2))>;
+  144:7|    3: <1, 3>                |    count 3;
+  147:4|    3: <7, 32>               |    @t0 = i32;
+  150:7|    4: <21, 0, 0, 0, 0>      |    @t1 = i32 (i32, i32); <%a0>
+  152:7|    3: <2>                   |    @t2 = void;
+  154:6|  0: <65534>                 |  }
+  156:0|  3: <8, 1, 0, 0, 0>         |  define external i32 @f0(i32, i32);
+  160:6|  1: <65535, 19, 4>          |  globals {  // BlockID = 19
+  168:0|    3: <5, 0>                |    count 0;
+  170:6|  0: <65534>                 |  }
+  172:0|  1: <65535, 14, 3>          |  valuesymtab {  // BlockID = 14
+  180:0|    6: <1, 0, 102>           |    @f0 : "f"; <@a2>
+  182:7|  0: <65534>                 |  }
+  184:0|  1: <65535, 12, 4>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  192:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  194:6|    5: <2, 2, 1, 0>          |    %v0 = add i32 %p0, %p1; <@a1>
+  197:2|    5: <2, 3, 1, 0>          |    %v1 = add i32 %p0, %v0; <@a1>
+  199:6|    8: <10, 1>               |    ret i32 %v1; <@a4>
+  201:0|  0: <65534>                 |  }
+  204:0|0: <65534>                   |}
+
+Note that the example above shows the standard abbreviations used by
+*pnacl-finalize*.
+
+.. _link_for_types_block_section:
+
+Types Block
+===========
+
+The types block defines all types used in a program. It must appear in the
+:ref:`module block<link_for_module_block>`, before any :ref:`function
+address<link_for_function_address_section>` records, the :ref:`globals
+block<link_for_globals_block_section>`, the :ref:`valuesymtab
+block<link_for_valuesymtab_block_section>`, and any :ref:`function
+blocks<link_for_function_blocks_section>`.
+
+All types used in a program must be defined in the types block. Many PNaClAsm
+constructs allow one to use explicit type names, rather than the type
+identifiers defined by this block. However, they are internally converted to the
+corresponding type identifier in the types block. Hence, the requirement that
+the types block must appear early in the module block.
+
+Each record in the types block defines a type used by the program.  Types can be
+broken into the following groups:
+
+Primitive value types
+  Defines the set of base types for values. This includes various sizes of
+  integer and floating point types.
+
+Void type
+  A primitive type that doesn't represent any value and has no size.
+
+Function types
+  The type signatures of functions.
+
+Vector type
+  Defines vectors of primitive types.
+
+In addition, any type that is not defined using another type is a primitive
+type.  All other types (i.e. function and vector) are composite types.
+
+Types must be defined in a topological order, causing primitive types to appear
+before the composite types that use them. Each type must be unique. There are no
+additional restrictions on the order that types can be defined in a types block.
+
+The following subsections introduce each valid PNaClAsm type, and the
+corresponding PNaClAsm construct that defines the type. Types not defined in the
+types block, can't be used in a PNaCl program.
+
+The first record of a types block must be a :ref:`count
+record<link_for_types_count_record>`, defining how many types are defined by the
+types block. All remaining records defines a type. The following subsections
+defines valid records within a types block. The order of type records is
+important. The position of each defining record implicitly defines the type ID
+that will be used to denote that type, within other PNaCl records of the bitcode
+file.
+
+To make this more concrete, consider the following example types block::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <2>                   |    @t2 = void;
+      57:2|    3: <21, 0, 2, 0, 1>      |    @t3 = void (i32, float);
+      62:0|  0: <65534>                 |  }
+
+This example defines a types block that defines four type IDs:
+
+@t0
+  A 32-bit integer type.
+@t1
+  A 32-bit floating point type.
+@t2
+  The void type.
+@t3
+   A function, taking 32-bit integer and float point arguments that returns
+   void.
+
+.. _link_for_types_count_record:
+
+Count Record
+------------
+
+The *count record* defines how many types are defined in the types
+block. Following the types count record are records that define types used by
+the PNaCl program.
+
+**Syntax**::
+
+  count N;                                       <A>
+
+**Record**::
+
+  AA: <1, N>
+
+**Semantics**:
+
+This construct defines the number of types used by the PNaCl program. ``N`` is
+the number of types defined in the types block. It is an error to define more
+(or fewer) types than value ``N``, within the enclosing types block.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  0 == NumTypes
+
+**Updates**:

[Jim Stichnoth, 2014/11/18 02:24:43]

::

[Karl, 2014/11/19 20:28:52]

Done.

+
+  ExpectedTypes = N;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <2>                   |    @t2 = void;
+      57:2|    3: <21, 0, 2, 0, 1>      |    @t3 = void (i32, float);
+      62:0|  0: <65534>                 |  }
+
+Void Type
+---------
+
+The *void* type record defines the void type, which corresponds to the type that
+doesn't define any value, and has no size.
+
+**Syntax**::
+
+  @tN = void;                                     <A>
+
+**Record**::
+
+  AA: <2>
+
+**Semantics**:
+
+The void type record defines the type that has no values and has no size.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumTypes
+
+**Updates**::
+
+  ++NumTypes;
+  TypeOf(@tN) = void;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <2>                   |    @t2 = void;
+      62:0|  0: <65534>                 |  }
+
+Integer Types
+-------------
+
+PNaClAsm allows integer types for various bit sizes. Valid bit sizes are 1, 8,
+16, 32, and 64. Integers can be signed or unsigned, but the signed component of
+an integer is not specified by the type. Rather, individual instructions
+determine whether the value is assumed to be signed or unsigned.
+
+It should be noted that in PNaClAsm, all pointers are implemented as 32-bit
+(unsigned) integers.  There isn't a separate type for pointers. The only way to
+tell that a 32-bit integer is a pointer, is when it is used in an instruction
+that requires a pointer (such as load and store instructions).
+
+**Syntax**::
+
+  @tN = iB;                                      <A>
+
+**Record**::
+
+  AA: <7, B>
+
+**Semantics**:
+
+An integer type record defines an integer type. ``B`` defines the number of bits
+of the integer type.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumTypes &
+  B in {1, 8, 16, 32, 64}
+
+**Updates**::
+
+  ++NumTypes;
+  TypeOf(@tN) = iB;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 64>               |    @t0 = i64;
+      53:6|    3: <7, 1>                |    @t1 = i1;
+      56:2|    3: <7, 8>                |    @t2 = i8;
+      58:6|    3: <7, 16>               |    @t3 = i16;
+      61:2|    3: <7, 32>               |    @t4 = i32;
+      64:4|    3: <21, 0, 0, 1>         |    @t5 = i64 (i1);
+      68:4|    3: <2>                   |    @t6 = void;
+      70:2|  0: <65534>                 |  }
+
+32-Bit Floating Point Type
+--------------------------
+
+PNaClAsm allows computation on 32-bit floating point values. A floating point
+type record defines the 32-bit floating point type.
+
+**Syntax**::
+
+  @tN = float;                                    <A>
+
+**Record**::
+
+  AA: <3>
+
+**Semantics**:
+
+A floating point type record defines the 32-bit floating point type.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumTypes
+
+**Updates**::
+
+  ++NumTypes;
+  TypeOf(@tN) = float;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <4>                   |    @t0 = double;
+      52:2|    3: <3>                   |    @t1 = float;
+      54:0|    3: <21, 0, 0, 1>         |    @t2 = double (float);
+      58:0|    3: <2>                   |    @t3 = void;
+      59:6|  0: <65534>                 |  }
+
+64-bit Floating Point Type
+--------------------------
+
+PNaClAsm allows computation on 64-bit floating point values. A 64-bit floating
+type record defines the 64-bit floating point type.
+
+**Syntax**::
+
+  @tN = double;                                   <A>
+
+**Record**::
+
+  AA: <4>
+
+**Semantics**:
+
+A double type record defines the 64-bit floating point type.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumTypes
+
+**Updates**::
+
+  ++NumTypes;
+  TypeOf(@tN) = double;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <4>                   |    @t0 = double;
+      52:2|    3: <3>                   |    @t1 = float;
+      54:0|    3: <21, 0, 0, 1>         |    @t2 = double (float);
+      58:0|    3: <2>                   |    @t3 = void;
+      59:6|  0: <65534>                 |  }
+
+Vector Types
+------------
+
+A vector type is a derived type that represents a vector of elements.  Vector
+types are used when multiple primitive data values are operated in parallel
+using a single (SIMD) :ref:`vector instruction<link_for_vector_instructions>`. A
+vector type requires a size (number of elements) and an underlying primitive
+data type.
+
+**Syntax**::
+
+  @tN = < E x T >                                 <A>
+
+**Record**::
+
+  AA: <12, E, TT>
+
+**Semantics**:
+
+The vector type defines a vector of elements. ``T`` is the type of each
+element. ``E`` is the number of elements in the vector.
+
+Vector types can only be defined on ``i1``, ``i8``, ``i16``, ``i32``, and
+``float``.  All vector types, except those on ``i1``, must contain exactly 128
+bits.  The valid element sizes are restricted as follows:
+
+====== ===================
+Type   Valid element sizes
+====== ===================
+i1     4, 8, 16
+i8     16
+i16    8
+i32    4
+float  4
+====== ===================
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TT == AbsoluteIndex(TypeID(T)) &
+  N == NumTypes
+
+**Updates**::
+
+  ++NumTypes
+  TypeOf(@tN) = <E x T>
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 14>               |    count 14;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <7, 1>                |    @t1 = i1;
+      56:2|    3: <2>                   |    @t2 = void;
+      58:0|    3: <12, 4, 1>            |    @t3 = <4 x i1>;
+      61:2|    3: <12, 8, 1>            |    @t4 = <8 x i1>;
+      64:4|    3: <12, 16, 1>           |    @t5 = <16 x i1>;
+      67:6|    3: <7, 8>                |    @t6 = i8;
+      70:2|    3: <12, 16, 6>           |    @t7 = <16 x i8>;
+      73:4|    3: <7, 16>               |    @t8 = i16;
+      76:0|    3: <12, 8, 8>            |    @t9 = <8 x i16>;
+      79:2|    3: <12, 4, 0>            |    @t10 = <4 x i32>;
+      82:4|    3: <3>                   |    @t11 = float;
+      84:2|    3: <12, 4, 11>           |    @t12 = <4 x float>;
+      87:4|    3: <21, 0, 2>            |    @t13 = void ();
+      90:6|  0: <65534>                 |  }
+
+.. _link_for_function_type:
+
+Function Type
+-------------
+
+The *function* type can be thought of as a function signature. It consists of a
+return type, and a (possibly empty) list of formal parameter types.
+
+**Syntax**::
+
+  %tN = RT (T1, ... , TM)                         <A>
+
+**Record**::
+
+  AA: <21, 0, IRT, IT1, ... , ITM>
+
+**Semantics**:
+
+The function type defines the signature of a function. ``RT`` is the return type
+of the function, while types ``T1`` through ``TM`` are the types of the
+arguments. Indices to the corresponding type identifiers are stored in the
+corresponding record.
+
+The return value must either be a primitive type, type ``void``, or a vector
+type.  Parameter types can be a primitive or vector type.
+
+For ordinary functions, the only valid integer types that can be used for a
+return or parameter type are ``i32`` and ``i64``.  All other integer types are
+not allowed.
+
+For :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, all
+integer types are allowed for both return and parameter types.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  M >= 0 &
+  IRT == AbsoluteIndex(TypeID(RT)) &
+  IT1 == AbsoluteIndex(TypeID(T1)) &
+  ...
+  ITM == AbsoluteIndex(TypeID(TM)) &
+  N == NumTypes
+
+**Updates**::
+
+  ++NumTypes
+  TypeOf(@tN) = RT (T1, ... , TM)
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <4>                   |    @t2 = double;
+      57:2|    3: <21, 0, 2, 1>         |    @t3 = double (float);
+      61:2|    3: <2>                   |    @t4 = void;
+      63:0|    3: <21, 0, 4>            |    @t5 = void ();
+      66:2|    3: <21, 0, 0, 0, 1, 0, 2>|    @t6 = 
+          |                             |        i32 (i32, float, i32, double);
+      72:4|  0: <65534>                 |  }
+
+.. _link_for_globals_block_section:
+
+Globals Block
+=============
+
+The globals block defines global addresses of variables and constants, used by
+the PNaCl program. It also defines the memory associated with the global
+addresses, and how to initialize each global variable/constant. It must appear
+in the :ref:`module block<link_for_module_block>`. It must appear after the
+:ref:`types block<link_for_types_block_section>`, as well as after all
+:ref:`function address<link_for_function_address_section>` records. But, it must
+also appear before the :ref:`valuesymtab
+block<link_for_valuesymtab_block_section>`, and any
+:ref:`function blocks<link_for_function_blocks_section>`.
+
+The globals block begins with a :ref:`count
+record<link_for_globals_count_record>`, defining how many global addresses are
+defined by the PNaCl program. It is then followed by a sequence of records that
+defines each global address, and how each global address is initialized.
+
+The standard sequence, for defining global addresses, begins with a global
+address record.  It is then followed by a sequence of records defining how the
+global address is initialized.  If the initializer is simple, a single record is
+used. Otherwise, the initializer is preceded with a :ref:`compound
+record<link_for_compound_initializer>`, specifying a number *N*, followed by
+sequence of *N* simple initializer records.
+
+The size of the memory referenced by each global address is defined by its
+initializer records. All simple initializer records define a sequence of
+bytes. A compound initializer defines the sequence of bytes by concatenating the
+corresponding sequence of bytes for each of its simple initializer records.
+
+For notational convenience, PNaClAsm begins a compound record with a "{", and
+inserts a "}" after the last initializer record associated with the compound
+record. This latter "}" does not correspond to any record. It is implicitly
+assumed by the size specified in the compound record, and is added only to
+improve readability.
+
+Explicit alignment is specified for global addresses, and must be a power of
+2. See :ref:`memory blocks and
+alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed
+discussion on how to define alignment.
+
+For example, consider the following pnacl-bcdis output snippet::
+
+      52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      60:0|    3: <5, 2>                |    count 2;
+      62:4|    3: <0, 1, 1>             |    const @g0, align 1,
+      65:6|    3: <2, 8>                |      zerofill 8;
+      68:2|    3: <0, 1, 0>             |    var @g1, align 1,
+      71:4|    3: <1, 2>                |      initializers 2 {
+      74:0|    3: <3, 1, 2, 3, 4>       |        {  1,   2,   3,   4}
+      78:6|    3: <2, 2>                |        zerofill 2;
+          |                             |      }
+      81:2|  0: <65534>                 |  }
+
+This snippet defines the global constant ``@g0``, and the global variable
+``@g1``. ``@g0`` is 8 bytes long, and initialized to zero. ``@g1`` is
+initialized with 6 bytes: ``1 2 3 4 0 0``.
+
+.. _link_for_globals_count_record:
+
+Count Record
+------------
+
+The count record defines the number of global addresses used by the PNaCl
+program.
+
+**Syntax**::
+
+  count N;                                       <A>
+
+**Record**::
+
+   AA: <5, N>
+
+**Semantics**:
+
+This record must appear first in the globals block.  The count record defines
+the number of global addresses used by the program.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A)
+
+**Updates**::
+
+  ExpectedGlobals = N;
+  ExpectedInitializers = 0;
+
+**Examples**::
+
+  52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+  60:0|    3: <5, 2>                |    count 2;
+  62:4|    3: <0, 1, 1>             |    const @g0, align 1,
+  65:6|    3: <2, 8>                |      zerofill 8;
+  68:2|    3: <0, 1, 0>             |    var @g1, align 1,
+  71:4|    3: <1, 2>                |      initializers 2 {
+  74:0|    3: <3, 1, 2, 3, 4>       |        {  1,   2,   3,   4}
+  78:6|    3: <2, 2>                |        zerofill 2;
+      |                             |      }
+  81:2|  0: <65534>                 |  }
+
+.. _link_for_global_variable_address:
+
+Global Variable Addresses
+-------------------------
+
+A global variable address record defines a global address to global data.  The
+global variable address record must be immediately followed by initializer
+record(s) that define how the corresponding global variable is initialized.
+
+**Syntax**::
+
+  var @gN, align V,                               <A>
+
+**Record**::
+
+  AA: <0, VV, 0>
+
+**Semantics**:
+
+A global variable address record defines a global address for a global variable.
+``V`` is the :ref:`memory
+alignment<link_for_memory_blocks_and_alignment_section>` for the global variable
+address, and is a power of 2.
+
+It is assumed that the memory, referenced by the global variable address, can be
+both read and written to.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumGlobalAddresses &
+  ExpectedInitializers == 0 &
+  VV == Log2(V+1)
+
+**Updates**::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**::
+
+      52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      60:0|    3: <5, 2>                |    count 2;
+      62:4|    3: <0, 3, 0>             |    var @g0, align 4,
+      65:6|    3: <2, 8>                |      zerofill 8;
+      68:2|    3: <0, 1, 0>             |    var @g1, align 1,
+      71:4|    3: <3, 1, 2, 3, 4>       |      {  1,   2,   3,   4}
+      76:2|  0: <65534>                 |  }
+      80:0|0: <65534>                   |}
+
+.. _link_for_global_constant_address:
+
+Global Constant Addresses
+-------------------------
+
+A global constant address record defines an address corresponding to a global
+constant that can't be modified by the program. The global constant address
+record must be immediately followed by initializer record(s) that define how
+the corresponding global constant is initialized.
+
+**Syntax**::
+
+  const @gN, align V,                             <A>
+
+**Record**::
+
+  AA: <0, VV, 1>
+
+**Semantics**:
+
+A global constant address record defines a global address for a global constant.
+``V`` is the :ref:`memory
+alignment<link_for_memory_blocks_and_alignment_section>` for the global constant
+address, and is a power of 2.
+
+It is assumed that the memory, referenced by the global constant address, is
+only read, and can't be written to.
+
+Note that the only difference between a global variable address and a global
+constant address record is the third element of the record. If the value is
+zero, it defines a global variable address. If the value is one, it defines a
+global constant address.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N == NumGlobalAddresses &
+  ExpectedInitializers == 0 &
+  VV == Log2(V+1)
+
+**Updates**::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**::
+
+      52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      60:0|    3: <5, 2>                |    count 2;
+      62:4|    3: <0, 3, 1>             |    const @g0, align 4,
+      65:6|    3: <2, 8>                |      zerofill 8;
+      68:2|    3: <0, 1, 1>             |    const @g1, align 1,
+      71:4|    3: <3, 1, 2, 3, 4>       |      {  1,   2,   3,   4}
+      76:2|  0: <65534>                 |  }
+
+Zerofill Initializer
+--------------------
+
+The zerofill initializer record initializes a sequence of bytes, associated with
+a global address, with zeros.
+
+**Syntax**::
+
+  zerofill N;                                     <A>
+
+**Record**::
+
+  AA: <2, N>
+
+**Semantics**:
+
+A zerofill initializer record initializes a sequence of bytes, associated with a
+global address, with zeros. The number of bytes initialized to zero is ``N``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  ExpectedInitializers > 0
+
+**Updates**::
+
+  --ExpectedInitializers;
+
+**Examples**::
+
+      52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      60:0|    3: <5, 2>                |    count 2;
+      62:4|    3: <0, 3, 1>             |    const @g0, align 4,
+      65:6|    3: <2, 8>                |      zerofill 8;
+      68:2|    3: <0, 1, 0>             |    var @g1, align 1,
+      71:4|    3: <2, 4>                |      zerofill 4;
+      74:0|  0: <65534>                 |  }
+
+Data Initializer
+----------------
+
+Data records define a sequence of bytes. These bytes define the initial value of
+the contents of the corresponding memory.
+
+**Syntax**::
+
+  { B1 , .... , BN }                              <A>
+
+**Record**::
+
+  AA: <3, B1, ..., BN>
+
+**Semantics**:
+
+A data record defines a sequence of (unsigned) bytes ``B1`` through ``BN``, that
+initialize ``N`` bytes of memory.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  ExpectedInitializers > 0
+
+**Updates**::
+
+  --ExpectedInitializers;
+
+**Examples**::
+
+   56:0|  3: <8, 1, 0, 1, 0>         |  declare external void @f0();
+   60:6|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+   68:0|    3: <5, 2>                |    count 2;
+   70:4|    3: <0, 1, 1>             |    const @g0, align 1,
+   73:6|    3: <3, 1, 2, 97, 36, 44, |      {  1,   2,  97,  36,  44,  88, 
+       |        88, 44, 50>          |        44,  50}
+   86:0|    3: <0, 1, 1>             |    const @g1, align 1,
+   89:2|    3: <1, 3>                |      initializers 3 {
+   91:6|    3: <3, 1, 2, 3, 4>       |        {  1,   2,   3,   4}
+   96:4|    3: <4, 0>                |        reloc @f0;
+   99:0|    3: <3, 99, 66, 22, 12>   |        { 99,  66,  22,  12}
+       |                             |      }
+  105:2|  0: <65534>                 |  }
+
+Relocation Initializer
+----------------------
+
+A relocation initializer record allows one to define the initial value of a
+global address with the value of another global address (i.e. either
+:ref:`function<link_for_function_address_section>`,
+:ref:`variable<link_for_global_variable_address>`, or
+:ref:`constant<link_for_global_constant_address>`). Since addresses are
+pointers, a relocation initializer record defines 4 bytes of memory.
+
+**Syntax**::
+
+  reloc V;                                        <A>
+
+**Record**::
+
+  AA: <4, VV>
+
+**Semantics**:
+
+A relocation initializer record defines a 4-byte value containing the specified
+global address ``V``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV == AbsoluteIndex(V) &
+  VV >= NumFuncAddresses &
+  VV < NumFuncAddresses + ExpectedGlobals &
+  ExpectedInitializers > 0
+
+**Updates**:

[Jim Stichnoth, 2014/11/18 02:24:42]

::

[Karl, 2014/11/19 20:28:52]

Done.

+
+  --ExpectedInitializers;
+
+**Examples**::
+
+  40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+  48:0|    3: <1, 2>                |    count 2;
+  50:4|    3: <2>                   |    @t0 = void;
+  52:2|    3: <21, 0, 0>            |    @t1 = void ();
+  55:4|  0: <65534>                 |  }
+  56:0|  3: <8, 1, 0, 1, 0>         |  declare external void @f0();
+  60:6|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+  68:0|    3: <5, 2>                |    count 2;
+  70:4|    3: <0, 1, 0>             |    var @g0, align 1,
+  73:6|    3: <1, 3>                |      initializers 3 {
+  76:2|    3: <4, 0>                |        reloc @f0;
+  78:6|    3: <4, 1>                |        reloc @g0;
+  81:2|    3: <4, 2>                |        reloc @g1;
+      |                             |      }
+  83:6|    3: <0, 3, 0>             |    var @g1, align 4,
+  87:0|    3: <2, 4>                |      zerofill 4;
+  89:4|  0: <65534>                 |  }
+
+This example defines global address ``@g0`` and ``@g1``. ``@g0`` defines 12
+bytes of memory, and is initialized with three addresses ``@f1``, ``@g0``, and
+``@g1``. Note that all global addresses can be used in a relocation
+initialization record, even if it isn't defined yet.
+
+Subfield Relocation Initializer
+-------------------------------
+
+A subfield relocation initializer record allows one to define the initial value
+of a global address with the value of another (non-function) global address
+(i.e. either :ref:`variable<link_for_global_variable_address>` or
+:ref:`constant<link_for_global_constant_address>` address), plus a
+constant. Since addresses are pointers, a relocation initializer record defines
+4 bytes of memory.
+
+**Syntax**::
+
+  reloc V + X;                                    <A>
+  reloc V - X;                                    <A>
+
+**Record**::
+
+  AA: <4, VV, XXX>
+
+**Semantics**:
+
+A subfield relocation initializer record defines a 4-byte value containing the
+specified global (non-function) address ``V``, modified by the unsigned offset
+``X``. ``XX`` is the corresponding signed offset. In the first form, ``XX ==
+X``. In the second form, ``XX == -X``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A)
+  VV == AbsoluteIndex(V)
+  VV >= NumFuncAddresses
+  VV < NumFuncAddresses + ExpectedGlobals
+  ExpectedInitializers > 0
+  XXX == SignRotate(XX)
+
+**Updates**::
+
+  --ExpectedInitializers;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 0>                |    count 0;
+      50:4|  0: <65534>                 |  }
+      52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      60:0|    3: <5, 3>                |    count 3;
+      62:4|    3: <0, 1, 0>             |    var @g0, align 1,
+      65:6|    3: <1, 3>                |      initializers 3 {
+      68:2|    3: <4, 0, 1>             |        reloc @g0 + 1;
+      71:4|    3: <4, 1, 4294967295>    |        reloc @g1 - 1;
+      79:2|    3: <4, 2, 4>             |        reloc @g2 + 4;
+          |                             |      }
+      82:4|    3: <0, 3, 0>             |    var @g1, align 4,
+      85:6|    3: <2, 4>                |      zerofill 4;
+      88:2|    3: <0, 3, 0>             |    var @g2, align 4,
+      91:4|    3: <2, 8>                |      zerofill 8;
+      94:0|  0: <65534>                 |  }
+
+.. _link_for_compound_initializer:
+
+Compound Initializer
+--------------------
+
+The compound initializer record must immediately follow a global
+:ref:`variable<link_for_global_variable_address>` or
+:ref:`constant<link_for_global_constant_address>` address record. It defines how
+many simple initializer records are used to define the initializer. The size of
+the corresponding memory is the sum of the bytes needed for each of the
+succeeding initializers.
+
+Note that a compound initializer can't be used as a simple initializer of
+another compound initializer (i.e. nested compound initializers are not
+allowed).
+
+**Syntax**::
+
+  initializers N {                                <A>
+   ...
+  }
+
+**Record**::
+
+  AA: <1, N>
+
+**Semantics**:
+
+Defines that the next `N` initializers should be associated with the global
+address of the previous record.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  ExpectedInitializers == 1
+
+**Updates**::
+
+  ExpectedInitializers = N;
+
+**Examples**::
+
+  40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+  48:0|    3: <1, 0>                |    count 0;
+  50:4|  0: <65534>                 |  }
+  52:0|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+  60:0|    3: <5, 2>                |    count 2;
+  62:4|    3: <0, 0, 1>             |    const @g0, align 0,
+  65:6|    3: <1, 2>                |      initializers 2 {
+  68:2|    3: <2, 8>                |        zerofill 8;
+  70:6|    3: <3, 3, 2, 1, 0>       |        {  3,   2,   1,   0}
+      |                             |      }
+  75:4|    3: <0, 0, 0>             |    var @g1, align 0,
+  78:6|    3: <1, 2>                |      initializers 2 {
+  81:2|    3: <3, 1, 2, 3, 4>       |        {  1,   2,   3,   4}
+  86:0|    3: <2, 2>                |        zerofill 2;
+      |                             |      }
+  88:4|  0: <65534>                 |  }
+
+.. _link_for_valuesymtab_block_section:
+
+Valuesymtab Block
+=================
+
+The valuesymtab block does not define any values.  Its only goal is to associate
+text names with external :ref:`function
+addresses<link_for_function_address_section>`.  Each association is defined by a
+record in the valuesymtab block.  Currently, only
+:ref:`intrinsic<link_for_intrinsic_functions_section>` function addresses and
+the (external) start function (``_start``) can be named.  All named function
+addresses must be external.  Each record in the valuesymtab block is a *entry*
+record, defining a single name association.
+
+Entry Record
+------------
+
+The *entry* record defines a name for a function address.
+
+**Syntax**::
+
+  V : "NAME";                                     <A>
+
+**Record**::
+
+  AA: <1, B1, ... , BN>
+
+**Semantics**:
+
+The *entry* record defines a name ``NAME`` for function address ``V``. ``NAME`` is a
+sequence of ANSCII characters ``B1`` through ``BN``.

[Jim Stichnoth, 2014/11/17 18:54:56]

ASCII

[Karl, 2014/11/17 20:17:28]

Done.

+
+**Examples**::
+
+      72:0|  3: <8, 4, 0, 1, 0>         |  declare external 
+          |                             |      void @f0(i32, i32, i32, i32, i1);
+      76:6|  3: <8, 4, 0, 1, 0>         |  declare external 
+          |                             |      void @f1(i32, i32, i32, i32, i1);
+      81:4|  3: <8, 5, 0, 0, 0>         |  define external void @f2(i32);
+      86:2|  1: <65535, 19, 2>          |  globals {  // BlockID = 19
+      92:0|    3: <5, 0>                |    count 0;
+      94:4|  0: <65534>                 |  }
+      96:0|  1: <65535, 14, 2>          |  valuesymtab {  // BlockID = 14
+     104:0|    3: <1, 1, 108, 108, 118, |    @f1 : "llvm.memmove.p0i8.p0i8.i32";
+          |        109, 46, 109, 101,   |
+          |        109, 109, 111, 118,  |
+          |        101, 46, 112, 48,    |
+          |        105, 56, 46, 112, 48,|
+          |        105, 56, 46, 105, 51,|
+          |        50>                  |
+     145:4|    3: <1, 2, 95, 115, 116,  |    @f2 : "_start";
+          |        97, 114, 116>        |
+     157:0|    3: <1, 0, 108, 108, 118, |    @f0 : "llvm.memcpy.p0i8.p0i8.i32";
+          |        109, 46, 109, 101,   |
+          |        109, 99, 112, 121,   |
+          |        46, 112, 48, 105, 56,|
+          |        46, 112, 48, 105, 56,|
+          |        46, 105, 51, 50>     |
+     197:0|  0: <65534>                 |  }
+
+.. _link_for_module_block:
+
+Module Block
+============
+
+The module block, like all blocks, is enclosed in a pair of
+:ref:`enter<link_for_enter_block_record_section>` /
+:ref:`exit<link_for_exit_block_record_section>` records, using block ID 8. A
+well-formed module block consists of the following records (in order):
+
+A version record
+   The :ref:`version record<link_for_version_record>` communicates which version
+   of the PNaCl bitcode reader/writer should be used. Note that this is
+   different than the PNaCl bitcode (ABI) version. The PNaCl bitcode (ABI)
+   version defines what is expected in records, and is defined in the header
+   record of the bitcode file. The version record defines the version of the
+   PNaCl bitcode reader/writer to use to convert records into bit sequences.
+
+Optional local abbreviations
+   Defines a list of local :ref:`abbreviations<link_for_abbreviations_section>`
+   to use for records within the module block.
+
+An abbreviations block
+   The :ref:`abbreviations block<link_for_abbreviations_block_section>` defines
+   user-defined, global abbreviations that are used to convert PNaCl records to
+   bit sequences in blocks following the abbreviations block.
+
+A types block
+   The :ref:`types block<link_for_types_block_section>` defines the set of all
+   types used in the program.
+
+A non-empty sequence of function address records
+   Each record defines a :ref:`function
+   address<link_for_function_address_section>` used by the program. Function
+   addresses must either be external, or defined internally by the program. If
+   they are defined by the program, there must be a :ref:`function
+   block<link_for_function_blocks_section>` (appearing later in the module) that
+   defines the sequence of instructions for each defined function.
+
+A globals block defining the global variables.
+   This :ref:`block<link_for_globals_block_section>` defines the set of
+   global :ref:`variable<link_for_global_variable_address>` and
+   :ref:`constant<link_for_global_constant_address>` addresses used by the
+   program. In addition to the addresses, each global variable also defines how
+   the corresponding global variable is initialized.
+
+An optional value symbol table block.
+   This :ref:`block<link_for_valuesymtab_block_section>`, if defined, provides
+   textual names for :ref:`function
+   addresses<link_for_function_address_section>` (previously defined in the
+   module). Note that only names for intrinsic functions and the start function
+   are specified.
+
+A sequence of function blocks.
+   Each :ref:`function block<link_for_Function_blocks_section>` defines the
+   corresponding intermediate representation for each defined function. The
+   order of function blocks is used to associate them with :ref:`function
+   addresses<link_for_function_address_section>`.  The order of the defined
+   function blocks must follow the same order as the corresponding function
+   addresses defined in the module block.
+
+Descriptions of the :ref:`abbreviations<link_for_abbreviations_section>`,
+:ref:`types<link_for_types_block_section>`,
+:ref:`globals<link_for_globals_block_section>`, :ref:`value symbol
+table<link_for_valuesymtab_block_section>`, and
+:ref:`function<link_for_function_blocks_section>` blocks are not provided
+here. See the appropriate reference for more details. The following subsections
+describe each of the records that can appear in a module block.
+
+.. _link_for_version_record:
+
+Version Record
+--------------
+
+The version record defines the implementation of the PNaCl bitstream
+reader/writer to use. That is, the implementation that converts PNaCl records to
+bit sequences, and converts them back to PNaCl records. Note that this is
+different than the PNaCl version of the bitcode file (encoded in the header
+record of the bitcode file).  The PNaCl version defines the valid forms of PNaCl
+records. The version record is specific to the PNaCl version, and may have
+different values for different PNaCl versions.
+
+Note that currently, only PNaCl bitcode version 2, and version record value 1 is
+defined.
+
+**Syntax**::
+
+  version N;                                  <A>
+
+**Record**::
+
+  AA: <1, N>
+
+**Semantics**:
+
+The version record defines which PNaCl reader/writer rules should be
+followed. ``N`` is the version number. Currently ``N`` must be 1. Future
+versions of PNaCl may define additional legal values.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A)
+
+*Examples*::
+
+      16:0|1: <65535, 8, 2>             |module {  // BlockID = 8
+      24:0|  3: <1, 1>                  |  version 1;
+      26:4|  1: <65535, 0, 2>           |  abbreviations {  // BlockID = 0
+      36:0|  0: <65534>                 |  }
+
+.. _link_for_function_address_section:
+
+Function Address
+----------------
+
+A function address record describes a function address. *Defined* function
+addresses define :ref:`implementations<link_for_function_blocks_section>` while
+*declared* function addresses do not.
+
+Since a PNaCl program is assumed to be a complete (statically linked)
+executable, All functions should be *defined* and *internal*.  The exception to
+this are :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, which
+should only be *declared* and *external*, since intrinsic functions will be
+automatically converted to appropriate code by the :ref:`PNaCl
+translator<link_for_pnacl_translator>`.
+
+The implementation of a *defined* function address is provided by a
+corresponding function block, appearing later in the module block. The
+association of a *defined* function address with the corresponding function
+block is based on position.  The *Nth* defined function address record, in the
+module block, has its implementation in the *Nth* function block of that module
+block.
+
+**Syntax**::
+
+  PN LN T0 @fN ( T1 , ... , TM );                 <A>
+
+**Record**::
+
+  AA: <8, T, C, P, L>
+
+**Semantics**:
+
+Describes the function address ``@fN``. ``PN`` is the name that specifies the
+prototype value ``P`` associated with the function. A function address is
+*defined* only if ``P == 0``. Otherwise, it is only *declared*.  The type of the
+function is :ref:`function type<link_for_function_type>` ``@tT``. ``L`` is the
+linkage specification corresponding to name ``LN``. ``C`` is the calling
+convention used by the function.
+
+Note that function signature must be defined by a function type in the types
+block. Hence, the return value must either be a primitive type, type ``void``,
+or a vector type.
+
+For ordinary functions, integer parameter and types can only be ``i32`` and
+``i64``.  All other integer types are not allowed. For intrinsic functions, all
+integer types are allowed.
+
+Valid prototype names ``PN``, and corresponding ``P`` values, are:
+
+= =======
+P PN
+= =======
+1 declare
+0 define
+= =======
+
+Valid linkage names ``LN``, and corresponding ``L`` values, are:
+
+= ========
+L LN
+= ========
+3 internal
+0 external
+= ========
+
+Currently, only one calling convention ``C`` is supported:
+
+= ====================
+C Calling Convention
+= ====================
+0 C calling convention
+= ====================
+
+**Constraints**::
+
+  AA = AbbrevIndex(A) &
+  T = TypeID(TypeOf(T0 ( T1 , ... , TN ))) &
+  N = NumFuncAddresses
+
+**Updates**::
+
+  ++NumFuncAddresses;
+  TypeOf(@fN) = TypeOf(TypeID(i32));
+  TypeOfFcn(@fN) = TypeOf(@tT);
+
+  if PN == 0:
+    DefiningFcnIDs += @FN;
+    ++NumDefinedFunctionAddresses;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <4>                   |    @t2 = double;
+      57:2|    3: <2>                   |    @t3 = void;
+      59:0|    3: <21, 0, 2, 1>         |    @t4 = double (float);
+      63:0|    3: <21, 0, 0, 0, 1, 0, 2>|    @t5 = 
+          |                             |        i32 (i32, float, i32, double);
+      69:2|    3: <21, 0, 3>            |    @t6 = void ();
+      72:4|  0: <65534>                 |  }
+      76:0|  3: <8, 4, 0, 1, 0>         |  declare external double @f0(float);
+      80:6|  3: <8, 5, 0, 1, 0>         |  declare external 
+          |                             |      i32 @f1(i32, float, i32, double);
+      85:4|  3: <8, 6, 0, 0, 0>         |  define external void @f2();
+
+.. _link_for_constants_block_section:
+
+Constants Blocks
+================
+
+Constants blocks define literal constants used within each function. Its intent
+it to define them once, before instructions. A constants block can only appear

[Jim Stichnoth, 2014/11/18 02:24:42]

is to define

[Karl, 2014/11/19 20:28:53]

Done.

+in a :ref:`function block<link_for_function_blocks_section>`, and must appear
+before any instructions in the function block.
+
+Currently, only integer literals, floating point literals, and undefined vector
+constants can be defined.
+
+To minimize type information put in a constants block, the type information is
+separated from the constants. This allows a sequence of constants to be given
+the same type. This is done by defining a :ref:`set type
+record<link_for_constants_set_type_record>`, followed by a sequence of literal
+constants. These literal constants all get converted to the type of the
+preceding set type record.
+
+Note that constants that are used for switch case selectors should not be added
+to the constants block, since the switch instruction contains the constants used
+for case selectors. All other constants in the function block must be put into a
+constants block, so that instructions can use them.
+
+To make this more concrete, consider the following example constants block::
+
+     106:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     116:0|      3: <1, 0>              |      i32:
+     118:4|      3: <4, 2>              |        %c0 = i32 1;
+     121:0|      3: <4, 4>              |        %c1 = i32 2;
+     123:4|      3: <1, 2>              |      i8:
+     126:0|      3: <4, 8>              |        %c2 = i8 4;
+     128:4|      3: <4, 6>              |        %c3 = i8 3;
+     131:0|      3: <1, 1>              |      float:
+     133:4|      3: <6, 1065353216>     |        %c4 = float 1;
+     139:6|    0: <65534>               |      }
+
+.. _link_for_constants_set_type_record:
+
+Set Type Record
+---------------
+
+The *set type* record defines the type to use for the (immediately) succeeding
+literals.
+
+**Syntax**::
+
+  T:                                              <A>
+
+**Record**::
+
+  AA: <1, TT>
+
+**Semantics**:
+
+The *set type* record defines type ``T`` to be used to type the (immediately)
+succeeding literals. ``T`` must be a non-void primitive value type or a vector
+type.
+
+**Constraints**::
+
+  TT == TypeID(T)
+
+**Updates**::
+
+  ConstantsSetType = T;
+
+**Examples**::
+
+     106:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     116:0|      3: <1, 0>              |      i32:
+     118:4|      3: <4, 2>              |        %c0 = i32 1;
+     121:0|      3: <4, 4>              |        %c1 = i32 2;
+     123:4|      3: <1, 2>              |      i8:
+     126:0|      3: <4, 8>              |        %c2 = i8 4;
+     128:4|      3: <4, 6>              |        %c3 = i8 3;
+     131:0|      3: <1, 1>              |      float:
+     133:4|      3: <6, 1065353216>     |        %c4 = float 1;
+     139:6|    0: <65534>               |      }
+
+.. _link_for_undefined_literal:
+
+Undefined Literal
+-----------------
+
+The *undefined* literal record creates an undefined literal for the type *T*
+defined by the preceding *set type* record.
+
+Note: See :ref:`insert element
+instruction<link_for_insert_element_instruction_section>` for an example of how
+you would use the undefined literal with vector types.
+
+**Syntax**::
+
+  %cN = T undef;                              <50>
+
+**Record**::
+
+  AA: <3>
+
+**Semantics**:
+
+The *undefined* literal record creates an undefined literal constant ``%cN`` for
+type ``T``.  ``T`` must be the type defined by the preceding *set type* record, and
+be a primitive value type or a vector type.
+
+**Constraints**::
+
+   N == NumFcnConsts &
+   T == ConstantsSetType &
+   IsPrimitive(T) or IsVector(T)
+
+**Updates**::
+
+   ++NumFcnConsts;
+   TypeOf(%cN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 5>                |    count 5;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <2>                   |    @t2 = void;
+      57:2|    3: <12, 4, 0>            |    @t3 = <4 x i32>;
+      60:4|    3: <21, 0, 2>            |    @t4 = void ();
+      63:6|  0: <65534>                 |  }
+      ...
+     106:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     116:0|      3: <1, 0>              |      i32:
+     118:4|      3: <3>                 |        %c0 = i32 undef;
+     120:2|      3: <4, 2>              |        %c1 = i32 1;
+     122:6|      3: <1, 3>              |      <4 x i32>:
+     125:2|      3: <3>                 |        %c2 = <4 x i32> undef;
+     127:0|      3: <1, 1>              |      float:
+     129:4|      3: <3>                 |        %c3 = float undef;
+     131:2|    0: <65534>               |      }
+
+.. _link_for_integer_literal:
+
+Integer Literal
+---------------
+
+The *integer literal* record creates an integer literal for the integer type *T*
+defined by the preceding *set type* record.
+
+**Syntax**::
+
+  %cN = T V;                                      <A>
+
+**Record**::
+
+  AA: <4, VV>
+
+**Semantics**:
+
+The *integer literal* record creates an integer literal constant ``%cN`` for
+type ``T``.  ``T`` must be the type defined by the preceding *set type* record,
+and an integer type. The literal ``V`` can be signed, but must be definable by
+type ``T``.
+
+**Constraints**::
+
+  N == NumFcnConsts &
+  T == ConstantsSetType &
+  VV == SignRotate(V) &
+  IsInteger(T)
+
+**Updates**::
+
+  TypeOf(%cN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 8>                |    @t0 = i8;
+      53:0|    3: <7, 16>               |    @t1 = i16;
+      55:4|    3: <7, 32>               |    @t2 = i32;
+      58:6|    3: <7, 64>               |    @t3 = i64;
+      62:0|    3: <7, 1>                |    @t4 = i1;
+      64:4|    3: <2>                   |    @t5 = void;
+      66:2|    3: <21, 0, 5>            |    @t6 = void ();
+      69:4|  0: <65534>                 |  }
+      ...
+     114:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     124:0|      3: <1, 0>              |      i8:
+     126:4|      3: <4, 2>              |        %c0 = i8 1;
+     129:0|      3: <4, 4>              |        %c1 = i8 2;
+     131:4|      3: <1, 1>              |      i16:
+     134:0|      3: <4, 6>              |        %c2 = i16 3;
+     136:4|      3: <4, 8>              |        %c3 = i16 4;
+     139:0|      3: <1, 2>              |      i32:
+     141:4|      3: <4, 10>             |        %c4 = i32 5;
+     144:0|      3: <4, 12>             |        %c5 = i32 6;
+     146:4|      3: <1, 3>              |      i64:
+     149:0|      3: <4, 3>              |        %c6 = i64 -1;
+     151:4|      3: <4, 5>              |        %c7 = i64 -2;
+     154:0|      3: <1, 4>              |      i1:
+     156:4|      3: <4, 3>              |        %c8 = i1 1;
+     159:0|      3: <4, 0>              |        %c9 = i1 0;
+     161:4|    0: <65534>               |      }
+
+Floating Point Literal
+----------------------
+
+The *floating point literal* record creates a floating point literal for the
+floating point type *T* defined by the preceding *set type* record.
+
+**Syntax**::
+
+  %cN = T V;                                      <A>
+
+**Record**::
+
+  AA: <6, VV>
+
+**Semantics**:
+
+The *floating point literal* record creates a floating point literal constant
+``%cN`` for type ``T``. ``T`` must the type type defined by the preceding *set
+type* record, and be a floating point type. The literal ``V`` is the floating
+value to be defined. The value ``VV`` if the corresponding IEEE unsigned integer
+that defines value ``V``. That is, the literal ``VV`` must be a valid IEEE 754
+32-bit (unsigned integer) value if ``T`` is ``float``, and a valid IEEE 754
+64-bit (unsigned integer) value if ``T`` is ``double``.
+
+**Constraints**::
+
+  N == NumFcnConsts
+  T == ConstantsSetType
+  IsFloat(T)
+
+**Updates**::
+
+  TypeOf(%cN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <3>                   |    @t0 = float;
+      52:2|    3: <4>                   |    @t1 = double;
+      54:0|    3: <2>                   |    @t2 = void;
+      55:6|    3: <21, 0, 2>            |    @t3 = void ();
+      59:0|  0: <65534>                 |  }
+      ...
+     102:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     112:0|      3: <1, 0>              |      float:
+     114:4|      3: <6, 0>              |        %c0 = float 0;
+     117:0|      3: <6, 1065353216>     |        %c1 = float 1;
+     123:2|      3: <6, 1088421888>     |        %c2 = float 7;
+     130:2|      3: <6, 1090519040>     |        %c3 = float 8;
+     137:2|      3: <3>                 |        %c4 = float undef;
+     139:0|      3: <6, 2143289344>     |        %c5 = float nan;
+     146:0|      3: <6, 2139095040>     |        %c6 = float inf;
+     153:0|      3: <6, 4286578688>     |        %c7 = float -inf;
+     160:0|      3: <1, 1>              |      double:
+     162:4|      3: <6,                 |        %c8 = double 1;
+          |        4607182418800017408> |
+     174:0|      3: <6, 0>              |        %c9 = double 0;
+     176:4|      3: <6,                 |        %c10 = double 5;
+          |        4617315517961601024> |
+     188:0|      3: <6,                 |        %c11 = double 6;
+          |        4618441417868443648> |
+     199:4|      3: <6,                 |        %c12 = double nan;
+          |        9221120237041090560> |
+     211:0|      3: <6,                 |        %c13 = double inf;
+          |        9218868437227405312> |
+     222:4|      3: <6,                 |        %c14 = double -inf;
+          |        18442240474082181120>|
+     234:0|    0: <65534>               |      }
+
+.. _link_for_function_blocks_section:
+
+Function Blocks
+===============
+
+A function block defines the implementation of a defined :ref:`function
+address<link_for_function_address_section>`. The function address it defines is
+based on the position of the corresponding defined function address. The Nth
+defined function address always corresponds to the Nth function block in the
+module block.
+
+A function implementation contains a list of basic blocks, forming the control
+flow graph. Each *basic block* contains a list of instructions, and ends with a
+:ref:`terminator instruction<link_for_terminator_instruction_section>`
+(e.g. branch).
+
+Basic blocks are not represented by records. Rather, context is implicit. The
+first basic block begins with the first instruction record in the function
+block.  Block boundaries are determined by terminator instructions. The
+instruction that follows a terminator instruction begins a new basic block.
+
+The first basic block in a function is special in two ways: it is immediately
+executed on entrance to the function, and it is not allowed to have predecessor
+basic blocks (i.e. there can't be any branches to the entry block of a
+function). Because the entry block has no predecessors, it also can't have any
+:ref:`phi<link_for_phi_instruction_section>` instructions.
+
+The parameters are implied by the type of the corresponding function
+address. One parameter is defined for each argument of the function :ref:`type
+signature<link_for_function_type>` of the corresponding :ref:`function
+address<link_for_function_address_section>`.
+
+The number of basic blocks is defined by the :ref:`count
+record<link_for_basic_blocks_count>`. Each ::ref::`terminator

[Jim Stichnoth, 2014/11/18 02:24:43]

::ref:: ==> :ref: (I think)

[Karl, 2014/11/19 20:28:52]

Done.

+instruction<link_for_terminator_instruction_section>` ends the current basic
+block, and the next instruction begins a new basic block.  Basic blocks are
+numbered by the order they appear (starting with index 0). Basic block IDs have
+the form ``%bN``, where ``N`` corresponds to the position of the basic block
+within the function block.
+
+Each instruction, within a function block, corresponds to a corresponding PNaCl
+record.  The layout of a function block is the (basic block) count record,
+followed by a sequence of instruction records.
+
+For readability, PNaClAsm introduces basic block IDs. These basic block IDs do
+not correspond to PNaCl records, since basic block boundaries are defined
+implicitly, after terminator instructions. They appear only for readability.
+
+Operands of instructions are defined using an :ref:`absolute
+index<link_for_absolute_index_section>`. This absolute index implicitly encodes
+function addresses, global addresses, parameters, constants, and instructions
+that generate values. The encoding takes advantage of the implied ordering of
+these values in the bitcode file, defining a contiguous sequence of indices for
+each kind of identifier.  That is, indices are ordered by putting function
+address identifiers first, followed by global address identifiers, followed by
+parameter identifiers, followed by constant identifiers, and lastly instruction
+value identifiers.
+
+To save space in the encoded bitcode file, most operands are encoded using a
+:ref:`relative index<link_for_relative_index>` value, rather than
+:ref:`absolute<link_for_absolute_index_section>`. This
+is done because most instruction operands refer to values defined earlier in the
+(same) basic block.  As a result, the relative distance (back) from the next
+value defining instruction is frequently a small number. Small numbers tend to
+require fewer bits when they are converted to bit sequences.
+
+Note that instructions that can appear in a function block are defined in sections
+:ref:`link_for_terminator_instruction_section`,
+:ref:`link_for_integer_binary_instructions`,
+:ref:`link_for_floating_point_binary_instructions`,
+:ref:`link_for_memory_creation_and_access_instructions`,
+:ref:`link_for_conversion_instructions`,
+:ref:`link_for_compare_instructions`,
+:ref:`link_for_vector_instructions`, and
+:ref:`link_for_other_pnaclasm_instructions`.
+
+The following subsections define the remaining records that can appear in a
+function block.
+
+Function Enter
+--------------
+
+PNaClAsm defines a function enter block construct. The corresponding record is
+simply an :ref:`enter block<link_for_enter_block_record_section>` record, with
+BlockID value ``12``. All context about the defining address is implicit by the
+position of the function block, and the corresponding defining :ref:`function
+address<link_for_function_address_section>`. To improve readability, PNaClAsm
+includes the function signature into the syntax rule.
+
+**Syntax**::
+
+  function TR @fN ( T0 %p0, ... , TM %pM ) {             <B>
+
+**Record**::
+
+  1: <65535, 12, B>
+
+**Semantics**:
+
+``B`` is the number of bits reserved for abbreviations in the block. If it is
+omitted, 2 is assumed. See :ref:`enter<link_for_enter_block_record_section>`
+block records for more details.
+
+The value of ``N`` corresponds to the positional index of the corresponding
+defining function address this block is associated with. ``M`` is the number of
+defined parameters (minus one) in the function heading.
+
+**Constraints**::
+
+  N == NumFcnImpls &
+  @fN in DefiningFcnIDs &
+  TypeOfFcn(@fN) == TypeOf(TypeID(TR (T0, ... , TM)))
+
+**Updates**::
+
+  ++NumFcnImpls;
+  EnclosingFcnID = @fN;
+  NumBasicBlocks = 0;
+  ExpectedBlocks = 0;
+  NumParams = M;
+  for I in [0..M]:
+    TypeOf(%pI) = TypeOf(TypeID(TI));
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <21, 0, 1>            |    @t2 = void ();
+      58:6|    3: <21, 0, 0, 0>         |    @t3 = i32 (i32);
+      62:6|  0: <65534>                 |  }
+      ...
+     104:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     114:4|    3: <10>                  |    ret void;
+     116:2|  0: <65534>                 |  }
+     120:0|  1: <65535, 12, 2>          |  function i32 @f1(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     128:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     130:4|    3: <10, 1>               |    ret i32 %p0;
+     133:0|  0: <65534>                 |  }
+
+.. _link_for_basic_blocks_count:
+
+Count Record
+------------
+
+The count record, within a function block, defines the number of basic blocks
+used to define the function implementation. It must be the first record in the
+function block.
+
+**Syntax**::
+
+    blocks: N;                                    <A>
+  %b0:
+
+**Record**::
+
+  AA: <1, N>
+
+**Semantics**:
+
+The count record defines the number ``N`` of basic blocks in the implemented
+function.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  ExpectedBasicBlocks == N &
+  NumBasicBlocks == 0
+
+**Updates**::
+
+     104:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     114:4|    3: <10>                  |    ret void;
+     116:2|  0: <65534>                 |  }
+     120:0|  1: <65535, 12, 2>          |  function i32 @f1(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     128:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     130:4|    3: <10, 1>               |    ret i32 %p0;
+     133:0|  0: <65534>                 |  }
+
+.. _link_for_terminator_instruction_section:
+
+Terminator Instructions
+=======================
+
+Terminator instructions are instructions that appear in a :ref:`function
+block<link_for_function_blocks_section>`, and define the end of the current
+basic block. A terminator instruction indicates which block should be executed
+after the current block is finished. The function block is well formed only if
+the number of terminator instructions, in the function block, corresponds to the
+value defined by the corresponding function basic block :ref:`count
+record<link_for_basic_blocks_count>`.
+
+Note that any branch instruction to label ``%bN``, where ``N >=
+ExpectedBasicBlocks``, is illegal. For ease of readability, this constraint
+hasn't been put on branch instructions. Rather it is only implied.
+
+In addition, it must be the case that ``NumBasicBlocks < ExpectedBasicBlocks``,
+and will not be listed as a constraint. Further, if ``B = NumBasicBlocks + 1``
+is the number associated with the next basic block.  Label `%bB:` only appears
+if::
+
+  B < ExpectedBasicBlocks
+
+That is, the label is omitted only if this terminator instruction is the last
+instruction in the function block.
+
+Return Void Instruction
+-----------------------
+
+The return void instruction is used to return control from a function back to
+the caller, without returning any value.
+
+**Syntax**::
+
+    ret void;                                     <A>
+  %bB:
+
+**Record**::
+
+   AA: <10>
+
+**Semantics**:
+
+The return void instruction returns control to the calling function.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  B == NumBasicBlocks + 1 &
+  ReturnType(TypeOf(EnclosingFcnID)) == void
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+     104:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     114:4|    3: <10>                  |    ret void;
+     116:2|  0: <65534>                 |  }
+
+Return Value Instruction
+------------------------
+
+The return value instruction is used to return control from a function back to
+the caller, including a value. The value must correspond to the return type of
+the enclosing function.
+
+**Syntax**::
+
+    ret T V;                                      <A>
+  %bB:
+
+**Record**::
+
+   AA: <10, VV>
+
+**Semantics**:
+
+The return value instruction returns control to the calling function, returning
+the provided value.
+
+``V`` is the value to return. Type ``T`` must be of the type returned by the
+function.  It must also be the type associated with value ``V``.
+
+The return type ``T`` must either be a (non-void) primitive type, or a vector
+type. If the function block is implementing an ordinary function, and the return
+type is an integer type, it must be either ``i32`` or ``i64``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV == RelativeIndex(V) &
+  B == NumBasicBlocks + 1 &
+  T == TypeOf(V) == ReturnType(TypeOf(EnclosingFcnID))
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+     120:0|  1: <65535, 12, 2>          |  function i32 @f1(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     128:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     130:4|    3: <10, 1>               |    ret i32 %p0;
+
+Unconditional Branch Instruction
+--------------------------------
+
+The unconditional branch instruction is used to cause control flow to transfer
+to a different basic block of the function.
+
+**Syntax**::
+
+    br %bN;                                       <A>
+  %bB:
+
+**Record**::
+
+  AA: <11, N>
+
+**Semantics**:
+
+The unconditional branch instruction causes control flow to transfer to basic
+block ``N``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  B == NumBasicBlocks + 1 &
+  0 < N &
+  N < ExpectedBasicBlocks
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+      88:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+      96:0|    3: <1, 5>                |    blocks 5;
+          |                             |  %b0:
+      98:4|    3: <11, 3>               |    br label %b3;
+          |                             |  %b1:
+     101:0|    3: <11, 4>               |    br label %b4;
+          |                             |  %b2:
+     103:4|    3: <11, 1>               |    br label %b1;
+          |                             |  %b3:
+     106:0|    3: <11, 2>               |    br label %b2;
+          |                             |  %b4:
+     108:4|    3: <10>                  |    ret void;
+     110:2|  0: <65534>                 |  }
+
+Conditional Branch Instruction
+------------------------------
+
+The conditional branch instruction is used to cause control flow to transfer to
+a different basic block of the function, based on a boolean test condition.
+
+**Syntax**::
+
+    br i1 C, %bT, %bBF;                          <A>
+  %bB:
+
+**Record**::
+
+  AA: <11, T, F, CC>
+
+**Semantics**:
+
+Upon execution of a conditional branch instruction, the *i1* (boolean) argument
+``C`` is evaluated. If the value is ``true``, control flows to basic block
+``%bT``. Otherwise control flows to basic block ``%bF``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  CC == RelativeIndex(C) &
+  B == NumBasicBlocks + 1 &
+  0 < T &
+  B1 < ExpectedBasicBlocks &
+  0 < F &
+  B2 < ExpectedBasicBlocks &
+  TypeOf(C) == i1
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+      92:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     100:0|    3: <1, 5>                |    blocks 5;
+     102:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     112:0|      3: <1, 1>              |      i1:
+     114:4|      3: <4, 3>              |        %c0 = i1 1;
+     117:0|      3: <4, 0>              |        %c1 = i1 0;
+     119:4|    0: <65534>               |      }
+          |                             |  %b0:
+     120:0|    3: <11, 3>               |    br label %b3;
+          |                             |  %b1:
+     122:4|    3: <11, 2, 4, 2>         |    br i1 %c0, label %b2, label %b4;
+          |                             |  %b2:
+     126:4|    3: <11, 3>               |    br label %b3;
+          |                             |  %b3:
+     129:0|    3: <10>                  |    ret void;
+          |                             |  %b4:
+     130:6|    3: <11, 2, 3, 1>         |    br i1 %c1, label %b2, label %b3;
+     134:6|  0: <65534>                 |  }
+
+Unreachable
+-----------
+
+The unreachable instruction has no defined semantics. The instruction is used to
+inform the :ref:`PNaCl translator<link_for_pnacl_translator>` that control
+can't reach this instruction.
+
+**Syntax**::
+
+    unreachable;                                  <A>
+  %bB:
+
+**Record**::
+
+  AA: <15>
+
+**Semantics**:
+
+Directive to the :ref:`PNaCl translator<link_for_pnacl_translator>` that
+this instruction is unreachable.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A)
+  B == NumBasicBlocks + 1 &
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+     108:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     116:0|    3: <1, 5>                |    blocks 5;
+     118:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     128:0|      3: <1, 2>              |      i1:
+     130:4|      3: <4, 3>              |        %c0 = i1 1;
+     133:0|      3: <4, 0>              |        %c1 = i1 0;
+     135:4|    0: <65534>               |      }
+          |                             |  %b0:
+     136:0|    3: <11, 1, 2, 2>         |    br i1 %c0, label %b1, label %b2;
+          |                             |  %b1:
+     140:0|    3: <11, 3, 4, 1>         |    br i1 %c1, label %b3, label %b4;
+          |                             |  %b2:
+     144:0|    3: <15>                  |    unreachable;
+          |                             |  %b3:
+     145:6|    3: <15>                  |    unreachable;
+          |                             |  %b4:
+     147:4|    3: <10>                  |    ret void;
+     149:2|  0: <65534>                 |  }
+
+Switch Instruction
+------------------
+
+The *switch* instruction transfers control flow to one of several different
+places, based on a selector value. It is a generalization of the conditional
+branch instruction.
+
+**Syntax**::
+
+    switch T V0 {
+      default: br label %bB0;
+      T V1:    br label %bB1;
+      ...
+      T VN:    br label %bBN;
+    }                                             <A>
+  %bB:
+
+**Record**::
+
+  AA: <12, TT, B0, N, (1, 1, VVI, BI | 1 <= i <= N)>
+
+**Semantics**:
+
+The switch instruction transfers control to a basic block in ``B0`` through
+``BN``.  Value ``V`` is used to conditionally select which block to branch
+to. ``T`` is the type of ``V`` and ``V1`` through ``VN``, and must be an integer
+type. Value ``V1`` through ``VN`` are integers to compare against ``V``. If selector
+``V`` matches ``VI`` (for some ``I``, ``1 <= I <= N``), then the instruction branches to
+block ``BI``. If ``V`` is not in ``V1`` through ``VN``, the instruction branches to
+block ``B0``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  B == NumBasicBlocks + 1 &
+  TT == TypeID(T) &
+  VI == SignRotate(VI) for all I, 1 <= I <= N &
+
+**Updates**::
+
+  ++NumBasicBlocks;
+
+**Examples**::
+
+     116:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     124:0|    3: <1, 6>                |    blocks 6;
+          |                             |  %b0:
+     126:4|    3: <12, 1, 1, 2, 4, 1, 1,|    switch i32 %p0 {
+          |        2, 3, 1, 1, 4, 3, 1, |      default: br label %b2;
+          |        1, 8, 4, 1, 1, 10, 4>|      i32 1: br label %b3;
+          |                             |      i32 2: br label %b3;
+          |                             |      i32 4: br label %b4;
+          |                             |      i32 5: br label %b4;
+          |                             |    }
+          |                             |  %b1:
+     143:2|    3: <11, 5>               |    br label %b5;
+          |                             |  %b2:
+     145:6|    3: <11, 5>               |    br label %b5;
+          |                             |  %b3:
+     148:2|    3: <11, 5>               |    br label %b5;
+          |                             |  %b4:
+     150:6|    3: <11, 5>               |    br label %b5;
+          |                             |  %b5:
+     153:2|    3: <10>                  |    ret void;
+     155:0|  0: <65534>                 |  }
+     156:0|  1: <65535, 12, 2>          |  function void @f1(i64 %p0) {  
+          |                             |                   // BlockID = 12
+     164:0|    3: <1, 6>                |    blocks 6;
+          |                             |  %b0:
+     166:4|    3: <12, 2, 1, 2, 4, 1, 1,|    switch i64 %p0 {
+          |        2, 3, 1, 1, 4, 3, 1, |      default: br label %b2;
+          |        1, 8, 4, 1, 1,       |      i64 1: br label %b3;
+          |        39777555332, 4>      |      i64 2: br label %b3;
+          |                             |      i64 4: br label %b4;
+          |                             |      i64 19888777666: br label %b4;
+          |                             |    }
+          |                             |  %b1:
+     188:4|    3: <11, 5>               |    br label %b5;
+          |                             |  %b2:
+     191:0|    3: <11, 5>               |    br label %b5;
+          |                             |  %b3:
+     193:4|    3: <11, 5>               |    br label %b5;
+          |                             |  %b4:
+     196:0|    3: <11, 5>               |    br label %b5;
+          |                             |  %b5:
+     198:4|    3: <10>                  |    ret void;
+     200:2|  0: <65534>                 |  }
+
+.. _link_for_integer_binary_instructions:
+
+Integer Binary Instructions
+===========================
+
+Binary instructions are used to do most of the computation in a program. This
+section focuses on binary instructions that operator on integer values, or
+vectors of integer values.
+
+All binary operations require two operands of the same type, execute an
+operation on them, and produce a value. The value may represent multiple values
+if the type is a vector type.  The result value always has the same type as its
+operands.
+
+Some integer binary operations can be applied to both signed and unsigned
+integers. Others, the sign is significant. In general, if the sign plays a role
+in the instruction, the sign information is encoded into the name of the
+instruction.
+
+For most binary operations (except some of the logical operations), integer
+type i1 is disallowed.
+
+Integer Add
+-----------
+
+The integer add instruction returns the sum of its two arguments. Both arguments
+and the result must be of the same type. That type must be integer, or an
+integer vector type.
+
+**Syntax**::
+
+  %vN = add T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 0>
+
+**Semantics**:
+
+The integer add instruction returns the sum of its two arguments. Arguments
+``V1`` and ``V2``, and the result ``%vN``, must be of type ``T``. ``T`` must be
+an integer type, or an integer vector type.  ``N`` is defined by the record
+position, defining the corresponding value generated by the instruction.
+
+The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` is
+the bitwidth of the integer result.

[Jim Stichnoth, 2014/11/17 18:54:55]

Could you make this "bit width" or "bit-width", here and below?

[Karl, 2014/11/17 20:17:28]

Done.

+
+Because integers are assumed to use a two's complement representation,
+this instruction is appropriate for both signed and unsigned integers.
+
+In the add instruction, integer type ``i1`` (and a vector of integer type
+``i1``) is disallowed.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 0>          |    %v0 = add i32 %p0, %p1;
+  110:4|    3: <2, 3, 1, 0>          |    %v1 = add i32 %p0, %v0;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Integer Subtract
+----------------
+
+The integer subtract instruction returns the difference of its two arguments.
+Both arguments and the result must be of the same type. That type must be
+integer, or an integer vector type.
+
+Note: Since there isn't a negate instruction, subtraction from constant zero
+should be used to negate values.
+
+**Syntax**::
+
+  %vN = sub T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 1>
+
+**Semantics**:
+
+The integer subtract returns the difference of its two arguments. Arguments ``V1``
+and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be an integer
+type, or an integer vector type. ``N`` is defined by the record position,
+defining the corresponding value generated by the instruction.
+
+The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` is
+the bitwidth of the integer result.
+
+Because integers are assumed to use a two's complement representation,
+this instruction is appropriate for both signed and unsigned integers.
+
+In the subtract instruction, integer type ``i1`` (and a vector of integer type
+``i1``) is disallowed.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 1>          |    %v0 = sub i32 %p0, %p1;
+  110:4|    3: <2, 3, 1, 1>          |    %v1 = sub i32 %p0, %v0;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Integer Multiply
+----------------
+
+The integer multiply instruction returns the product of its two arguments.  Both
+arguments and the result must be of the same type. That type must be integer,
+or an integer based vector type.
+
+**Syntax**::
+
+  &vN = mul T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 2>
+
+**Semantics**:
+
+The integer multiply instruction returns the product of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type
+``T``.  ``T`` must be an integer type, or an integer vector type. ``N`` is
+defined by the record position, defining the corresponding value generated by
+the instruction.
+
+The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` is
+the bitwidth of the integer result.
+
+Because integers are assumed to use a two's complement representation,
+this instruction is appropriate for both signed and unsigned integers.
+
+In the subtract instruction, integer type ``i1`` (or a vector on integer type
+``i1``) is disallowed.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 2>          |    %v0 = mul i32 %p0, %p1;
+  110:4|    3: <2, 1, 3, 2>          |    %v1 = mul i32 %v0, %p0;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Signed Integer Divide
+---------------------
+
+The signed integer divide instruction returns the quotient of its two arguments.
+Both arguments and the result must be of the same type. That type must be
+integer, or an integer vector type.
+
+**Syntax**::
+
+  %vN = sdiv T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 4>
+
+**Semantics**:
+
+The signed integer divide instruction returns the quotient of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type
+``T``. ``T`` must be a integer type, or an integer vector type. ``N`` is defined
+by the record position, defining the corresponding value generated by the
+instruction.
+
+Signed values are assumed.  Note that signed and unsigned integer division are
+distinct operations. For unsigned integer division use the unsigned integer
+divide instruction (udiv).
+
+In the signed integer divide instruction, integer type ``i1`` (and a vector of
+integer type ``i1``) is disallowed. Integer division by zero is guaranteed to
+trap.
+
+Note that overflow can happen with this instruction when dividing the maximum
+negative integer by ``-1``. The behavior for this case is currently undefined.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**:: 
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 4>          |    %v0 = sdiv i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 4>          |    %v1 = sdiv i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Unsigned Integer Divide
+-----------------------
+
+The unsigned integer divide instruction returns the quotient of its two
+arguments. Both the arguments and the result must be of the same type. That type
+must be integer, or an integer vector type.
+
+**Syntax**::
+
+  %vN = udiv T V1, V2;                            <a>
+
+**Record**::
+
+  AA: <2, A1, A2, 3>
+
+**Semantics**:
+
+The unsigned integer divide instruction returns the quotient of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type
+``T``. ``T`` must be an integer type, or an integer vector type.  ``N`` is
+defined by the record position, defining the corresponding value generated by
+the instruction.
+
+Unsigned integer values are assumed.  Note that signed and unsigned integer
+division are distinct operations. For signed integer division use the signed
+integer divide instruction (sdiv).
+
+In the unsigned integer divide instruction, integer type ``i1`` (and a vector of
+integer type ``i1``) is disallowed. Division by zero is guaranteed to trap.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 3>          |    %v0 = udiv i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 3>          |    %v1 = udiv i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Signed Integer Remainder
+------------------------
+
+The signed integer remainder instruction returns the remainder of the quotient
+of its two arguments. Both arguments and the result must be of the same
+type. That type must be integer, or an integer based vector type.
+
+**Syntax**::
+
+  %vN = srem T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 6>
+
+**Semantics**:
+
+The signed integer remainder instruction returns the remainder of the quotient
+of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must
+be of type ``T``. ``T`` must be a integer type, or an integer vector type. ``N``
+is defined by the record position, defining the corresponding value generated by
+the instruction.
+
+Signed values are assumed.  Note that signed and unsigned integer division are
+distinct operations. For unsigned integer division use the unsigned integer
+remainder instruction (urem).
+
+In the signed integer remainder instruction, integer type ``i1`` (and a vector of
+integer type ``i1``) is disallowed.  Division by zero is guaranteed to trap.
+
+Note that overflow can happen with this instruction when dividing the maximum
+negative integer by ``-1``. The behavior for this case is currently undefined.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 6>          |    %v0 = srem i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 6>          |    %v1 = srem i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Unsigned Integer Remainder Instruction
+--------------------------------------
+
+The unsigned integer remainder instruction returns the remainder of the quotient
+of its two arguments. Both the arguments and the result must be of the same
+type. The type must be integer, or an integer vector type.
+
+**Syntax**::
+
+  %vN = urem T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, A1, A2, 5>
+
+**Semantics**:
+
+The unsigned integer remainder instruction returns the remainder of the quotient
+of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must
+be of type ``T``. ``T`` must be an integer type, or an integer vector type.
+``N`` is defined by the record position, defining the corresponding value
+generated by the instruction.
+
+Unsigned values are assumed. Note that signed and unsigned integer division are
+distinct operations. For signed integer division use the remainder instruction
+(srem).
+
+In the unsigned integer remainder instruction, integer type ``i1`` (and a vector of
+integer type ``i1``) is disallowed.  Division by zero is guaranteed to trap.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+      96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     106:4|    3: <2, 2, 1, 5>          |    %v0 = urem i32 %p0, %p1;
+     110:4|    3: <2, 1, 2, 5>          |    %v1 = urem i32 %v0, %p1;
+     114:4|    3: <10, 1>               |    ret i32 %v1;
+     117:0|  0: <65534>                 |  }
+
+Shift Left
+----------
+
+The (integer) shift left instruction returns the first operand, shifted to the
+left a specified number of bits with zero fill. The shifted value must be
+integer, or an integer vector type.
+
+**Syntax**::
+
+  %vN = shl T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 7>
+
+**Semantics**:
+
+This instruction performs a shift left operation. Arguments ``V1`` and ``V2``
+and the result ``%vN`` must be of type ``T``. ``T`` must be an integer, or a
+vector of integers. ``N`` is defined by the record position, defining the
+corresponding value generated by the instruction.
+
+``V2`` is assumed to be unsigned.  The least significant bits of the result will
+be filled with zero bits after the shift. If ``V2`` is (statically or
+dynamically) negative or equal to or larger than the number of bits in
+``V1``, the result is undefined. If the arguments are vectors, each vector
+element of ``V1`` is shifted by the corresponding shift amount in ``V2``.
+
+In the shift left instruction, integer type ``i1`` (and a vector of integer type
+``i1``) is disallowed.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 7>          |    %v0 = shl i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 7>          |    %v1 = shl i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Logical Shift Right
+-------------------
+ 
+The logical shift right instruction returns the first operand, shifted to the
+right a specified number of bits with zero fill.
+
+**Syntax**::
+
+  %vN = lshr T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 8>
+
+**Semantics**:
+
+This instruction performs a logical shift right operation. Arguments ``V1`` and
+``V2`` and the result ``%vN`` must be of type ``T``. ``T`` must be an integer,
+or a vector of integers. ``N`` is defined by the record position, defining the
+corresponding value generated by the instruction.
+
+``V2`` is assumed to be unsigned. The most significant bits of the result will be
+filled with zero bits after the shift. If ``V2`` is (statically or dynamically)
+negative or equal to or larger than the number of bits in ``V1``, the result is
+undefined. If the arguments are vectors, each vector element of ``V1`` is shifted
+by the corresponding shift amount in ``V2``.
+
+In the logical shift right instruction, integer type ``i1`` (and a vector of
+integer type ``i1``) is disallowed.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 8>          |    %v0 = lshr i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 8>          |    %v1 = lshr i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Arithmetic Shift Right
+----------------------
+ 
+The arithmetic shift right instruction returns the first operand, shifted to the
+right a specified number of bits with sign extension.
+
+**Syntax**::
+
+  %vN = ashr T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, VV1, VVA2, 9>
+
+**Semantics**:
+
+This instruction performs an arithmetic shift right operation. Arguments ``V1``
+and ``V2`` and and the result ``%vN`` must be of type ``T``. ``T`` must be an
+integer, or a vector of integers. ``N`` is defined by the record position,
+defining the corresponding value generated by the instruction.
+
+``V2`` is assumed to be unsigned. The most significant bits of the result will be
+filled with the sign bit of ``V1``. If ``V2`` is (statically or dynamically)
+negative or equal to or larger than the number of bits in ``V1``, the result is
+undefined. If the arguments are vectors, each vector element of ``V1`` is shifted
+by the corresponding shift amount in ``V2``.
+
+In the arithmetic shift right instruction, integer type ``i1`` (and a vector of
+integral type ``i1``) is disallowed.

[Jim Stichnoth, 2014/11/18 02:24:42]

Hmm, the html version says "integrl" here, so I guess they are out of sync?

[Karl, 2014/11/19 20:28:52]

Will regenerate to verify.

+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T)) &
+  UnderlyingType(T) != i1 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 9>          |    %v0 = ashr i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 9>          |    %v1 = ashr i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Logical And
+-----------
+
+The *and* instruction returns the bitwise logical and of its two operands.
+
+**Syntax**::
+ 
+  %vN = and T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 10>
+
+**Semantics**:
+
+This instruction performs a bitwise logical and of its arguments.  Arguments
+``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be an
+integer, or a vector of integers. ``N`` is defined by the record position,
+defining the corresponding value generated by the instruction.  ``A`` is the
+(optional) abbreviation associated with the corresponding record.
+
+The truth table used for the *and* instruction is:
+
+===== ===== ======
+Arg 1 Arg 2 Result
+===== ===== ======
+0     0     0
+0     1     0
+1     0     0
+1     1     1
+===== ===== ======
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T))) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+       |                             |                   // BlockID = 12
+  104:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  106:4|    3: <2, 2, 1, 10>         |    %v0 = and i32 %p0, %p1;
+  110:4|    3: <2, 1, 2, 10>         |    %v1 = and i32 %v0, %p1;
+  114:4|    3: <10, 1>               |    ret i32 %v1;
+  117:0|  0: <65534>                 |  }
+
+Logical Or
+----------
+ 
+The *or* instruction returns the bitwise logical inclusive or of its
+two operands.
+
+**Syntax**::
+
+  %vN = or T V1, V2;                              <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 11>
+
+**Semantics**:
+
+This instruction performs a bitwise logical inclusive or of its arguments.
+Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T``
+must be an integer, or a vector of integers. ``N`` is defined by the record
+position, defining the corresponding value generated by the instruction.
+
+The truth table used for the *or* instruction is:
+
+===== ===== ======
+Arg 1 Arg 2 Result
+===== ===== ======
+0     0     0
+0     1     1
+1     0     1
+1     1     1
+===== ===== ======
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T))) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+      96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     106:4|    3: <2, 2, 1, 11>         |    %v0 = or i32 %p0, %p1;
+     110:4|    3: <2, 1, 2, 11>         |    %v1 = or i32 %v0, %p1;
+     114:4|    3: <10, 1>               |    ret i32 %v1;
+     117:0|  0: <65534>                 |  }
+
+Logical Xor
+-----------
+ 
+The *xor* instruction returns the bitwise logical exclusive or of its
+two operands.
+
+**Syntax**::
+
+  %vN = xor T V1, V2;                             <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 12>
+
+**Semantics**:
+
+This instruction performs a bitwise logical exclusive or of its arguments.
+Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T``
+must be an integer, or a vector of integers. ``N`` is defined by the record
+position, defining the corresponding value generated by the instruction.
+
+The truth table used for the *or* instruction is:

[Jim Stichnoth, 2014/11/18 02:24:42]

xor

[Karl, 2014/11/19 20:28:53]

Done.

+
+===== ===== ======
+Arg 1 Arg 2 Result
+===== ===== ======
+0     0     0
+0     1     1
+1     0     1
+1     1     0
+===== ===== ======
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  A1 == RelativeIndex(V1) &
+  A2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsInteger(UnderlyingType(T))) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+    96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+        |                             |                   // BlockID = 12
+   104:0|    3: <1, 1>                |    blocks 1;
+        |                             |  %b0:
+   106:4|    3: <2, 2, 1, 12>         |    %v0 = xor i32 %p0, %p1;
+   110:4|    3: <2, 1, 2, 12>         |    %v1 = xor i32 %v0, %p1;
+   114:4|    3: <10, 1>               |    ret i32 %v1;
+   117:0|  0: <65534>                 |  }
+
+.. _link_for_floating_point_binary_instructions:
+
+Floating Point Binary Instructions
+==================================
+
+Floating point binary instructions require two operands of the same type,
+execute an operation on them, and produce a value. The value may represent
+multiple values if the type is a vector type.  The result value always has the
+same type as its operands.
+
+Floating Point Add
+------------------
+
+The floating point add instruction returns the sum of its two arguments. Both
+arguments and the result must be of the same type. That type must be a floating
+point type, or a vector of a floating point type.
+
+**Syntax**::
+
+  %vN = fadd T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 0>
+
+**Semantics**:
+
+The floating point add instruction returns the sum of its two arguments.
+Arguments ``V1`` and ``V2`` and the result ``%vN`` must be of type ``T``. ``T``
+must be a floating point type, or a vector of a floating point type. ``N`` is
+defined by the record position, defining the corresponding value generated by
+the instruction.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsFloat(UnderlyingType(T)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   92:0|  1: <65535, 12, 2>          |  function 
+       |                             |      float @f0(float %p0, float %p1) {
+       |                             |                    // BlockID = 12
+  100:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  102:4|    3: <2, 2, 1, 0>          |    %v0 = fadd float %p0, %p1;
+  106:4|    3: <2, 3, 1, 0>          |    %v1 = fadd float %p0, %v0;
+  110:4|    3: <10, 1>               |    ret float %v1;
+  113:0|  0: <65534>                 |  }
+
+Floating Point Subtract
+-----------------------
+
+The floating point subtract instruction returns the difference of its two
+arguments. Both arguments and the result must be of the same type. That type
+must be a floating point type, or a vector of a floating point type.
+
+**Syntax**::
+
+  %vN = fsub T V1, V2;                            <a>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 1>
+
+**Semantics**:
+
+The floating point subtract instruction returns the difference of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type
+``T``. ``T`` must be a floating point type, or a vector of a floating point
+type. ``N`` is defined by the record position, defining the corresponding value
+generated by the instruction.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsFloat(UnderlyingType(T)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   92:0|  1: <65535, 12, 2>          |  function 
+       |                             |      float @f0(float %p0, float %p1) {
+       |                             |                    // BlockID = 12
+  100:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  102:4|    3: <2, 2, 1, 1>          |    %v0 = fsub float %p0, %p1;
+  106:4|    3: <2, 3, 1, 1>          |    %v1 = fsub float %p0, %v0;
+  110:4|    3: <10, 1>               |    ret float %v1;
+  113:0|  0: <65534>                 |  }
+
+Floating Point Multiply
+-----------------------
+
+The floating point multiply instruction returns the product of its two
+arguments. Both arguments and the result must be of the same type. That type
+must be a floating point type, or a vector of a floating point type.
+
+**Syntax**::
+
+  &vN = fmul T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 2>
+
+**Semantics**:
+
+The floating point multiply instruction returns the product of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type
+``T``.  ``T`` must be a floating point type, or a vector of a floating point
+type. ``N`` is defined by the record position, defining the corresponding value
+generated by the instruction.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsFloat(UnderlyingType(T)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+      92:0|  1: <65535, 12, 2>          |  function 
+          |                             |      float @f0(float %p0, float %p1) {
+          |                             |                    // BlockID = 12
+     100:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     102:4|    3: <2, 2, 1, 2>          |    %v0 = fmul float %p0, %p1;
+     106:4|    3: <2, 3, 1, 2>          |    %v1 = fmul float %p0, %v0;
+     110:4|    3: <10, 1>               |    ret float %v1;
+     113:0|  0: <65534>                 |  }
+
+Floating Point Divide
+---------------------
+
+The floating point divide instruction returns the quotient of its two
+arguments. Both arguments and the result must be of the same type. That type
+must be a floating point type, or a vector of a floating point type.
+
+**Syntax**::
+
+  %vN = fdiv T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, V1, V2, 4>
+
+**Semantics**:
+
+The floating point divide instruction returns the quotient of its two
+arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type
+``T``. ``T`` must be a floating point type, or a vector of a floating point
+type. ``N`` is defined by the record position, defining the corresponding value
+generated by the instruction.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV22 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  IsFloat(UnderlyingType(T)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**::
+
+   92:0|  1: <65535, 12, 2>          |  function 
+       |                             |      double 
+       |                             |      @f0(double %p0, double %p1) {  
+       |                             |                   // BlockID = 12
+  100:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  102:4|    3: <2, 2, 1, 4>          |    %v0 = fdiv double %p0, %p1;
+  106:4|    3: <2, 3, 1, 4>          |    %v1 = fdiv double %p0, %v0;
+  110:4|    3: <10, 1>               |    ret double %v1;
+  113:0|  0: <65534>                 |  }
+
+Floating Point Remainder
+------------------------
+
+The floating point remainder instruction returns the remainder of the quotient
+of its two arguments. Both arguments and the result must be of the same
+type. That type must be a floating point type, or a vector of a floating point
+type.
+
+**Syntax**::
+
+  %vN = frem T V1, V2;                            <A>
+
+**Record**::
+
+  AA: <2, VV1, VV2, 6>
+
+**Semantics**:
+
+The floating point remainder instruction returns the remainder of the quotient
+of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of
+type ``T``. ``T`` must be a floating point type, or a vector of a floating point
+type. ``N`` is defined by the record position, defining the corresponding value
+generated by the instruction.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2)  &
+  IsFloat(UnderlyingType(T)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**::
+
+   92:0|  1: <65535, 12, 2>          |  function 
+       |                             |      double 
+       |                             |      @f0(double %p0, double %p1) {  
+       |                             |                   // BlockID = 12
+  100:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  102:4|    3: <2, 2, 1, 6>          |    %v0 = frem double %p0, %p1;
+  106:4|    3: <2, 3, 1, 6>          |    %v1 = frem double %p0, %v0;
+  110:4|    3: <10, 1>               |    ret double %v1;
+  113:0|  0: <65534>                 |  }
+
+.. _link_for_memory_creation_and_access_instructions:
+
+Memory Creation and Access Instructions
+=======================================
+
+A key design point of SSA-based representation is how it represents
+memory. In PNaCl bitcode files, no memory locations are in SSA
+form. This makes things very simple.
+
+.. _link_for_alloca_instruction:
+
+Alloca Instruction
+------------------
+
+The *alloca* instruction allocates memory on the stack frame of the
+currently executing function. This memory is automatically released
+when the function returns to its caller.
+
+**Syntax**::
+
+  %vN = alloca i8, i32 S, align V;                <A>
+
+**Record**::
+
+  AA: <19, SS, VV>
+
+**Semantics**:
+
+The *alloca* instruction allocates memory on the stack frame of the currently
+executing function.  The resulting value is a pointer to the allocated memory
+(i.e. of type i32). ``S`` is the number of bytes that are allocated on the
+stack. ``S`` must be of integer type i32. ``V`` is the alignment of the generated
+stack address.
+
+Alignment must be a power of 2. See :ref:`memory blocks and
+alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed
+discussion on how to define alignment.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  VV == Log2(V+1) &
+  SS == RelativeIndex(S) &
+  i32 == TypeOf(S) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = i32;
+
+**Examples**::
+
+     112:0|  1: <65535, 12, 2>          |  function void @f1() {  
+          |                             |                   // BlockID = 12
+     120:0|    3: <1, 1>                |    blocks 1;
+     122:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     132:0|      3: <1, 0>              |      i32:
+     134:4|      3: <4, 4>              |        %c0 = i32 2;
+     137:0|      3: <4, 8>              |        %c1 = i32 4;
+     139:4|      3: <4, 16>             |        %c2 = i32 8;
+     142:0|    0: <65534>               |      }
+          |                             |  %b0:
+     144:0|    3: <19, 3, 1>            |    %v0 = alloca i8, i32 %c0, align 1;
+     147:2|    3: <19, 3, 3>            |    %v1 = alloca i8, i32 %c1, align 4;
+     150:4|    3: <19, 3, 4>            |    %v2 = alloca i8, i32 %c2, align 8;
+     153:6|    3: <10>                  |    ret void;
+     155:4|  0: <65534>                 |  }
+
+Load Instruction
+----------------
+
+The *load* instruction is used to read from memory.
+
+**Syntax**::
+
+  %vN = load T* P, align V;                       <A>
+
+**Record**::
+
+  AA: <20, PP, VV, TT>
+
+**Semantics**:
+
+The load instruction is used to read from memory. ``P`` is the identifier of the
+memory address to read. The type of ``P`` must be an ``i32``.  ``T`` is the type
+of value to read. ``V`` is the alignment of the memory address.
+
+Type ``T`` must be a vector, integer, or floating point type. Both ``float`` and
+``double`` types are allowed for floating point types. All integer types except i1
+are allowed.
+
+Alignment must be a power of 2. See :ref:`memory blocks and
+alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed
+discussion on how to define alignment.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  i32 == TypeOf(P) &
+  PP == RelativeIndex(P) &
+  VV == Log2(V+1) &
+  %tTT == TypeID(T) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <4>                   |    @t2 = double;
+      57:2|    3: <21, 0, 1, 0>         |    @t3 = void (i32);
+      61:2|  0: <65534>                 |  }
+      ...
+      96:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     106:4|    3: <20, 1, 1, 0>         |    %v0 = load i32* %p0, align 1;
+     110:4|    3: <20, 1, 4, 2>         |    %v1 = load double* %v0, align 8;
+     114:4|    3: <10>                  |    ret void;
+     116:2|  0: <65534>                 |  }
+
+Store Instruction
+-----------------
+
+The *store* instruction is used to write to memory.
+
+**Syntax**::
+
+  store T S, T* P, align V;                     <A>
+
+**Record**::
+
+  AA: <24, PP, SS, VV>
+
+**Semantics**:
+
+The store instruction is used to write to memory. ``P`` is the identifier of the
+memory address to write to.  The type of ``P`` must be an i32 integer.  ``T`` is
+the type of value to store. ``S`` is the value to store, and must be of type
+``T``.  ``V`` is the alignment of the memory address.  ``A`` is the (optional)
+abbreviation index associated with the record.
+
+Type ``T`` must be an integer or floating point type. Both ``float`` and
+``double`` types are allowed for floating point types. All integer types except
+i1 are allowed.
+
+Alignment must be a power of 2. See :ref:`memory blocks and
+alignment<link_for_memory_Blocks_and_alignment_section>` for a more detailed
+discussion on how to define alignment.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  i32 == TypeOf(P) &
+  PP == RelativeIndex(P) &
+  VV == Log2(V+1)
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <4>                   |    @t2 = double;
+      57:2|    3: <21, 0, 1, 0, 0, 0, 2>|    @t3 = void (i32, i32, i32, double);
+      63:4|  0: <65534>                 |  }
+      ...
+      96:0|  1: <65535, 12, 2>          |  function 
+          |                             |      void 
+          |                             |      @f0(i32 %p0, i32 %p1, i32 %p2, 
+          |                             |          double %p3) {  
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     106:4|    3: <24, 4, 3, 1>         |    store i32 %p1, i32* %p0, align 1;
+     110:4|    3: <24, 2, 1, 4>         |    store double %p3, double* %p2, 
+          |                             |        align 8;
+     114:4|    3: <10>                  |    ret void;
+     116:2|  0: <65534>                 |  }
+
+.. _link_for_conversion_instructions:
+
+Conversion Instructions
+=======================
+
+Conversion instructions all take a single operand and a type. The value is
+converted to the corresponding type.
+
+Integer Truncating Instruction
+------------------------------
+
+The integer truncating instruction takes a value to truncate, and a type
+defining the truncated type. Both types must be integer types, or integer
+vectors with the same number of elements. The bit size of the value must be
+larger than the bit size of the destination type. Equal sized types are not
+allowed.
+
+**Syntax**::
+
+  %vN = trunc T1 V to T2;                         <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 0>
+
+**Semantics**:
+
+The integer truncating instruction takes a value ``V``, and truncates to type
+``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with the
+same number of elements. ``T1`` has to be wider than ``T2``.  If the value doesn't
+fit in in ``T2``, then the higher order bits are dropped.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsInteger(UnderlyingType(T1)) &
+  IsInteger(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 5>                |    count 5;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <7, 16>               |    @t2 = i16;
+      58:0|    3: <21, 0, 1, 0>         |    @t3 = void (i32);
+      62:0|    3: <7, 8>                |    @t4 = i8;
+      64:4|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     110:4|    3: <3, 1, 2, 0>          |    %v0 = trunc i32 %p0 to i16;
+     114:4|    3: <3, 1, 4, 0>          |    %v1 = trunc i16 %v0 to i8;
+     118:4|    3: <10>                  |    ret void;
+     120:2|  0: <65534>                 |  }
+
+Floating Point Truncating Instruction
+--------------------------------------
+
+The floating point truncating instruction takes a value to truncate, and a type
+defining the truncated type. Both types must be floating point types, or
+floating point vectors with the same number of elements. The source must be
+``double`` while the destination is ``float``.  If the source is a vector, the
+destination must also be vector with the same size as the source.
+
+**Syntax**::
+
+  %vN = fptrunc T1 V to T2;                       <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 7>
+
+**Semantics**
+
+The floating point truncating instruction takes a value ``V``, and truncates to
+type ``T2``. Both ``T1`` and ``T2`` must be floating point types, or floating
+point vectors with the same number of elements. ``T1`` must be defined on
+``double`` while ``T2`` is defined on ``float``.  If the value can't fit within
+the destination type ``T2``, the results are undefined.
+
+**Constraints**::
+
+  TypeOf(V) == T1 &
+  double == UnderlyingType(T1) &
+  float == UnderlyingType(T2) &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsFloat(UnderlyingType(T1)) &
+  IsFloat(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+   40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+   48:0|    3: <1, 4>                |    count 4;
+   50:4|    3: <3>                   |    @t0 = float;
+   52:2|    3: <4>                   |    @t1 = double;
+   54:0|    3: <21, 0, 0, 1>         |    @t2 = float (double);
+   58:0|    3: <2>                   |    @t3 = void;
+   59:6|  0: <65534>                 |  }
+  ...
+   92:0|  1: <65535, 12, 2>          |  function float @f0(double %p0) {  
+       |                             |                   // BlockID = 12
+  100:0|    3: <1, 1>                |    blocks 1;
+       |                             |  %b0:
+  102:4|    3: <3, 1, 0, 7>          |    %v0 = fptrunc double %p0 to float;
+  106:4|    3: <10, 1>               |    ret float %v0;
+  109:0|  0: <65534>                 |  }
+
+
+Zero Extending Instruction
+--------------------------
+
+The zero extending instruction takes a value to extend, and a type to extend it
+to. Both types must be integer types, or integer vectors with the same number
+of elements. The bit size of the source type must be smaller than the bit size
+of the destination type. Equal sized types are not allowed.
+
+**Syntax**::
+
+  %vN = zext T1 V to T2;                          <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 1>
+
+
+**Semantics**:
+
+The zero extending instruction takes a value ``V``, and expands it to type
+``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with the
+same number of elements. ``T2`` must be wider than ``T1``.
+
+The instruction fills the high order bits of the value with zero bits until it
+reaches the size of the destination type. When zero extending from i1, the
+result will always be either 0 or 1.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsInteger(UnderlyingType(T1)) &
+  IsInteger(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 5>                |    count 5;
+      50:4|    3: <7, 64>               |    @t0 = i64;
+      53:6|    3: <7, 32>               |    @t1 = i32;
+      57:0|    3: <21, 0, 0>            |    @t2 = i64 ();
+      60:2|    3: <7, 8>                |    @t3 = i8;
+      62:6|    3: <2>                   |    @t4 = void;
+      64:4|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function i64 @f0() {  // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+     110:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     120:0|      3: <1, 3>              |      i8:
+     122:4|      3: <4, 2>              |        %c0 = i8 1;
+     125:0|    0: <65534>               |      }
+          |                             |  %b0:
+     128:0|    3: <3, 1, 1, 1>          |    %v0 = zext i8 %c0 to i32;
+     132:0|    3: <3, 1, 0, 1>          |    %v1 = zext i32 %v0 to i64;
+     136:0|    3: <10, 1>               |    ret i64 %v1;
+     138:4|  0: <65534>                 |  }
+
+Sign Extending Instruction
+--------------------------
+
+The sign extending instruction takes a value to cast, and a type to extend it
+to. Both types must be integer types, or integral vectors with the same number
+of elements. The bit size of the source type must be smaller than the bit size
+of the destination type. Equal sized types are not allowed.
+
+**Syntax**::
+
+  %vN = sext T1 V to T2;                          <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 2>
+
+**Semantics**:
+
+The sign extending instruction takes a value ``V``, and expands it to type
+``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with the
+same number of integers.  ``T2`` has to be wider than ``T1``.
+
+When sign extending, the instruction fills the high order bits of the value with
+the (current) high order bit of the value. When sign extending from i1, the
+extension always results in -1 or 0.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsInteger(UnderlyingType(T1)) &
+  IsInteger(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 5>                |    count 5;
+      50:4|    3: <7, 64>               |    @t0 = i64;
+      53:6|    3: <7, 32>               |    @t1 = i32;
+      57:0|    3: <21, 0, 0>            |    @t2 = i64 ();
+      60:2|    3: <7, 8>                |    @t3 = i8;
+      62:6|    3: <2>                   |    @t4 = void;
+      64:4|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function i64 @f0() {  // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+     110:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     120:0|      3: <1, 3>              |      i8:
+     122:4|      3: <4, 3>              |        %c0 = i8 -1;
+     125:0|    0: <65534>               |      }
+          |                             |  %b0:
+     128:0|    3: <3, 1, 1, 2>          |    %v0 = sext i8 %c0 to i32;
+     132:0|    3: <3, 1, 0, 2>          |    %v1 = sext i32 %v0 to i64;
+     136:0|    3: <10, 1>               |    ret i64 %v1;
+     138:4|  0: <65534>                 |  }
+
+Floating Point Extending Instruction
+------------------------------------
+
+The floating point extending instruction takes a value to extend, and a type to
+extend it to. Both types must either be floating point types, or vectors of
+floating point types with the same number of elements. The source value must be
+``float`` while the destination is ``double``.  If the source is a vector, the
+destination must also be vector with the same size as the source.
+
+**Syntax**::
+
+  %vN = fpext T1 V to T2;                           <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 8>
+
+**Semantics**:
+
+The floating point extending instruction converts floating point values.
+``V`` is the value to extend, and ``T2`` is the type to extend it
+to. Both ``T1`` and ``T2`` must be floating point types, or floating point
+vector types with the same number of floating point values. ``T1`` contains
+``float`` while ``T2`` contains ``double``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsFloat(UnderlyingType(T1)) &
+  IsFloat(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <4>                   |    @t0 = double;
+      52:2|    3: <3>                   |    @t1 = float;
+      54:0|    3: <21, 0, 0, 1>         |    @t2 = double (float);
+      58:0|    3: <2>                   |    @t3 = void;
+      59:6|  0: <65534>                 |  }
+      ...
+      92:0|  1: <65535, 12, 2>          |  function double @f0(float %p0) {  
+          |                             |                   // BlockID = 12
+     100:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     102:4|    3: <3, 1, 0, 8>          |    %v0 = fpext float %p0 to double;
+     106:4|    3: <10, 1>               |    ret double %v0;
+     109:0|  0: <65534>                 |  }
+
+Floating Point to Unsigned Integer Instruction
+----------------------------------------------
+
+The floating point to unsigned integer instruction converts floating point
+values to unsigned integers.
+
+**Syntax**::
+
+  %vN = fptoui T1 V to T2;                        <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 3>
+
+**Semantics**:
+
+The floating point to unsigned integer instruction converts floating point
+value(s) in ``V`` to its unsigned integer equivalent of type ``T2``. ``T1`` must
+be a floating point type, or a floating point vector type. ``T2`` must be an
+integer type, or an integer vector type. If either type is a vector type, they
+both must have the same number of elements.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 == TypeID(T2) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsFloat(UnderlyingType(T1)) &
+  IsInteger(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 6>                |    count 6;
+      50:4|    3: <3>                   |    @t0 = float;
+      52:2|    3: <4>                   |    @t1 = double;
+      54:0|    3: <2>                   |    @t2 = void;
+      55:6|    3: <21, 0, 2, 0, 1>      |    @t3 = void (float, double);
+      60:4|    3: <7, 32>               |    @t4 = i32;
+      63:6|    3: <7, 16>               |    @t5 = i16;
+      66:2|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function 
+          |                             |      void @f0(float %p0, double %p1) {
+          |                             |                    // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     110:4|    3: <3, 2, 4, 3>          |    %v0 = fptoui float %p0 to i32;
+     114:4|    3: <3, 2, 5, 3>          |    %v1 = fptoui double %p1 to i16;
+     118:4|    3: <10>                  |    ret void;
+     120:2|  0: <65534>                 |  }
+
+Floating Point to Signed Integer Instruction
+--------------------------------------------
+
+The floating point to signed integer instruction converts floating point
+values to signed integers.
+
+**Syntax**::
+
+  %vN = fptosi T1 V to T2;                        <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 4>
+
+**Semantics**:
+
+The floating point to signed integer instruction converts floating point value(s)
+in ``V`` to its signed integer equivalent of type ``T2``. ``T1`` must be a
+floating point type, or a floating point vector type. ``T2`` must be an integer
+type, or an integer vector type. If either type is a vector type, they both must
+have the same number of elements.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 = TypeID(T2) &
+  UnderlyingCount(T1) = UnderlyingCount(T2) &
+  IsFloat(UnderlyingType(T1)) &
+  IsInteger(UnderlyingType(T2)) &
+  N = NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 6>                |    count 6;
+      50:4|    3: <3>                   |    @t0 = float;
+      52:2|    3: <4>                   |    @t1 = double;
+      54:0|    3: <2>                   |    @t2 = void;
+      55:6|    3: <21, 0, 2, 0, 1>      |    @t3 = void (float, double);
+      60:4|    3: <7, 8>                |    @t4 = i8;
+      63:0|    3: <7, 16>               |    @t5 = i16;
+      65:4|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function 
+          |                             |      void @f0(float %p0, double %p1) {
+          |                             |                    // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     110:4|    3: <3, 2, 4, 4>          |    %v0 = fptosi float %p0 to i8;
+     114:4|    3: <3, 2, 5, 4>          |    %v1 = fptosi double %p1 to i16;
+     118:4|    3: <10>                  |    ret void;
+     120:2|  0: <65534>                 |  }
+
+Unsigned Integer to Floating Point Instruction
+----------------------------------------------
+
+The unsigned integer to floating point instruction converts unsigned integers to
+floating point values.
+
+**Syntax**::
+
+  %vN = uitofp T1 V to T2;                        <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 5>
+
+**Semantics**:
+
+The unsigned integer to floating point instruction converts unsigned integer(s) to
+its floating point equivalent of type ``T2``. ``T1`` must be an integer type, or
+a integer vector type. ``T2`` must be a floating point type, or a floating point
+vector type. If either type is a vector type, they both must have the
+same number of elements.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 = TypeID(T2) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsInteger(UnderlyingType(T1)) &
+  IsFloat(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) == T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <7, 64>               |    @t1 = i64;
+      57:0|    3: <2>                   |    @t2 = void;
+      58:6|    3: <3>                   |    @t3 = float;
+      60:4|    3: <21, 0, 2, 0, 1>      |    @t4 = void (i32, i64);
+      65:2|    3: <7, 1>                |    @t5 = i1;
+      67:6|    3: <4>                   |    @t6 = double;
+      69:4|  0: <65534>                 |  }
+     ...
+     104:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0, i64 %p1) {
+          |                             |                    // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+     114:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     124:0|      3: <1, 5>              |      i1:
+     126:4|      3: <4, 3>              |        %c0 = i1 1;
+     129:0|    0: <65534>               |      }
+          |                             |  %b0:
+     132:0|    3: <3, 1, 6, 5>          |    %v0 = uitofp i1 %c0 to double;
+     136:0|    3: <3, 4, 3, 5>          |    %v1 = uitofp i32 %p0 to float;
+     140:0|    3: <3, 4, 3, 5>          |    %v2 = uitofp i64 %p1 to float;
+     144:0|    3: <10>                  |    ret void;
+     145:6|  0: <65534>                 |  }
+
+Signed Integer to Floating Point Instruction
+--------------------------------------------
+
+The signed integer to floating point instruction converts signed integers to
+floating point values.
+
+**Syntax**::
+
+  %vN = sitofp T1 V to T2;                        <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 6>
+
+**Semantics**:
+
+The signed integer to floating point instruction converts signed integer(s) to its
+floating point equivalent of type ``T2``. ``T1`` must be an integer type, or a
+integer vector type. ``T2`` must be a floating point type, or a floating point
+vector type. If either type is a vector type, they both must have the
+same number of elements.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV == RelativeIndex(V) &
+  %tTT2 = TypeID(T2) &
+  UnderlyingCount(T1) == UnderlyingCount(T2) &
+  IsInteger(UnderlyingType(T1)) &
+  IsFloat(UnderlyingType(T2)) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 7>                |    count 7;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <7, 64>               |    @t1 = i64;
+      57:0|    3: <2>                   |    @t2 = void;
+      58:6|    3: <3>                   |    @t3 = float;
+      60:4|    3: <21, 0, 2, 0, 1>      |    @t4 = void (i32, i64);
+      65:2|    3: <7, 8>                |    @t5 = i8;
+      67:6|    3: <4>                   |    @t6 = double;
+      69:4|  0: <65534>                 |  }
+      ...
+     104:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0, i64 %p1) {
+          |                             |                    // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+     114:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     124:0|      3: <1, 5>              |      i8:
+     126:4|      3: <4, 3>              |        %c0 = i8 -1;
+     129:0|    0: <65534>               |      }
+          |                             |  %b0:
+     132:0|    3: <3, 1, 6, 6>          |    %v0 = sitofp i8 %c0 to double;
+     136:0|    3: <3, 4, 3, 6>          |    %v1 = sitofp i32 %p0 to float;
+     140:0|    3: <3, 4, 3, 6>          |    %v2 = sitofp i64 %p1 to float;
+     144:0|    3: <10>                  |    ret void;
+     145:6|  0: <65534>                 |  }
+
+Bitcast Instruction
+-------------------
+
+The bitcast instruction converts the type of the value without changing the bit
+contents of the value. The bit size of the type of the value must be the same as
+the bit size of the cast type.
+
+**Syntax**::
+
+  %vN = bitcast T1 V to T2;                       <A>
+
+**Record**::
+
+  AA: <3, VV, TT2, 11>
+
+**Semantics**:
+
+The bitcast instruction converts the type of value ``V`` to type ``T2``. ``T1``
+and ``T2`` must be primitive types or vectors, and define the same number of
+bits.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  TypeOf(V) == T1 &
+  VV = RelativeIndex(V) &
+  %tTT2 = TypeID(T2) &
+  BitSizeOf(T1) == BitSizeOf(T2) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 6>                |    count 6;
+      50:4|    3: <3>                   |    @t0 = float;
+      52:2|    3: <7, 64>               |    @t1 = i64;
+      55:4|    3: <2>                   |    @t2 = void;
+      57:2|    3: <21, 0, 2, 0, 1>      |    @t3 = void (float, i64);
+      62:0|    3: <7, 32>               |    @t4 = i32;
+      65:2|    3: <4>                   |    @t5 = double;
+      67:0|  0: <65534>                 |  }
+      ...
+     100:0|  1: <65535, 12, 2>          |  function void @f0(float %p0, i64 %p1)
+          |                             |      {  // BlockID = 12
+     108:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     110:4|    3: <3, 2, 4, 11>         |    %v0 = bitcast float %p0 to i32;
+     114:4|    3: <3, 2, 5, 11>         |    %v1 = bitcast i64 %p1 to double;
+     118:4|    3: <10>                  |    ret void;
+     120:2|  0: <65534>                 |  }
+
+.. _link_for_compare_instructions:
+
+Comparison Instructions
+=======================
+
+The comparison instructions compares values returns a boolean (i1) result for

[Jim Stichnoth, 2014/11/18 02:24:42]

... compare ...
... and return ...

[Karl, 2014/11/19 20:28:52]

Done.

+each pair of compared values. There are different comparison operations for
+integer and floating point values.
+
+
+Integer Comparison Instructions
+-------------------------------
+
+The integer comparison instruction compares integer values and returns a
+boolean (i1) result for each pair of compared values.
+
+**Syntax**::
+
+  %vN = icmp C T V1, V2;                          <A>
+
+**Record**::
+
+  AA: <9, VV1, VV2, CC>
+
+**Semantics**:
+
+The integer comparison instruction compares integer values and returns a boolean
+(i1) result for each pair of compared values in ``V1`` and ``V2``. ``V1`` and
+``V2`` must be of type ``T``. ``T`` must be an integer type, or an integer
+vector type. Condition code ``C`` is the condition applied to all elements in
+``V1`` and ``V2``.  Each comparison always yields an i1. If ``T`` is a primitive
+type, the resulting type is i1. If ``T`` is a vector, then the resulting type is
+a vector of i1 with the same size as ``T``.
+
+Legal test conditions are:
+
+=== == ==============================
+C   CC Operator
+=== == ==============================
+eq  32 equal
+ne  33 not equal
+ugt 34 unsigned greater than
+uge 35 unsigned greater than or equal
+ult 36 unsigned less than
+ule 37 unsigned less than or equal
+sgt 38 signed greater than
+sge 39 signed greater than or equal
+slt 40 signed less than
+sle 41 signed less than or equal
+=== == ==============================
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  IsInteger(UnderlyingType(T) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  if IsVector(T) then
+    TypeOf(%vN) = <UnderlyingCount(T), i1>
+  else
+    TypeOf(%vN) = i1
+  endif
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <7, 1>                |    @t1 = i1;
+      56:2|    3: <2>                   |    @t2 = void;
+      58:0|    3: <21, 0, 2>            |    @t3 = void ();
+      61:2|  0: <65534>                 |  }
+      ...
+     108:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     116:0|    3: <1, 1>                |    blocks 1;
+     118:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     128:0|      3: <1, 0>              |      i32:
+     130:4|      3: <4, 0>              |        %c0 = i32 0;
+     133:0|      3: <4, 2>              |        %c1 = i32 1;
+     135:4|    0: <65534>               |      }
+          |                             |  %b0:
+     136:0|    3: <28, 2, 1, 32>        |    %v0 = icmp eq i32 %c0, %c1;
+     140:6|    3: <28, 3, 2, 33>        |    %v1 = icmp ne i32 %c0, %c1;
+     145:4|    3: <28, 4, 3, 34>        |    %v2 = icmp ugt i32 %c0, %c1;
+     150:2|    3: <28, 5, 4, 36>        |    %v3 = icmp ult i32 %c0, %c1;
+     155:0|    3: <28, 6, 5, 37>        |    %v4 = icmp ule i32 %c0, %c1;
+     159:6|    3: <28, 7, 6, 38>        |    %v5 = icmp sgt i32 %c0, %c1;
+     164:4|    3: <28, 8, 7, 38>        |    %v6 = icmp sgt i32 %c0, %c1;
+     169:2|    3: <28, 9, 8, 39>        |    %v7 = icmp sge i32 %c0, %c1;
+     174:0|    3: <28, 10, 9, 40>       |    %v8 = icmp slt i32 %c0, %c1;
+     178:6|    3: <28, 11, 10, 41>      |    %v9 = icmp sle i32 %c0, %c1;
+     183:4|    3: <10>                  |    ret void;
+     185:2|  0: <65534>                 |  }
+
+
+Floating Point Comparison Instructions
+--------------------------------------
+
+The floating point comparison instruction compares floating point values and
+returns a boolean (i1) result for each pair of compared values.
+
+**Syntax**::
+
+  %vN = fcmp C T V1, V2;                          <A>
+
+**Record**::
+
+  AA: <9, VV1, VV2, CC>
+
+**Semantics**:
+
+The floating point comparison instruction compares floating point values and
+returns a boolean (i1) result for each pair of compared values in ``V1`` and
+``V2``. ``V1`` and ``V2`` must be of type ``T``. ``T`` must be a floating point
+type, or a floating point vector type. Condition code ``C`` is the condition
+applied to all elements in ``V1`` and ``V2``. Each comparison always yields an
+i1. If ``T`` is a primitive type, the resulting type is i1. If ``T`` is a
+vector, then the resulting type is a vector of i1 with the same size as ``T``.
+
+Legal test conditions are:
+
+===== == ==================================
+C     CC Operator
+===== == ==================================
+false  0 Always false
+oeq    1 Ordered and equal
+ogt    2 Ordered and greater than
+oge    3 Ordered and greater than or equal
+olt    4 Ordered and less than
+ole    5 Ordered and less than or equal
+one    6 Ordered and not equal
+ord    7 Ordered (no nans)

[Jim Stichnoth, 2014/11/17 18:54:56]

For these two lines, maybe write "NaNs" instead of "nans"?

[Karl, 2014/11/17 20:17:28]

Done.

+uno    8 Unordered (either nans)
+ueq    9 Unordered or equal
+ugt   10 Unordered or greater than
+uge   11 Unordered or greater than or equal
+ult   12 Unordered or less than
+ule   13 Unordered or less than or equal
+une   14 Unordered or not equal
+true  15 Always true
+===== == ==================================
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  IsFloat(UnderlyingType(T) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  if IsVector(T) then
+    TypeOf(%vN) = <UnderlyingCount(T), i1>
+  else
+    TypeOf(%vN) = i1
+  endif
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <3>                   |    @t0 = float;
+      52:2|    3: <7, 1>                |    @t1 = i1;
+      54:6|    3: <2>                   |    @t2 = void;
+      56:4|    3: <21, 0, 2>            |    @t3 = void ();
+      59:6|  0: <65534>                 |  }
+      ...
+     108:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     116:0|    3: <1, 1>                |    blocks 1;
+     118:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     128:0|      3: <1, 0>              |      float:
+     130:4|      3: <6, 0>              |        %c0 = float 0;
+     133:0|      3: <6, 1065353216>     |        %c1 = float 1;
+     139:2|    0: <65534>               |      }
+          |                             |  %b0:
+     140:0|    3: <28, 2, 1, 0>         |    %v0 = fcmp false float %c0, %c1;
+     144:0|    3: <28, 3, 2, 1>         |    %v1 = fcmp oeq float %c0, %c1;
+     148:0|    3: <28, 4, 3, 2>         |    %v2 = fcmp ogt float %c0, %c1;
+     152:0|    3: <28, 5, 4, 3>         |    %v3 = fcmp oge float %c0, %c1;
+     156:0|    3: <28, 6, 5, 4>         |    %v4 = fcmp olt float %c0, %c1;
+     160:0|    3: <28, 7, 6, 5>         |    %v5 = fcmp ole float %c0, %c1;
+     164:0|    3: <28, 8, 7, 6>         |    %v6 = fcmp one float %c0, %c1;
+     168:0|    3: <28, 9, 8, 7>         |    %v7 = fcmp ord float %c0, %c1;
+     172:0|    3: <28, 10, 9, 9>        |    %v8 = fcmp ueq float %c0, %c1;
+     176:0|    3: <28, 11, 10, 10>      |    %v9 = fcmp ugt float %c0, %c1;
+     180:0|    3: <28, 12, 11, 11>      |    %v10 = fcmp uge float %c0, %c1;
+     184:0|    3: <28, 13, 12, 12>      |    %v11 = fcmp ult float %c0, %c1;
+     188:0|    3: <28, 14, 13, 13>      |    %v12 = fcmp ule float %c0, %c1;
+     192:0|    3: <28, 15, 14, 14>      |    %v13 = fcmp une float %c0, %c1;
+     196:0|    3: <28, 16, 15, 8>       |    %v14 = fcmp uno float %c0, %c1;
+     200:0|    3: <28, 17, 16, 15>      |    %v15 = fcmp true float %c0, %c1;
+     204:0|    3: <10>                  |    ret void;
+     205:6|  0: <65534>                 |  }
+     208:0|0: <65534>                   |}
+
+.. _link_for_vector_instructions:
+
+Vector Instructions
+===================
+
+PNaClAsm supports several instructions that process vectors. This includes the
+:ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating
+point<link_for_floating_point_binary_instructions>` binary instructions as well
+as :ref:`compare<link_for_compare_instructions>` instructions. These
+instructions work with vectors and generate resulting (new) vectors. This
+section introduces the instructions to construct vectors and extract results.
+
+.. _link_for_insert_element_instruction_section:
+
+Insert Element Instruction
+--------------------------
+
+The *insert element* instruction inserts a scalar value into a vector at a
+specified index. The *insert element* instruction takes an existing vector and
+puts a scalar value in one of the elements of the vector.
+
+The *insert element* instruction can be used to construct a vector, one element
+at a time.  At first glance, it may appear that one can't construct a vector,
+since the *insert element* instruction needs a vector to insert elements into.
+
+The key to understanding vector construction is understand that one can create
+an :ref:`undefined<link_for_undefined_literal>` vector literal. Using that
+constant as a starting point, one can built up the wanted vector by a sequence
+of *insert element* instructions.
+
+**Syntax**::
+
+  %vN = insertelement TV V, TE E, i32 I;          <A>
+
+**Record**::
+
+  AA: <7, VV, EE, II>
+
+**Semantics**:
+
+The *insert element* instruction inserts scalar value ``E`` into index ``I`` of
+vector ``V``. ``%vN`` holds the updated vector. Type ``TV`` is the type of
+vector.  It is also the type of updated vector ``%vN``.  Type ``TE`` is the type
+of scalar value ``E`` and must be the element type of vector ``V``. ``I`` must
+be an :ref:`i32 literal<link_for_integer_literal>`.
+
+If ``I`` exceeds the length of ``V``, the result is undefined.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  IsVector(TV) &
+  TypeOf(V) == TV &
+  UnderlyingType(TV) == TE &
+  TypeOf(I) == i32 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = TV;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 5>                |    count 5;
+      50:4|    3: <7, 1>                |    @t0 = i1;
+      53:0|    3: <12, 4, 0>            |    @t1 = <4 x i1>;
+      56:2|    3: <7, 32>               |    @t2 = i32;
+      59:4|    3: <2>                   |    @t3 = void;
+      61:2|    3: <21, 0, 3>            |    @t4 = void ();
+      64:4|  0: <65534>                 |  }
+      ...
+     116:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     124:0|    3: <1, 1>                |    blocks 1;
+     126:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     136:0|      3: <1, 0>              |      i1:
+     138:4|      3: <4, 0>              |        %c0 = i1 0;
+     141:0|      3: <4, 3>              |        %c1 = i1 1;
+     143:4|      3: <1, 1>              |      <4 x i1>:
+     146:0|      3: <3>                 |        %c2 = <4 x i1> undef;
+     147:6|      3: <1, 2>              |      i32:
+     150:2|      3: <4, 0>              |        %c3 = i32 0;
+     152:6|      3: <4, 2>              |        %c4 = i32 1;
+     155:2|      3: <4, 4>              |        %c5 = i32 2;
+     157:6|      3: <4, 6>              |        %c6 = i32 3;
+     160:2|    0: <65534>               |      }
+          |                             |  %b0:
+     164:0|    3: <7, 5, 7, 4>          |    %v0  =  insertelement <4 x i1> %c2,
+          |                             |        i1 %c0, i32 %c3;
+     168:0|    3: <7, 1, 7, 4>          |    %v1  =  insertelement <4 x i1> %v0,
+          |                             |        i1 %c1, i32 %c4;
+     172:0|    3: <7, 1, 9, 4>          |    %v2  =  insertelement <4 x i1> %v1,
+          |                             |        i1 %c0, i32 %c5;
+     176:0|    3: <7, 1, 9, 4>          |    %v3  =  insertelement <4 x i1> %v2,
+          |                             |        i1 %c1, i32 %c6;
+     180:0|    3: <10>                  |    ret void;
+     181:6|  0: <65534>                 |  }
+
+Extract Element Instruction
+---------------------------
+
+The *extract element* instruction extracts a single scalar value from a vector
+at a specified index.
+
+**Syntax**::
+
+  %vN = extractelement TV V, i32 I;                <A>
+
+**Record**::
+
+  AA: <6, VV, II>
+
+**Semantics**:
+
+The *extract element* instruction extracts the scalar value at index ``I`` from
+vector ``V``. The extracted value is assigned to ``%vN``. Type ``TV`` is the
+type of vector ``V``. ``I`` must be an :ref:`i32
+literal<link_for_integer_literal>`. The type of ``vN`` must be the element type
+of vector ``V``.
+
+If ``I`` exceeds the length of ``V``, the result is undefined.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  IsVector(TV) &
+  TypeOf(V) == TV &
+  TypeOf(I) == i32 &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = UnderlyingType(TV);
+
+**Examples**::
+
+      96:0|  1: <65535, 12, 2>          |  function void @f0(<4 x i32> %p0) {  
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+     106:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     116:0|      3: <1, 0>              |      i32:
+     118:4|      3: <4, 0>              |        %c0 = i32 0;
+     121:0|    0: <65534>               |      }
+          |                             |  %b0:
+     124:0|    3: <6, 2, 1>             |    %v0  =  
+          |                             |        extractelement <4 x i32> %p0, 
+          |                             |        i32 %c0;
+     127:2|    3: <10>                  |    ret void;
+     129:0|  0: <65534>                 |  }
+
+.. _link_for_other_pnaclasm_instructions:
+
+Other Instructions
+==================
+
+This section defines miscellaneous instructions which defy better
+classification.
+
+.. _link_for_forward_type_declaration_section:
+
+Forward Type Declaration
+------------------------
+
+The forward type declaration exists to deal with the fact that all instruction
+values must have a type associated with them before they are used. For some
+simple functions one can easily topologically sort instructions so that
+instruction values are defined before they are used. However, if the
+implementation contains loops, the loop induced values can't be defined before
+they are used.
+
+The solution is to forward declare the type of an instruction value. One could
+forward declare the types of all instructions at the beginning of the function
+block.  However, this would make the corresponding file size considerably
+larger. Rather, one should only generate these forward type declarations
+sparingly and only when needed.
+
+**Syntax**::
+
+  declare T %vN;                                  <A>
+
+**Record**::
+
+  AA: <43, N, TT>
+
+**Semantics**:
+
+The forward declare type declaration defines the type to be associated with a
+(not yet defined) instruction value ``%vN``. ``T`` is the type of the value
+generated by the ``Nth`` value generating instruction in the function block.
+
+Note: It is an error to define the type of ``%vN`` with a different type than
+will be generated by the ``Nth`` value generating instruction in the function
+block.
+
+Also note that this construct is a declaration and not considered an
+instruction, even though it appears in the list of instruction records. Hence,
+they may appear before and between :ref:`phi<link_for_phi_instruction_section>`
+instructions in a basic block.
+
+**Constraints**::
+
+  AA = AbbrevIndex(A) &
+  TT = TypeID(T)
+
+**Updates**::
+
+  TypeOf(%vN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <7, 1>                |    @t2 = i1;
+      58:0|    3: <21, 0, 1, 0>         |    @t3 = void (i32);
+      62:0|  0: <65534>                 |  }
+      ...
+     108:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     116:0|    3: <1, 7>                |    blocks 7;
+     118:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     128:0|      3: <1, 2>              |      i1:
+     130:4|      3: <4, 3>              |        %c0 = i1 1;
+     133:0|    0: <65534>               |      }
+          |                             |  %b0:
+     136:0|    3: <11, 4>               |    br label %b4;
+          |                             |  %b1:
+     138:4|    3: <43, 6, 0>            |    declare i32 %v3;
+     142:4|    3: <2, 2, 4294967293, 0> |    %v0 = add i32 %p0, %v3;
+     151:0|    3: <11, 6>               |    br label %b6;
+          |                             |  %b2:
+     153:4|    3: <43, 7, 0>            |    declare i32 %v4;
+     157:4|    3: <2, 3, 4294967293, 0> |    %v1 = add i32 %p0, %v4;
+     166:0|    3: <11, 6>               |    br label %b6;
+          |                             |  %b3:
+     168:4|    3: <2, 4, 4294967295, 0> |    %v2 = add i32 %p0, %v3;
+     177:0|    3: <11, 6>               |    br label %b6;
+          |                             |  %b4:
+     179:4|    3: <2, 5, 5, 0>          |    %v3 = add i32 %p0, %p0;
+     183:4|    3: <11, 1, 5, 5>         |    br i1 %c0, label %b1, label %b5;
+          |                             |  %b5:
+     187:4|    3: <2, 1, 6, 0>          |    %v4 = add i32 %v3, %p0;
+     191:4|    3: <11, 2, 3, 6>         |    br i1 %c0, label %b2, label %b3;
+          |                             |  %b6:
+     195:4|    3: <10>                  |    ret void;
+     197:2|  0: <65534>                 |  }
+
+.. _link_for_phi_instruction_section:
+
+Phi Instruction
+---------------
+
+The *phi* instruction is used to implement phi nodes in the SSA graph
+representing the function. Phi instructions can only appear at the beginning of
+a basic block.  There must be no non-phi instructions (other than forward type
+declarations) between the start of the basic block and the *phi* instruction.
+
+To clarify the origin of each incoming value, the incoming value is associated
+with the incoming edge from the corresponding predecessor block that the
+incoming value comes from.
+
+**Syntax**::
+
+  %vN = phi T [V1, %bB1], ... , [VM, %bBM];        <A>
+
+**Record**::
+
+  AA: <16, TT, VV1, B1, ..., VVM, BM>
+
+**Semantics**:
+
+The phi instruction is used to implement phi nodes in the SSA graph representing
+the function. ``%vN`` is the resulting value of the corresponding phi node. ``T`` is
+the type of the phi node. Values ``V1`` through ``VM`` are the reaching definitions
+for the phi node while ``%bB1`` through ``%bBM`` are the corresponding predecessor
+blocks.  Each ``VI`` reaches via the incoming predecessor edge from block ``%bBI``
+(for 1 <= I <= M). Type ``T`` must be the type associated with each ``VI``.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  M > 1 &
+  TT == TypeID(T) &
+  T = TypeOf(VI) for all I, 1 <= I <= M &
+  BI < ExpectedBasicBlocks for all I, 1 <= I <= M &
+  VVI = SignRotate(RelativeIndex(VI)) for all I, 1 <= I <= M &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 4>                |    count 4;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <2>                   |    @t1 = void;
+      55:4|    3: <21, 0, 1>            |    @t2 = void ();
+      58:6|    3: <7, 1>                |    @t3 = i1;
+      61:2|  0: <65534>                 |  }
+      ...
+     112:0|  1: <65535, 12, 2>          |  function void @f0() {  
+          |                             |                   // BlockID = 12
+     120:0|    3: <1, 4>                |    blocks 4;
+     122:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     132:0|      3: <1, 0>              |      i32:
+     134:4|      3: <4, 2>              |        %c0 = i32 1;
+     137:0|      3: <1, 3>              |      i1:
+     139:4|      3: <4, 0>              |        %c1 = i1 0;
+     142:0|    0: <65534>               |      }
+          |                             |  %b0:
+     144:0|    3: <11, 1, 2, 1>         |    br i1 %c1, label %b1, label %b2;
+          |                             |  %b1:
+     148:0|    3: <2, 2, 2, 0>          |    %v0 = add i32 %c0, %c0;
+     152:0|    3: <2, 3, 3, 1>          |    %v1 = sub i32 %c0, %c0;
+     156:0|    3: <11, 3>               |    br label %b3;
+          |                             |  %b2:
+     158:4|    3: <2, 4, 4, 2>          |    %v2 = mul i32 %c0, %c0;
+     162:4|    3: <2, 5, 5, 3>          |    %v3 = udiv i32 %c0, %c0;
+     166:4|    3: <11, 3>               |    br label %b3;
+          |                             |  %b3:
+     169:0|    3: <16, 0, 8, 1, 4, 2>   |    %v4 = phi i32 [%v0, %b1], 
+          |                             |        [%v2, %b2];
+     174:4|    3: <16, 0, 8, 1, 4, 2>   |    %v5 = phi i32 [%v1, %b1], 
+          |                             |        [%v3, %b2];
+     180:0|    3: <10>                  |    ret void;
+     181:6|  0: <65534>                 |  }
+
+Select Instruction
+------------------
+
+The *select* instruction is used to choose between pairs of values, based on a
+condition, without PNaClAsm-level branching.
+
+**Syntax**::
+
+  %vN = select CT C, T V1, T V2;                <A>
+
+**Record**::
+
+  AA: <29, VV1, VV2, CC>
+
+**Semantics**:
+
+The *select* instruction chooses pairs of values ``V1`` and ``V2``, based on
+condition value ``C``.  The type ``CT`` of value ``C`` must either be an i1, or a
+vector of type i1. The type of values ``V1`` and ``V2`` must be of type ``T``. Type
+``T`` must either be a primitive type, or a vector of a primitive type.
+
+Both ``CT`` and ``T`` must be primitive types, or both must be vector types of the
+same size. When the contents of ``C`` is 1, the corresponding value from ``V1`` will
+be chosen. Otherwise the corresponding value from ``V2`` will be chosen.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  CC == RelativeIndex(C) &
+  VV1 == RelativeIndex(V1) &
+  VV2 == RelativeIndex(V2) &
+  T == TypeOf(V1) == TypeOf(V2) &
+  UnderlyingType(CT) == i1 &
+  IsInteger(UnderlyingType(T)) or IsFloat(UnderlyingType(T)) &
+  UnderlyingCount(C) == UnderlyingCount(T) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**::
+
+      96:0|  1: <65535, 12, 2>          |  function i32 @f0(i32 %p0, i32 %p1) { 
+          |                             |                   // BlockID = 12
+     104:0|    3: <1, 1>                |    blocks 1;
+     106:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     116:0|      3: <1, 2>              |      i1:
+     118:4|      3: <4, 3>              |        %c0 = i1 1;
+     121:0|    0: <65534>               |      }
+          |                             |  %b0:
+     124:0|    3: <29, 3, 2, 1>         |    %v0 = select i1 %c0, i32 %p0, 
+          |                             |        i32 %p1;
+     128:0|    3: <10, 1>               |    ret i32 %v0;
+     130:4|  0: <65534>                 |  }
+
+
+Call Instructions
+-----------------
+
+The *call* instruction does a function call. The call instruction is used to
+cause control flow to transfer to a specified routine, with its incoming
+arguments bound to the specified values. When a return instruction in the called
+function is reached, control flow continues with the instruction after the
+function call. If the call is to a function, the returned value is the value
+generated by the call instruction. Otherwise no result is defined by the call.
+
+If the *tail* flag is associated with the call instruction, then the :ref:`PNaCl
+translator<link_for_pnacl_translator>` is free to perform tail call
+optimization. That is, the *tail* flag is a hint that may be ignored by the
+PNaCl translator.
+
+There are two kinds of calls: *direct* and *indirect*. A *direct* call calls a
+defined :ref:`function address<link_for_function_address_section>` (i.e. a
+reference to a bitcode ID of the form ``%fF``). All other calls are *indirect*.
+
+Direct Procedure Call
+^^^^^^^^^^^^^^^^^^^^^
+
+The direct procedure call calls a defined :ref:`function
+address<link_for_function_address_section>` whose :ref:`type
+signature<link_for_function_type>` returns type void.
+
+**Syntax**::
+
+  TAIL call void @fF (T1 A1, ... , TN AN);        <A>
+
+**Record**::
+
+  AA: <34, CC, F, AA1, ... , AAN>
+
+**Semantics**:
+
+The direct procedure call calls a define function address ``%fF`` whose type
+signature return type is void. The arguments ``A1`` through ``AN`` are passed
+in the order specified. The type of argument ``AI`` must be type ``TI`` (for all I,
+1 <=I <= N).  Flag ``TAIL`` is optional. If it is included, it must be the
+literal ``tail``.
+
+The types of the arguments must match the corresponding types of the function
+signature associated with ``%fF``. The return type of ``%f`` must be void.
+
+TAIL is encoded into calling convention value ``CC`` as follows:
+
+====== ==
+TAIL   CC
+====== ==
+""     0
+"tail" 1
+====== ==
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N >= 0 &
+  TypeOfFcn(%fF) == void (T1, ... , TN) &
+  TypeOf(AI) == TI for all I, 1 <= I <= N
+
+**Updates**::
+
+  ++NumValuedInsts;
+
+**Examples**::
+
+      72:0|  3: <8, 3, 0, 1, 0>         |  declare external 
+          |                             |      void @f0(i32, i64, i32);
+      ...
+     116:0|  1: <65535, 12, 2>          |  function void @f1(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     124:0|    3: <1, 1>                |    blocks 1;
+     126:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     136:0|      3: <1, 2>              |      i64:
+     138:4|      3: <4, 2>              |        %c0 = i64 1;
+     141:0|    0: <65534>               |      }
+          |                             |  %b0:
+     144:0|    3: <34, 0, 4, 2, 1, 2>   |    call void 
+          |                             |        @f0(i32 %p0, i64 %c0, i32 %p0);
+     150:2|    3: <10>                  |    ret void;
+     152:0|  0: <65534>                 |  }
+
+Direct Function Call
+^^^^^^^^^^^^^^^^^^^^
+
+The direct function call calls a defined function address whose type signature
+returns a value.
+
+**Syntax**::
+
+  %vN = TAIL call RT %fF (T1 A1, ... , TM AM);  <A>
+
+
+**Record**::
+
+  AA: <34, CC, F, AA1, ... , AAM>
+
+**Semantics**:
+
+The direct function call calls a defined function address ``%fF`` whose type
+signature returned is not type void. The arguments ``A1`` through ``AM`` are
+passed in the order specified. The type of argument ``AI`` must be type ``TI``
+(for all I, 1 <= I <= N).  Flag ``TAIL`` is optional. If it is included, it must
+be the literal ``tail``.
+
+The types of the arguments must match the corresponding types of the function
+signature associated with ``%fF``. The return type must match ``RT``.
+
+Each parameter type ``TI``, and return type ``RT``, must either be a primitive type,
+or a vector type.  If the parameter type is an integer type, it must either be
+i32 or i64.
+
+TAIL is encoded into calling convention value ``CC`` as follows:
+
+====== ==
+TAIL   CC
+====== ==
+""     0
+"tail" 1
+====== ==
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N >= 0 &
+  TypeOfFcn(%fF) == RT (T1, ... , TN) &
+  TypeOf(AI) == TI for all I, 1 <= I <= M &
+  IsFcnArgType(TI) for all I, 1 <= I <= M &
+  IsFcnArgType(RT) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = RT;
+
+**Examples**::
+
+      72:0|  3: <8, 2, 0, 1, 0>         |  declare external 
+          |                             |      i32 @f0(i32, i64, i32);
+      ...
+     116:0|  1: <65535, 12, 2>          |  function i32 @f1(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     124:0|    3: <1, 1>                |    blocks 1;
+     126:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     136:0|      3: <1, 1>              |      i64:
+     138:4|      3: <4, 2>              |        %c0 = i64 1;
+     141:0|    0: <65534>               |      }
+          |                             |  %b0:
+     144:0|    3: <34, 0, 4, 2, 1, 2>   |    %v0 = call i32 
+          |                             |        @f0(i32 %p0, i64 %c0, i32 %p0);
+     150:2|    3: <34, 1, 4, 1>         |    %v1 = tail call i32 @f1(i32 %v0);
+     155:0|    3: <10, 2>               |    ret i32 %v0;
+     157:4|  0: <65534>                 |  }
+
+Indirect Procedure Call
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The indirect procedure call calls a function using an indirect function address,
+and whose type signature is assumed to return type void. It is different from
+the direct procedure call because we can't use the type signature of the
+corresponding direct function address to type check the construct.
+
+**Syntax**::
+
+  TAIL call void V (T1 A1, ... , TN AN);        <A>
+
+**Record**::
+
+  AA: <44, CC, TV, VV, AA1, ... , AAN>
+
+**Semantics**:
+
+The indirect call procedure calls a function using value ``V`` that is an indirect
+function address, and whose type signature is assumed to return type void.  The
+arguments ``A1`` through ``AN`` are passed in the order specified. The type of
+argument ``AI`` must be type ``TI`` (for all I, 1 <= I <= N).  Flag ``TAIL`` is
+optional. If it is included, it must be the literal ``tail``.
+
+Each parameter type ``TI`` (1 <= I <= N) must either be a primitive type, or a
+vector type.  If the parameter type is an integer type, it must either be i32
+or i64.
+
+TAIL is encoded into calling convention value ``CC`` as follows:
+
+====== ==
+TAIL   CC
+====== ==
+""     0
+"tail" 1
+====== ==
+
+The type signature of the called procedure is assumed to be::
+
+  void (T1, ... , TN)
+
+It isn't necessary to define this type in the :ref:`types
+block<link_for_types_block_section>`, since the type is inferred rather than
+used.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  N >= 0 &
+  TV = TypeID(void) &
+  AbsoluteIndex(V) >= NumFuncAddresses &
+  TypeOf(AI) == TI for all I, 1 <= I <= N &
+  IsFcnArgType(TI) for all I, 1 <= I <= N
+
+**Updates**::
+
+  ++NumValuedInsts;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 3>                |    count 3;
+      50:4|    3: <2>                   |    @t0 = void;
+      52:2|    3: <7, 32>               |    @t1 = i32;
+      55:4|    3: <21, 0, 0, 1>         |    @t2 = void (i32);
+      59:4|  0: <65534>                 |  }
+      ...
+      92:0|  1: <65535, 12, 2>          |  function void @f0(i32 %p0) {  
+          |                             |                   // BlockID = 12
+     100:0|    3: <1, 1>                |    blocks 1;
+     102:4|    1: <65535, 11, 2>        |    constants {  // BlockID = 11
+     112:0|      3: <1, 1>              |      i32:
+     114:4|      3: <4, 2>              |        %c0 = i32 1;
+     117:0|    0: <65534>               |      }
+          |                             |  %b0:
+     120:0|    3: <44, 0, 2, 0, 1>      |    call void %p0(i32 %c0);
+     125:4|    3: <10>                  |    ret void;
+     127:2|  0: <65534>                 |  }
+
+Indirect Function Call
+^^^^^^^^^^^^^^^^^^^^^^
+
+The indirect function call calls a function using a value that is an indirect
+function address. It is different from the direct function call because we can't
+use the type signature of the corresponding literal function address to type
+check the construct.
+
+**Syntax**::
+
+  %vN = TAIL call RT V (T1 A1, ... , TM AM);  <A>
+
+**Record**::
+
+  AA: <34, CC, RRT, VV, AA1, ... , AAM>
+
+**Semantics**:
+
+The indirect function call calls a function using a value ``V`` that is an
+indirect function address, and is assumed to return type ``RT``.  The arguments
+``A1`` through ``AM`` are passed in the order specified. The type of argument ``AI``
+must be type ``TI`` (for all I, 1 <= I <= N).  Flag ``TAIL`` is optional. If it is
+included, it must be the literal ``tail``.
+
+Each parameter type ``TI`` (1 <= I <= M), and return type ``RT``, must either be a
+primitive type, or a vector type.  If the parameter type is an integer type, it
+must either be i32 or i64.
+
+TAIL is encoded into calling convention value ``CC`` as follows:
+
+====== ==
+TAIL   CC
+====== ==
+''     0
+'tail' 1
+====== ==
+
+The type signature of the called function is assumed to be::
+
+   RT (T1, ... , TN)
+
+It isn't necessary to define this type in the :ref:`types
+block<link_for_types_block_section>`, since the type is inferred rather than
+used.
+
+**Constraints**::
+
+  AA == AbbrevIndex(A) &
+  RRT = TypeID(RT) &
+  VV = RelativeIndex(V) &
+  M >= 0 &
+  AbsoluteIndex(V) >= NumFcnAddresses &
+  TypeOf(AI) == TI for all I, 1 <= I <= M &
+  IsFcnArgType(TI) for all I, 1 <= I <= M &
+  IsFcnArgType(RT) &
+  N == NumValuedInsts
+
+**Updates**::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = RT;
+
+**Examples**::
+
+      40:0|  1: <65535, 17, 2>          |  types {  // BlockID = 17
+      48:0|    3: <1, 6>                |    count 6;
+      50:4|    3: <7, 32>               |    @t0 = i32;
+      53:6|    3: <3>                   |    @t1 = float;
+      55:4|    3: <4>                   |    @t2 = double;
+      57:2|    3: <21, 0, 0, 0, 1, 2>   |    @t3 = i32 (i32, float, double);
+      62:6|    3: <21, 0, 0, 1, 2>      |    @t4 = i32 (float, double);
+      67:4|    3: <2>                   |    @t5 = void;
+      69:2|  0: <65534>                 |  }
+      ...
+     104:0|  1: <65535, 12, 2>          |  function 
+          |                             |      i32 
+          |                             |      @f0(i32 %p0, float %p1, 
+          |                             |          double %p2) {  
+          |                             |                   // BlockID = 12
+     112:0|    3: <1, 1>                |    blocks 1;
+          |                             |  %b0:
+     114:4|    3: <44, 0, 3, 0, 2, 1>   |    %v0 = call i32 
+          |                             |        %p0(float %p1, double %p2);
+     120:6|    3: <10, 1>               |    ret i32 %v0;
+     123:2|  0: <65534>                 |  }
+
+.. _link_for_memory_blocks_and_alignment_section:
+
+Memory Blocks and Alignment
+===========================
+
+In general, variable and heap allocated data are represented as byte addressable
+memory blocks. Alignment is always a power of 2, and defines an expectation on
+the memory address. That is, an alignment is met if the memory address is
+(evenly) divisible by the alignment. Note that alignment of 0 is never allowed.
+
+ Alignment plays a role at two points:
+
+* When you create a local/global variable
+
+* When you load/store data using a pointer.
+
+PNaClAsm allows most types to be placed at any address, and therefore can
+have alignment of 1. However, many architectures can load more efficiently
+if the data has an alignment that is larger than 1. As such, choosing a larger
+alignment can make load/stores more efficient.
+
+On loads and stores, the alignment in the instruction is used to communicate
+what assumptions the :ref:`PNaCl translator<link_for_pnacl_translator>` can
+make when choosing the appropriate machine instructions. If the alignment is 1,
+it can't assume anything about the memory address used by the instruction. When
+the alignment is greater than one, it can use that information to potentially
+chose a more efficient sequence of instructions to do the load/store.
+
+When laying out data within a variable, one also considers alignment. The reason
+for this is that if you want an address to be aligned, within the bytes defining
+the variable, you must choose an alignment for the variable that guarantees that
+alignment.
+
+In PNaClAsm, the valid load/store alignments are:
+
+=========== ==============
+Type        Alignment
+=========== ==============
+i1          1
+i8          1
+i16         1
+i32         1
+i64         1
+Float       1, 4
+Double      1, 8
+<4 x i1>    not applicable
+<8 x i1>    not applicable
+<16 x i1>   not applicable
+<16 x i8>   1
+<8 x i16>   2
+<4 x i32>   4
+<4 x float> 4
+=========== ==============
+
+Note that only vectors do not have an alignment value of 1. Hence, they can't be
+placed at an arbitrary memory address. Also, since vectors on ``i1`` can't be
+loaded/stored, the alignment is not applicable for these types.
+
+.. _link_for_intrinsic_functions_section:
+
+Intrinsic Functions
+===================
+
+Intrinsic functions are special in PNaClAsm. They are implemented as specially
+named (external) function calls. The purpose of these intrinsic functions is to
+extend the PNaClAsm instruction set with additional functionality that is
+architecture specific. Hence, they either can't be implemented within PNaClAsm,
+or a non-architecture specific implementation may be too slow on some
+architectures. In such cases, the :ref:`PNaCl
+translator<link_for_pnacl_translator>` must fill in the corresponding
+implementation, since only it knows the architecture it is compiling down to.
+
+Examples of intrinsic function calls are for concurrent operations, atomic
+operations, bulk memory moves, thread pointer operations, and long jumps.
+
+It should be noted that calls to intrinsic functions do not have the same
+calling type constraints as ordinary functions. That is, an intrinsic can use
+any integer type for arguments/results, unlike ordinary functions (which
+restrict integer types to ``i32`` and ``i64``).
+
+See the :doc:`PNaCl bitcode reference manual<pnacl-bitcode-abi>` for the full
+set of intrinsic functions allowed. Note that in PNaClAsm, all pointer types to
+an (LLVM) intrinsic function is converted to type i32.
+
+.. _link_for_support_functions_section:
+
+Support Functions
+=================
+
+Defines functions used to convert syntactic representation to values in the
+corresponding record.
+
+SignRotate
+----------
+
+The SignRotate function encodes a signed integer in an easily compressible
+form. This is done by rotating the sign bit to the rightmost bit, rather than
+the leftmost bit. By doing this rotation, both small positive and negative
+integers are small (unsigned) integers. Therefore, all small integers can be
+encoded as a small (unsigned) integers.
+
+The definition of SignRotate(N) is:
+
+======== ============= =========
+Argument Value         Condition
+======== ============= =========
+N        abs(N)<<1     N >= 0
+N        abs(N)<<1 + 1 N < 0
+======== ============= =========
+
+.. _link_for_absolute_index_section:
+
+AbsoluteIndex
+-------------
+
+Bitcode IDs of the forms ``@fN``, ``@gN``, ``%pN``, ``%cN``, and ``%vN``, are
+combined into a single index space. This can be done because of the ordering
+imposed by PNaClAsm. All function address bitcode IDs must be defined before any
+of the other forms of bitcode IDs. All global address bitcode IDs must be
+defined before any local bitcode IDs. Within a function block, the parameter
+bitcode IDs must be defined before constant IDs, and constant IDs must be
+defined before instruction value IDs.
+
+Hence, within a function block, it is safe to refer to all of these
+bitcode IDs using a single *absolute* index. The absolute index for
+each kind of bitcode ID is computed as follows:
+
+========== ===================================================================
+Bitcode ID AbsoluteIndex
+========== ===================================================================
+@tN        N
+@fN        N
+@gN        N + NumFcnAddresses
+@pN        N + NumFcnAddresses + NumGlobalAddresses
+@cN        N + NumFcnAddresses + NumGlobalAddresses + NumParams
+@vN        N + NumFcnAddresses + NumGlobalAddresses + NumParams + NumFcnConsts
+========== ===================================================================
+
+.. _link_for_relative_index:
+
+RelativeIndex
+-------------
+
+Relative indices are used to refer to values within instructions of a function.
+The relative index of an ID is always defined in terms of the index associated
+with the next value generating instruction. It is defined as follows::
+
+   RelativeIndex(J) = AbsoluteIndex(%vN) - AbsoluteIndex(J)
+
+where::
+
+   N = NumValuedInsts
+
+AbbrevIndex
+-----------
+
+This function converts user-defined abbreviation indices to the corresponding
+internal abbreviation index saved in the bitcode file. It adds 4 to its
+argument, since there are 4 predefined internal abbreviation indices (0, 1, 2,
+and 3).
+
+========= ==============
+N         AbbrevIndex(N)
+========= ==============
+undefined 3
+%aA       A + 4
+@aA       A + 4
+========= ==============
+
+Log2
+----
+
+This is the 32-bit log2 value of its argument.
+
+BitSizeOf
+---------
+
+Returns the number of bits needed to represent its argument (a type).
+
+======= ================
+T       BitSizeOf
+======= ================
+i1       1
+i8       8
+i16     16
+i32     32
+i64     64
+float   32
+double  64
+<N X T> N * BitSizeOf(T)
+======= ================
+
+UnderlyingType
+--------------
+
+Returns the primitive type of the type construct. For primitive types, the
+*UnderlyingType* is itself. For vector types, the base type of the vector is the
+underlying type.
+
+UnderlyingCount
+---------------
+
+Returns the size of the vector if given a vector, and 0 for primitive types.
+Note that this function is used to check if two vectors are of the same size.
+It is also used to test if two types are either primitive (i.e. UnderlyingCount
+returns 0 for both types) or are vectors of the same size (i.e. UnderlyingCount
+returns the same non-zero value).
+
+IsInteger
+---------
+
+Returns true if the argument is in {i1, i8, i16, i32, i64}.
+
+IsFloat
+-------
+
+Returns true if the argument is in {``float``, ``double``}.
+
+IsVector
+--------
+
+Returns true if the argument is a vector type.
+
+IsPrimitive
+-----------
+
+Returns true if the argument is a primitive type. That is::
+
+  IsPrimitive(T) == IsInteger(T) or IsFloat(T)
+
+IsFcnArgType
+------------
+
+Returns true if the argument is a primitive type or a vector type. Further,
+if it is an integer type, it must be i32 or i64. That is::
+
+  IsFcnArgType(T) = (IsInteger(T) and (i32 = BitSizeOf(T)
+                                       or i64 == BitSizeOf(T)))
+                    or IsFloat(T) or IsVector(T)
+
+.. _link_for_abbreviations_section:
+
+Abbreviations
+=============
+
+Abbreviations are used to convert PNaCl records to a sequence of bits. PNaCl
+uses the same strategy as `LLVM's bitcode file format
+<http://llvm.org/docs/BitCodeFormat.html>`_.  See that document for more
+details.
+
+It should be noted that we replace LLVM's header (called the *Bitcode Wrapper
+Format*) with the bytes of the :ref:`PNaCl record
+header<link_for_header_record_section>`.  In addition, PNaCl bitcode files do
+not allow *blob* abbreviation.
+
+.. _link_for_abbreviations_block_section:
+
+Abbreviations Block
+-------------------
+
+The abbreviations block is the first block in the module build. The
+block is divided into sections.  Each section is a sequence of records. Each
+record in the sequence defines a user-defined abbreviation.  Each section
+defines abbreviations that can be applied to all (succeeding) blocks of a
+particular kind. These abbreviations are denoted by the (global) ID of the form
+*@aN*.
+
+In terms of `LLVM's bitcode file format
+<http://llvm.org/docs/BitCodeFormat.html>`_, the abbreviations block is called a
+*BLOCKINFO* block. Records *SETBID* and *DEFINE_ABBREV* are the only records
+allowed in PNaCl's abbreviation block (i.e. it doesn't allow *BLOCKNAME* and
+*SETRECORDNAME* records).
+
+TODO
+----
+
+Extend this document to describe PNaCl's bitcode bit sequencer
+without requiring the reader to refer to `LLVM's bitcode file
+format <http://llvm.org/docs/BitCodeFormat.html>`_.