Update LangRef.rst to the 3.3 version and add PnaclRef.rst

PnaclRef.rst is an initial reference manual for PNaCl bitcode. It's
using the same documentation system to build as the other LLVM .rst
docs and has multiple links into relevant sections of LangRef.

BUG=None
R=jvoung@chromium.org

Review URL: https://codereview.chromium.org/17463004

2 files changed, 583 insertions, 107 deletions

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index c08cee1dbd..2c55d333a6 100644
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -127,7 +127,8 @@ lexical features of LLVM:
 #. Comments are delimited with a '``;``' and go until the end of line.
 #. Unnamed temporaries are created when the result of a computation is
    not assigned to a named value.
-#. Unnamed temporaries are numbered sequentially
+#. Unnamed temporaries are numbered sequentially (using a per-function
+   incrementing counter, starting with 0).
 
 It also shows a convention that we follow in this document. When
 demonstrating instructions, we will follow an instruction with a comment
@@ -148,20 +149,20 @@ symbol table entries. Here is an example of the "hello world" module:
 
 .. code-block:: llvm
 
-    ; Declare the string constant as a global constant. 
-    @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" 
+    ; Declare the string constant as a global constant.
+    @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
 
-    ; External declaration of the puts function 
-    declare i32 @puts(i8* nocapture) nounwind 
+    ; External declaration of the puts function
+    declare i32 @puts(i8* nocapture) nounwind
 
     ; Definition of main function
-    define i32 @main() {   ; i32()*  
-      ; Convert [13 x i8]* to i8  *... 
+    define i32 @main() {   ; i32()*
+      ; Convert [13 x i8]* to i8  *...
       %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
 
-      ; Call puts function to write out the string to stdout. 
+      ; Call puts function to write out the string to stdout.
       call i32 @puts(i8* %cast210)
-      ret i32 0 
+      ret i32 0
     }
 
     ; Named metadata
@@ -386,6 +387,8 @@ More calling conventions can be added/defined on an as-needed basis, to
 support Pascal conventions or any other well-known target-independent
 convention.
 
+.. _visibilitystyles:
+
 Visibility Styles
 -----------------
 
@@ -411,6 +414,8 @@ styles:
     defining module will bind to the local symbol. That is, the symbol
     cannot be overridden by another module.
 
+.. _namedtypes:
+
 Named Types
 -----------
 
@@ -563,7 +568,11 @@ A function definition contains a list of basic blocks, forming the CFG
 start with a label (giving the basic block a symbol table entry),
 contains a list of instructions, and ends with a
 :ref:`terminator <terminators>` instruction (such as a branch or function
-return).
+return). If explicit label is not provided, a block is assigned an
+implicit numbered label, using a next value from the same counter as used
+for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
+function entry block does not have explicit label, it will be assigned
+label "%0", then first unnamed temporary in that block will be "%1", etc.
 
 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
@@ -591,6 +600,8 @@ Syntax::
            [fn Attrs] [section "name"] [align N]
            [gc] { ... }
 
+.. _langref_aliases:
+
 Aliases
 -------
 
@@ -692,7 +703,7 @@ Currently, only the following parameter attributes are defined:
     the first parameter. This is not a valid attribute for return
     values.
 ``noalias``
-    This indicates that pointer values `*based* <pointeraliasing>` on
+    This indicates that pointer values :ref:`based <pointeraliasing>` on
     the argument or return value do not alias pointer values which are
     not *based* on it, ignoring certain "irrelevant" dependencies. For a
     call to the parent function, dependencies between memory references
@@ -719,12 +730,17 @@ Currently, only the following parameter attributes are defined:
 ``nest``
     This indicates that the pointer parameter can be excised using the
     :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
-    attribute for return values.
-``nobuiltin``
-    This indicates that the callee function at a call site is not
-    recognized as a built-in function. LLVM will retain the original call
-    and not replace it with equivalent code based on the semantics of the
-    built-in function.
+    attribute for return values and can only be applied to one parameter.
+
+``returned``
+    This indicates that the value of the function always returns the value
+    of the parameter as its return value. This is an optimization hint to
+    the code generator when generating the caller, allowing tail call
+    optimization and omission of register saves and restores in some cases;
+    it is not checked or enforced when generating the callee. The parameter
+    and the function return type must be valid operands for the
+    :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for
+    return values and can only be applied to one parameter.
 
 .. _gc:
 
@@ -764,10 +780,10 @@ inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
 .. code-block:: llvm
 
    ; Target-independent attributes:
-   #0 = attributes { alwaysinline alignstack=4 }
+   attributes #0 = { alwaysinline alignstack=4 }
 
    ; Target-dependent attributes:
-   #1 = attributes { "no-sse" }
+   attributes #1 = { "no-sse" }
 
    ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
    define void @f() #0 #1 { ... }
@@ -802,6 +818,11 @@ example:
     This attribute indicates that the inliner should attempt to inline
     this function into callers whenever possible, ignoring any active
     inlining size threshold for this caller.
+``cold``
+    This attribute indicates that this function is rarely called. When
+    computing edge weights, basic blocks post-dominated by a cold
+    function call are also considered to be cold; and, thus, given low
+    weight.
 ``nonlazybind``
     This attribute suppresses lazy symbol binding for the function. This
     may make calls to the function faster, at the cost of extra program
@@ -814,6 +835,12 @@ example:
 ``naked``
     This attribute disables prologue / epilogue emission for the
     function. This can have very system-specific consequences.
+``nobuiltin``
+    This indicates that the callee function at a call site is not
+    recognized as a built-in function. LLVM will retain the original call
+    and not replace it with equivalent code based on the semantics of the
+    built-in function. This is only valid at call sites, not on function
+    declarations or definitions.
 ``noduplicate``
     This attribute indicates that calls to the function cannot be
     duplicated. A call to a ``noduplicate`` function may be moved
@@ -949,6 +976,8 @@ two digit hex code for the number.
 The inline asm code is simply printed to the machine code .s file when
 assembly code is generated.
 
+.. _langref_datalayout:
+
 Data Layout
 -----------
 
@@ -1338,6 +1367,8 @@ transformation. A strong type system makes it easier to read the
 generated code and enables novel analyses and transformations that are
 not feasible to perform on normal three address code representations.
 
+.. _typeclassifications:
+
 Type Classifications
 --------------------
 
@@ -1843,14 +1874,16 @@ double, and there are three forms of long double. The 80-bit format used
 by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
 128-bit format used by PowerPC (two adjacent doubles) is represented by
 ``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
-represented by ``0xL`` followed by 32 hexadecimal digits; no currently
-supported target uses this format. Long doubles will only work if they
-match the long double format on your target. The IEEE 16-bit format
-(half precision) is represented by ``0xH`` followed by 4 hexadecimal
-digits. All hexadecimal formats are big-endian (sign bit at the left).
+represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles
+will only work if they match the long double format on your target.
+The IEEE 16-bit format (half precision) is represented by ``0xH``
+followed by 4 hexadecimal digits. All hexadecimal formats are big-endian
+(sign bit at the left).
 
 There are no constants of type x86mmx.
 
+.. _complexconstants:
+
 Complex Constants
 -----------------
 
@@ -2172,6 +2205,8 @@ instruction.
 Finally, some targets may provide defined semantics when using the value
 as the operand to an inline assembly, but that is target specific.
 
+.. _constantexprs:
+
 Constant Expressions
 --------------------
 
@@ -2224,7 +2259,7 @@ The following is the syntax for constant expressions:
     won't fit in the floating point type, the results are undefined.
 ``ptrtoint (CST to TYPE)``
     Convert a pointer typed constant to the corresponding integer
-    constant ``TYPE`` must be an integer type. ``CST`` must be of
+    constant. ``TYPE`` must be an integer type. ``CST`` must be of
     pointer type. The ``CST`` value is zero extended, truncated, or
     unchanged to make it fit in ``TYPE``.
 ``inttoptr (CST to TYPE)``
@@ -2276,6 +2311,8 @@ The following is the syntax for constant expressions:
 Other Values
 ============
 
+.. _inlineasmexprs:
+
 Inline Assembler Expressions
 ----------------------------
 
@@ -2533,14 +2570,14 @@ Examples:
 It is sometimes useful to attach information to loop constructs. Currently,
 loop metadata is implemented as metadata attached to the branch instruction
 in the loop latch block. This type of metadata refer to a metadata node that is
-guaranteed to be separate for each loop. The loop-level metadata is prefixed
-with ``llvm.loop``.
+guaranteed to be separate for each loop. The loop identifier metadata is 
+specified with the name ``llvm.loop``.
 
 The loop identifier metadata is implemented using a metadata that refers to
-itself to avoid merging it with any other identifier metadata, e.g., 
-during module linkage or function inlining. That is, each loop should refer 
-to their own identification metadata even if they reside in separate functions. 
-The following example contains loop identifier metadata for two separate loop 
+itself to avoid merging it with any other identifier metadata, e.g.,
+during module linkage or function inlining. That is, each loop should refer
+to their own identification metadata even if they reside in separate functions.
+The following example contains loop identifier metadata for two separate loop
 constructs:
 
 .. code-block:: llvm
@@ -2548,32 +2585,17 @@ constructs:
     !0 = metadata !{ metadata !0 }
     !1 = metadata !{ metadata !1 }
 
+The loop identifier metadata can be used to specify additional per-loop
+metadata. Any operands after the first operand can be treated as user-defined
+metadata. For example the ``llvm.vectorizer.unroll`` metadata is understood
+by the loop vectorizer to indicate how many times to unroll the loop:
 
-'``llvm.loop.parallel``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: llvm
 
-This loop metadata can be used to communicate that a loop should be considered
-a parallel loop. The semantics of parallel loops in this case is the one
-with the strongest cross-iteration instruction ordering freedom: the
-iterations in the loop can be considered completely independent of each
-other (also known as embarrassingly parallel loops).
-
-This metadata can originate from a programming language with parallel loop
-constructs. In such a case it is completely the programmer's responsibility
-to ensure the instructions from the different iterations of the loop can be
-executed in an arbitrary order, in parallel, or intertwined. No loop-carried
-dependency checking at all must be expected from the compiler.
-
-In order to fulfill the LLVM requirement for metadata to be safely ignored,
-it is important to ensure that a parallel loop is converted to
-a sequential loop in case an optimization (agnostic of the parallel loop
-semantics) converts the loop back to such. This happens when new memory
-accesses that do not fulfill the requirement of free ordering across iterations
-are added to the loop. Therefore, this metadata is required, but not
-sufficient, to consider the loop at hand a parallel loop. For a loop
-to be parallel,  all its memory accessing instructions need to be
-marked with the ``llvm.mem.parallel_loop_access`` metadata that refer
-to the same loop identifier metadata that identify the loop at hand.
+      br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
+    ...
+    !0 = metadata !{ metadata !0, metadata !1 }
+    !1 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 2 }
 
 '``llvm.mem``'
 ^^^^^^^^^^^^^^^
@@ -2585,29 +2607,28 @@ for optimizations are prefixed with ``llvm.mem``.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For a loop to be parallel, in addition to using
-the ``llvm.loop.parallel`` metadata to mark the loop latch branch instruction,
+the ``llvm.loop`` metadata to mark the loop latch branch instruction,
 also all of the memory accessing instructions in the loop body need to be
 marked with the ``llvm.mem.parallel_loop_access`` metadata. If there
 is at least one memory accessing instruction not marked with the metadata,
-the loop, despite it possibly using the ``llvm.loop.parallel`` metadata,
-must be considered a sequential loop. This causes parallel loops to be
+the loop must be considered a sequential loop. This causes parallel loops to be
 converted to sequential loops due to optimization passes that are unaware of
 the parallel semantics and that insert new memory instructions to the loop
 body.
 
 Example of a loop that is considered parallel due to its correct use of
-both ``llvm.loop.parallel`` and ``llvm.mem.parallel_loop_access``
+both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
 metadata types that refer to the same loop identifier metadata.
 
 .. code-block:: llvm
 
    for.body:
-   ...
-   %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   br i1 %exitcond, label %for.end, label %for.body, !llvm.loop.parallel !0
+     ...
+     %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
 
    for.end:
    ...
@@ -2623,27 +2644,75 @@ the loop identifier metadata node directly:
    ...
 
    inner.for.body:
-   ...
-   %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop.parallel !1
+     ...
+     %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
 
    inner.for.end:
-   ...
-   %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
-   ...
-   br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop.parallel !2
+     ...
+     %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+     ...
+     br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
 
    outer.for.end:                                          ; preds = %for.body
    ...
-   !0 = metadata !{ metadata !1, metadata !2 } ; a list of parallel loop identifiers
-   !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop
-   !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop
+   !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
+   !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
+   !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
+
+'``llvm.vectorizer``'
+^^^^^^^^^^^^^^^^^^^^^
+
+Metadata prefixed with ``llvm.vectorizer`` is used to control per-loop
+vectorization parameters such as vectorization factor and unroll factor.
+
+``llvm.vectorizer`` metadata should be used in conjunction with ``llvm.loop``
+loop identification metadata.
+
+'``llvm.vectorizer.unroll``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata instructs the loop vectorizer to unroll the specified
+loop exactly ``N`` times.
+
+The first operand is the string ``llvm.vectorizer.unroll`` and the second
+operand is an integer specifying the unroll factor. For example:
+
+.. code-block:: llvm
 
+   !0 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 4 }
+
+Note that setting ``llvm.vectorizer.unroll`` to 1 disables unrolling of the
+loop.
+
+If ``llvm.vectorizer.unroll`` is set to 0 then the amount of unrolling will be
+determined automatically.
+
+'``llvm.vectorizer.width``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata sets the target width of the vectorizer to ``N``. Without
+this metadata, the vectorizer will choose a width automatically.
+Regardless of this metadata, the vectorizer will only vectorize loops if
+it believes it is valid to do so.
+
+The first operand is the string ``llvm.vectorizer.width`` and the second
+operand is an integer specifying the width. For example:
+
+.. code-block:: llvm
+
+   !0 = metadata !{ metadata !"llvm.vectorizer.width", i32 4 }
+
+Note that setting ``llvm.vectorizer.width`` to 1 disables vectorization of the
+loop.
+
+If ``llvm.vectorizer.width`` is set to 0 then the width will be determined
+automatically.
 
 Module Flags Metadata
 =====================
@@ -2829,7 +2898,7 @@ For example, the following metadata section specifies two separate sets of
 linker options, presumably to link against ``libz`` and the ``Cocoa``
 framework::
 
-    !0 = metadata !{ i32 6, metadata !"Linker Options", 
+    !0 = metadata !{ i32 6, metadata !"Linker Options",
        metadata !{
           metadata !{ metadata !"-lz" },
           metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
@@ -2845,6 +2914,8 @@ Each individual option is required to be either a valid option for the target's
 linker, or an option that is reserved by the target specific assembly writer or
 object file emitter. No other aspect of these options is defined by the IR.
 
+.. _intrinsicglobalvariables:
+
 Intrinsic Global Variables
 ==========================
 
@@ -2854,13 +2925,15 @@ All globals of this sort should have a section specified as
 "``llvm.metadata``". This section and all globals that start with
 "``llvm.``" are reserved for use by LLVM.
 
+.. _gv_llvmused:
+
 The '``llvm.used``' Global Variable
 -----------------------------------
 
-The ``@llvm.used`` global is an array with i8\* element type which has
+The ``@llvm.used`` global is an array which has
 :ref:`appending linkage <linkage_appending>`. This array contains a list of
-pointers to global variables and functions which may optionally have a
-pointer cast formed of bitcast or getelementptr. For example, a legal
+pointers to named global variables, functions and aliases which may optionally
+have a pointer cast formed of bitcast or getelementptr. For example, a legal
 use of it is:
 
 .. code-block:: llvm
@@ -2873,18 +2946,20 @@ use of it is:
        i8* bitcast (i32* @Y to i8*)
     ], section "llvm.metadata"
 
-If a global variable appears in the ``@llvm.used`` list, then the
-compiler, assembler, and linker are required to treat the symbol as if
-there is a reference to the global that it cannot see. For example, if a
-variable has internal linkage and no references other than that from the
-``@llvm.used`` list, it cannot be deleted. This is commonly used to
-represent references from inline asms and other things the compiler
-cannot "see", and corresponds to "``attribute((used))``" in GNU C.
+If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
+and linker are required to treat the symbol as if there is a reference to the
+symbol that it cannot see (which is why they have to be named). For example, if
+a variable has internal linkage and no references other than that from the
+``@llvm.used`` list, it cannot be deleted. This is commonly used to represent
+references from inline asms and other things the compiler cannot "see", and
+corresponds to "``attribute((used))``" in GNU C.
 
 On some targets, the code generator must emit a directive to the
 assembler or object file to prevent the assembler and linker from
 molesting the symbol.
 
+.. _gv_llvmcompilerused:
+
 The '``llvm.compiler.used``' Global Variable
 --------------------------------------------
 
@@ -2897,6 +2972,8 @@ by ``@llvm.used``.
 This is a rare construct that should only be used in rare circumstances,
 and should not be exposed to source languages.
 
+.. _gv_llvmglobalctors:
+
 The '``llvm.global_ctors``' Global Variable
 -------------------------------------------
 
@@ -2911,6 +2988,8 @@ array will be called in ascending order of priority (i.e. lowest first)
 when the module is loaded. The order of functions with the same priority
 is not defined.
 
+.. _llvmglobaldtors:
+
 The '``llvm.global_dtors``' Global Variable
 -------------------------------------------
 
@@ -3997,7 +4076,7 @@ Example:
       <result> = lshr i32 4, 1   ; yields {i32}:result = 2
       <result> = lshr i32 4, 2   ; yields {i32}:result = 1
       <result> = lshr i8  4, 3   ; yields {i8}:result = 0
-      <result> = lshr i8 -2, 1   ; yields {i8}:result = 0x7FFFFFFF 
+      <result> = lshr i8 -2, 1   ; yields {i8}:result = 0x7F
       <result> = lshr i32 1, 32  ; undefined
       <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
 
@@ -4534,7 +4613,7 @@ The '``load``' instruction is used to read from memory.
 Arguments:
 """"""""""
 
-The argument to the '``load``' instruction specifies the memory address
+The argument to the ``load`` instruction specifies the memory address
 from which to load. The pointer must point to a :ref:`first
 class <t_firstclass>` type. If the ``load`` is marked as ``volatile``,
 then the optimizer is not allowed to modify the number or order of
@@ -4555,14 +4634,14 @@ any defined semantics for atomic loads.
 
 The optional constant ``align`` argument specifies the alignment of the
 operation (that is, the alignment of the memory address). A value of 0
-or an omitted ``align`` argument means that the operation has the abi
+or an omitted ``align`` argument means that the operation has the ABI
 alignment for the target. It is the responsibility of the code emitter
 to ensure that the alignment information is correct. Overestimating the
 alignment results in undefined behavior. Underestimating the alignment
 may produce less efficient code. An alignment of 1 is always safe.
 
 The optional ``!nontemporal`` metadata must reference a single
-metatadata name <index> corresponding to a metadata node with one
+metatadata name ``<index>`` corresponding to a metadata node with one
 ``i32`` entry of value 1. The existence of the ``!nontemporal``
 metatadata on the instruction tells the optimizer and code generator
 that this load is not expected to be reused in the cache. The code
@@ -4570,7 +4649,7 @@ generator may select special instructions to save cache bandwidth, such
 as the ``MOVNT`` instruction on x86.
 
 The optional ``!invariant.load`` metadata must reference a single
-metatadata name <index> corresponding to a metadata node with no
+metatadata name ``<index>`` corresponding to a metadata node with no
 entries. The existence of the ``!invariant.load`` metatadata on the
 instruction tells the optimizer and code generator that this load
 address points to memory which does not change value during program
@@ -4618,10 +4697,10 @@ The '``store``' instruction is used to write to memory.
 Arguments:
 """"""""""
 
-There are two arguments to the '``store``' instruction: a value to store
-and an address at which to store it. The type of the '``<pointer>``'
+There are two arguments to the ``store`` instruction: a value to store
+and an address at which to store it. The type of the ``<pointer>``
 operand must be a pointer to the :ref:`first class <t_firstclass>` type of
-the '``<value>``' operand. If the ``store`` is marked as ``volatile``,
+the ``<value>`` operand. If the ``store`` is marked as ``volatile``,
 then the optimizer is not allowed to modify the number or order of
 execution of this ``store`` with other :ref:`volatile
 operations <volatile>`.
@@ -4638,18 +4717,18 @@ has undefined behavior if the alignment is not set to a value which is
 at least the size in bytes of the pointee. ``!nontemporal`` does not
 have any defined semantics for atomic stores.
 
-The optional constant "align" argument specifies the alignment of the
+The optional constant ``align`` argument specifies the alignment of the
 operation (that is, the alignment of the memory address). A value of 0
-or an omitted "align" argument means that the operation has the abi
+or an omitted ``align`` argument means that the operation has the ABI
 alignment for the target. It is the responsibility of the code emitter
 to ensure that the alignment information is correct. Overestimating the
-alignment results in an undefined behavior. Underestimating the
+alignment results in undefined behavior. Underestimating the
 alignment may produce less efficient code. An alignment of 1 is always
 safe.
 
-The optional !nontemporal metadata must reference a single metatadata
-name <index> corresponding to a metadata node with one i32 entry of
-value 1. The existence of the !nontemporal metatadata on the instruction
+The optional ``!nontemporal`` metadata must reference a single metatadata
+name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
+value 1. The existence of the ``!nontemporal`` metatadata on the instruction
 tells the optimizer and code generator that this load is not expected to
 be reused in the cache. The code generator may select special
 instructions to save cache bandwidth, such as the MOVNT instruction on
@@ -4658,8 +4737,8 @@ x86.
 Semantics:
 """"""""""
 
-The contents of memory are updated to contain '``<value>``' at the
-location specified by the '``<pointer>``' operand. If '``<value>``' is
+The contents of memory are updated to contain ``<value>`` at the
+location specified by the ``<pointer>`` operand. If ``<value>`` is
 of scalar type then the number of bytes written does not exceed the
 minimum number of bytes needed to hold all bits of the type. For
 example, storing an ``i24`` writes at most three bytes. When writing a
@@ -6647,6 +6726,9 @@ memory. Implementations are allowed to either return a application
 specific value or a system wide value. On backends without support, this
 is lowered to a constant 0.
 
+Note that runtime support may be conditional on the privilege-level code is
+running at and the host platform.
+
 Standard C Library Intrinsics
 -----------------------------
 
@@ -8342,6 +8424,46 @@ strings. This can be useful for special purpose optimizations that want
 to look for these annotations. These have no other defined use; they are
 ignored by code generation and optimization.
 
+'``llvm.ptr.annotation.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
+pointer to an integer of any width. *NOTE* you must specify an address space for
+the pointer. The identifier for the default address space is the integer
+'``0``'.
+
+::
+
+      declare i8*   @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare i16*  @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare i32*  @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare i64*  @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32  <int>)
+
+Overview:
+"""""""""
+
+The '``llvm.ptr.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to an integer value of arbitrary bitwidth
+(result of some expression), the second is a pointer to a global string, the
+third is a pointer to a global string which is the source file name, and the
+last argument is the line number. It returns the value of the first argument.
+
+Semantics:
+""""""""""
+
+This intrinsic allows annotation of a pointer to an integer with arbitrary
+strings. This can be useful for special purpose optimizations that want to look
+for these annotations. These have no other defined use; they are ignored by code
+generation and optimization.
+
 '``llvm.annotation.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/PNaClLangRef.rst b/docs/PNaClLangRef.rst
new file mode 100644
index 0000000000..45e4599c9d
--- /dev/null
+++ b/docs/PNaClLangRef.rst
@@ -0,0 +1,354 @@
+==============================
+PNaCl Bitcode Reference Manual
+==============================
+
+.. contents::
+   :local:
+   :depth: 3
+
+Introduction
+============
+
+This document is a reference manual for the PNaCl bitcode format. It describes
+the bitcode on a *semantic* level; the physical encoding level will be described
+elsewhere. For the purpose of this document, the textual form of LLVM IR is
+used to describe instructions and other bitcode constructs.
+
+Since the PNaCl bitcode is based to a large extent on LLVM IR, many sections
+in this document point to a relevant section of the LLVM language reference
+manual. Only the changes, restrictions and variations specific to PNaCl are
+described - full semantic descriptions are not duplicated from the LLVM
+reference manual.
+
+*[TODO(eliben): this may gradually change in the future, as we move more
+contents into this document; also, the physical encoding will also be described
+here in the future, once we know what it's going to be]*
+
+High Level Structure
+====================
+
+A PNaCl portable executable ("pexe" in short) is a single LLVM IR module.
+
+Linkage Types
+-------------
+
+`LLVM LangRef: Linkage Types <LangRef.html#linkage>`_
+
+The linkage types supported by PNaCl bitcode are ``internal`` and ``external``.
+A single function in the pexe, named ``_start``, has the linkage type
+``external``. All the other functions have the linkage type ``internal``.
+
+Calling Conventions
+-------------------
+
+`LLVM LangRef: Calling Conventions <LangRef.html#callingconv>`_
+
+The only calling convention supported by PNaCl bitcode is ``ccc`` - the C
+calling convention.
+
+Visibility Styles
+-----------------
+
+`LLVM LangRef: Visibility Styles <LangRef.html#visibilitystyles>`_
+
+PNaCl bitcode does not support visibility styles.
+
+Global Variables
+----------------
+
+`LLVM LangRef: Global Variables <LangRef.html#globalvars>`_
+
+PNaCl bitcode does not support TLS models.
+
+TODO: describe other restrictions on global variables
+
+Functions
+---------
+
+`LLVM LangRef: Functions <LangRef.html#functionstructure>`_
+
+The restrictions on linkage types, calling conventions and visibility styles
+apply to functions. In addition, the following are not supported for functions:
+
+* Function attributes.
+* Section specification.
+* Garbage collector name.
+* Parameter attributes for the return type.
+
+Aliases
+-------
+
+`LLVM LangRef: Aliases <LangRef.html#langref_aliases>`_
+
+PNaCl bitcode does not support aliases.
+
+Named Metadata
+--------------
+
+`LLVM LangRef: Named Metadata <LangRef.html#namedmetadatastructure>`_
+
+While PNaCl bitcode has provisions for debugging metadata, it is not considered
+part of the stable ABI. It exists for tool support and should not appear in
+distributed pexes.
+
+Other kinds of LLVM metadata are not supported.
+
+Parameter Attributes
+--------------------
+
+`LLVM LangRef: Parameter Attributes <LangRef.html#paramattrs>`_
+
+TODO: what parameter attributes are supported.
+
+Function Attributes
+-------------------
+
+`LLVM LangRef: Function Attributes <LangRef.html#fnattrs>`_
+
+PNaCl bitcode does not support function attributes.
+
+Module-Level Inline Assembly
+----------------------------
+
+`LLVM LangRef: Module-Level Inline Assembly <LangRef.html#moduleasm>`_
+
+PNaCl bitcode does not support inline assembly.
+
+Volatile Memory Accesses
+------------------------
+
+`LLVM LangRef: Volatile Memory Accesses <LangRef.html#volatile>`_
+
+TODO: are we going to promote volatile to atomic?
+
+Memory Model for Concurrent Operations
+--------------------------------------
+
+`LLVM LangRef: Memory Model for Concurrent Operations <LangRef.html#memmodel>`_
+
+TODO.
+
+Atomic Memory Ordering Constraints
+----------------------------------
+
+`LLVM LangRef: Atomic Memory Ordering Constraints <LangRef.html#ordering>`_
+
+TODO.
+
+Fast-Math Flags
+---------------
+
+`LLVM LangRef: Fast-Math Flags <LangRef.html#fastmath>`_
+
+Fast-math mode is not currently supported by the PNaCl bitcode.
+
+Type System
+===========
+
+`LLVM LangRef: Type System <LangRef.html#typesystem>`_
+
+The LLVM types allowed in PNaCl bitcode are restricted, as follows:
+
+Scalar types
+------------
+
+* The only scalar types allowed are integer, float, double and void.
+
+  * The only integer sizes allowed are i1, i8, i16, i32 and i64.
+  * The only integer sizes allowed for function arguments are i32 and i64.
+
+Arrays and structs are only allowed in TODO.
+
+.. _pointertypes:
+
+Pointer types
+-------------
+
+Pointer types are allowed with the following restrictions:
+
+* Pointers to valid PNaCl bitcode scalar types, as specified above.
+* Pointers to functions (but not intrinsics).
+* The address space for all pointers must be 0.
+
+A pointer is *inherent* when it represents the return value of an ``alloca``
+instruction, or is an address of a global value.
+
+A pointer is *normalized* if it's either:
+
+* *inherent*
+* Is the return value of a ``bitcast`` instruction.
+* Is the return value of a ``inttoptr`` instruction.
+
+Note: the size of a pointer in PNaCl is 32 bits.
+
+Global Variable and Function Addresses
+--------------------------------------
+
+Undefined Values
+----------------
+
+`LLVM LangRef: Undefined Values <LangRef.html#undefvalues>`_
+
+Poison Values
+-------------
+
+`LLVM LangRef: Poison Values <LangRef.html#poisonvalues>`_
+
+PNaCl bitcode does not support poison values; consequently, the ``nsw`` and
+``nuw`` are not supported.
+
+Constant Expressions
+--------------------
+
+`LLVM LangRef: Constant Expressions <LangRef.html#constantexprs>`_
+
+In the general sense, PNaCl bitcode does not support constant expressions.
+There is a single, restricted, use case permitted in global initializers,
+where the ``add`` and ``ptrtoint`` constant expressions are allowed.
+
+Other Values
+============
+
+Metadata Nodes and Metadata Strings
+-----------------------------------
+
+`LLVM LangRef: Metadata Nodes and Metadata Strings <LangRef.html#metadata>`_
+
+While PNaCl bitcode has provisions for debugging metadata, it is not considered
+part of the stable ABI. It exists for tool support and should not appear in
+distributed pexes.
+
+Other kinds of LLVM metadata are not supported.
+
+Intrinsic Global Variables
+==========================
+
+`LLVM LangRef: Intrinsic Global Variables <LangRef.html#intrinsicglobalvariables>`_
+
+PNaCl bitcode does not support intrinsic global variables.
+
+Instruction Reference
+=====================
+
+This is a list of LLVM instructions supported by PNaCl bitcode. Where
+applicable, PNaCl-specific restrictions are provided.
+
+Only the LLVM instructions listed here are supported by PNaCl bitcode.
+
+* ``ret``
+* ``br``
+* ``switch``
+* ``add``
+
+  The ``nsw`` and ``nuw`` modes are not supported.
+
+* ``sub``
+
+  The ``nsw`` and ``nuw`` modes are not supported.
+
+* ``mul``
+
+  The ``nsw`` and ``nuw`` modes are not supported.
+
+* ``shl``
+
+  The ``nsw`` and ``nuw`` modes are not supported.
+
+* ``udiv``, ``sdiv``, ``urem``, ``srem``
+
+  Integer division is guaranteed to trap in PNaCl bitcode. This trap can
+  not be intercepted.
+
+* ``lshr``
+* ``ashr``
+* ``and``
+* ``or``
+* ``xor``
+* ``fadd``
+* ``fsub``
+* ``fmul``
+* ``fdiv``
+* ``frem``
+* ``alloca``
+
+  The only allowed type for ``alloca`` instructions in PNaCl bitcode is an
+  array of i8. For example:
+
+.. code-block:: llvm
+
+    %buf = alloca [4 x i8], align 1
+
+* ``load``, ``store``
+
+  The pointer argument of these instructions must be a *normalized* pointer
+  (see :ref:`pointer types <pointertypes>`).
+
+* ``fence``
+* ``cmpxchg``, ``atomicrmw``
+
+  The pointer argument of these instructions must be a *normalized* pointer
+  (see :ref:`pointer types <pointertypes>`).
+
+  TODO(jfb): this may change
+
+* ``trunc``
+* ``zext``
+* ``sext``
+* ``fptrunc``
+* ``fpext``
+* ``fptoui``
+* ``fptosi``
+* ``uitofp``
+* ``sitofp``
+
+* ``ptrtoint``
+
+  The pointer argument of a ``ptrtoint`` instruction must be a *normalized*
+  pointer (see :ref:`pointer types <pointertypes>`) and the integer argument
+  must be an i32.
+
+* ``inttoptr``
+
+  The integer argument of a ``inttoptr`` instruction must be an i32.
+
+* ``bitcast``
+
+  The pointer argument of a ``bitcast`` instruction must be a *inherent* pointer
+  (see :ref:`pointer types <pointertypes>`).
+
+* ``icmp``
+* ``fcmp``
+* ``phi``
+* ``select``
+* ``call``
+
+Intrinsic Functions
+===================
+
+`LLVM LangRef: Intrinsic Functions <LangRef.html#intrinsics>`_
+
+The only intrinsics supported by PNaCl bitcode are the following.
+
+TODO(jfb): atomics
+
+* ``llvm.memcpy``
+* ``llvm.memmove``
+* ``llvm.memset``
+* ``llvm.bswap``
+
+  The llvm.bswap intrinsic is only supported with the following argument types:
+  i16, i32, i64.
+
+* ``llvm.trap``
+* ``llvm.nacl.read.tp``
+
+  TODO: describe
+
+* ``llvm.nacl.longjmp``
+
+  TODO: describe
+
+* ``llvm.nacl.setjmp``
+
+  TODO: describe
+