Initial draft of PNaCl bitcode files.

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

+===================================
+Pnacl Bitcode File Reference Manual

[jvoung (off chromium), 2014/07/28 19:20:35]

PNaCl

[Karl, 2014/11/14 22:35:34]

Done.

+===================================
+
+.. contents::
+   :local:
+   :backlinks: none
+   :depth: 3
+
+
+Introduction

[JF, 2014/07/28 20:58:11]

The intro is pretty long. I think having a figure illustrating the three layers
would make it much easier to follow the explanation.

[Karl, 2014/11/14 22:35:29]

Done.

+============
+
+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 *PNaCl records*. The
+final layer applies abbreviations that convert each PNaCl record into a
+corresponding sequence of bits.
+
+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 the abbreviations are used to convert PNaCl records into the sequence of bits.

[Sam Clegg, 2014/07/28 18:28:31]

Wrap at 80 here and a few lines down.

[Jim Stichnoth, 2014/07/28 22:52:08]

the the

[Karl, 2014/11/14 22:35:27]

Done.

[Karl, 2014/11/14 22:35:29]

Done.

+
+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, PNaCl records have a notion of tags (i.e. the first element in a record,

[Jim Stichnoth, 2014/07/28 22:52:03]

Instead of "tags", can you say "a tag", to keep singular/plural agreement with
the clarification in parentheses?

[Karl, 2014/11/14 22:35:31]

Rewrote to fix agreement.

+called a *code*), and nested structures. The nested structures are defined by
+corresponding *enter* and *exit* block records.
+
+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) sequence of bits. The output

[Jim Stichnoth, 2014/07/28 22:52:04]

"variable" - do you mean "variable-length"?

[Karl, 2014/11/14 22:35:34]

Done.

+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 default method for converting records into

[jvoung (off chromium), 2014/07/28 19:20:36]

nit: is "default" important for this first sentence?

vs

"For every kind of record, there is a method for converting records into bit
sequences"... Abbreviations can be user defined, but there are also pre-defined
defaults. Something like that?

[Karl, 2014/11/14 22:35:35]

Done.

+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. The default conversion methods
+are simply predefined abbreviations.
+
+The default abbreviations can be overridden with user-specified abbreviations.
+All user-specified abbreviations are included in the generated bitcode
+file. Each abbreviation defines how a record is converted to a bit sequence. The
+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.

[JF, 2014/07/28 20:58:12]

Mention pnacl-bccompress here?

[Karl, 2014/11/14 22:35:32]

Done.

+
+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.
+
+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*).

[JF, 2014/07/28 20:58:12]

Code should be in backticks: ``long long``

[Karl, 2014/11/14 22:35:28]

Done.

+
+Integers are assumed to be modeled using two's complement.  Floating point
+support is fixed at IEEE 754 32-bit and 64-bit values (float and double,
+respectively).

[JF, 2014/07/28 20:58:11]

The file reference/pnacl-c-cpp-language-support.rst has a section on IEEE-754,
you should link to it (you'll need to add an anchor in that file for the link to
work).

[Karl, 2014/11/14 22:35:31]

Done.

+
+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. This block defines global information
+  used by the program, followed by function blocks defining the implementation
+  of functions within the program.

[jvoung (off chromium), 2014/07/28 19:20:35]

Would it make sense to talk about any subblocks nested within the module block?

[Karl, 2014/11/14 22:35:32]

Done.

+
+Types block
+  Defines the set of types used by the program. All types used in the program
+  must be defined in this block. These types consist of primitive types as well
+  as high level constructs such as vectors and function signatures.
+
+Globals block
+  Defines the set of global addresses of global variables and constants used by
+  the program. It also defines how each global (associated with the global
+  address) is initialized.
+
+Valuesymtab block
+  Defines textual names for external function addresses.
+
+Function block
+  Each function (implemented) in a program has its own block that defines the
+  implementation of the corresponding function.
+
+Constants block
+  Each implemented function, that uses constants in its instructions, defines a

[Jim Stichnoth, 2014/07/28 22:52:04]

I would remove both commas.

[Karl, 2014/11/14 22:35:35]

Done.

+  constant block. Constants blocks appear within the corresponding function

[Jim Stichnoth, 2014/07/28 22:52:03]

"constants block", right?

[Karl, 2014/11/14 22:35:33]

Correct, and fixed.

+  block of the implemented function.
+
+Abbreviations block
+  Defines global abbreviations that are used to compress PNaCl records. This
+  block is segmented into multiple sections, one section for each kind of
+  block. This block appears at the beginning of the module block.

[JF, 2014/07/28 20:58:11]

Could you make all of the above links to the sections that describe them below.

[Karl, 2014/11/14 22:35:27]

Done.

+
+This section is only intended as a high-level discussion of blocks. Later
+subsections will dive more deeply into the constraints on how blocks must be

[Jim Stichnoth, 2014/07/28 22:52:04]

Use "sections" instead of "subsections"?

[Karl, 2014/11/14 22:35:35]

Done.

+laid out. This section only presents the overall concepts of what kinds of data

[Jim Stichnoth, 2014/07/28 22:52:06]

Either "what kinds of data are stored" or "what kind of data is stored".

[Karl, 2014/11/14 22:35:30]

Done.

+is stored in each of the blocks.
+
+A PNaCl program consists of a header record and a module block. The header
+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 module, types,
+globals, and abbreviations blocks define global identifiers, and only a single
+instance can appear.  The function and constant blocks define local identifiers,

[Jim Stichnoth, 2014/07/28 22:52:04]

only a single instance of each global identifier?

[Karl, 2014/11/14 22:35:31]

Yes. Each global is represented by a "global variable" value, and each of these
values have a single identifier associated with it.

+and can have multiple instances (one for each implemented function).
+
+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
+*constants block*, nested within the corresponding function block.
+
+All function blocks are associated with a corresponding function address. This
+association is (again) positional rather than explicit. That is, the Nth

[jvoung (off chromium), 2014/07/28 19:20:35]

After the reordering suggested in the previous rev of this, this is now the
first time positional association is mentioned. So the "again" can be removed.

[Karl, 2014/11/14 22:35:35]

Done.

+function block in a module block corresponds to the Nth defining (rather than
+declared) function address record in the module block.

[jvoung (off chromium), 2014/07/28 19:20:35]

I'm not sure it's clear that there are "function address records" in the module
block, until this point. Would it make sense to talk about that in the module
block description earlier?

[Karl, 2014/11/14 22:35:32]

Added a short paragraph before the paragraph on function blocks that describes
that only function addresses are defined as values 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 heading, 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 backwards

[Jim Stichnoth, 2014/07/28 22:52:08]

backward?

[Karl, 2014/11/14 22:35:33]

Done.

+compatibility, old 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 block. To separate global record codes from local record codes, large

[Jim Stichnoth, 2014/07/28 22:52:03]

blocks

[Karl, 2014/11/14 22:35:29]

Done.

+values are used.  Currently there are four global record codes.  To make these

[jvoung (off chromium), 2014/07/28 19:20:36]

Maybe add a link to the later deep dive?

[Karl, 2014/11/14 22:35:34]

Done.

+cases clear, and to leave room for lots of future growth in PNaClAsm, these

[Jim Stichnoth, 2014/07/28 22:52:03]

I would remove "lots of", maybe say "to leave ample room".

[Karl, 2014/11/14 22:35:35]

Done.

+special records have record codes close to the value 2**16. Note: Well-formed
+PNaCl bitcode files do not have record codes >= 2**16.

[JF, 2014/07/28 20:58:11]

You can do superscripts with:
2\ :sup:`16`\ .

(note that spaces need to be escaped after the 2 and before the period)

[Karl, 2014/11/14 22:35:32]

Done.

+ 
+A PNaCl record is denoted as follows:
+
+.. naclcode::
+
+  a: <v0, v1, ... , vN>
+
+The value *v0* is the record code. The remaining values, *v1* through *vN*, are

[JF, 2014/07/28 20:58:12]

You should use ``code quotes`` here, to be consistent with the naclcode above.

[Karl, 2014/11/14 22:35:27]

Done.

+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

[JF, 2014/07/28 20:58:11]

Same for ``a``

[Karl, 2014/11/14 22:35:29]

Done.

+a bit sequence.
+
+While most records (for a given record code) are of the same length, it is not

[Jim Stichnoth, 2014/07/28 22:52:08]

are of --> have ?

[Karl, 2014/11/14 22:35:35]

Done.

+true of all record codes. Some record codes can have arbitrary length. In
+particular, function type signatures, call instructions, phi nodes, switch
+instructions, and global variable initialization records all have variable
+length. The expected length is predefined and part of the PNaClAsm language. See
+the corresponding contruct (associated with the record) to determine the

[Jim Stichnoth, 2014/07/28 22:52:06]

construct

[Karl, 2014/11/14 22:35:34]

Done.

+expected length.
+
+The PNaCl bitstream writer, which converts records to bit sequences, does 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 block enter records.  These
+records must define how many bits are required to hold abbreviation indices
+associated with records of that block.
+
+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,
+  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,

[Jim Stichnoth, 2014/07/28 22:52:03]

may (in addition), --> may, in addition,
?

[Karl, 2014/11/14 22:35:30]

Done.

+abbreviations (of length *U*). The number of bits *B* specified for an enter
+record must be sufficiently large such that
+
+.. naclcode::
+
+   2**B >= U + 4
+
+In addition, the upper limit for B is 32.
+
+PNaClAsm requires that you specify the number of bits needed to read

[Jim Stichnoth, 2014/07/28 22:52:08]

that you specify --> specifying

[Karl, 2014/11/14 22:35:32]

Done.

+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 as a sequence of top-level *blocks*. Blocks can be nested
+within other blocks. 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

[Jim Stichnoth, 2014/07/28 22:52:07]

PNaClAsm. --> PNaClAsm,
(period to comma)

[Karl, 2014/11/14 22:35:30]

Done.

+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. 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 *PNaCl translator* uses this separation to
+parallelize the compilation of functions.
+
+In general, global identifiers are tied to a specific type of block. Local

[jvoung (off chromium), 2014/07/28 19:20:35]

There's some redundancy between this paragraph and the next. Can that be cleaned
up?

[Karl, 2014/11/14 22:35:29]

Done.

+identifiers are unique to the function block they appear in.
+
+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 *'%'*.

[JF, 2014/07/28 20:58:12]

I'd just use ``code quotes`` here too. Also 5 paragraphs up, when you defined
these, I'd be consistent.

[Karl, 2014/11/14 22:35:27]

Done.

+
+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 PNaCl translator, and downloaded though

[Jim Stichnoth, 2014/07/28 22:52:05]

though --> through
(or "over" or "via")

[Karl, 2014/11/14 22:35:28]

Done.

+the internet.

[Jim Stichnoth, 2014/07/28 18:21:07]

Internet?

[Karl, 2014/11/14 22:35:29]

Changed to 'cloud'.

+
+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), no topological sort
+exists. Loop carried value dependencies simply do not allow topologically
+sorting. To deal with this, function blocks have a notion of a forward
+(instruction value) declaration. 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 (see :ref:`forward type
+declarations<link_for_forward_type_declaration_section>`).
+
+The kinds of identifiers used in PNaClAsm are:
+
+@a
+  Global abbreviation identifier.
+
+%a
+  Block local abbreviation identifier.
+
+%b
+  Function local basic block identifier.
+
+%c
+  Function local constant identifier.
+
+@f
+  Global function address identifier.
+
+@g
+  Global variable/constant address identifier.
+
+%p
+  Function local parameter identifier.
+
+@t
+  Global type identifier.
+
+%v
+  Function local instruction generated value identifier.
+
+Conventions For Describing Records
+==================================
+
+PNaClAsm is the textual representation of 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:`link_for_global_state_section`. The global

[jvoung (off chromium), 2014/07/28 19:20:35]

For "notion of ... link_for_global_state_section"

Should that have a description other than "link_for_global_state_section"?

[Karl, 2014/11/14 22:35:29]

Good point. Fixing.

+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
+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 globa state and the corresponding syntax. It also

[Jim Stichnoth, 2014/07/28 18:21:08]

global

[Karl, 2014/11/14 22:35:30]

Done.

+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

[Jim Stichnoth, 2014/07/28 22:52:09]

remove parentheses?

[Karl, 2014/11/14 22:35:28]

Done.

+the corresponding PNaClAsm construct.
+
+Some semantics subsections use functions to compute values. The meaning of
+functions can be found in :ref:`link_for_support_functions_section`.

[jvoung (off chromium), 2014/07/28 19:20:35]

similar, does this "found in :ref:..." end up showing a more readable link text
than "found in link_for_support_functions_section" ? Does RST end up pulling the
section header in to fill the link text?

[Karl, 2014/11/14 22:35:32]

Just checked. If you don't specify text with a reference, it uses the
corresponding name associated with the link. Hence, that is why I dropped the
text on this, and the "global state" links. However, since the title of these
sections may change, fixing the :ref:'s to provide an explicit name.

+
+The syntax rule may include the abbreviation 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 abbreviation are optional in the

[Jim Stichnoth, 2014/07/28 22:52:09]

abbreviations

[Karl, 2014/11/14 22:35:29]

Done.

+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, lower case characters are literal values. Sequences of
+upper case alphanumeric characters are named values.  if we mix lower and upper

[jvoung (off chromium), 2014/07/28 19:20:34]

"if" -> "If"

[Karl, 2014/11/14 22:35:31]

Done.

+case letters within a name appearing in a syntax rule, the lower case letters
+are literal while the upper case sequence of alphanumeric charaters denote rule

[Jim Stichnoth, 2014/07/28 18:21:08]

characters

[Karl, 2014/11/14 22:35:31]

Done.

+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:
+
+.. naclcode::
+
+   %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.
+
+To be concrete, the syntactic rule above defines the structure of the following
+PNaClAsm examples.
+
+.. naclcode::
+
+  %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 a name that is defined by the other

[jvoung (off chromium), 2014/07/28 19:20:34]

At least to me, this sentence is a bit hard to understand: "a name that is
defined by the other subsections associated with the construct" mean?

Why subsections, plural? What's the difference between name vs identifier
(identifier seemed better defined than name)?

[Karl, 2014/11/14 22:35:28]

Tried cleaning this up (including using identifier).

+subsections 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:
+
+.. naclcode::
+
+  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 *pnacl-bcdis*, the corresponding output is:
+
+.. naclcode::
+
+    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 *Bth* byte. Hence, the bit position (in bits) is:
+
+.. naclcode::
+
+  B*8 + N
+
+Hence, the first *header* 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 header record 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, PNaClBitcode files. The first four bytes define the magic number of

[jvoung (off chromium), 2014/07/28 19:20:34]

"PNaClBitcode" is that meant to have a space between?

[Karl, 2014/11/14 22:35:32]

Done.

+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
+bitsequences using default abbreviations.

[Jim Stichnoth, 2014/07/28 18:21:05]

bit sequences

[Karl, 2014/11/14 22:35:27]

Done.

+
+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)".
+
+.. _link_for_memory_blocks_and_alignment_section:

[jvoung (off chromium), 2014/07/28 19:20:35]

This isn't linked to till later, so can it be moved later?

Is there a theme/higher level topic to group this under?

[Karl, 2014/11/14 22:35:30]

I didn't see a better place to put this, but I will think about it some more.
Decided (at least for the moment) to move this past the instructions, and before
the section on support functions.

I also moved the "intrinsic functions" section to appear after instructions.

+
+Memory Blocks and Alignment
+===========================
+
+In general, variable and heap allocated data are represented as byte addressable
+memory blocks. Alignment is address placement of these memory blocks. Alignment

[jvoung (off chromium), 2014/07/28 19:20:34]

Is there some word missing in the sentence "Alignment is address placement of
these memory blocks"? Are the later sentences enough to describe alignment?
(then you can remove that one sentence)

[Karl, 2014/11/14 22:35:32]

Removing the sentence.

+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, chosing a larger

[jvoung (off chromium), 2014/07/28 19:20:35]

"chosing" -> "choosing"

[Karl, 2014/11/14 22:35:34]

Done.

+alignment can make load/stores more efficient.
+
+On loads and stores, the aligment in the instruction is used to communicate what

[Jim Stichnoth, 2014/07/28 18:21:05]

alignment

[Karl, 2014/11/14 22:35:35]

Done.

+assumptions the 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 efficent sequence of

[Jim Stichnoth, 2014/07/28 18:21:05]

efficient

[Karl, 2014/11/14 22:35:32]

Done.

+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:

[Jim Stichnoth, 2014/07/28 22:52:07]

Do we say anything about <16 x i1> alignment?

[Karl, 2014/11/14 22:35:34]

Added not applicable entries since they can be loaded/stored. Also extended note
below to clarify this.

+
+=========== =========
+Type        Alignment
+=========== =========
+i1          1
+i8          1
+i16         1
+i32         1
+i64         1
+Float       1, 4
+Double      1, 8
+<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 any memory address.

[jvoung (off chromium), 2014/07/28 19:20:36]

they can't be placed at "an arbitrary" memory address (vs "any")?

[Karl, 2014/11/14 22:35:31]

Done.

+
+.. _link_for_intrinsic_functions_section:
+
+Intrinsic functions

[Jim Stichnoth, 2014/07/28 22:52:03]

Functions (capitalized for consistency)

[Karl, 2014/11/14 22:35:29]

Done.

+===================
+
+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 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 instrisic can use

[Jim Stichnoth, 2014/07/28 18:21:08]

intrinsic

[Karl, 2014/11/14 22:35:28]

Done.

+any integral type for arguments/results, unlike ordinary functions (which

[Jim Stichnoth, 2014/07/28 22:52:06]

The document has mixed use of "integer type" and "integral type".  I'm not sure
I understand the distinction between the two.  If there is none, could we just
use "integer" throughout?

[Karl, 2014/11/14 22:35:29]

Done.

[Karl, 2014/11/14 22:35:32]

Done.

+restrict integral types to i32 and i64).

[jvoung (off chromium), 2014/07/28 19:20:34]

The i32 and i64 parameter/return type restriction doesn't appear till later. Do
intrinsic functions need to be described here, or can it be moved till later
also?

[Karl, 2014/11/14 22:35:32]

Again, moved to appear after sections on instructions.

+
+See the :doc:`PNaCl bitcode reference manual<pnacl-bitcode-abi>` for the full
+set of intrinsic functions allowed.
+
+.. _link_for_global_state_section:
+

[jvoung (off chromium), 2014/07/28 19:20:35]

Can you add something to help w/ transitions between the previous section and
the upcoming sections?

Seems like this is about to deep dive into the various blocks (or after Global
State)

[Karl, 2014/11/14 22:35:33]

Added a "road map" section to describe the remaining sections.

+Global State
+============
+
+This section describes the global state associated with PNaClAsm.  It is used to
+define contextual data that is carried between records. The following
+subsections describe each element of the global state.
+
+Typing
+------
+
+Associated with most identifiers is a type. This type defines what type the
+corresponding value has. It is defined by the (initially empty) map
+
+.. naclcode::
+
+  TypeOf: ID -> Type
+
+For each type in the :ref:`types block<link_for_types_block_section>`, a
+corresponding inverse map
+
+.. naclcode::
+
+  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

[jvoung (off chromium), 2014/07/28 19:20:35]

capitalize "Updates" for consistency

[Karl, 2014/11/14 22:35:28]

Done.

+will not contain assignments to this map.
+
+Associated with each function identifier is its type signature. This is
+different than the type of the function identifier, since function identifiers
+represent the function addrress which is a pointer (and pointers are alwyas

[Jim Stichnoth, 2014/07/28 18:21:05]

address

[Jim Stichnoth, 2014/07/28 18:21:06]

always

[Karl, 2014/11/14 22:35:33]

Done.

[Karl, 2014/11/14 22:35:34]

Done.

+implemented as a 32-bit integer following the ILP32 data model).
+
+Function type signatures are maintained using:
+
+.. naclcode::
+
+  TypeOfFcn: ID -> Type
+
+In addition, if a function address has an implementing block, there is a
+corresponding implementation associated with the function address. To capture
+this association, we use the set:

[jvoung (off chromium), 2014/07/28 19:20:35]

nit: Just a set of IDs doesn't seem sufficient to "capture this association".
Seems like there would need to be map, instead, for ID -> Block.

It does indicate that a function has an implementation Block though?

[Karl, 2014/11/14 22:35:30]

Changed to say: "To indicate which functions have implementations, we use the
set:"

+
+.. naclcode::
+
+  DefiningFcnIDs: set(ID)
+
+ID Counters
+-----------
+
+Each block defines one (or more) kinds of values.  Value indices are generated

[Jim Stichnoth, 2014/07/28 22:52:08]

remove parentheses

[Karl, 2014/11/14 22:35:29]

Done.

+sequentially, starting at zero. To capture this, the following counters are
+defined:
+
+NumTypes
+  The number of types defined so far (in the types block)

[Jim Stichnoth, 2014/07/28 22:52:04]

period at the end for consistency

[Karl, 2014/11/14 22:35:33]

Done.

+
+NumFuncAddresses
+  The number of function addresses defined so far (in the module block).
+
+NumGlobalAddresses
+  The number of global variable/constant addresses defined so far (in the
+  globals block).
+
+NumParams
+  The number of parameters defined for a function.

[jvoung (off chromium), 2014/07/28 19:20:34]

So this is the only one that's not "so far".

[Karl, 2014/11/14 22:35:33]

Yes. Mainly because we introduce them all at once, from the corresponding type
signature of the function. Added note to clarify.

+
+NumFcnConsts
+  The number of constants defined in a function so far.
+
+NumBasicBlocks
+  The number of basic blocks defined so far (within a function block).
+
+NumValuedInsts
+  The number of instructions, generating values, defined so far (within a
+  function block) so far.

[jvoung (off chromium), 2014/07/28 19:20:34]

"so far" appears twice here

[Karl, 2014/11/14 22:35:31]

Done.

+
+Size Variables
+--------------
+
+A number of blocks define expected sizes of constructs. These sizes are recorded
+in the following size variables:
+
+ExpectedBasicBlocks
+  The expected number of basic blocks within a function implementation.
+
+ExpectedTypes
+  The expected number of types defined in the types block.
+
+ExpectedGlobals
+  The expected number of global variable/constant addresses in the globals
+  block.
+
+ExpectedInitializers
+  The expected number of initializers for a global variable/constant address in
+  the globals block.
+
+Other Variables
+---------------
+
+EnclosingFcnID
+  The function ID of the function block being processed.
+
+ConstantsSetType
+  Holds the type associated with the last *set type* record in the
+  constants block. Note: at the beginning of each constants block, this
+  variable is set to type void.
+
+Global records

[Jim Stichnoth, 2014/07/28 22:52:04]

capitalize Records

[Karl, 2014/11/14 22:35:34]

Done.

+==============
+
+There are four global PNaCl records, each having its own record code. These
+global records are:
+
+Header
+  The header record 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 enter record 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 exit record defines the end of a block. Hence, it must appear in every
+  block, to end the block.
+
+Abbreviation
+  An 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 special records can't have user-defined abbreviations associated with

[jvoung (off chromium), 2014/07/28 19:20:35]

Are "special records" the same as "global records"? Might be better to stick
with "global" than special.

[Karl, 2014/11/14 22:35:34]

Good point. Missed this when I changed from "special" to "global".

+them. The default abbreviation is always used.
+
+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**

[Sam Clegg, 2014/07/28 18:28:31]

Would it be better use a third level of section headers.  IIRC using **Foo** is
just adding a paragraph with some bold text rather than telling rest that this
is a header.  You could use ~~~~~~~~~ underlining maybe?

[Karl, 2014/11/14 22:35:35]

I don't really want to distinguish these. The reasons are:

1) In some cases, we exceed the maximum level for section headers.

2) I don't want these subsections showing up on the sidebar.

3) I want it easy to move these around, without having to edit.

+
+There is no syntax for header records in PNaClAsm.
+
+**Record**
+
+.. naclcode::
+
+   <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**
+
+There are no examples for the header record, since it is not part of PNaClAsm.

[jvoung (off chromium), 2014/07/28 19:20:34]

Instead of "since it is not part of", how about "since there is not syntax"? 

[Karl, 2014/11/14 22:35:30]

Done.

+
+.. _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 *exit* record.
+
+**Syntax**
+
+.. naclcode::
+
+  N {                                             <B>
+
+**Record**
+
+.. naclcode::

[Sam Clegg, 2014/07/28 18:28:31]

If you just want to fixed width font than I prefer not to use 'naclcode'.  Just
add :: to the end of the preceding paragraph:

**Record**::

[Karl, 2014/11/14 22:35:28]

Ok. I did not see that in the available documentation. Changing where
applicable.

+
+  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
+*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**
+
+.. naclcode::
+
+   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>                   |}
+
+Exit Block Record
+-----------------
+
+Block records can be top-level, as well as nested, records. Blocks must begin
+with an *enter* record, and end with an *exit* record.
+
+**Syntax**
+
+.. naclcode::
+
+  }
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+   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>                   |}
+
+Abbreviation Record
+-------------------
+
+Abbreviation records define abbreviations. See
+:ref:`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**
+
+.. naclcode::
+
+  A = abbrev <E1, ... , EM>;
+
+**Record**
+
+.. naclcode::
+
+  <65533, M, EE1, ... , EEM>
+
+**Semantics**
+
+Defines an abbreviation *A* as the sequence of encodings *E1* through *EM*.  If
+the abbreviation appears within the abbreviations block, *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 bit.

[jvoung (off chromium), 2014/07/28 19:20:35]

"N bit" -> "N bits"

[Karl, 2014/11/14 22:35:32]

Done.

+Vbr(N)   0, 2, N Encode value using a variable bit rate of N

[jvoung (off chromium), 2014/07/28 19:20:35]

end with period (for consistency w/ the rest of these)

[Karl, 2014/11/14 22:35:32]

Done.

+Char6    0, 4    Encode value as 6-bit char containing characters [a-zA-Z0-9._].
+Array    0, 3    Allow zero or more of the enclosed encoding

[jvoung (off chromium), 2014/07/28 19:20:36]

Clarify what is the "enclosed encoding"? It's the next element in the <E1, ...
EM>?

edit: okay, that's described below...

In the pnacl-bcdis syntax you use "array(Ei+1)" though.

[Karl, 2014/11/14 22:35:32]

I tried to clean this up, but I'm still not sure it is clear.

+======== ======= ===============================================================
+
+Notationally, Array encloses the encoding that immediately follows it, and must
+appear at the end of the abbreviation.
+
+**Examples**
+
+The following example shows the standard abbreviations used by *pnacl-finalize*.
+
+.. naclcode::
+
+    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>                   |}
+
+.. _link_for_types_block_section:
+
+Types Block
+===========
+
+The types block defines all types used in a program. It must appear in the
+module block, before any function address records, the globals block, the
+valuesymtab block, and any function blocks.
+
+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 identifer in the types block. Hence, the requirement that the

[Jim Stichnoth, 2014/07/28 18:21:07]

identifier

[Karl, 2014/11/14 22:35:27]

Done.

+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
+  integral and floating types.

[Jim Stichnoth, 2014/07/28 22:52:07]

There are a lot of uses of "floating type", and a lot of uses of "floating point
type".  Is there a difference in meaning?  If not, can we use one of them
consistently?  Preferably "floating point type".

[Karl, 2014/11/14 22:35:34]

Changed to use "floating point" everywhere.

+
+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 *count* record, defining how many
+types are defined by the types block. All remaining records defines a type. The

[Jim Stichnoth, 2014/07/28 22:52:04]

defines --> define

[Karl, 2014/11/14 22:35:31]

Done.

+following subsections define 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:
+
+.. naclcode::
+
+      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 type.
+@t2
+  The void type.
+@t3
+   A function, taking 32-bit integer and float arguments that returns void.
+
+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**
+
+.. naclcode::
+
+  count: N;                                       <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  0 == NumTypes
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedTypes = N;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  @tN = void;                                     <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <2>
+
+**Semantics**
+
+The void type record defines the type that has no values and has no size.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = void;
+
+**Examples**
+
+.. naclcode::
+
+   @t0 = void;
+
+defines the record

[jvoung (off chromium), 2014/07/28 19:20:34]

I wanted to check if this was meant to be a complete sentence: "defines the
record"? This also seems to be the only type w/ two examples instead of one. Is
one sufficient?

Also, perhaps in the second example, you can describe how "void"'s type ID is
referenced by the function type definition?

[Karl, 2014/11/14 22:35:29]

Simplified to a single case. Also removed partial sentence.

+
+.. naclcode::
+
+      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>                 |  }
+
+Integer Types
+-------------
+
+PNaClAsm allows integral 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**
+
+.. naclcode::
+
+  @tN = iB;                                      <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <7, B>
+
+**Semantics**
+
+An integer type record defines an integral type. *B* defines the number of bits
+of the integral type.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N == NumTypes
+  NumTypes < ExpectedTypes
+  B in {1, 8, 16, 32, 64}
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = iB;
+
+**Examples**
+
+.. naclcode::
+
+      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 float type record
+defines the 32-bit floating point type.
+
+**Syntax**
+
+.. naclcode::
+
+  @tN = float;                                    <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3>
+
+**Semantics**
+
+A floating type record defines the 32-bit floating point type.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A).
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = float;
+
+**Examples**
+
+.. naclcode::
+
+      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 double type
+record defines the 64-bit floating point type.
+
+**Syntax**
+
+.. naclcode::
+
+  @tN = double;                                   <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <4>
+
+**Semantics**
+
+A double type record defines the 64-bit floating point type.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = double;
+
+**Examples**
+
+.. naclcode::
+
+      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 primitve data are operated in parallel using a

[Jim Stichnoth, 2014/07/28 18:21:08]

primitive

[Karl, 2014/11/14 22:35:34]

Done.

+single instruction (SIMD). A vector type requires a size (number of elements)
+and an uderlying primitive data type.

[Jim Stichnoth, 2014/07/28 22:52:04]

underlying

[Karl, 2014/11/14 22:35:34]

Done.

+
+**Syntax**
+
+.. naclcode::
+
+  @tN = < E x T >                                 <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TT == AbsoluteIndex(TypeID(T))
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+*Updates*

[jvoung (off chromium), 2014/07/28 19:20:36]

double star the Updates for consistency?

[Karl, 2014/11/14 22:35:33]

Done.

+
+.. naclcode::
+
+  ++NumTypes
+  TypeOf(@tN) = <E x T>
+
+**Examples**
+
+The following types block defines all valid vector types:
+
+.. naclcode::
+
+      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>                 |  }
+
+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**
+
+.. naclcode::
+
+  %tN = RT (T1, ... , TM)                         <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral types that can be used for a
+return or parameter type are i32 and i64.  All other integral types are not
+allowed. For intrisic functions, all integral types are allowed for both return and

[Jim Stichnoth, 2014/07/28 18:21:06]

intrinsic

[Jim Stichnoth, 2014/07/28 22:52:07]

80-char

[Karl, 2014/11/14 22:35:28]

Done.

[Karl, 2014/11/14 22:35:34]

Done.

+parameter types.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  M >= 0
+  IRT == AbsoluteIndex(TypeID(RT))
+  IT1 == AbsoluteIndex(TypeID(T1))
+  ...
+  ITM == AbsoluteIndex(TypeID(TM))
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes
+  TypeOf(@tN) = RT (T1, ... , TM)
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:09]

capitalize Block

[Karl, 2014/11/14 22:35:27]

Done.

+=============
+
+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 module block. It must appear after the types block, as well as after all
+function address records. But, it must also appear before the valuesymtab block,
+and any function blocks.
+
+The globals block begins with a 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 compound record, 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 compound record. This

[Jim Stichnoth, 2014/07/28 22:52:07]

associated *with the* compound record ?

[Karl, 2014/11/14 22:35:34]

Done.

+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:`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:
+
+.. naclcode::
+
+      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 with 6 bytes: "1 2 3

[Jim Stichnoth, 2014/07/28 22:52:06]

g1 is initialized with ?

[Karl, 2014/11/14 22:35:28]

Done.

+4 0 0".
+
+Count Record
+------------
+
+The count record defines the number of global addresses used by the PNaCl
+program.
+
+**Syntax**
+
+.. naclcode::
+
+  count: N;                                       <A>
+
+**Record**
+
+.. naclcode::
+
+   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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedGlobals = N;
+  ExpectedInitializers = 0;
+
+**Examples**
+
+.. naclcode::
+
+  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>                 |  }
+
+Global Variable Addressses

[Jim Stichnoth, 2014/07/28 18:21:06]

Addresses

[Karl, 2014/11/14 22:35:35]

Done.

+--------------------------
+
+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**
+
+.. naclcode::
+
+  var @gN, align V,                               <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <0, VV, 0>
+
+**Semantics**
+
+A global variable address record defines a global address for a global variable.
+*V* is the memory alignment 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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N == NumGlobalAddresses
+  NumGlobalAddresses < ExpectedGlobals
+  ExpectedInitializers == 0
+  VV == Log2(V+1)
+
+**Updates**
+
+.. naclcode::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**
+
+.. naclcode::
+
+      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>                   |}
+
+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**
+
+.. naclcode::
+
+  const @gN, align V,                             <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <0, VV, 1>
+
+**Semantics**
+
+A global constant address record defines a global address for a global constant.
+*V* is the memory alignment 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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N == NumGlobalAddresses
+  NumGlobalAddresses < ExpectedGlobals
+  ExpectedInitializers == 0
+  VV == Log2(V+1)
+
+**Updates**
+
+.. naclcode::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  zerofill N;                                     <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <2, N>
+
+**Semantics**
+
+A zerofill initializer record intializes a sequence of bytes, associated with a

[Jim Stichnoth, 2014/07/28 18:21:06]

initializes

[Karl, 2014/11/14 22:35:33]

Done.

+global address, with zeros. The number of bytes initialized to zero is *N*.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  ExpectedInitializers > 0;
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  { B1 , .... , BN }                              <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, B1, ..., BN>
+
+**Semantics**
+
+A data record defines a sequence of bytes *B1* through *BN*, that initialize *N*
+bytes of memory.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  ExpectedInitializers > 0
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+   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 function,
+variable, or constant). Since addresses are pointers, a relocation initializer
+record defines 4 bytes of memory.
+
+**Syntax**
+
+.. naclcode::
+
+  reloc V;                                        <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <4, VV>
+
+**Semantics**
+
+A relocation initializer record defines a 4-byte value containing the specified
+global address *V*.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV == AbsoluteIndex(V);
+  VV >= NumFuncAddresses
+  VV < NumFuncAddresses + ExpectedGlobals
+  ExpectedInitializers > 0
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+  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 variable or constant), plus a constant. Since addresses are
+pointers, a relocation initializer record defines 4 bytes of memory.
+
+**Syntax**
+
+.. naclcode::
+
+  reloc V + O;                                    <A>

[Jim Stichnoth, 2014/07/28 22:52:06]

I don't have a constructive suggestion here, but "O" looks too much like "0".

[Karl, 2014/11/14 22:35:31]

Changed to use "X".

+  reloc V - O;                                    <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <4, VV, OOO>
+
+**Semantics**
+
+A relocation initializer record defines a 4-byte value containing the specified
+global (non-function) address *V*, modified by the unsigned offset *O*. *OO* is
+the corresponding signed offset. In the first form, *OO == O*. In the second
+form, *OO == - O*.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV == AbsoluteIndex(V)
+  VV >= NumFuncAddresses
+  VV < NumFuncAddresses + ExpectedGlobals
+  ExpectedInitializers > 0
+  OOO == SignRotate(OO)
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+      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>                 |  }
+
+
+Compound Initializer
+--------------------
+
+The compound initializer record must immediately follow a global
+variable/constant 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**
+
+.. naclcode::
+
+  initializers N {                                <A>
+   ...
+  }
+
+**Record**
+
+.. naclcode::
+
+  AA: <1, N>
+
+**Semantics**
+
+Defines that the next *N* initializers should be associated with the global
+address of the previous record.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  ExpectedInitializers == 1
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedInitializers = N;
+
+**Examples**
+
+.. naclcode::
+
+  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 ref does not define any values.  Its only goal is to

[Jim Stichnoth, 2014/07/28 22:52:04]

Is "ref" supposed to be here?

[Karl, 2014/11/14 22:35:33]

Removed.

+associate text names with external function addresses.  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 (see the module block's
+:ref:`link_for_function_address_section` record).  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**
+
+.. naclcode::
+
+  V : "NAME";                                     <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <1, B1, ... , BN>
+
+**Semnatics**

[Jim Stichnoth, 2014/07/28 18:21:08]

Semantics

[Karl, 2014/11/14 22:35:30]

Done.

+
+The *entry* record defines a name *NAME* for function address *V*. *NAME* is a
+sequence of anscii characters *B1* through *BN*.

[Jim Stichnoth, 2014/07/28 18:21:06]

ascii or ASCII

[Karl, 2014/11/14 22:35:32]

Done.

+
+**Examples**
+
+.. naclcode::
+
+      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>                 |  }
+
+Module Block
+============
+
+The module block, like all blocks, is enclosed in a pair of enter/exit records,
+using block ID 8. A well-formed module block consists of the following records
+(in order):
+
+A version record
+   The 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 abbreviations to use for records within the module
+   block.
+
+An abbreviations block
+   The abbreviations block 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 types block defines the set of all types used in the program.
+
+A non-empty sequence of function address records
+   Each record defines a function address 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 function block (appearing
+   later in the module) that defines the sequence of instructions for each
+   defined function.
+
+A globals block defining the global variables.
+   This block defines the set of global variable (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 block, if defined, provides textual names for function and global
+   variable addresses (previously defined in the module). Note that only names
+   for intrinsic functions and the start function are specified.
+
+A sequence of function blocks.
+   Each function block defines the corresponding control flow graph for each

[Jim Stichnoth, 2014/07/28 22:52:07]

control flow graph --> intermediate representation

This makes it consistent with line 146 above.

[Karl, 2014/11/14 22:35:35]

Done.

+   defined function. The order of function blocks is used to associate them with
+   function addresses.  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.
+
+Version
+-------
+
+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**
+
+.. naclcode::
+
+  version N;                                  <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+
+*Examples*
+
+.. naclcode::
+
+      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 implementations 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

[Jim Stichnoth, 2014/07/28 22:52:04]

"exception ... is" or "exceptions ... are"

[Jim Stichnoth, 2014/07/28 22:52:05]

All --> all

+this are *intrinsic* functions, which should only be *declared* and *external*,
+since intrinsic functions will automatically converted to appropriate code by

[Jim Stichnoth, 2014/07/28 22:52:04]

will be automatically

[Karl, 2014/11/14 22:35:33]

Done.

+the 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**
+
+.. naclcode::
+
+  PN LN T0 @fN ( T1 , ... , TM );                 <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <8, T, C, P, L>
+
+**Semantics**
+
+Decribes the function address *@fN*. *PN* is the name that specifies the

[Jim Stichnoth, 2014/07/28 18:21:06]

Describes

+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 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, integral parameter and types can only be i32 and i64.
+All other integer types are not 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
+= ====================
+
+**Constraint**
+
+.. naclcode::
+
+  AA = AbbrevIndex(A)
+  T = TypeID(TypeOf(T0 ( T1 , ... , TN )))
+  N = NumFuncAddresses
+
+**Updates**
+
+.. naclcode::
+
+  ++NumFuncAddresses;
+  TypeOf(@fN) = TypeOf(TypeID(i32));
+  TypeOfFcn(@fN) = TypeOf(@tT);
+
+  if PN == 0:
+    DefiningFcnIDs += @FN;
+    ++NumDefinedFunctionAddresses;
+
+**Examples**
+
+.. naclcode::
+
+      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();
+
+Constants Blocks
+================
+
+Constants blocks define literal constants used within each function. It's intent

[Jim Stichnoth, 2014/07/28 22:52:07]

It's --> Its

[Karl, 2014/11/14 22:35:28]

Done.

+it to define them once, before instructions. A constants block can only appear
+in a function block, and must appear before any instructions in the function
+block.
+
+Currently, only literal integrals, 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 *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:
+
+.. naclcode::
+
+  types {
+    @t0 = i1;
+    ...
+  }
+  ...
+  constants {
+    i1:
+      %c0 = i1 1;
+      %c2 = i1 2;
+  }
+
+The corresponding records for the constants block are:
+
+.. naclcode::
+
+  <65535, 11, 2>
+  <1, 0>
+  <4, 0>
+  <4, 2>
+  <65534>
+
+TODO(kschimpf) Generate pnacl-bcdis output for above.
+
+Set Type
+--------
+
+The *set type* record defines the type to use for the (immediately) succeeding
+literals.
+
+**Syntax**
+
+.. naclcode::
+
+  T:                                              <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <1, TT>
+
+**Semantics**
+
+The *set type* record deifnes type *T* to be used to type the (immediately)

[Jim Stichnoth, 2014/07/28 18:21:05]

defines

[Karl, 2014/11/14 22:35:28]

Done.

+succeeding literals. *T* must be a non-void primitive value type or a vector
+type.
+
+**Constraints**
+
+.. naclcode::
+
+  TT == TypeID(T)
+
+**Updates**
+
+.. naclcode::
+
+  ConstantsSetType = T;
+
+**Examples**
+
+.. naclcode::
+
+     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>               |      }
+
+Undefined Literal
+-----------------
+
+The *undefined* literal record creates an undefined literal for the type *T*
+defined by the preceding *set type* record.
+
+Note: See :ref:`link_for_insert_element_instruction_section` for an example of
+how you would use the undefined literal with vector types.
+
+**Syntax**
+
+.. naclcode::
+
+  %cN = T undef;                              <50>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3>
+
+**Semantics**
+
+The *undefined* lieral record creates an undefined literal constant *%cN* for

[Jim Stichnoth, 2014/07/28 18:21:05]

literal

[Karl, 2014/11/14 22:35:29]

Done.

+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**
+
+.. naclcode::
+
+   N == NumFcnConsts
+   T == ConstantsSetType
+   IsPrimitive(T) or IsVector(T)
+
+**Updates**
+
+.. naclcode::
+
+   ++NumFcnConsts;
+   TypeOf(%cN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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>               |      }
+
+
+Integer Literal
+---------------
+
+The *integer literal* record creates an integer literal for the integral type *T*

[Jim Stichnoth, 2014/07/28 22:52:05]

80-col

[Karl, 2014/11/14 22:35:30]

Done.

+defined by the preceding *set type* record.
+
+**Syntax**
+
+.. naclcode::
+
+  %cN = T V;                                      <A>
+
+**Record**
+
+.. naclcode::
+
+  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
+integral type. The literal *V* can be signed, but must be definable by type *T*.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumFcnConsts
+  T == ConsgtantsSetType

[Jim Stichnoth, 2014/07/28 18:21:06]

ConstantsSetType?

[Karl, 2014/11/14 22:35:27]

Done.

+  VV == SignRotate(V)
+  IsInteger(T)
+
+**Updates**
+
+  TypeOf(%cN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:07]

Floating Point Literal

+----------------------
+
+The *floating point literal* record creates a floating point literal for the
+floating type *T* defined by the preceding *set type* record.
+
+**Syntax**
+
+.. naclcode::
+
+  %cN = T V;                                      <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <6, V>
+
+**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* must be a valid IEE 754
+32-bit (unsigned integer) value if *T* is float, and a IEEE 754 64-bit (unsigned
+integer) value if *T* is double.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumFcnConsts
+  T == ConstantsSetType
+  IsFloat(T)
+
+**Updates**
+
+.. naclcode::
+
+  TypeOf(%cN) = T;
+
+** Examples **
+
+.. naclcode::
+
+      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* function address. 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 CFG

[Jim Stichnoth, 2014/07/28 22:52:05]

I don't think you need to use the CFG abbreviation, since it's not used anywhere
else in the document.

[Karl, 2014/11/14 22:35:30]

Done.

+(control flow graph). Each basic block contains a list of instructions, and ends
+with a :ref:`terminator<link_for_terminator_instruction_section>` (e.g. branch)
+instruction.
+
+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.  Blocks boundaries are determined by *terminator* instructions. The

[Jim Stichnoth, 2014/07/28 22:52:08]

Block boundaries

[Karl, 2014/11/14 22:35:27]

Done.

+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 type
+signature.
+
+The number of basic blocks is defined by the count record. Each terminator
+instruction 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
+relative index value, rather than absolute. 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.
+
+The following subsections define records that can appear in a function block.
+
+Function enter

[Jim Stichnoth, 2014/07/28 22:52:08]

Function Enter

[Karl, 2014/11/14 22:35:34]

Done.

+--------------
+
+PNaClAsm defines a function enter block construct. The corresponding record is
+simply an enter block record, with BlockID value 12. All context about the
+defining address is implicit by the position of the function block, and the
+corresponding defining function address. To improve readability, PNaClAsm
+includes the function signature into the syntax rule.
+
+**Syntax**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  N == NumFcnImpls
+  @fN in DefiningFcnIDs
+  TypeOfFcn(@fN) == TypeOf(TypeID(TR (T0, ... , TM)))
+
+**Updates**
+
+.. naclcode::
+
+  ++NumFcnImpls;
+  EnclosingFcnID = @fN;
+  NumBasicBlocks = 0;
+  ExpectedBlocks = 0;
+  NumParams = M;
+  for I in [0..M]:
+    TypeOf(%pI) = TypeOf(TypeID(TI));
+
+**Examples**
+
+.. naclcode::
+
+      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>                 |  }
+
+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**
+
+.. naclcode::
+
+    blocks: N;                                    <A>
+  %b0:
+
+**Record**
+
+.. naclcode::
+
+  AA: <1, N>
+
+**Semantics**
+
+The count record defines the number *N* of basic blocks in the implemented
+function.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  ExpectedBasicBlocks == N
+  NumBasicBlocks = 0
+
+**Updates**
+
+.. naclcode::
+
+     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 function block, 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 count
+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**
+
+.. naclcode::
+
+    ret void;                                     <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+   AA: <10>
+
+**Semantics**
+
+The return instruction returns control to the calling function.

[Jim Stichnoth, 2014/07/28 22:52:08]

Do you want "return instruction" or "return void instruction"?

[Karl, 2014/11/14 22:35:29]

Added void.

+
+*B* 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.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBLocks
+  ReturnType(TypeOf(EnclosingFcnID)) == void
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+.. naclcode::
+
+     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**
+
+.. naclcode::
+
+    ret T V;                                      <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+   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*.
+
+*B* 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.
+
+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 integral type, it must be either i32 or i64.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV == RelativeIndex(V)
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBlocks
+  T == TypeOf(V) == ReturnType(TypeOf(EnclosingFcnID))
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+.. naclcode::
+
+     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**
+
+.. naclcode::
+
+    br %bN;                                       <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+  AA: <11, N>
+
+**Semantics**
+
+The unconditional branch instruction causes control flow to transfer to basic
+block *N*.
+
+*B* 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.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  0 < N
+  N < ExpectedBasicBlocks
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+    br i1 C, %bT, %bBF;                          <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+  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*.
+
+*B* 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.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  CC == RelativeIndex(C)
+  0 < T
+  B1 < ExpectedBasicBlocks 
+  0 < F
+  B2 < ExpectedBasicBlocks
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBlocks
+  TypeOf(C) == i1
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+.. naclcode::
+
+      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 *PNaCl translator* that control can't reach this instruction.
+
+**Syntax**
+
+.. naclcode::
+
+    unreachable;                                  <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+  AA: <15>
+
+**Semantics**
+
+Directive to the *PNaCl translator* that this instruction is unreachable.  *B*
+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.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+.. naclcode::
+
+     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 generaliation of the conditional

[Jim Stichnoth, 2014/07/28 18:21:05]

generalization

[Karl, 2014/11/14 22:35:32]

Done.

+branch instruction.
+
+**Syntax**
+
+.. naclcode::
+
+    switch T V0 {
+      default: br label %bB0;
+      T V1:    br label %bB1;
+      ...
+      T VN:    br label %bBN;
+    }                                             <A>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+  AA: <12, TT, B0, N, (1, 1, VVI, BI | 1 <= i <= N)>
+
+**Sematics**

[Jim Stichnoth, 2014/07/28 18:21:05]

Semantics

[Karl, 2014/11/14 22:35:29]

Done.

+
+The switch instruction transfer control to a basic block in B0 through BN.

[Jim Stichnoth, 2014/07/28 22:52:06]

transfers

[Karl, 2014/11/14 22:35:35]

Done.

+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 integral 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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TT == TypeID(T)
+  VI == SignRotate(VI) for all I, 1 <= I <= N
+  B == NumBasicBlocks + 1
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode:
+
+  ++NumBasicBlocks;
+
+**Examples**  
+
+.. naclcode::
+
+     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>                 |  }
+
+
+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 integral values, or
+vectors of integral 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), integral
+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 integral, or an
+integral vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = add T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral
+type, or an integral 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 *exp(2,n)*, where *n* is

[Jim Stichnoth, 2014/07/28 22:52:04]

Here (and 2 other places) you use exp(2,n), but in 3 places near the beginning,
you use 2**n.  Can these be consistent?

[Karl, 2014/11/14 22:35:31]

Done.

+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 add instruction, integral type i1 (and a vector on integral type i1) is
+disallowed.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks

[jvoung (off chromium), 2014/07/28 19:20:34]

Do we need to have the NumBasicBlocks < ExpectedBasicBlocks constraint here, if
it's not updated?

[Karl, 2014/11/14 22:35:27]

Yes. It states that you can't branch to an unknown block. However, added
comment earlier in document so that it need not appear on all jump instructions.

+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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
+integral, or an integral vector type.
+
+Note: Since there isn't a negate instruction, subtraction from constant zero
+should be used to negate values.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = sub T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral
+type, or an integral 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 *exp(2, n)*, where *n* is
+the integer bitwidth of the 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, integral type i1 (and a vector on integral type i1)
+is disallowed.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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 integral,
+or an integral based vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  &vN = mul T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral type, or an integral 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 *exp(2, n)*, where *n* is
+the bitwidth of the 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, integral type i1 (or a vector on integrap type i1)

[Jim Stichnoth, 2014/07/28 18:21:05]

integral

[Jim Stichnoth, 2014/07/28 22:52:07]

multiply instruction

[Karl, 2014/11/14 22:35:35]

Done.

+is disallowed.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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
+integral, or an integral vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = sdiv T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral type, or an integral 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, integral type i1 (and a vector on
+integral 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 behaviour for this case is undefined.

[Jim Stichnoth, 2014/07/28 18:21:08]

behavior :)

[Jim Stichnoth, 2014/07/28 22:52:05]

Maybe say behavior is "currently" undefined?  Since we probably want to fix
that.

[Karl, 2014/11/14 22:35:29]

Done.

[Karl, 2014/11/14 22:35:29]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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 integral, or an integral vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = udiv T V1, V2;                            <a>
+
+**Record**
+
+.. naclcode::
+
+  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 integral type, or an integral vector type.  *N* is defined
+by the record position, defining the corresponding value generated by the
+instruction.
+
+Unsigned integral 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, integral type i1 (and a vector on
+integral type i1) is disallowed. Division by zero is guaranteed to trap.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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 integral, or an integral based vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = srem T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral type, or an integral 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, integral type i1 (and a vector on
+integral type i1) is disallowed.  Division by zero is guaranteed to trap.

[Jim Stichnoth, 2014/07/28 22:52:09]

You need the same comment as sdiv about undefined behavior when dividing min_int
by -1.

[Karl, 2014/11/14 22:35:32]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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 integral, or an integral vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = urem T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral type, or an integral 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, integral type i1 (and a vector on
+integral type i1) is disallowed.  Division by zero is guaranteed to trap.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+      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
+integral, or an integral vector type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = shl T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be an integral, or a vector of

[Jim Stichnoth, 2014/07/28 18:21:07]

must

[Karl, 2014/11/14 22:35:34]

Done.

+integrals. *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) is negative or equal to or larger than the

[Jim Stichnoth, 2014/07/28 22:52:08]

remove "is"

[Karl, 2014/11/14 22:35:31]

Done.

+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, integral type i1 (and a vector on integral type
+i1) is disallowed.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+
+.. naclcode::
+
+  %vN = lshr T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be an integral, or a

[Jim Stichnoth, 2014/07/28 18:21:04]

must

[Karl, 2014/11/14 22:35:34]

Done.

+vector of integrals. *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, integral type i1 (and a vector on
+integral type i1) is disallowed.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+
+.. naclcode::
+
+  %vN = ashr T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be an integral,

[Jim Stichnoth, 2014/07/28 18:21:09]

must

[Karl, 2014/11/14 22:35:35]

Done.

+or a vector of integrals. *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, integral type i1 (and a vector on
+integrl type i1) is disallowed.

[Jim Stichnoth, 2014/07/28 18:21:07]

integral

[Karl, 2014/11/14 22:35:29]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T))
+  UnderlyingType(T) != i1
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+ 
+.. naclcode::
+
+  %vN = and T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be an

[Jim Stichnoth, 2014/07/28 18:21:07]

must

[Karl, 2014/11/14 22:35:31]

Done.

+integral, or a vector of integrals. *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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T)))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+ 
+.. naclcode::
+
+  %vN = or T V1, V2;                              <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be

[Jim Stichnoth, 2014/07/28 18:21:05]

must

[Karl, 2014/11/14 22:35:35]

Done.

+an integral, or a vector of integrals. *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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T)))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+      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**
+ 
+.. naclcode::
+
+  %vN = xor T V1, V2;                             <A>
+
+**Record**
+
+.. naclcode::
+
+  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* nust be an integral, or a vector of integrals. *N* is

[Jim Stichnoth, 2014/07/28 18:21:07]

must

[Karl, 2014/11/14 22:35:33]

Done.

+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     0
+===== ===== ======
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  A1 == RelativeIndex(V1)
+  A2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsInteger(UnderlyingType(T)))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+    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>                 |  }
+
+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**
+
+.. naclcode::
+
+  %vN = fadd T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsFloat(UnderlyingType(T))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+
+.. naclcode::
+
+  %vN = fsub T V1, V2;                            <a>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsFloat(UnderlyingType(T))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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**
+
+.. naclcode::
+
+  &vN = fmul T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsFloat(UnderlyingType(T))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = fdiv T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <2, V1, V2, 4>
+
+**Semantics**
+
+The float divide instruction returns the quotient of its two

[Jim Stichnoth, 2014/07/28 22:52:06]

floating point divide instruction

[Karl, 2014/11/14 22:35:35]

Done.

+arguments. Arguments *V1* and *V2*, and the result *%vN* must be of type
+*T*. *T* must be a floating type, or a vector of a floating point type. *N* is

[Jim Stichnoth, 2014/07/28 22:52:06]

floating type --> floating point type

[Karl, 2014/11/14 22:35:27]

Done.

+defined by the record position, defining the corresponding value generated by
+the instruction.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV22 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsFloat(UnderlyingType(T))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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 floatint point remainder instruction returns the remainder of the quotient

[Jim Stichnoth, 2014/07/28 18:21:07]

floating

[Karl, 2014/11/14 22:35:31]

Done.

+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**
+
+.. naclcode::
+
+  %vN = frem T V1, V2;                            <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV1 == RelativeIndex(V1)
+  VV2 == RelativeIndex(V2)
+  T == TypeOf(V1) == TypeOf(V2)
+  IsFloat(UnderlyingType(T))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+.. naclcode::
+
+   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>                 |  }
+
+Memory Creation And Access Instructions

[Jim Stichnoth, 2014/07/28 22:52:09]

don't capitalize "and"

[Karl, 2014/11/14 22:35:31]

Done.

+---------------------------------------
+
+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.
+
+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**
+
+.. naclcode::
+
+  %vN = alloca i8, i32 S, align V;                <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral 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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  VV == Log2(V+1)
+  SS == RelativeIndex(S)
+  i32 == TypeOf(S)
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = i32;
+
+**Examples**
+
+.. naclcode::
+
+     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**
+
+.. naclcode::
+
+  %vN = load T* P, align V;                       <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integer.  *T* is the type
+of value to read. *V* is the alignment of the memory address.  *A* is the
+(optional) abbreviation associated with the record.
+
+Type *T* must be a vector, integral, or floating point type. Both float and
+double types are allowed for floating point types. All integral 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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  store T S, T* P, align V;                     <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral or floating point type. Both float and double types
+are allowed for floating point types. All integral 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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  i32 == TypeOf(P)
+  PP == RelativeIndex(P)
+  VV == Log2(V+1)
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Examples**
+
+The following instructions store an i32 integer and a 32-bit floating
+value.
+
+.. naclcode::
+
+      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>                 |  }
+
+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 integral
+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**
+
+.. naclcode::
+
+  %vN = trunc T1 V to T2;                         <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral 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 higer order bits are dropped.

[Jim Stichnoth, 2014/07/28 18:21:06]

higher

[Karl, 2014/11/14 22:35:28]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:06]

Can we just say T1 must be double and T2 must be float?

[Karl, 2014/11/14 22:35:34]

Done.

+floating point vectors with the same number of elements. The bit size of the
+source type must be larger than the bit size of the destination type. Equal
+sized types are not allowed.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = fptrunc T1 V to T2;                       <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 7>
+
+**Semantics**
+
+The floating 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* has to be wider than *T2*. If the value
+can't fit within the destination type *T2*, the results are undefined.
+
+**Constraints**
+
+.. naclcode::
+
+  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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+   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 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**
+
+.. naclcode::
+
+  %vN = zext T1 V to T2;                          <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral types, or integral 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**
+
+.. naclcode::
+
+  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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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 integral types, or integarl vectors with the same number

[Jim Stichnoth, 2014/07/28 18:21:09]

integral

[Karl, 2014/11/14 22:35:33]

Done.

+of Elements. The bit size of the source type must be smaller than the bit size

[Jim Stichnoth, 2014/07/28 22:52:03]

Elements --> elements

[Karl, 2014/11/14 22:35:34]

Done.

+of the destination type. Equal sized types are not allowed.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = sext T1 V to T2;                          <A>
+
+**Record**
+
+.. naclcode::
+
+  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 integral types, or integral 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**
+
+.. naclcode::
+
+  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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:06]

point --> Point

[Karl, 2014/11/14 22:35:33]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The floating point extending instruction takes a value to extend, and a type to
+extend it to. Both types must be floating types, or vectors of floating a

[Jim Stichnoth, 2014/07/28 22:52:04]

Like above, can we just say T1 must be float and T2 must be double?

[Karl, 2014/11/14 22:35:30]

Done.

+floating type with the same number of elements. The source value must be of
+float type, or a vector of float type. The extended value must be a double type,
+or a vector of double type.  If the source is a vector, the destination must
+also be vector with the same size as the source.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = fpext T1 V to T2;                           <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 8>
+
+**Semantics**
+
+The floating point extending instruction converts float values to double.  *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 values. *T2* has to be wider than *T1*.
+
+**Constraints**
+
+.. naclcode::
+
+  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
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:05]

To --> to ?

[Karl, 2014/11/14 22:35:28]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The floating point to unsigned integer instruction converts floating point
+values to an unsigned integers.

[Jim Stichnoth, 2014/07/28 22:52:05]

remobe "an"

[Karl, 2014/11/14 22:35:29]

Done.

+
+**Syntax**
+
+.. naclcode::
+
+  %vN = fptoui T1 V to T2;                        <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 3>
+
+**Semantics**
+
+The floating point to unsigned integer instruction coverts floating point values

[Jim Stichnoth, 2014/07/28 18:21:06]

converts

[Jim Stichnoth, 2014/07/28 22:52:05]

converts a floating point value

[Karl, 2014/11/14 22:35:34]

Done.

+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 integral type, or a
+integral vector type. If either type is a vector type, they both must be and

[Jim Stichnoth, 2014/07/28 22:52:06]

remove "be and"

[Karl, 2014/11/14 22:35:35]

Done.

+have the same number of elements.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TypeOf(V) == T1
+  VV == RelativeIndex(V)
+  %tTT2 == TypeID(T2)
+  UnderlyingCount(T1) == UnderlyingCount(T2)
+  IsFloat(UnderlyingType(T1))
+  IsInteger(UnderlyingType(T2))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:05]

To --> to ?

[Karl, 2014/11/14 22:35:34]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The floating point to signed integer instruction converts floating point
+values to signed integers.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = fptosi T1 V to T2;                        <A>
+
+**Record**
+
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 4>
+
+**Semantics**
+
+The floating point to signed integer instruction coverts floating point values

[Jim Stichnoth, 2014/07/28 18:21:05]

converts

[Jim Stichnoth, 2014/07/28 22:52:08]

converts a floating point value

+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 integral type, or a
+integral vector type. If either type is a vector type, they both must be and

[Jim Stichnoth, 2014/07/28 22:52:03]

Remove "be and"

[Karl, 2014/11/14 22:35:28]

Done.

+have the same number of elements.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TypeOf(V) == T1
+  VV == RelativeIndex(V)
+  %tTT2 = TypeID(T2)
+  UnderlyingCount(T1) = UnderlyingCount(T2)
+  IsFloat(UnderlyingType(T1))
+  IsInteger(UnderlyingType(T2))
+  N = NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+

[jvoung (off chromium), 2014/07/28 19:20:36]

naclcode ?

[Karl, 2014/11/14 22:35:31]

Done.

+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:08]

To --> to ?

[Karl, 2014/11/14 22:35:30]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The unsigned integer to floating point instruction converts unsigned integers to
+floating point values.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = uitofp T1 V to T2;                        <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 5>
+
+**Semantics**
+
+The unsigned integer to floating point instruction converts unsigned integers to

[Jim Stichnoth, 2014/07/28 22:52:03]

converts an unsigned integer

[Karl, 2014/11/14 22:35:33]

Done.

+its floating point equivalent of type *T2*. *T1* must be an integral type, or a
+integral 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 be and have the

[Jim Stichnoth, 2014/07/28 22:52:05]

remove "be and"

[Karl, 2014/11/14 22:35:34]

Done.

+same number of elements.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TypeOf(V) == T1
+  VV == RelativeIndex(V)
+  %tTT2 = TypeID(T2)
+  UnderlyingCount(T1) == UnderlyingCount(T2)
+  IsInteger(UnderlyingType(T1))
+  IsFloat(UnderlyingType(T2))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) == T2;
+
+**Examples**
+
+.. naclcode::
+
+      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

[Jim Stichnoth, 2014/07/28 22:52:05]

To --> to ?

[Karl, 2014/11/14 22:35:29]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The signed integer to floating point instruction converts signed integers to
+floating point values.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = sitofp T1 V to T2;                        <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <3, VV, TT2, 6>
+
+**Semantics**
+
+The signed integer to floating point instruction converts signed integers to its

[Jim Stichnoth, 2014/07/28 22:52:07]

converts a signed integer

[Karl, 2014/11/14 22:35:34]

Done.

+floating point equivalent of type *T2*. *T1* must be an integral type, or a
+integral 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 be and have the

[Jim Stichnoth, 2014/07/28 22:52:07]

remove "be and"

[Karl, 2014/11/14 22:35:28]

Done.

+same number of elements.
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TypeOf(V) == T1
+  VV == RelativeIndex(V)
+  %tTT2 = TypeID(T2)
+  UnderlyingCount(T1) == UnderlyingCount(T2)
+  IsInteger(UnderlyingType(T1))
+  IsFloat(UnderlyingType(T2))
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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 bitsize of the type of the value must be the same as

[Jim Stichnoth, 2014/07/28 18:21:08]

bit size

[Karl, 2014/11/14 22:35:28]

Done.

+the bitsize of the type it is casted to.

[Jim Stichnoth, 2014/07/28 18:21:05]

bit size

[Jim Stichnoth, 2014/07/28 18:21:08]

casted or cast?

[Karl, 2014/11/14 22:35:32]

Done.

+
+**Sytax**

[Jim Stichnoth, 2014/07/28 22:52:08]

Syntax

[Karl, 2014/11/14 22:35:33]

Done.

+
+.. naclcode::
+
+  %vN = bitcast T1 V to T2;                       <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  TypeOf(V) == T1
+  VV = RelativeIndex(V)
+  %tTT2 = TypeID(T2)
+  BitSizeOf(T1) == BitSizeOf(T2)
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T2;
+
+**Examples**
+
+.. naclcode::
+
+      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>                 |  }
+
+Integer Comparison Instructions
+-------------------------------
+
+The integer comparison instruction compares integral values and returns a
+boolean (i1) result for each pair of compared values.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = icmp C T V1, V2;                          <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <9, VV1, VV2, CC>
+
+**Semantics**
+
+The integer comparison instruction compares integral 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 integral type, or an integral 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 then
+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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  IsInteger(UnderlyingType(T)
+  T == TypeOf(V1) == TypeOf(V2)
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks  
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  if IsVector(T) then
+    TypeOf(%vN) = <UnderlyingCount(T), i1>
+  else
+    TypeOf(%vN) = i1
+  endif
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = fcmp C T V1, V2;                          <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <9, VV1, VV2, CC>
+
+**Semantics**
+
+The floating point comparison instruciton compares floating point values and

[Jim Stichnoth, 2014/07/28 18:21:06]

instruction

[Karl, 2014/11/14 22:35:27]

Done.

+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 yeilds an i1. If *T* is a

[Jim Stichnoth, 2014/07/28 18:21:06]

yields

[Karl, 2014/11/14 22:35:28]

Done.

+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)
+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 Alwyas true

[Jim Stichnoth, 2014/07/28 18:21:08]

Always

[Karl, 2014/11/14 22:35:30]

Done.

+===== == ==================================
+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  IsFloat(UnderlyingType(T)
+  T == TypeOf(V1) == TypeOf(V2)
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks  
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  if IsVector(T) then
+    TypeOf(%vN) = <UnderlyingCount(T), i1>
+  else
+    TypeOf(%vN) = i1
+  endif
+
+**Examples**
+
+.. naclcode::
+
+      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>                   |}
+
+Vector Instructions
+-------------------
+
+PNaClAsm supports several instructions that process vectors. This includes
+binary instructions and compare instructions. These instructions work with
+existing vectors and generate resulting (new) vectors. This section instroduces

[Jim Stichnoth, 2014/07/28 18:21:07]

introduces

[Karl, 2014/11/14 22:35:27]

Done.

+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 undefined vector literal. Using that constant as a starting point, one can
+built up the wanted vector by a sequence of *insert element* instructions.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = insertelement TV V, TE E, i32 I;          <A>
+
+**Record**
+
+.. naclcode::
+
+  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 i32 value.
+
+If *I* exceeds the length of *V*, the results is undefined.

[Jim Stichnoth, 2014/07/28 22:52:03]

result

[Karl, 2014/11/14 22:35:27]

Done.

+
+**Constrants**

[Jim Stichnoth, 2014/07/28 18:21:07]

Constraints

[Karl, 2014/11/14 22:35:28]

Done.

+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  IsVector(TV)
+  TypeOf(V) == TV
+  UnderlyingType(TV) == TE
+  TypeOf(I) == i32
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = TV;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = extractelement TV V, i32 I;                <A>
+
+**Record**
+
+.. naclcode::
+
+  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 i32 value. The type of *vN* must be the element type
+of vector *V*.
+
+If *I* exceeds the length of *V*, the results is undefined.

[Jim Stichnoth, 2014/07/28 22:52:08]

result

[Karl, 2014/11/14 22:35:33]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  IsVector(TV)
+  TypeOf(V) == TV
+  TypeOf(I) == i32
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = UnderlyingType(TV);
+
+**Examples**
+
+.. naclcode::
+
+      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>                 |  }
+
+Other Instructions
+------------------
+
+This section defines miscellaneous instructions which defy better
+classification.
+
+.. _link_for_forward_type_declaration_section:
+
+Forward type declaration

[Jim Stichnoth, 2014/07/28 22:52:05]

Forward Type Declaration

[Karl, 2014/11/14 22:35:32]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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**
+
+.. naclcode::
+
+  declare T %vN;                                  <A>
+
+**Record**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  AA = AbbrevIndex(A)
+  TT = TypeID(T)
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  TypeOf(%vN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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 predicessor block for which the

[Jim Stichnoth, 2014/07/28 18:21:05]

predecessor

[Jim Stichnoth, 2014/07/28 22:52:05]

for which --> that ?

[Karl, 2014/11/14 22:35:30]

Done.

[Karl, 2014/11/14 22:35:32]

Done.

+incoming value comes from.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = phi T [V1, %bB1], ... , [VM, %bBM];        <A>
+
+**Record**
+
+.. naclcode::
+
+  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 predicessor

[Jim Stichnoth, 2014/07/28 18:21:08]

predecessor

[Karl, 2014/11/14 22:35:30]

Done.

+blocks.  Each *VI* reaches via the incoming predicessor edge from block *%bBI*

[Jim Stichnoth, 2014/07/28 18:21:06]

predecessor

[Karl, 2014/11/14 22:35:31]

Done.

+(for 1 <= I <= M). Type *T* must be the type associated with each *VI*.
+
+**Constraints**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = select CT C, T V1, T V2;                <A>
+
+**Record**
+
+.. naclcode::
+
+  AA: <29, VV1, VV2, CC>
+
+**Semantics**
+
+The *select* instruction choses pairs of values *V1* and *V2*, based on

[Jim Stichnoth, 2014/07/28 18:21:08]

chooses

[Karl, 2014/11/14 22:35:28]

Done.

+condition values *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 conrresponding value from *V2* will be chosen.

[Jim Stichnoth, 2014/07/28 22:52:06]

corresponding

[Karl, 2014/11/14 22:35:35]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T;
+
+**Examples**
+
+.. naclcode::
+
+      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 *ret* instruction, in the called
+function, is reached control flow continues with instruction after the function

[Jim Stichnoth, 2014/07/28 22:52:03]

Commas more like this?

When a *ret* instruction in the called function is reached, control flow ...

[Jim Stichnoth, 2014/07/28 22:52:08]

with --> with the

[Karl, 2014/11/14 22:35:33]

Done.

[Karl, 2014/11/14 22:35:33]

Done.

+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 optimizers in

[Jim Stichnoth, 2014/07/28 22:52:09]

Remove "optimizers in", I think.

[Karl, 2014/11/14 22:35:30]

Done.

+the PNaCl translator is free to perform tail call optimiziation. That is, the

[Jim Stichnoth, 2014/07/28 18:21:06]

optimization

[Karl, 2014/11/14 22:35:31]

Done.

+*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 function address (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 function address whose type signature
+returns type void.
+
+**Syntax**
+
+.. naclcode::
+
+  TAIL call void @fF (T1 A1, ... , TN AN);        <A>
+
+**Record**
+
+.. naclcode::
+
+  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 arugment *AI* must be type *TI* (for all I,

[Jim Stichnoth, 2014/07/28 18:21:07]

argument

[Karl, 2014/11/14 22:35:31]

Done.

+1 <=I <= N).  Flag *TAIL* is optional. If it is included, it must the the

[Jim Stichnoth, 2014/07/28 22:52:06]

the the --> be the

[Karl, 2014/11/14 22:35:32]

Done.

+literal *tail*.
+
+The types of the arugments must match the corresponding types of the function

[Jim Stichnoth, 2014/07/28 18:21:07]

arguments

[Karl, 2014/11/14 22:35:35]

Done.

+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**
+
+.. naclcode::
+
+  AA == AbbrevIndex(A)
+  N >= 0
+  TypeOfFcn(%fF) == void (T1, ... , TN)
+  TypeOf(AI) == TI for all I, 1 <= I <= N
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = TAIL call RT %fF (T1 A1, ... , TM AM);  <A>
+
+
+**Record**
+
+.. naclcode::
+
+  AA: <34, CC, F, AA1, ... , AAM>
+
+**Semantics**
+
+The direct function call calls a defined function address *%fF* whose type
+signature returns is not type void. The arguments *A1* through *AM* are passed

[Jim Stichnoth, 2014/07/28 22:52:04]

returns --> returned

[Karl, 2014/11/14 22:35:33]

Done.

+in the order specified. The type of arugment *AI* must be type *TI* (for all I,

[Jim Stichnoth, 2014/07/28 18:21:07]

argument

[Karl, 2014/11/14 22:35:31]

Done.

+1 <= I <= N).  Flag *TAIL* is optional. If it is included, it must the the

[Jim Stichnoth, 2014/07/28 22:52:07]

the the --> be the

[Karl, 2014/11/14 22:35:29]

Done.

+literal *tail*.
+
+The types of the arugments must match the corresponding types of the function

[Jim Stichnoth, 2014/07/28 18:21:08]

arguments

[Karl, 2014/11/14 22:35:30]

Done.

+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 integral type, it must either be
+i32 or i64.
+
+TAIL is encoded into calling convention value *CC* as follows:
+
+====== ==
+TAIL   CC
+====== ==
+''     0
+'tail' 1
+====== ==
+
+**Constraints**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = RT;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  TAIL call void V (T1 A1, ... , TN AN);        <A>
+
+**Record**
+
+.. naclcode::
+
+  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
+arugment *AI* must be type *TI* (for all I, 1 <= I <= N).  Flag *TAIL* is

[Jim Stichnoth, 2014/07/28 18:21:06]

argument

[Karl, 2014/11/14 22:35:30]

Done.

+optional. If it is included, it must the the literal *tail*.

[Jim Stichnoth, 2014/07/28 22:52:05]

the the --> be the

[Karl, 2014/11/14 22:35:30]

Done.

+
+Each parameter type *TI* (1 <= I <= N) must either be a primitive type, or a
+vector type.  If the parameter type is an integral 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:
+
+.. naclcode::
+
+  void (T1, ... , TN)
+
+It isn't necessary to define this type in the types block, since the type is
+inferred rather than used.
+
+**Constraints**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+
+**Examples**
+
+.. naclcode::
+
+      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**
+
+.. naclcode::
+
+  %vN = TAIL call RT V (T1 A1, ... , TM AM);  <A>
+
+
+**Record**
+
+.. naclcode::
+
+  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 arugment *AI*

[Jim Stichnoth, 2014/07/28 18:21:08]

argument

[Karl, 2014/11/14 22:35:31]

Done.

+must be type *TI* (for all I, 1 <= I <= N).  Flag *TAIL* is optional. If it is
+included, it must the the literal *tail*.

[Jim Stichnoth, 2014/07/28 22:52:05]

the the --> be the

[Karl, 2014/11/14 22:35:33]

Done.

+
+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 integral 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:
+
+.. naclcode::
+
+   RT (T1, ... , TN)
+
+It isn't necessary to define this type in the types block, since the type is
+inferred rather than used.
+
+**Constraints**
+
+.. naclcode::
+
+  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**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = RT;
+
+**Examples**
+
+.. naclcode::
+
+      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_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 ID's of the forms *@fN*, *@gN*, *%pN*, *%cN*, and *%vN*, are combined

[Jim Stichnoth, 2014/07/28 22:52:07]

ID's --> IDs

[Karl, 2014/11/14 22:35:30]

Done.

+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
+========== ==========================================================================
+@fN        N
+@gN        N + NumFcnAddresses
+@pN        N + NumFcnAddresses + NumGlobalAddresses
+@cN        N + NumFcnAddresses + NumGlobalAddresses + NumParams
+@vN        N + NumFcnAddresses + NumGlobalAddresses + NumParams + NumFcnConsts
+========== ==========================================================================

[Sam Clegg, 2014/07/28 18:28:31]

Can you shorten the ======== lines to be 80 chars since none of the contents is
longer than 80?

[Karl, 2014/11/14 22:35:33]

Done.

+
+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:
+
+.. naclcode::
+
+   RelativeIndex(J) = AbsoluteIndex(%vN) - AbsoluteIndex(J)
+
+where
+
+.. naclcode::
+
+   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.
+
+exp
+---
+
+.. naclcode::
+
+  exp(n, m)
+
+Denotes the *m* power of *n*.
+
+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

[Sam Clegg, 2014/07/28 18:28:31]

Wrap at 80.

[Karl, 2014/11/14 22:35:27]

Done.

+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,
+
+.. naclcode::
+
+  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 integral type, it must be i32 or i64. That is,
+
+.. naclcode::
+
+  IsFcnArgType(T) = (IsInteger(T) and (i32 = BitSizeOf(T)
+                                       or i64 == BitSizeOf(T)))
+                    or IsFloat(T) or IsVector(T)
+
+.. _link_for_abbreviations_section:
+
+Abbreviations
+-------------
+
+TODO(kschimpf) Discuss the following:
+
+* Blocks.
+* Data Records.
+* Abbreviations.
+* Abbreviation Ids.
+
+Bitstream Format
+^^^^^^^^^^^^^^^^
+
+TODO(kschimpf)
+
+* Header
+* Block Structure
+* Primitives
+* Abbreviations
+* Abbreviations block
+
+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*.
+
+TODO(kschimpf) Fill this in more.
+
+Reference Implementation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO(kschimpf)