[PATCH] D29121: [Docs] Add LangRef documention for freeze instruction

[Nuno Lopes via Phabricator via llvm-commits]

nlopes updated this revision to Diff 85871.
nlopes added a comment.

- rebase
- add UB semantics to indirectbr and switch


https://reviews.llvm.org/D29121

Files:
  LangRef.rst


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
@@ -5417,6 +5417,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:
 """"""""
@@ -5467,6 +5469,8 @@
 for the given value. If the value is found, control flow is transferred
 to the corresponding destination; otherwise, control flow is transferred
 to the default destination.
+If "value" is either ``undef`` or ``poison``, this instruction has
+undefined behavior.
 
 Implementation:
 """""""""""""""
@@ -5531,6 +5535,8 @@
 possible destination blocks must be listed in the label list, otherwise
 this instruction has undefined behavior. This implies that jumps to
 labels defined in other functions have undefined behavior as well.
+If "address" is either ``undef`` or ``poison``, this instruction has
+undefined behavior.
 
 Implementation:
 """""""""""""""
@@ -8566,6 +8572,55 @@
 
       %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 a '``freeze``' instruction 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D29121.85871.patch
Type: text/x-patch
Size: 2679 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20170126/a98cb2cd/attachment.bin>