From 905f645c8070b872015d2c146fe953431a0506cc Mon Sep 17 00:00:00 2001
From: Gui Andrade <guiand@google.com>
Date: Mon, 22 Jun 2020 16:49:41 +0000
Subject: [PATCH] [LangRef] Introduce `noundef` attribute for fully defined
 function params

LLVM currently does not require function parameters or return values
to be fully initialized, and does not care if they are poison. This can
be useful if the frontend ABI makes no such demands, but may prevent
helpful backend transformations in case they do. Specifically, the C
and C++ languages require all scalar function operands to be fully
determined.

Introducing this attribute is of particular use to MemorySanitizer
today, although other transformations may benefit from it as well.
We can modify MemorySanitizer instrumentation to provide modest (17%)
space savings where `frozen` is present.

This commit only adds the attribute to the Language Reference, and
the actual implementation of the attribute will follow in a separate
commit.

Differential Revision: https://reviews.llvm.org/D82316
---
 docs/BitCodeFormat.rst |  1 +
 docs/LangRef.rst       | 11 +++++++++++
 2 files changed, 12 insertions(+)

diff --git a/docs/BitCodeFormat.rst b/docs/BitCodeFormat.rst
index 065f9c3d49d..6e491c6e285 100644
--- a/docs/BitCodeFormat.rst
+++ b/docs/BitCodeFormat.rst
@@ -1067,6 +1067,7 @@ The integer codes are mapped to well-known attributes as follows.
 * code 65: ``preallocated``
 * code 66: ``no_merge``
 * code 67: ``null_pointer_is_valid``
+* code 68: ``noundef``
 
 .. note::
   The ``allocsize`` attribute has a special encoding for its arguments. Its two
diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index cc2f6d1b3a0..566d761d307 100644
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -1252,6 +1252,12 @@ Currently, only the following parameter attributes are defined:
     only valid on intrinsic declarations and cannot be applied to a
     call site or arbitrary function.
 
+``noundef``
+    This attribute applies to parameters and return values. If the value
+    representation contains any undefined or poison bits, the behavior is
+    undefined. Note that this does not refer to padding introduced by the
+    type's storage representation.
+
 .. _gc:
 
 Garbage Collector Strategy Names
@@ -3657,6 +3663,11 @@ behavior. Notably this includes (but is not limited to):
 -  The condition operand of a :ref:`br <i_br>` instruction.
 -  The callee operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
    instruction.
+-  The parameter operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
+   instruction, when the function or invoking call site has a ``noundef``
+   attribute in the corresponding position.
+-  The operand of a :ref:`ret <i_ret>` instruction if the function or invoking
+   call site has a `noundef` attribute in the return value position.
 
 Here are some examples: