Initial draft of PNaCl bitcode files document.

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

Index: native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
diff --git a/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst b/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
new file mode 100644
index 0000000000000000000000000000000000000000..efa2b727ce489c9d0252247d814d6e36e0b401d9
--- /dev/null
+++ b/native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst
@@ -0,0 +1,2720 @@
+===================================
+PNaCl Bitcode File Reference Manual
+===================================
+
+.. contents::
+   :local:
+   :backlinks: none
+   :depth: 3
+
+
+Introduction
+============
+
+This document is a reference manual for the contents of PNaCl bitcode

[Jim Stichnoth, 2014/05/08 12:55:17]

Formatting nit.  Looks like your emacs fill column is set to 70 or 72.  How
about 80?

[Karl, 2014/06/02 22:39:29]

Done.

+files. It is presented using assembly language *PNaClAsm*. PNaClAsm
+uses a *static single assignment* (SSA) model, based a representation

[Jim Stichnoth, 2014/05/08 12:55:17]

This sentence doesn't parse.  Do you mean something like "... (SSA) based
representation that ..." ?

[Karl, 2014/06/02 22:39:29]

Done.

+that requires generated results to have a single (assignment)
+source. PNaClAsm is the textual version of the bitcode file.
+
+PNaClAsm focusses on the semantic content of the file, not the

[jvoung (off chromium), 2014/05/27 23:18:50]

focuses

[Karl, 2014/06/02 22:39:29]

Done.

+bit-encoding of that content. However, it does provide annotations
+that allows one to specify how the PNaCl bitcode writer converts the

[Jim Stichnoth, 2014/05/08 12:55:17]

allows --> allow

[Karl, 2014/06/02 22:39:29]

Done.

+semantic content of a PNaClAsm program, into a specific bit sequence.
+
+Below PNaClAsm is the high-level form of the data stored in PNaCl
+bitcode files. Each construct in PNaClAsm defines a corresponding
+*PNaCl record* [ref].  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, 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 parentheses to define the block

[jvoung (off chromium), 2014/05/27 23:18:50]

how about "like balanced parentheses" ?

[Karl, 2014/06/02 22:39:29]

Done.

+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 wrtier* takes the sequence of records, defined by a

[Jim Stichnoth, 2014/05/08 12:55:17]

writer

[Karl, 2014/06/02 22:39:29]

Done.

+PNaClAsm program, and coverts each record into a (variable) sequence

[Jim Stichnoth, 2014/05/08 12:55:17]

converts

[Karl, 2014/06/02 22:39:29]

Done.

+of bits. The output of each bit sequence is appended together. The
+resulting generated sequence of bits is the contents of the PNaCl
+bitcode file.
+
+For every kind of record, there are default methods for converting

[Jim Stichnoth, 2014/05/08 12:55:17]

"..., there is a default method ...", right?

[Karl, 2014/06/02 22:39:29]

Done.

+records into bit sequences. These methods correspond to a notion of
+*abbreviations* [ref]. Each abbreviation defines a specific bit
+sequence conversion to be applied. The default conversion methods are
+simply predefined abbreviations.
+
+The default abbreviations can be overriddeen with user-specified

[binji, 2014/05/02 18:04:52]

overridden 

[Karl, 2014/06/02 22:39:29]

Done.

+abbrreviations.  All user-specified abbreviations are included in the

[binji, 2014/05/02 18:04:52]

abbreviations

[Karl, 2014/06/02 22:39:29]

Done.

+generated bitcode file. Each abbreviation defines how records are
+converted to bit sequences. The *PNaCl bitcode writer* uses these
+abbreviations to convert the corresponding record sequence into a
+corresponding bit sequence. As a result, all records have an
+abbreviation (user or default) associated with them.
+
+The *PNaCl bitcode reader* then uses these abbreviations to convert
+the bit sequences back into the corresponding records.
+
+Conceptually, abbreviations are used to define how to pack the
+contents of records into bit sequenes.  The main reason for defining

[binji, 2014/05/02 18:04:52]

sequences

[Karl, 2014/06/02 22:39:29]

Done.

+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 seperated from semantic

[binji, 2014/05/02 18:04:52]

separated

[Karl, 2014/06/02 22:39:29]

Done.

+content. This allows different use cases to decide how much effort
+should be spent on compressing records.
+
+For a JIT translator, little (if any) compression should be

[Jim Stichnoth, 2014/05/08 12:55:17]

For PNaCl, we've been consistently using "translator" to mean the compiler that
translates from PNaCl bitcode to native code.  Can you instead say "JIT
compiler", and maybe also clarify that you mean a JIT compiler that produces
PNaCl bitcode?

[Karl, 2014/06/02 22:39:29]

Done.

+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 accross the web, one may want to compress the sequence of

[binji, 2014/05/02 18:04:52]

across

[Karl, 2014/06/02 22:39:29]

Done.

+bits considerably, to reduce costs in delivering web pages.
+
+High Level Basics
+=================
+
+A program is defined as a sequence of top-level Blocks. Blocks
+can be nested within other blocks. Each *block* defines a sequence of

[Jim Stichnoth, 2014/05/08 12:55:17]

Weird inconsistency involving capitalization and italicization of "block".  I
think you want this:

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.

[Karl, 2014/06/02 22:39:29]

Done.

+records.
+
+Most of the records, within a block, also define a unique values.

[jvoung (off chromium), 2014/05/27 23:18:50]

"define a unique values" -> "define unique values" ?

[Karl, 2014/06/02 22:39:29]

Done.

+Each unique value is given a corresponding unique identifier
+(i.e. *ID*). In PNaClAms. each kind of block defines it own kind of

[binji, 2014/05/02 18:04:52]

PNaClAsm

[Jim Stichnoth, 2014/05/08 12:55:17]

it --> its

[Karl, 2014/06/02 22:39:29]

Done.

[Karl, 2014/06/02 22:39:29]

Done.

+identifiers. The names of these identifiers are defined by
+concatinating a prefix character ('@' or '%'), the kind of block (a

[binji, 2014/05/02 18:04:52]

concatenating

[Karl, 2014/06/02 22:39:29]

Done.

+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. All other identifiers are
+global. This split is intentional. Global identifiers are used by
+multiple functions, and therefore must be unique accross all function

[Jim Stichnoth, 2014/05/08 12:55:17]

across

[Karl, 2014/06/02 22:39:29]

Done.

+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.
+
+Global identifiers use the prefix character *'@'* while local
+identifiers use the prefix character *'%'*.
+
+Note: There is one exception to this separation of local and global

[jvoung (off chromium), 2014/05/27 23:18:50]

How is this an exception?

For identifiers, locals only apply to the block it appears in (the current
function). Globals can be referenced by multiple block instances (multiple
functions).

I think what you want to clarify is that the global abbreviations, though
global, are tied to a specific type of block. E.g., there can be global function
abbreviations, that work on function blocks but don't work on value symbol table
blocks. The identifiers for those globals are therefore not unique (unless you
want to make the identifier of global abbreviations have a sort of namespacing).

E.g., instead of @a1 and @a1. Have @b4::a1 and @b3::a1.

[Karl, 2014/06/02 22:39:29]

I did not like the idea of adding abbreviation namespacing, so I did not add it.
However, I agree that this paragraph needed rewriting, and the need to clarify
uniqueness of identifiers. I rewrote it (and moved it before the previous
paragraph).

+identifiers.  Abbreviations can be defined locally and globally. An
+abbreviation is local if it only applies to the block it appears
+in. If it is global, the abberviation can apply to multiple block

[binji, 2014/05/02 18:04:52]

abbreviation

[Karl, 2014/06/02 22:39:29]

Done.

+instances.
+
+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.

[jvoung (off chromium), 2014/05/27 23:18:50]

and downloaded through the internets ?

[Karl, 2014/06/02 22:39:29]

Done.

+
+In general, most of the records and blocks are assumed to be
+topologically sorted, putting value definitions before thier uses.

[binji, 2014/05/02 18:04:52]

their

[Karl, 2014/06/02 22:39:29]

Done.

+This implies that records do not need to encode data if it can use the
+corresponding information from it's uses.

[Jim Stichnoth, 2014/05/08 12:55:17]

it's --> its

Also, there is an agreement problem, should probably be one of the following:

This implies that a record does not need to encode data if it can use the
corresponding information from its uses.

This implies that records do not need to encode data if they can use the
corresponding information from their uses.

[Karl, 2014/06/02 22:39:29]

Done.

+
+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 with the
+instruction.
+
+However, For function blocks (which define instructions), no

[Jim Stichnoth, 2014/05/08 12:55:17]

For --> for

[Karl, 2014/06/02 22:39:29]

Done.

+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) declarations. These

[Jim Stichnoth, 2014/05/08 12:55:17]

declarations --> declaration

[Karl, 2014/06/02 22:39:29]

Done.

+decalrations must appear before any of the uses of that value, if the

[binji, 2014/05/02 18:04:52]

declarations

[Karl, 2014/06/02 22:39:29]

Done.

+(instruction) value is defined later in the function, than its first

[Jim Stichnoth, 2014/05/08 12:55:17]

I would drop the comma.

[Karl, 2014/06/02 22:39:29]

Done.

+use.

[jvoung (off chromium), 2014/05/27 23:18:50]

link to the special fwd ref record opcode?

[Karl, 2014/06/02 22:39:29]

Done.

+
+PNaCl Blocks
+============
+
+Blocks are used to organize records in the bitcode file.  The
+kinds of blocks defined in PNaClAsm are:
+
+Types block

[jvoung (off chromium), 2014/05/27 23:18:50]

Is it worth splitting this into blocks that are expected to have one global
instance, and blocks that have multiple instances?

Or just within the description of each block clarify that.

Should the module block come first?

[Karl, 2014/06/02 22:39:29]

Moved the module block first. Added clarifying paragraph, following this list,
that clarifies which blocks define global identifiers, and can appear only once,
and those that can be repeated.

+  Defines the set of types used by the program. All types used in the
+  program must be defined in this block.

[Jim Stichnoth, 2014/05/08 12:55:17]

Question.  Since PNaCl bitcode types are limited to i1, i8, i16, i32, i64, f32,
and f64, why bother listing them?

Edit: I see my question is answered below.  Might not hurt to add a clarifying
hint here:  "These types consist of primitive types as well as high level
constructs such as vectors and function signatures."

[jvoung (off chromium), 2014/05/27 23:18:50]

Might be good to link to a section about the allowed types?

[Karl, 2014/06/02 22:39:29]

Good suggestion. done.

+
+Globals block
+  Defines the set of global addresses of global variables and
+  constants, used by the program. It also defines how each global

[jvoung (off chromium), 2014/05/27 23:18:50]

I'm not a grammar expert, but you might not need that comma:

 "constants, used by" ?

[Karl, 2014/06/02 22:39:29]

Done.

+  (associated with the global address) is initialized.
+
+Valuesymtab block
+  Defines textual names for global and function addresses.
+
+Function block
+  Each function (implemented) in a program has it's own block that

[Jim Stichnoth, 2014/05/08 12:55:17]

its

[Karl, 2014/06/02 22:39:29]

Done.

+  defines the implementation of the corresponding function.
+
+Constants Block

[Jim Stichnoth, 2014/05/08 12:55:17]

Block --> block

[Karl, 2014/06/02 22:39:29]

Done.

+  Each implemented function, that uses constants in its
+  instructions, defines a constant block. Constants blocks appear
+  within corresponding function block.

[Jim Stichnoth, 2014/05/08 12:55:17]

within the corresponding

[Karl, 2014/06/02 22:39:29]

Done.

+
+Modue block

[binji, 2014/05/02 18:04:52]

Module

[Karl, 2014/06/02 22:39:29]

Done.

+  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.
+
+Abbreviations block
+  Defines abbreviations that are used to compress PNaCl records. This

[jvoung (off chromium), 2014/05/27 23:18:50]

The "Abbreviations block" formerly known as the "Block Info Block". Is it worth
mentioning this alias? I agree that it's clearer to call this the Abbreviations
block instead of "block info block", since we aren't using the block info block
for anything else (dropped SETRECORDNAME, etc.).

Clarify that this is the block for defining *global* abbreviations?

The other (local) DEFINE_ABBREV don't have a separate
ENTER_SUBBLOCK/EXIT_SUBBLOCK.

[Karl, 2014/06/02 22:39:29]

From what I can tell, the "block info block" of llvm only contains abbreviations
as well. That is why I decided to change the name. I see
more confusion being added to this document to reference the internal names
used by the implementation. For readers (and implementors) of new language
translators, none of this matters.

I tried to clarify that the abbreviations block only defines *global*
abbreviations.

+  block is segmented into multiple sections, one section for each kind
+  of block. This block is optional and need not be defined.
+
+A PNaCl program consists of a header record, an optional abbreviations
+block, and a module block.

[jvoung (off chromium), 2014/05/27 23:18:50]

Is it worth mentioning that in the next couple of sections, you will describe a
few more constraints on how the blocks are laid out?

[Karl, 2014/06/02 22:39:29]

Added an initial paragraph (after the block list) clarifying that we aren't
doing a deep dive here. Nor are we defining layout constraints. Rather, the
paragraph states that later subsections will do these deep dives.

+
+Each block, within a bitcode file, defines values. These values are
+associated with IDs. Each type of block defines different kinds of
+IDs.
+

[jvoung (off chromium), 2014/05/27 23:18:50]

How does this look in the html? Should there be a bigger subsection dividing
line for each of the deep dives?

[Karl, 2014/06/02 22:39:29]

What I may agree on is that I am probably introducing too deep a concept when I
introduce the types of identifier names associated with each blocks. Will
refactor identifier names into a separate section, or move them to the
corresponding subsection that describes the contents of that block.

+The *types block* [ref] defines types used by the program. Each record
+in the types block defines a separate type. Valid types include
+various sizes of integer and floating types. They also define higher
+level constructs such as vectors and function signatures. For each
+definition, a type ID is defined. A type ID is of the form *@tN*,
+where *N* corresponds to the (relative) position of the corresponding
+defining record in the types block.
+
+The types block must appear within the module block,
+and must appear before any block that uses a typed value.  Many
+PNaClAsm constructs allows one to use explicit type names, rather than

[Jim Stichnoth, 2014/05/08 12:55:17]

allow

[Karl, 2014/06/02 22:39:29]

Done.

+type IDs. However, they are internally converted to the corresponding
+type ID in the types block. Hence, the requirement that the types
+block must appear early in the module block.
+
+The *module block* [ref] contains all other blocks (except for the
+abbreviations block, which can either appear within the module block,
+or immediately before the module block). The only values defined in a
+module block are function addresses.  All remaining definitions appear

[jvoung (off chromium), 2014/05/27 23:18:50]

function address / declarations ? Is it worth using the term declaration? At
least internal to LLVM it uses the term "declaration" as in "isDeclaration()".

[Karl, 2014/06/02 22:39:29]

Removed this, as part of the removal of the deep dive.

+within blocks of the module block.
+
+Function addresses are global IDs of the form *@fN*, where *N*
+corresponds to the position of the corresponding function address
+record in the module block. Function addresses must appear after the
+types block.
+
+The *globals block* [ref] defines global addresses for global variables
+and constants, used in the program. This block not only defines the
+addresses, but the size of the corresponding memory associated with

[Jim Stichnoth, 2014/05/08 12:55:17]

This block defines not only the addresses, but also the size ...

[Karl, 2014/06/02 22:39:29]

Done.

+these addresses, and how the memory should be initialized.
+
+The globals block must appear in the module block, and after all
+function address records.  Global addresses (defined by the globals
+block) are of the form *@gN*, where *N* is the (relative) position of
+the corresponding defining records.
+
+The *valuesymtab block* [ref] does not define any values. Rather, its
+only goal is to associate text names with previously defined global
+addresses (i.e. function, constant, and variable).  Each association
+is defined by a record in the Valuesymtab block. Currently, only

[Jim Stichnoth, 2014/05/08 12:55:17]

Valuesymtab --> valuesymtab

[Karl, 2014/06/02 22:39:29]

Done.

+*intrinsic* [ref] function addresses need a name. All other entries in
+this block are considered as a hint for debugging. The PNaCl
+translator may (or may not) pass these names to the running
+executable, allowing the (runtime) debugger to associate names with
+addresses.
+
+Each *function block* [ref] defines the implementation of a single
+function. Each function block defines the control-flow graph of the

[Jim Stichnoth, 2014/05/08 12:55:17]

Usually "control flow graph" just refers to the basic blocks at a high level and
the edges connecting the basic blocks, and not the individual instructions
within the basic blocks.  What you're describing seems more like "intermediate
representation".  Or maybe if you want to draw the line at instructions and
higher, "instruction representation"?

[Karl, 2014/06/02 22:39:29]

Simplified paragraph, and introduced notion of intermediate representation.

+function, which consists 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 function block in a module block
+corresponds to the Nth defining function address record in the
+module block.
+
+Hence, within a function block, there is no explicit reference to the
+function address the block defines. For readability, PNaClAsm uses the
+corresponding function heading, associated with the corresponding
+function address record, even though that data does not appear in the
+corresponding records.
+
+Unlike other blocks, a function block defines multiple kinds of
+values: parameter, basic block, and instruction. Parameter IDs (in
+PNaClAsm) are identified using local IDs of the form *%pN*. Basic
+block IDs are identified using local IDs of the form
+*%bN*. Instructions that generate values are identified using local
+IDs of the form *%vN*.
+
+Hence, *%pN* denotes the Nth parameter of the function. *%bN* denotes
+the *Nth* basic block within the function. *%vN* denotes the value
+generated by the *Nth* instruction that generates a value. Note: *%vN*
+does not necessarily refer to the *Nth* instruction in the function
+block, because not all instructions generate values.
+
+Within a function block, basic blocks are not explicitly defined in
+the PNaCl records of a function block. Rather, the first record of the
+block identifies how many basic blocks appear in the control flow
+graph of the function. This record is then followed by a sequence of
+records, each record defining a single instruction. Special
+*terminating* [ref] (i.e. branch) instructions are used to determine

[Jim Stichnoth, 2014/05/08 12:55:17]

i.e. --> e.g.

[Karl, 2014/06/02 22:39:29]

Done.

+block boundaries.
+
+Each *constants block* [ref] defines constants that are used by the
+enclosing function block. The purpose of the constant block is to

[Jim Stichnoth, 2014/05/08 12:55:17]

constant --> constants

[Karl, 2014/06/02 22:39:29]

Done.

+merge all uses of a constant (within a function) into a single
+defining ID.  Constant IDs are of the form *%cN*, where *N*
+corresponds to the (relative) position of constant defined in the

[Jim Stichnoth, 2014/05/08 12:55:17]

of --> of the

[Karl, 2014/06/02 22:39:29]

Done.

+corresponding constants block.  The constants block must appear before
+any instruction.
+
+The *abbreviations block* [ref] is optional. If it is included, it 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 ares denoted by the

[Jim Stichnoth, 2014/05/08 12:55:17]

are

[Karl, 2014/06/02 22:39:29]

Done.

+(global) ID of the form *@aN*.
+
+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 accross

[binji, 2014/05/02 18:04:52]

across

[Karl, 2014/06/02 22:39:29]

Done.

+different kinds of blocks. The record code acts as the variant
+descriminator (i.e. tag) within a block, to identify what type of

[binji, 2014/05/02 18:04:52]

discriminator

[Karl, 2014/06/02 22:39:29]

Done.

+record it is.
+
+Record codes are typically small numbers. 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[ref]).  For backwards

[Jim Stichnoth, 2014/05/08 12:55:17]

space before [ref] for consistency?  (This is the first instance, but there are
several more in the document.)

[Karl, 2014/06/02 22:39:29]

Done.

+compatability, old numbers have not been reused, leaving gaps in the

[binji, 2014/05/02 18:04:52]

compatibility

[Karl, 2014/06/02 22:39:29]

Done.

+actual record code values used.
+
+The exception of using small numbers for record codes, are four
+special kinds of records.  What makes these four kinds of records
+special is that they either apply in multiple blocks, or don't occur

[jvoung (off chromium), 2014/05/27 23:18:50]

How about these record codes as being "global", in contrast to other record
codes which are local to a specific type of block? Is that more clear than 
"either apply in multiple blocks, or don't occur in any block"?

Because they are global, they can't be the same number as the local record
codes, and therefore have gone to greater lengths to put them far away, close to
2**16?

In the actual bitstream, they have special reserved abbreviation IDs which are
small, and that makes it less of an issue in terms of # bits emitted. They are
also special in the sense that they use these special reserved abbreviations
(which are defined like user-defined abbreviations), and I'm not sure if this is
the best time to mention that bit of trivia. Mentioning it now does help
identify them, rather then leaving them unknown (but considered special).

[Karl, 2014/06/02 22:39:29]

I like the concept of local/global record codes.  Rewrote (and simplified) above
paragraphs, based on this concept.

+in any block. To make these cases clear, and to leave room for lots of
+future growth in PNaClAsm, these special records have record codes

[Jim Stichnoth, 2014/05/08 12:55:17]

hmm, are we expecting lots of future growth in our bitcode specification?

[Karl, 2014/06/02 22:39:29]

This gap is intentional to make them clearly distinguishable.

+close to value 2**16. Note: Well-formed PNaCl bitcode files do not

[Jim Stichnoth, 2014/05/08 12:55:17]

to the value

[Karl, 2014/06/02 22:39:29]

Done.

+have record codes >= 2**16.
+ 
+A PNaCl record is denoted as follows:
+
+.. naclcode::
+
+  <v1, v2, ... , vN>
+
+The value *v1* is the record code. The remaining values, *v2* through
+*vN*, are parameters that fill in additional information needed by the
+construct it represents. All records must hava record code. Hence,

[binji, 2014/05/02 18:04:52]

have a

[Karl, 2014/06/02 22:39:29]

Done.

+empty PNaCl records are not allowed.
+
+While most records (for a given record code) are of the same length,
+it is not true of all record codes. Some record codes, such as the
+records for the call instruction, can have arbitrary length.

[Jim Stichnoth, 2014/05/08 12:55:17]

Are there any variable-length records besides call, phi, and switch
instructions?  (Do types and initializers count?)  If not, maybe just enumerate
them all here?

[Karl, 2014/06/02 22:39:29]

Enumerated the cases out.

+
+In PNaClAsm, if the record is converted to a bit sequence using the
+default abbreviation, no additional notation is used. Otherwise, the

[jvoung (off chromium), 2014/05/27 23:18:50]

That's not true, right? pnacl-objdump currently prints the 0-3: ?

I guess you are talking about if you were to make a parser for that
pnacl-objdump dump.

[Karl, 2014/06/02 22:39:29]

Yes, I am talking about the text form. I did notice that I was somewhat
inconsistent, since the records column of pnacl-bcdis always defines an
abbreviation index. I have tried to fix this document to reflect this reality.

+record is prefixed with the the abbreviation ID *I* to use (wrt the

[binji, 2014/05/02 18:04:52]

s/the //

[Jim Stichnoth, 2014/05/08 12:55:17]

please spell out "with respect to"

[Karl, 2014/06/02 22:39:29]

Removed the clause, since it didn't really provide any information anyway.

+block it appears in) as follows:
+
+.. naclcode::
+
+  I: <v1, v2, ... , vN>
+
+The PNaCl bitcode 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 PNaCl record. The details of
+this are left to section on abbreviations[ref]. However, at the PNaCL

[binji, 2014/05/02 18:04:52]

PNaCl

[Karl, 2014/06/02 22:39:29]

Done.

+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. A block may (in addition),
+define a list of block specific, user-defined, abbreviations (of
+length *U&). The number of bits *B* specified for an enter

[Jim Stichnoth, 2014/05/08 12:55:17]

*U& --> *U*

[Karl, 2014/06/02 22:39:29]

Done.

+record must be sufficiently large such that
+
+.. naclcode::
+
+   2**B >= U + 4
+
+In addition, the upper limit for B is 32.
+
+Like much of PNaClAsm, PNaClAsm requires that you specify sizes

[Jim Stichnoth, 2014/05/08 12:55:17]

"Like much of PNaClAsm, PNaClAsm requires ..." sounds oddly tautological.  I'm
not sure what you *really* mean.  Can you clarify/rewrite?

[Karl, 2014/06/02 22:39:29]

Rewrote this paragraph.

+(associated with a block) up front so that the PNaCl bitcode
+reader/writer can determine how to encode abbreviation indices. Hence,
+within an enter block record, you must specify how bits will be used

[Jim Stichnoth, 2014/05/08 12:55:17]

This seems to be the only paragraph written in the second person -- two uses of
"you".  Fix this?

[Karl, 2014/06/02 22:39:29]

Done.

[Jim Stichnoth, 2014/06/06 18:24:46]

There's still one more use of the second person at the beginning of the
paragraph.

+to hold abbreviation indexes.

[Jim Stichnoth, 2014/05/08 12:55:17]

indices, since you use that everywhere else

[Karl, 2014/06/02 22:39:29]

Done.

+
+Conventions for describing records
+==================================
+
+The PNaClAsm assembler can be viewed as a parser of PNaCl records. The

[Jim Stichnoth, 2014/05/08 12:55:17]

Remove the last "The".

[jvoung (off chromium), 2014/05/27 23:18:50]

Were you still planning on writing the assembler, or is it just used for
illustrative purposes. A way to structure the documentation:

"How to write your own PNaCl bitcode reader, by example"?

This way of structuring things does help people understand the constraints, what
types of counts are written out in headers, how terminators work, etc. so that's
good.

[Karl, 2014/06/02 22:39:29]

Done.

+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. The parser also has
+state, that is updated after the instruction is parsed.  These state
+updates are part of the sementics of the corresponding record

[binji, 2014/05/02 18:04:52]

semantics

[Karl, 2014/06/02 22:39:29]

Done.

+construct.
+
+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 parse state
+and the corresponding syntax.

[jvoung (off chromium), 2014/05/27 23:18:50]

Clarify where other high-level semantics will be defined? (like divide by 0
should trap) -- link to other PNaCl ABI document?

[Karl, 2014/06/02 22:39:29]

Added sentence to clarify this?

That is, additional higher-level semantics will be given (or linked) in the
semantics section.

+
+The **Constraints** subsection (if present) defines any constraints
+associated with the construct. The **Updates** subsection (if present)
+defines how the parse state is updated when the construct is parsed.
+The **Examples** subsection gives one (or more) examples of using the
+corresponding PNaClAsm construct.
+
+Some semantics subsections use functions to compute values. The
+meaning of functions can be found in *Support Functions* [ref].
+
+Within a syntax rule, there may specifications about abbreviations.
+These abbreviation specifications, if allowed, are at the end of the
+construct, and enclosed in *<* and *>* bracket. These abbreviation
+specifications are optional in the syntax, and can be omitted. If they
+are used, the abbreviation brackets are part of the actual syntax of
+the construct. To make it clear that abbreviation specifications are
+optional, syntax rules separate abbreviation specifications using
+plenty of whitespace.
+
+Abbreviation specifications consist of user-defined abbreviations,
+abbreviation identifiers, and the number of bits required to repressent

[binji, 2014/05/02 18:04:52]

represent

[Karl, 2014/06/02 22:39:29]

Done.

+abbreviations in a block. These notations appear, as appropriate, in
+the corresponding syntax rules.
+
+The most common abbreviation syntax is the corresponding abbreviation
+identifier to use to read/write the corresponding record. In such
+cases, if the specified abbreviation identifier is omitted, the
+corresponding default abbreviation will be used by the PNaCl
+reader/writer.
+
+Also, within PNaClAsm, all alphabetic characters are lower case unless
+they appear within a literal value. Hence, if we mix lower and upper
+case letters within a name appearing in a syntax rule, the lower case
+letters are literal while the upper case sequence of letters denote
+(rule specific) values. If an upper case sequence of letters is
+followed by digits, the corresponding embedded name includes both the
+upper case letters and the digits.  The valid values for each of these
+names will be defined in the corresponding semantics subsection.
+
+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 to two values (*O1* and *O2*) to generate

[jvoung (off chromium), 2014/05/27 23:18:50]

"adds to two values" -> "adds two values" ?

[Karl, 2014/06/02 22:39:29]

Done.

+instruction value *%vN*. The types of the arguments, and the result,
+are all of type *T*. Since abbreviation ID *A* is present,  the

[jvoung (off chromium), 2014/05/27 23:18:50]

extra space

[Karl, 2014/06/02 22:39:29]

Done.

+record is encoded using that abbreviation.
+
+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 also specifies
+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 subsections associated with the
+construct.
+
+Parse State
+===========
+
+This section describes the parse state of the PNaClAsm assembler. It
+is used to define contextual data that is carried between records. The
+following subsections describes each element of the parse state.

[Jim Stichnoth, 2014/05/08 12:55:17]

describe

[Karl, 2014/06/02 22:39:29]

Done.

+
+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 *types block* [ref], 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 will not contain assignments to this
+map.
+
+Associated with each function identifier is it's type signature. This

[Jim Stichnoth, 2014/05/08 12:55:17]

its

[Karl, 2014/06/02 22:39:29]

Done.

+is different than the type of the function identifer, since function

[binji, 2014/05/02 18:04:52]

identifier

[Karl, 2014/06/02 22:39:29]

Done.

+identifiers are pointers (and always implemented as a 32-bit integer).
+
+Function type signatures are maintained using:
+
+.. naclcode::
+
+  TypeOfFcn: ID -> Type
+
+In addition, if a function address is defining, there is a corresponding

[Jim Stichnoth, 2014/05/08 12:55:17]

is defined?  is being defined?

[Karl, 2014/06/02 22:39:29]

Rewrote to clarify it has an implementing block.

+implementation associated with the function address. To capture this association,

[Jim Stichnoth, 2014/05/08 12:55:17]

80-col

[Karl, 2014/06/02 22:39:29]

Done.

+we use the set:
+
+.. naclcode::
+
+  DefiningFcnIDs: set(ID)
+
+ID Counters
+-----------
+
+Each block defines one (or more) kinds of values.  Value indices are
+generated sequentially, starting at zero. To capture this, the
+following counters are defined:
+
+NumTypes
+  The number of types defined so far (in the types block)
+
+NumFuncAddresses
+  The number of function addresses defined so far (in the module
+  block).
+
+NumDefinedFcnAddresses
+  The number of defining function addresses defined so far (in the
+  module block).
+
+NumFuncImpls
+  The number of implemented functions 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.
+
+NumFcnConsts
+  The number of constants defined in a fucntion.

[binji, 2014/05/02 18:04:52]

function

[Karl, 2014/06/02 22:39:29]

Done.

+
+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).
+
+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.
+
+ExpectTypes
+  The expected number of types defined in the Types Block.

[Jim Stichnoth, 2014/05/08 12:55:17]

Types Block --> types block

[Karl, 2014/06/02 22:39:29]

Done.

+
+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.
+
+Special records
+===============
+
+There are four special PNaCl records, each having their own record

[Jim Stichnoth, 2014/05/08 12:55:17]

their --> its

[Karl, 2014/06/02 22:39:29]

Done.

+code. These special 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, it can appear inside other blocks, as well as at the

[Jim Stichnoth, 2014/05/08 12:55:17]

it --> one

[Karl, 2014/06/02 22:39:29]

Done.

+  top level.
+
+Exit
+  An exit record defines the end of a block. Hence, it must appear in
+  every block, to end the block.
+
+Addreviation

[Jim Stichnoth, 2014/05/08 12:55:17]

Abbreviation

[Karl, 2014/06/02 22:39:29]

Done.

+  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 them. The default abbreviation is always used.
+
+The following subsections define valid special records, other than abbreviation
+records. Abbreviation records are described in the Abbreviations[ref] section.
+
+Header Record
+-------------
+
+The header record must be the first record in the file. It is the only
+record in the bitcode file that doesn't have a corresponding construct
+in PNaClAsm. Rather, the PNaClAsm assembler always automatically
+inserts this record as the first record of the PNaCl bitcode file.
+
+**Syntax**
+
+There is no syntax for header records in PNaClAsm. They are
+automatically inserted by the PNaCl bitcode writer.
+
+**Record**
+
+.. naclcode::
+
+   <66532, 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 PNaCl bitcode files.
+
+**Examples**
+
+There are no examples for the header record, since it is not part of
+PNaClAsm.
+
+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::
+
+  <655335, BlockID, B>

[Jim Stichnoth, 2014/05/08 12:55:17]

Are these values 655335 and 655334 correct?  They seem suspiciously similar to
2**16-1 and 2**16-2, yet they appear here >20 times.

[Karl, 2014/06/02 22:39:29]

Hmm. Don't know what happened here. Fixing.

+
+**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 always assumed.
+
+The *BlockID* value is dependent on the name *N*. Valid names and
+corresponding *BlockID* values are defined as follows:
+
+============= =======
+Name          BlockID
+============= =======
+abbreviations 0
+constants     11
+function      12
+globals       19
+module        8
+types         17
+valuesymtab   14
+============= =======
+
+Note: For readability, PNaClAsm allows a more readable form of a
+function block enter record.  See *function blocks* [ref] for more
+details.
+
+**Examples**
+
+.. naclcode::
+
+  module {
+    types {
+      count: 0;
+    }
+    globals {
+      count: 0;
+    }
+  }
+
+This example defines a module, types, and globals block. Both the type
+and the modules block appears within the module block.

[Jim Stichnoth, 2014/05/08 12:55:17]

modules block --> module block

[Jim Stichnoth, 2014/05/08 12:55:17]

appears --> appear

[Karl, 2014/06/02 22:39:29]

Done.

[Karl, 2014/06/02 22:39:29]

Done.

+
+The corresponding records are:
+
+.. naclcode::
+
+  <655335, 8, 2>
+  <655335, 17, 2>
+  <1, 0>
+  <655334>
+  <655335, 19, 2>
+  <5, 0>
+  <655334>
+  <655334>
+
+
+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::
+
+  <65536>
+
+**Semantics**
+
+All exit records are identical, no matter what block they are ending. An
+exit record defines the end of the block.
+
+**Examples**
+
+.. naclcode::
+
+  module {
+    types {
+      count: 0;
+    }
+    globals {
+      count: 0;
+    }
+  }
+
+This example defines a module, types, and globals block. Both the type
+and the modules block appears within the module block.

[Jim Stichnoth, 2014/05/08 12:55:17]

modules block --> module block

[Jim Stichnoth, 2014/05/08 12:55:17]

appears --> appear

[Karl, 2014/06/02 22:39:29]

Actually, I was using the names defined earlier. Hence "module" and "types".

[Karl, 2014/06/02 22:39:29]

Done.

+
+The corresponding records are:
+
+.. naclcode::
+
+  <655335, 8, 2>
+  <655335, 17, 2>
+  <1, 0>
+  <655334>
+  <655335, 19, 2>
+  <5, 0>
+  <655334>
+  <655334>
+
+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.
+
+Each record in the types block defines a type used by the program.
+Types can be broken into the following groups:
+
+
+Primitive types
+  Defines the set of base types for values. This includes various
+  sizes of integral and floating types, as well as vector types.
+
+Void type
+  A primitive type that doesn't represent any value and has no size.
+
+Function types
+  The type signatures of functions.
+
+Vector type
+  Defines vectors of primitive types.
+
+In addition, any type that is not defined using another type is a
+primitive type.  All other types (i.e. function and vector)are

[Jim Stichnoth, 2014/05/08 12:55:17]

space after parens

[Karl, 2014/06/02 22:39:29]

Done.

+composite types.
+
+Types must be defined in a topological order, causing primitive types
+to apear before the composite types that use them.  There are no

[binji, 2014/05/02 18:04:52]

appear

[Karl, 2014/06/02 22:39:29]

Done.

+additional restrictions on the order that types can be defined in a
+types block.
+
+The following subsections introduces each valid PNaClAsm type, and the

[Jim Stichnoth, 2014/05/08 12:55:17]

introduce

[Karl, 2014/06/02 22:39:29]

Done.

+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 following subsections define valid records within

[Jim Stichnoth, 2014/05/08 12:55:17]

defines --> define

[Karl, 2014/06/02 22:39:29]

Done.

+a types block. The order of type records is important. The position of
+these defining records implicitly define the type ID that will be used

[Jim Stichnoth, 2014/05/08 12:55:17]

The position of each defining record implicitly defines the type...

[Karl, 2014/06/02 22:39:29]

Done.

+to denote that type, within other PNaCl records of the bitcode file.
+
+To make this more concrete, consider the following example types
+block:
+
+.. naclcode::
+
+  types {
+    count: 4;
+    @t0 = void;
+    @t1 = i32;
+    @t2 = float;
+    @t3 = void (i32, float);
+  }
+
+This example defines a types block that defines four type IDs:
+
+0. The void type.
+1. A 32-bit integer type.
+2. A 32-bit floating type.
+3. A function, taking 32-bit integer and float arguments, and returns void.

[Jim Stichnoth, 2014/05/08 12:55:17]

"and returning" or "that returns"

[Karl, 2014/06/02 22:39:29]

Done.

+
+Note that the order defines the corresponding ID that will be used for
+that type, is based on the position of the type within the types

[Jim Stichnoth, 2014/05/08 12:55:17]

and is based

[Karl, 2014/06/02 22:39:29]

Done.

+record. Hence, the assignment to ID @tN can never appear before the
+assignment to ID @tN-1. Further, if type ID @tN is assigned, it must
+appear immediatedly after the assignment to ID @tN-1.

[Jim Stichnoth, 2014/05/08 12:55:17]

immediately

[Karl, 2014/06/02 22:39:29]

Done.

+
+Count Record
+------------
+
+The *count record* defines how many types are defined in the

[Jim Stichnoth, 2014/05/08 12:55:17]

For this and other types of count records, what happens if the bitcode file
gives multiple (differing) count records?  Validation error?  First one wins? 
Last one wins?

[Karl, 2014/06/02 22:39:29]

This is currently undefined. Fixing code to verify it is first record.

+types block. Following the types count record are records that define
+types used by the PNaCl program.
+
+**Syntax**
+
+.. naclcode::
+
+  count: N;                                       <I>
+
+**Record**
+
+  I: <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 less) types than value *N*, within the enclosing

[Jim Stichnoth, 2014/05/08 12:55:17]

less --> fewer

[Karl, 2014/06/02 22:39:29]

Done.

+types block. *I* is the (optional) abbreviation associated with the
+record.
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedTypes = N;
+
+**Examples**
+
+.. naclcode::
+
+  types {
+    count: 2;
+    @t0 = float;
+    @t1 = i32;
+  }
+
+This example defines that the only types used by the PNaCl program are
+are 32 bit integer and floating type.

[Jim Stichnoth, 2014/05/08 12:55:17]

are are --> are

[Jim Stichnoth, 2014/05/08 12:55:17]

types

[Karl, 2014/06/02 22:39:29]

Done.

[Karl, 2014/06/02 22:39:29]

Done.

+
+The corresponding PNaCl Records are:

[Jim Stichnoth, 2014/05/08 12:55:17]

Records --> records

[Karl, 2014/06/02 22:39:29]

Done.

+
+.. naclcode::
+
+  <655335, 17, 2>
+  <1, 2>
+  <3>
+  <7, 32>
+  <655334>
+
+Void Type
+---------
+
+The *void* type record defines the void type, which corrresponds to

[binji, 2014/05/02 18:04:52]

corresponds

[Karl, 2014/06/02 22:39:29]

Done.

+the type that doesn't define any value, and has no size.
+
+**Syntax**
+
+.. naclcode::
+
+  @tN = void;                                     <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <2>
+
+**Semantics**
+
+The void type record defines the type that has no values and has no

[Jim Stichnoth, 2014/05/08 12:55:17]

values --> value ?

[Karl, 2014/06/02 22:39:29]

Rewrote sentence.

+size.  *I* is the (optional) abbreviation associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = void;
+
+**Examples**
+
+.. naclcode::
+
+   @t0 = void;
+
+defines the record
+
+.. naclcode::
+
+  <2>
+
+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 in integer is not specified by the type. Rather,

[Jim Stichnoth, 2014/05/08 12:55:17]

in integer --> an integer

[Karl, 2014/06/02 22:39:29]

Done.

+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;                                      <I>
+
+**Record**
+
+  I: <7, B>
+
+**Semantics**
+
+An integer type record defines an integral type. *B* defines the
+number of bits of the integral type.  *I* is the (optional)
+abbreviation associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumTypes
+  NumTypes < ExpectedTypes
+  B in {1, 8, 16, 32, 64}
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = iB;
+
+**Examples**
+
+.. naclcode::
+
+  @t1 = i32;
+  @t2 = i1;
+  @t3 = i64;
+
+defines the records
+
+.. naclcode::
+
+  <7, 32>
+  <7, 1>
+  <7, 64>
+
+32-Bit Floating Type
+--------------------
+
+PNaClAsm allows computation on 32-bit floating values. A floating type
+record defines the 32-bit floating type.
+
+**Syntax**
+
+.. naclcode::
+
+  @tN = float;                                    <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <3>
+
+**Semantics**
+
+A floating type record defines the 32-bit floating type.  *I* is the
+(optional) abbreviation associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = float;
+
+**Examples**
+
+.. naclcode::
+
+  @t5 = float;
+
+defines the record
+
+.. naclcode::
+
+  <3>
+
+64-bit Floating Type
+--------------------
+
+PNaClAsm allows computation on 64-bit floating values. A double type
+record defines the 64-bit floating type.
+
+**Syntax**
+
+.. naclcode::
+
+  @tN = double;                                   <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <4>
+
+**Semantics**
+
+A double type record defines the 64-bit floating type.  *I* is the
+(optional) abbreviation associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == NumTypes
+  NumTypes < ExpectedTypes
+
+**Updates**
+
+.. naclcode::
+
+  ++NumTypes;
+  TypeOf(@tN) = double;
+
+**Examples**
+
+.. naclcode::
+
+  @t3 = double;
+
+defines the record
+
+.. naclcode::
+
+  <4>
+
+Vector Types
+------------
+
+TBD.

[Jim Stichnoth, 2014/05/08 12:55:17]

TODO for missing content, for easier searching, here and many other places.

[Karl, 2014/06/02 22:39:29]

Done.

+
+Function Types
+--------------
+
+TBD.
+
+Globals block
+=============
+
+The globals block defines global addresses of variables and constants,
+used by the PNaCl program. It also defines the memory associated with
+the global addresses, and how to initialize each global
+variable/constant. It must appear in the 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 how each global addresss is

[binji, 2014/05/02 18:04:52]

address

[Karl, 2014/06/02 22:39:29]

Done.

+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 initalizer records. All simple initializer records define a

[binji, 2014/05/02 18:04:52]

initializer

[Karl, 2014/06/02 22:39:29]

Done.

+sequence of bytes. A compound initializer defines a sequence of bytes
+by concatenating corresponding sequence of bytes for each of its

[Jim Stichnoth, 2014/05/08 12:55:17]

concatenating a corresponding

[Karl, 2014/06/02 22:39:29]

Done.

+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 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.
+
+For example, consider the following:
+
+.. naclcode::
+
+  globals {
+    count: 2;
+    const @g0, align 1,
+      zerofill 8;
+    var @g1, align 4,
+      initializers 2 {
+        {1, 2, 3, 4},
+        zerofill 2;
+      }
+  }
+
+In this example, the globals block contains 9 records. All lines,
+inside the block delimiters of this example (except the second to
+last) defines a record. The first record defines the number of global
+addresses defined by the program, i.e. 2. The second defines that
+second global addresses will be defined.

[Jim Stichnoth, 2014/05/08 12:55:17]

I'm not sure how to parse the last sentence.  Should second --> two?

If I was paying attention, this is the first relatively complex example with
low-level descriptions of the records.  As such, it would be very helpful to
match the text to the record numbers.  E.g.: The first record, "count:", defines
the number...

+
+The third record defines the global constant address *@g0*, and it's

[Jim Stichnoth, 2014/05/08 12:55:17]

its

[Karl, 2014/06/02 22:39:29]

ditto.

+corresponding memory layout alignment. The forth record defines to

[Jim Stichnoth, 2014/05/08 12:55:17]

fourth

[Karl, 2014/06/02 22:39:29]

ditto.

+initialize the constant with 8 bytes, all with the value zero. This

[Jim Stichnoth, 2014/05/08 12:55:17]

This --> The

[Karl, 2014/06/02 22:39:29]

Ditto.

+size of *@g0* is 8 bytes.
+
+The fifth record defines the global variable address *@g1*, and it's

[Jim Stichnoth, 2014/05/08 12:55:17]

its

[Karl, 2014/06/02 22:39:29]

Ditto.

+corresponding memory layout alignment. The sixth record defines that
+the initial value of *@g1* is defined by the sequence of bytes defined
+by the following 2 initializer records. The seventh record defines that
+the first 4 bytes of *@g1* are initialized with bytes 1, 2, 3, 4. The
+eighth record initializes bytes 5 and 6 to zero. The size of *@g2* is

[Jim Stichnoth, 2014/05/08 12:55:17]

What is @g2?  This is its first mention.

[Karl, 2014/06/02 22:39:29]

Ditto.

+therefore 6 bytes.
+
+The nine record is the exit block record.
+
+In other words, the corresponding records are:
+
+.. naclcode::
+
+  <655335, 19, 2>
+  <5, 2>
+  <0, 1, 1>
+  <2, 8>
+  <0, 4, 0>
+  <1, 2>
+  <3, 1, 2, 3, 4>
+  <2, 2>
+  <655334>
+
+
+Count Record
+------------
+
+The count record defines the number of global addresses used by the
+PNaCl program.
+
+**Syntax**
+
+.. naclcode::
+
+  count: N;                                       <I>
+
+**Record**
+
+.. naclcode::
+
+   I: <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. *I* is the
+(optional) abbreviation associated with the record.
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedGlobals = N;
+  ExpectedInitializers = 0;
+
+Global Variable Addressses
+--------------------------
+
+A global variable address record defines a global address to global
+data.  The global variable address record must be immediatedly

[binji, 2014/05/02 18:04:52]

immediately

[Karl, 2014/06/02 22:39:29]

Done.

+followed by initializer record(s) that define how the corresponding
+global variable is initialized.
+
+**Syntax**
+
+.. naclcode::
+
+  var @gN, align A,                               <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <0, A, 0>
+
+**Semantics**
+
+A global varaible address record defines a global address for a global

[binji, 2014/05/02 18:04:52]

variable

[Karl, 2014/06/02 22:39:29]

Done.

+variable.  *A* is the alignment to for the global variable.  *I* is

[Jim Stichnoth, 2014/05/08 12:55:17]

to for --> for
(or "of")

[Karl, 2014/06/02 22:39:29]

Done.

+the (optional) abbreviation associated with the record.
+
+It is assumed that the memory, referenced by the global variable
+address, can be both read and written to.
+
+??? Valid values for A. Section defining notion of memory alignments ???

[Jim Stichnoth, 2014/05/08 12:55:17]

TODO

[Karl, 2014/06/02 22:39:29]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  N == NumGlobalAddresses
+  NumGlobalAddresses < ExpectedGlobals
+  ExpectedInitializers == 0
+
+**Updates**
+
+.. naclcode::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**
+
+.. naclcode::
+
+   var @g0, align 1,
+     zerofill 8;
+   var @g1, align 1,
+     {1, 2, 3, 4}
+
+This example defines two global variable addresses, *@g0* and
+*@g1*. Both use memory alignment of 1. *@g0* is an 8 byte variable
+initialized to zero.  *@g1* is a 4 byte variable, initialized by the
+sequence of bytes 1, 2, 3, and 4.
+
+The corresponding records defined by the example above are:
+
+.. naclcode::
+
+  <0, 1, 0>
+  <2, 8>
+  <0, 1, 0>
+  <3, 1, 2, 3, 4>
+
+Glboal Constant Addresses

[jvoung (off chromium), 2014/05/27 23:18:50]

Global

[Karl, 2014/06/02 22:39:29]

Done.

+-------------------------
+
+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 immediatedly followed by initializer

[binji, 2014/05/02 18:04:52]

immediately

[Karl, 2014/06/02 22:39:29]

Done.

+record(s) that define how the corresponding global constant is
+initialized.
+
+**Syntax**
+
+.. naclcode::
+
+  const @gN, align A,                             <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <0, A, 1>
+
+**Semantics**
+
+A global constant address record defines a global address for a global
+constant.  *A* is the memory alignment for the global constant. *I* is
+the (optional) abbreviation associated with the record.
+
+It is assumed that the memory, referenced by the global constant
+address, is only read, and can't be written to.
+
+??? Valid values for A. Section defining notion of memory alignments ???

[Jim Stichnoth, 2014/05/08 12:55:17]

TODO

[Karl, 2014/06/02 22:39:29]

Done.

+
+**Constraints**
+
+.. naclcode::
+
+  N == NumGlobalAddresses
+  NumGlobalAddresses < ExpectedGlobals
+  ExpectedInitializers = 0
+
+**Updates**
+
+.. naclcode::
+
+  ++NumGlobalAddresses;
+  ExpectedInitializers = 1;
+  TypeOf(@gN) = i32;
+
+**Examples**
+
+.. naclcode::
+
+  const @g0, align 1,
+    zerofill 8;
+  var @g1, align 1,
+    {1, 2}
+
+This example defines two global constants, with global addresses *@g0*
+and *@g1*. Both use memory alignment of 1. *@g0* is an 8 byte constant
+initialized to zero.  *@g1* is a 2 byte variable, initialized by the
+sequence of bytes 1 and 2.
+
+The corresponding PNaCl bitcode records are:
+
+.. naclcode::
+
+  <0, 1, 1>
+  <2, 8>
+  <0, 1, 1>
+  <3, 1, 2>
+
+Zerofill Initializer
+--------------------
+
+The zerofill initializer record intializes a sequence of bytes,

[binji, 2014/05/02 18:04:52]

initializes

+associated with a global address, with zeros.
+
+**Syntax**
+
+.. naclcode::
+
+  zerofill N;                                     <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <2, N>
+
+**Semantics**
+
+A zerofill initializer record intializes a sequence of bytes,

[binji, 2014/05/02 18:04:52]

initializes

[Karl, 2014/06/02 22:39:29]

Done.

[Jim Stichnoth, 2014/06/06 18:24:46]

Actually not done (though the one above was done and not marked done...)

+associated with a global address, with zeros. *I* is the (optional)
+abbreviation of the associated record.
+
+**Constraints**
+
+.. naclcode::
+
+  ExpectedInitializers > 0;
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+  const @g0, align 1,
+    zerofill 8;
+  var @g1, align 1,
+    zerofill 4;
+
+This example defines two global constants, with global addresses *@g0*
+and *@g1*.  The global memory associated with address *@g0*, is an
+eight byte value, initialized to zero.  The global memory associated
+with address *@g1*, is a 4 byte value, initialized to zero.
+
+The corresponding PNaCl records are:
+
+.. naclcode::
+
+  <0, 1, 1>
+  <2, 8>
+  <0, 1, 1>
+  <2, 4>
+
+Data Initializer
+----------------
+
+Data records define a sequence of bytes, defining the contents of the
+corresponding memory. The bytes defined by a data record corresponds
+the the corresponding bytes the memory will be initialized with.

[binji, 2014/05/02 18:04:52]

s/the //

[Karl, 2014/06/02 22:39:29]

Done.

+
+**Syntax**
+
+.. naclcode::
+
+  { B1 , .... , BN }                              <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <3, B1, ..., BN>
+
+**Semantics**
+
+A data record defines a sequence of bytes *B1* throught *BN*, that

[binji, 2014/05/02 18:04:52]

through

[Karl, 2014/06/02 22:39:29]

Done.

+intialize *N* bytes of memory. *I* is the (optional) abbreviation

[binji, 2014/05/02 18:04:52]

initialize

[Karl, 2014/06/02 22:39:29]

Done.

+associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  ExpectedInitializers > 0
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+  const @g0, align 1,
+    {1, 2, 97, 36, 44, 88, 44}
+  const @g1, align 1
+    initializers 3 {
+      {4, 5, 6, 7}
+      reloc @f1;
+      {99, 66, 22, 12}
+    }
+
+The corresponding PNaCl records are:
+
+.. naclcode::
+
+  <0, 1, 1>
+  <3, 1, 2, 97, 36, 44, 88, 44>
+  <0, 1, 1>
+  <1, 3>
+  <3, 4, 5, 6, 7>
+  <4, 1>
+  <3, 99, 66, 22, 12>
+
+Relocation Initializer
+----------------------
+
+A relocation initializer record allows one to fill the initial value
+with the value of another global address (i.e. either function,
+variable, or constant). Since addresses are pointers, and in PNaClAsm
+all pointers are of integral type i32, a relocation initializer record
+defines 4 bytes of memory.
+
+**Syntax**
+
+.. naclcode::
+
+  reloc A;                                        <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <4, N>
+
+**Semantics**
+
+A relocation initializer record defines a 4-byte value containing the
+specified global address *A*. *N* is the absolute index associated
+with address *A*. *I* is the (optional) abbreviation associated with
+the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == AbsoluteIndex(A);
+  ExpectedInitializers > 0
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+  var @g0, align 1,
+    initializers 3 {
+      reloc @f1;
+      reloc @g0;
+      reloc @g10;
+    }
+
+This example defines global address *@g0*. It defines 12 bytes of
+memory, and is initialized with three addresses *@f1*, *@g0*, and
+*@g10*. Note that all globals can be used in a relocation
+initialization record, even if it isn't defined yet.
+
+Assuming
+
+.. naclcode::
+
+  100 = AbsoluteIndex(@g0))
+
+The corresponding PNaCl bitcode records are:
+
+.. naclcode::
+
+  <0, 1, 0>
+  <1, 3>
+  <4, 1>
+  <4, 100>
+  <4, 110>
+
+Subfield Relocation Initializer
+-------------------------------
+
+A subfield relocation initializer record allows one to fill the
+initial value with the value of another (non-function) global address
+(i.e. either variable or constant), plus a constant. This constant
+must refer to an offset within the memory associated with the global
+address. Since addresses are pointers, and in PNaClAsm all pointers
+are of integral type i32, a relocation initializer record defines 4
+bytes of memory.
+
+**Syntax**
+
+.. naclcode::
+
+  reloc A + V;                                    <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <4, N, V>
+
+**Semantics**
+
+A relocation initializer record defines a 4-byte value containing the
+specified global (non-funciton) address *A*, modified by the (unsigned

[binji, 2014/05/02 18:04:52]

function

[Karl, 2014/06/02 22:39:29]

Done.

+integer) offset *V*. *N* is the absolute indexassociated with *A*. The

[binji, 2014/05/02 18:04:52]

index associated

[Karl, 2014/06/02 22:39:29]

Done.

+size of *V* must refer to a byte in the memory associated with address
+*A*. *I* is the (optional) abbreviation associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  N == AbsoluteIndex(A)
+  V >= 0
+  ExpectedInitializers > 0
+
+**Updates**
+
+.. naclcode::
+
+  --ExpectedInitializers;
+
+**Examples**
+
+.. naclcode::
+
+  var @g0, align 1,
+    initializers 3 {
+      reloc @f1;
+      reloc @g0 + 4;
+      reloc @g10 + 32;
+    }
+
+This example defines global address *@g0*, and is initialized with
+three pointers, addresses *@f1*, *@g0+4*, and *@g10+32*. Note that all
+global addresses can be used in a relocation initialization record,
+even if it isn't defined yet. Validity of the reference can be
+verified, since a global address *@g10* must be smaller than the value
+specified in the globals count record.
+
+Assuming
+
+.. naclcode::
+
+  100 = AbsoluteIndex(@g0))
+
+The corresponding PNaCl bitcode records are:
+
+.. naclcode::
+
+  <0, 1, 0>
+  <1, 3>
+  <4, 1>
+  <4, 100, 4>
+  <4, 110, 32>
+
+Compound Initializer
+--------------------
+
+The compound initializer record must immediately follow a global variable/constant

[Jim Stichnoth, 2014/05/08 12:55:17]

80-col

[Karl, 2014/06/02 22:39:29]

Done.

+address record. It defines how many (non-compound) 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.
+
+**Syntax**
+
+.. naclcode::
+
+  initializers N {                                <I>
+   ...
+  }
+
+**Record**
+
+.. naclcode::
+
+  I: <1, N>
+
+**Semantics**
+
+Defines that the next *N* initializers should be associated with the
+global address of the previous record. *I* is the (optional)
+abbreviation index associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  ExpectedInitializers == 1
+
+**Updates**
+
+.. naclcode::
+
+  ExpectedInitializers = N;
+
+**Examples**
+
+.. naclcode::
+
+  const @g1, align 1
+    initializers 3 {
+      {4, 5, 6, 7}
+      reloc @f1;
+      {99, 66, 22, 12}
+    }
+
+The corresponding PNaCl records are:
+
+.. naclcode::
+
+  <0, 1, 1>
+  <1, 3>
+  <3, 4, 5, 6, 7>
+  <4, 1>
+  <3, 99, 66, 22, 12>
+
+Valuesymtab Block
+=================
+
+TBD.
+
+Module Block
+============
+
+The module block, like all blocks, are enclosed in a pair of

[Jim Stichnoth, 2014/05/08 12:55:17]

are --> is

[Karl, 2014/06/02 22:39:29]

Done.

+enter/exit records, using block ID 8. A well-formed module block
+consists The following records (in order):

[Jim Stichnoth, 2014/05/08 12:55:17]

The --> of the

[Karl, 2014/06/02 22:39:29]

Done.

+
+A version record
+   The version record communicates the version of the PNaCl bitcode
+   reader/writer to use. Note that this is different than the PNaCl
+   bitcode (ABI) verion. The PNaCl bitcode (ABI) version defines what

[binji, 2014/05/02 18:04:52]

version

[Karl, 2014/06/02 22:39:29]

Done.

+   is expected in records, and is defined in the header record of the
+   bitcode file. The version record defines the version of the PNaC

[binji, 2014/05/02 18:04:52]

PNaCl

[Karl, 2014/06/02 22:39:29]

Done.

+   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 optional 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 instrinsic functions must be provided. Any

[binji, 2014/05/02 18:04:52]

intrinsic

[Karl, 2014/06/02 22:39:29]

Done.

+   additional names are hints that may (or may not) be used by the
+   PNaCl translator, and be available for debugging when executed.
+
+A sequence of function blocks.
+   Each function block defines the corresponding control flow graph
+   for each 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 abbreviations[ref], types[ref], global
+variables[ref], value symbol table[ref], and function[ref] 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
+reader/writer that converts PNaCl records to bit sequences. 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 version 2, and version record value 1
+is defined.  Larger version record values are reserved for future
+changes.
+
+**Syntax**
+
+.. naclcode::
+
+  version N;                                  <I>
+
+**Record**
+
+.. naclcode::
+
+  I: <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 other values. *I* is the (optional)
+abbreviation index associated with the record.
+
+*Examples*
+
+.. naclcode::
+
+   version 1;
+
+The corresponding record is:
+
+.. naclcode::
+
+  <1, 1>
+
+Function Address
+----------------
+
+A function address record defines a function address. Defining
+function addresses also imply a corresponding

[Jim Stichnoth, 2014/05/08 12:55:17]

implies

[Karl, 2014/06/02 22:39:29]

Done.

+implementation. Implementations of function addresses are defined by a
+corresponding function block. The association of defining function
+address with the corresponding function block is based on position.
+The *Nth* defining 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 );                 <I>
+
+**Record**
+
+.. naclcode:
+
+  I: <8, T, C, P, L>
+
+**Semnatics**

[Jim Stichnoth, 2014/05/08 12:55:17]

Semantics

[Karl, 2014/06/02 22:39:29]

Done.

+
+Defines the function address *@fN*. *PN* is the name that specifies
+the prototype value *P* associated with the function. A function
+address is defining only if *P==0*. Otherwise, it is only declared.

[Jim Stichnoth, 2014/05/08 12:55:17]

defined

[Karl, 2014/06/02 22:39:29]

Done.

+The type of the function is defined by function type *@tT. *L*
+is the linkage specification corresponding to name *LN*. *C* is the
+calling convention used by the function.
+
+Type *@tT* (associated with the corresponding syntax rules) is
+defined as:
+
+.. naclcode::
+
+   @tT = TypeOf(T0 ( T1 , ... , TN ))
+
+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::
+
+  N == NumFuncAddresses
+
+Updates
+^^^^^^^
+
+.. naclcode::
+
+  ++NumFuncAddresses;
+  TypeOf(@fN) = TypeOf(TypeID(i32));
+  TypeOfFcn(@fN) = TypeOf(@tT);
+
+  if PN == 0:
+    DefiningFcnIDs += @FN;
+    ++NumDefinedFunctionAddresses;
+
+**Examples**
+
+.. naclcode::
+
+  module {
+    ...
+    types {
+      @t0 = void;
+      @t1 = i32;
+      @t3 = float;
+      @t4 = void (i32, float);
+      @t5 = i32 ();
+    }
+    ...
+    declare external void @f0(i32, float);
+    define internal i32 @f1();
+
+This defines function addresses *@f0* and *@f1*. Function address
+*@f0* is defined externally while *@f2* has an implementation (defined
+by a corresponding function block). The type signature of *@f0* is
+defined by type *@t4* while the type signature of *@f1* is *@t5*.
+
+The corresopnding records for these two function addresses are:

[binji, 2014/05/02 18:04:52]

corresponding

[Karl, 2014/06/02 22:39:29]

Done.

+
+.. naclcode::
+
+  <8, 4, 0, 1, 0>
+  <8, 5, 0, 0, 1>
+
+Constants Blocks
+================
+
+TBD.
+
+Function Blocks
+===============
+
+A function block defines the implementation of a function address. The
+function address it defines is based on the position of the
+corresponding defining function address. The Nth defining function
+address always corresponds to the corresponding Nth function block in
+the module block.
+
+A function definition contains a list of basic block, forming the CFG

[Jim Stichnoth, 2014/05/08 12:55:17]

blocks

[Karl, 2014/06/02 22:39:29]

Done.

+(control flow graph). Each basic block contains a list of
+instructions, and ends with a *terminator* [ref] (branch) instruction.

[Jim Stichnoth, 2014/05/08 12:55:17]

e.g., branch

since there are several kinds of terminator instructions

[Karl, 2014/06/02 22:39:29]

Done.

+
+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 *PHI nodes* [ref].

[Jim Stichnoth, 2014/05/08 12:55:17]

nodes --> instructions

[Karl, 2014/06/02 22:39:29]

Done.

+
+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 are defined by the count record. Each

[Jim Stichnoth, 2014/05/08 12:55:17]

are --> is

[Karl, 2014/06/02 22:39:29]

Done.

+termimintor instruction ends the current basic block, and the next

[binji, 2014/05/02 18:04:52]

terminator

[Karl, 2014/06/02 22:39:29]

Done.

+instruction begins a new basic blocks.  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 block IDs. These block IDs do not
+correspond to PNaCl records, since basic block boundaries are defined
+implicitly, after terminator instructions. They appear only for
+readability.
+
+Most operands of instructions are encoded using a relative index
+value, rather than abolute. The is done because most instruction

[binji, 2014/05/02 18:04:52]

absolute

[Karl, 2014/06/02 22:39:29]

Done.

+operands refer to values defined earlier in the (same) basic block.
+As a result, the relative distance (back) from the next defining
+instruction value index (for the function block) is frequently a small
+number. Small numbers tend to require less bits when they are

[Jim Stichnoth, 2014/05/08 12:55:17]

less --> fewer

[Karl, 2014/06/02 22:39:29]

Done.

+converted to bit sequences. This distance is used in the corresponding
+records to denote the operand values.
+
+The following subsections define records that can appear in a function
+block.
+
+Function enter
+--------------
+
+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**
+
+  <655335, 12, B>
+
+**Semantics**
+
+*B* is the number of bits reserved for abbreviations in the block. See
+enter block records[ref] for more details.
+
+The value of *N* corresponds the the positional index of the

[binji, 2014/05/02 18:04:52]

s/the //

[Jim Stichnoth, 2014/05/08 12:55:17]

Actually, the the --> to the

[Karl, 2014/06/02 22:39:29]

Done.

+corresponding defining function address this block is associated
+with. *M* is the number of defined paramaters (plus one)

[binji, 2014/05/02 18:04:52]

parameters

[Karl, 2014/06/02 22:39:29]

Done.

+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::
+
+  types {
+    ...
+    @t10 = void (i32, float);
+    ...
+  }
+  ...
+  define internal void @f12(i32, float);
+  ...
+  function void @f12(i32 %p0, float %p1) {
+  ...
+  }
+
+defines the enter block record:
+
+.. naclcode::
+
+  <655335, 12, 2>
+
+Count Record
+------------
+
+The count record, within a function block, defines the number of basic
+blocks used to define the function implementation.
+
+**Syntax**
+
+.. naclcode::
+
+    blocks: N;                                    <I>
+  %b0:
+
+**Record**
+
+.. naclcode::
+
+  I: <1, N>
+
+**Semantics**
+
+The count record defines the number of basic blocks *N*, defined by
+the implemented function. *I* is the (optional) abbreviation
+associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  ExpectedBasicBlocks == 0
+  NumBasicBlocks == 0
+
+Updates
+^^^^^^^
+
+.. naclcode::
+
+  ExpectedBlocks = N;
+
+**Examples**
+
+.. naclcode::
+
+  blocks: 5
+
+The corresponding PNaCl bitcode record is:
+
+.. naclcode::
+
+  <1, 5>
+
+Terminator Instructions
+-----------------------
+
+Terminator instructions are instructions that appear in a function
+block, and define the end of the current basic block. A terminator
+instuction indicates which block should be executed after the current

[binji, 2014/05/02 18:04:52]

instruction

[Karl, 2014/06/02 22:39:29]

Done.

+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;                                          <I>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+   I: <10>
+
+**Semantics**
+
+The return instruction returns control to the calling function.
+
+*B* is the number associated with the next basic block. Label *%bB:*
+only appears if *B + 1 < ExpectedBasicBlocks*. That is, the label is
+omitted only if this terminator instruction is the last instruction in
+the function block.  *I* is the (optional) abbreviation index
+associated with the record.
+
+**Constraints**
+
+.. naclcode::
+
+  B == NumBasicBlocks
+  NumBasicBlocks < ExpectedBasicBLocks
+  ReturnType(TypeOf(EnclosingFcnID)) == void
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+The following shows the implementation of a function that simply returns.
+
+.. naclcode::
+
+  function void @f5() {
+    ret;
+  }
+
+The corresponding PNaCl records are:
+
+.. naclcode::
+
+  <655335, 12, 2>
+  <10>
+  <655334>
+
+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;                                      <I>
+  %bB:
+
+**Record**
+
+.. naclcode::
+
+   I: <10, R>
+
+**Semantics**
+
+The return instruction returns control to the calling function,

[Jim Stichnoth, 2014/05/08 12:55:17]

return instruction --> return value instruction ?

[Karl, 2014/06/02 22:39:29]

Done.

+returning the provided value.
+
+*V* is the value to return. *R* is the corresponding relative index
+defining 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*.
+*I* is the (optional) abbreviation index associated with the record.
+
+*B* is the number associated with the next basic block.  Label *%bB:*
+only appears if *B + 1 < ExpectedBasicBlocks*. That is, the label is
+omitted only if this terminator instruction is the last instruction in
+the function block.
+
+**Constraints**
+
+.. naclcode::
+
+  R = RelativeIndex(V)
+  B == NumBasicBlocks
+  NumBasicBlocks < ExpectedBasicBlocks
+  T == TypeOf(V) == ReturnType(TypeOf(EnclosingFcnID))
+
+**Updates**
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+**Examples**
+
+The following shows a return statement that returns the value
+generated by the previous instruction:
+
+.. naclcode::
+
+  %v10 = add i32 %v1, @v2;

[Jim Stichnoth, 2014/05/08 12:55:17]

If you want, you could avoid the implicit forward reference to the Add
instruction with an example that just returns a function argument.

[Karl, 2014/06/02 22:39:29]

Done.

+  ret i32 @v10;
+
+The corresponding PNaCl records are:
+
+.. naclcode::
+
+  <2, 9, 8, 0>
+  <10, 1>
+
+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;                                       <I>
+  %bB:
+
+Record
+""""""
+
+.. naclcode::
+
+  I: <11, N>
+
+Semantics
+"""""""""
+
+The unconditional branch instruction causes control flow to transfer
+to basic block *N*.  *I* is the (optional) abbreviation index
+associated with the record.
+
+*B* is the number associated with the next basic block. Label *%bB:*
+only appears if *B + 1 < ExpectedBasicBlocks*. That is, the label is
+omitted only if this terminator instruction is the last instruction in
+the function block.
+
+Constraints
+"""""""""""
+
+.. naclcode::
+
+  0 < N
+  N < ExpectedBasicBlocks
+  B == NumBasicBlocks
+  NumBasicBlocks < ExpectedBasicBlocks
+
+Updates
+"""""""
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+Examples
+""""""""
+
+.. naclcode::
+
+    br %b2;
+
+This branch instruction branches to the 3rd basic block of the function. It
+defines the following PNaCL record:

[binji, 2014/05/02 18:04:52]

PNaCl

[Karl, 2014/06/02 22:39:29]

Done.

+
+.. naclcode::
+
+  <11, 2>
+
+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, %bB1, %bB2;                          <I>
+  %bB:
+
+Record
+""""""
+
+.. naclcode::
+
+  I: <11, B1, B2, V>
+
+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 *B1*. Otherwise control flows to basic block
+*B2*. Condition value V is the relative index of condition C. *I* is
+the (optional) abbreviation index associated with the record.
+
+*B* is the number associated with the next basic block. Label *%bB:*
+only appears if *B + 1 < ExpectedBasicBlocks*. That is, the label is
+omitted only if this terminator instruction is the last instruction in
+the function block.
+
+Constraints
+"""""""""""
+
+.. naclcode::
+
+  V == RelativeIndex(C)
+  0 < B1
+  B1 < ExpectedBasicBlocks 
+  0 < B2
+  B2 < ExpectedBasicBlocks
+  B == NumBasicBlocks and
+  NumBasicBlocks < ExpectedBasicBlocks
+  TypeOf(C) == i1
+
+Updates
+"""""""
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+Examples
+""""""""
+
+.. naclcode::
+
+  %b2:
+    %v10 = cmp eq i32 %v8, %v9;

[Jim Stichnoth, 2014/05/08 12:55:17]

Could avoid a forward reference to the Cmp instruction by making %v10 a function
argument, or perhaps introduce Cmp before Br.

[Karl, 2014/06/02 22:39:29]

Can't do this. Only i32 and i64 arguments are allowed. However, did complete
example to a complete function.

+    br i1 %v10, %b3, %b4;
+  %b3:
+    ret i32 1;
+  %b4:
+    ret i32 0;
+
+The record generated for the conditional branch instruction is:
+
+.. naclcode::
+
+  <11, 3, 4, 1>
+
+Unreachable
+^^^^^^^^^^^
+
+The unreachable instruction has no defined semantics. The instruction
+is used to inform the *PNaCl translator* that control can't reach this
+instruction.  The most common use of this is when one calls a

[Jim Stichnoth, 2014/05/08 12:55:17]

A more tangible/recognizable example may be the low-level implementation of
assert() or abort().

[Karl, 2014/06/02 22:39:29]

Decided to drop the clarification example.

+no-return function.
+
+Syntax
+""""""
+
+.. naclcode::
+
+    unreachable;                                  <I>
+  %bB:
+
+Record
+""""""
+
+.. naclcode::
+
+  I: <15>
+
+Semantics
+"""""""""
+
+Directive to the *PNaCl translator* that this instruction is unreachable.
+
+*I* is the (optional) abbreviation index associated with the record.

[jvoung (off chromium), 2014/05/27 23:18:50]

Is it necessary to put these "I: " under all the Record descriptions?

In the end, any record can optionally be abbreviated by some user-defined
abbreviation. So, isn't it a bit repetitive to mention it all the time (yet
sometimes leave the mention out, e.g., for conditional branch, even though
someone could make a user-defined abbrev for conditional branch)?  It's also
left out for the special 2**16 - 1, even though that is where the abbreviation
is special and is *not* optional in terms of writing to the bitstream.

It just happens to be that we have some common "user-defined" abbreviations that
*our* bitcode writer writes out all the time?

[Karl, 2014/06/02 22:39:29]

I agree that it is a bit repetitive. However, I haven't found a way to remove
them yet that is clean. I will continue to look for an answer.

+
+*B* is the number associated with the next basic block. Label *%bB:*
+only appears if *B + 1 < ExpectedBasicBlocks*. That is, the label is
+omitted only if this terminator instruction is the last instruction in
+the function block.
+
+Constraints
+"""""""""""
+
+.. naclcode::
+
+  B == NumBasicBlocks and
+  NumBasicBlocks < ExpectedBasicBlocks
+
+Updates
+"""""""
+
+.. naclcode::
+
+  ++NumBasicBlocks;
+
+Examples
+""""""""
+
+TBD.
+
+Switch Instruction
+^^^^^^^^^^^^^^^^^^
+
+TBD.
+
+Binary Inststructions

[Jim Stichnoth, 2014/05/08 12:55:17]

Instructions

+---------------------
+
+Binary instructions are used to do most of the computation in a
+program. They 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.
+
+Most integer binary operations can be applied to signed and unsigned
+integers.  In the few cases where the sign can make a difference,
+there are two separate binary operations, one for each case. For
+floating binary operations, the binary operation has the same name as
+the corresponding signed integer operation. One can tell whether the

[Jim Stichnoth, 2014/05/08 12:55:17]

I don't really like this attempt at generalization.  From my perspective, there
are 3 categories of binary instructions:

* Generic (non-signed) integer plus (signed) floating: add/fadd, sub/fsub,
mul/fmul.  This category does fit nicely into the generalization.

* Generic (non-signed) integer-only: shl, lshr, ashr, and, or, xor.  Here,
you'll have to make it explicit that FP types are not allowed.

* Signed+unsigned integer plus (signed) floating: sdiv/udiv/fdiv,
srem/urem/frem.  For each of {div,rem}, there are actually 3 instructions.  In
your generalization, you have to list two of them, and then point out that one
but not the other disallows the FP type.  And if you list e.g. "div" and "sdiv",
I think the implication would be that e.g. "div" allows both unsigned integer
and (signed) FP types, while "sdiv" allows signed integer types and no FP types,
which is a bit backwards - nicer would be "div" that allows signed integer and
(signed) FP types, and "udiv" that allowed just unsigned integer types.

(I'm wondering if you chose this generalization because of the specific encoding
that isn't yet documented here?)

Given all this, I think it would be clearer to just enumerate the 18 binary
instructions, each one's argument types being either signed int, unsigned int,
non-signed int, or FP, rather than enumerating 11 binary instructions with
implicit qualifications.

[Karl, 2014/06/02 22:39:29]

I refactored this into two sections: Integral binary operations and Floating
binary operations. Hopefully it now looks better.

+operation is integral or floating, by the type associated with the
+binary operation.
+
+Add Instruction
+^^^^^^^^^^^^^^^
+
+The add instruction returns the sum of its two operands. Both
+arguments, and the result, must be an integer, floating, or vector

[Jim Stichnoth, 2014/05/08 12:55:17]

"an" --> "the same", right?

[Karl, 2014/06/02 22:39:29]

Done.

+type.
+
+**Syntax**
+
+.. naclcode::
+
+  %vN = add T V1, V2;                             <I>
+
+**Record**
+
+  I: <2, A1, A2, 0>
+
+**Semantics**
+
+The add instruction returns the sum of its two operands. Arguments
+*V1* and *V2*, and the result *%vN*, must be of type *T*. *T* must be
+an integral, floating, or vector type.  *N* is defined by the record
+position, defining the corresponding value generated by the
+instruction.  *I* is the (optiona) abbreviation associated with the

[binji, 2014/05/02 18:04:52]

optional

[Karl, 2014/06/02 22:39:29]

Done.

+corresponding record.
+
+**Constraints**
+
+.. naclcode::
+
+  A1 == RelativeIndex(V1)
+  A2 == RelativeIndex(V2)
+  TypeOf(V1) == TypeOf(V2)
+  N == NumValuedInsts
+  NumBasicBlocks < ExpectedBasicBlocks
+
+**Updates**
+
+.. naclcode::
+
+  ++NumValuedInsts;
+  TypeOf(%vN) = T
+
+**Examples**
+
+TBD.
+
+Subtract Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+sub
+
+TBD.
+
+Multiply Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+mul
+
+TBD.
+
+Divide Instruction
+^^^^^^^^^^^^^^^^^^
+
+div
+sdiv
+
+TBD.
+
+Remainder Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+div
+sdiv

[Jim Stichnoth, 2014/05/08 12:55:17]

This should be rem and srem.

[Karl, 2014/06/02 22:39:29]

Done.

+
+TBD.
+
+Shift left Instruction

[Jim Stichnoth, 2014/05/08 12:55:17]

left --> Left

[Karl, 2014/06/02 22:39:29]

Done.

+^^^^^^^^^^^^^^^^^^^^^^
+
+shl
+
+TBD.
+
+Logical Shift right Instructions

[Jim Stichnoth, 2014/05/08 12:55:17]

right --> Right
Instructions --> Instruction

[Karl, 2014/06/02 22:39:29]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ashr

[Jim Stichnoth, 2014/05/08 12:55:17]

ashr --> lshr

[Karl, 2014/06/02 22:39:29]

Done.

+
+TBD.
+
+Arithmetic Shift right Instructions

[Jim Stichnoth, 2014/05/08 12:55:17]

right --> Right

[Karl, 2014/06/02 22:39:29]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ashr
+
+TBD.
+
+And Instruction
+^^^^^^^^^^^^^^^
+
+TBD.
+
+Or Instruction
+^^^^^^^^^^^^^^
+
+TBD.
+
+Xor Instruction
+^^^^^^^^^^^^^^^
+
+TBD.
+
+Memory creation and access Instructions
+---------------------------------------
+
+TBD.
+
+Stack frame memory allocation Instruction

[Jim Stichnoth, 2014/05/08 12:55:17]

Capitalize all words for consistency?

[Karl, 2014/06/02 22:39:29]

Done.

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+alloca
+
+TBD.
+
+Load Instruction
+^^^^^^^^^^^^^^^^
+
+load
+
+TBD.
+
+??? Vector
+
+Store Instruction
+^^^^^^^^^^^^^^^^^
+
+store
+
+??? Vector.
+
+Conversion Instructions
+-----------------------
+
+TBD.
+
+Truncating Instructions
+^^^^^^^^^^^^^^^^^^^^^^^
+
+trunc
+fptrunc
+
+TBD.
+
+Extending Instructions
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Extending
+
+* Type Conversion
+
+TBD.
+
+Comparison Instructions
+-----------------------
+
+cmp
+
+TBD.
+
+
+Other Instructions
+------------------
+
+TBD.
+
+Phi Instruction

[Jim Stichnoth, 2014/05/08 12:55:17]

Be sure to mention that within any given basic block, all the Phi instructions
must come before all the non-Phi instructions.

[Karl, 2014/06/02 22:39:29]

Agreed.

+^^^^^^^^^^^^^^^
+
+TBD.
+
+Forward type declarations

[Jim Stichnoth, 2014/05/08 12:55:17]

I know what all the other instructions are, but I don't recognize this.  I think
you should move this to the beginning or end of the list of instruction kinds so
it doesn't break the flow of descriptions of instructions that essentially
actually map to machine instructions.

[Jim Stichnoth, 2014/06/06 18:24:46]

Did you mean to add a comment here? :)

+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TBD.
+
+
+Select Instruction
+^^^^^^^^^^^^^^^^^^
+
+TBD.
+
+Call Instructions
+^^^^^^^^^^^^^^^^^
+
+TBD.
+
+Intrinsic Functions
+-------------------
+
+TBD.
+
+Support Functions
+-----------------
+
+Defines functions used to convert syntactic representation to corresponding
+records.
+
+AbsoluteIndex
+^^^^^^^^^^^^^
+
+Bitcode ID's of the forms *@fN*, *@gN*, *%pN*, *%cN*, and *%vN*, are
+combined into a single index space. This can be done because of the
+ordering imposed by PNaClAsm. All function address bitcode IDs must be
+defined before any of the other forms of bitcode IDs. All global
+address bitcode IDs must be defined before any local bitcode
+IDs. Within a function block, the parameter bitcode IDs must be
+defined before constant IDs, and constant IDs must be defined before
+instruction value IDs.
+
+Hence, within a function block, it is safe to refer to all of these
+bitcode IDs using a single *absolute* index. The abolute index for

[binji, 2014/05/02 18:04:52]

absolute

[Karl, 2014/06/02 22:39:29]

Done.

+each kind of bitcode ID is computed as follows:
+
+========== ==========================================================================
+Bitcode ID AbsoluteIndex
+========== ==========================================================================
+@fN        N
+@gN        N + NumDefinedFcnAddresses
+@pN        N + NumDefinedFcnAddresses + NumGlobalAddresses
+@cN        N + NumDefinedFcnAddresses + NumGlobalAddresses + NumParams
+@vN        N + NumDefinedFcnAddresses + NumGlobalAddresses + NumParams + NumFcnConsts
+========== ==========================================================================
+
+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(NumValuedInsts) - AbsoluteIndex(J)
+
+Abbreviations
+-------------
+
+TBD.
+
+Introduction
+^^^^^^^^^^^^
+
+TBD.
+
+* Blocks
+* Data Records
+* Abbreviations
+* Abbreviation Ids.
+
+Bitstream Format
+^^^^^^^^^^^^^^^^
+
+TBD.
+
+* Header
+* Block Structue

[binji, 2014/05/02 18:04:52]

Structure

[Karl, 2014/06/02 22:39:29]

Done.

+* Primitives
+* Abbreviations
+* BlockInfoBlock
+
+Reference Implementation
+------------------------
+
+TBD.