Index: LangRef.rst
===================================================================
--- LangRef.rst
+++ LangRef.rst
@@ -3007,7 +3007,7 @@
       %poison4 = load i64, i64* %wideaddr  ; Returns a poison value.
 
       %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
-      br i1 %cmp, label %true, label %end  ; Branch to either destination.
+      br i1 %cmp, label %true, label %end  ; undefined behavior
 
     true:
       store volatile i32 0, i32* @g        ; This is control-dependent on %cmp, so
@@ -5404,6 +5404,8 @@
 argument is evaluated. If the value is ``true``, control flows to the
 '``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
 to the '``iffalse``' ``label`` argument.
+If "cond" is either ``undef`` or ``poison``, this instruction has
+undefined behavior.
 
 Example:
 """"""""
@@ -8553,6 +8555,54 @@
 
       %X = select i1 true, i8 17, i8 42          ; yields i8:17
 
+
+.. _i_freeze:
+
+'``freeze``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+      <result> = freeze ty <val>    ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``freeze``' instruction is used to stop propagation of ``undef``
+and ``poison`` values.
+
+Arguments:
+""""""""""
+
+The '``freeze``' instruction takes a single argument, which is currently
+required to be of integer type.
+
+Semantics:
+""""""""""
+
+If the argument is ``undef`` or ``poison``, '``freeze``' returns an
+arbitrary, but fixed, value of type '``ty``'.
+Otherwise, this instruction is a no-op and returns the input argument.
+All uses of '``freeze``' are guaranteed to always observe the same value.
+
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+      %w = i32 undef
+      %x = freeze i32 %w
+      %y = add i32 %w, %w      ; undef
+      %z = add i32 %x, %x      ; even number
+
+      %cmp.fr = freeze i1 undef
+      br i1 %cmp.fr, label %foo, label %bar ; non-deterministic branch to %foo or %bar
+
+
 .. _i_call:
 
 '``call``' Instruction