[llvm] Add 'initialized' attribute langref (PR #84803)

[Haopeng Liu via llvm-commits]

https://github.com/haopliu updated https://github.com/llvm/llvm-project/pull/84803

>From 2554c821dfa3893213f934253ecbca5d9d43ceab Mon Sep 17 00:00:00 2001
From: Haopeng Liu <haopliu at google.com>
Date: Mon, 11 Mar 2024 17:47:08 +0000
Subject: [PATCH 1/2] Add 'initialized' attribute langref

---
 llvm/docs/LangRef.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index b70220dec92615..39a555edfa80d6 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -1621,6 +1621,28 @@ Currently, only the following parameter attributes are defined:
     ``readonly`` or a ``memory`` attribute that does not contain
     ``argmem: write``.
 
+``initialized((Lo1,Hi1),...)``
+    This attribute is a list of const ranges in ascending order with no
+    overlapping or continuous. It indicates that the function initializes the
+    memory through the pointer argument, [%p+LoN, %p+HiN): there are no reads,
+    and no special accesses (such as volatile access or untrackable capture)
+    before the initialization in the function. LoN/HiN are 64-bit ints;
+    negative values are allowed in case a pointer to partway through the
+    allocation is passed to.
+
+    This attribute implies that the function initializes and does not read
+    before initialization through this pointer argument, even though it may
+    read the memory before initialization that the pointer points to, such
+    as through other arguments.
+
+    The ``writable`` or ``dereferenceable`` attribute does not imply
+    ``initialized`` attribute, and ``initialized`` does not imply ``writeonly``
+    since cases that read from the pointer after write, can be ``initialized``
+    but not ``writeonly``.
+
+    Note that this attribute does not apply to the unwind edge: the memory may
+    not actually be written to when unwinding happens.
+
 ``dead_on_unwind``
     At a high level, this attribute indicates that the pointer argument is dead
     if the call unwinds, in the sense that the caller will not depend on the

>From a9256bf15dd3e9bb836a467979f61569df98cf8e Mon Sep 17 00:00:00 2001
From: Haopeng Liu <haopliu at google.com>
Date: Tue, 12 Mar 2024 22:10:14 +0000
Subject: [PATCH 2/2] Update the LangRef

---
 llvm/docs/LangRef.rst | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 39a555edfa80d6..0d0f21b8d203ef 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -1622,26 +1622,29 @@ Currently, only the following parameter attributes are defined:
     ``argmem: write``.
 
 ``initialized((Lo1,Hi1),...)``
-    This attribute is a list of const ranges in ascending order with no
-    overlapping or continuous. It indicates that the function initializes the
-    memory through the pointer argument, [%p+LoN, %p+HiN): there are no reads,
-    and no special accesses (such as volatile access or untrackable capture)
-    before the initialization in the function. LoN/HiN are 64-bit ints;
-    negative values are allowed in case a pointer to partway through the
-    allocation is passed to.
+    This attribute indicates that the function initializes the ranges of the
+    pointer parameter's memory, [%p+LoN, %p+HiN): there are no reads, and no
+    special accesses (such as volatile access or untrackable capture) before
+    the initialization write in the function.
 
     This attribute implies that the function initializes and does not read
     before initialization through this pointer argument, even though it may
     read the memory before initialization that the pointer points to, such
     as through other arguments.
 
-    The ``writable`` or ``dereferenceable`` attribute does not imply
+    Note that this attribute does not apply to the unwind edge: the
+    initializing function does not read the pointer before writing to it
+    regardless of unwinding or not, but the memory may not actually be
+    written to when unwinding happens.
+
+    The ``writable`` or ``dereferenceable`` attribute does not imply the
     ``initialized`` attribute, and ``initialized`` does not imply ``writeonly``
-    since cases that read from the pointer after write, can be ``initialized``
-    but not ``writeonly``.
+    since ``initialized`` allows reading from the pointer after writing.
 
-    Note that this attribute does not apply to the unwind edge: the memory may
-    not actually be written to when unwinding happens.
+    This attribute is a list of const ranges in ascending order with no
+    overlapping or adjoining list elements. LoN/HiN are 64-bit ints, and
+    negative values are allowed in case the argument points partway into
+    an allocation.
 
 ``dead_on_unwind``
     At a high level, this attribute indicates that the pointer argument is dead