[llvm] [LangRef] Document the difference between `<abi>` and `<pref>` (PR #147929)

[Trevor Gross via llvm-commits]

https://github.com/tgross35 updated https://github.com/llvm/llvm-project/pull/147929

>From f583014b5a5831b7225159b3e85b4604e6962af7 Mon Sep 17 00:00:00 2001
From: Trevor Gross <tmgross at umich.edu>
Date: Thu, 10 Jul 2025 05:52:50 -0400
Subject: [PATCH 1/3] [LangRef] Document the difference between `<abi>` and
 `<pref>`

Document how LLVM expects to use `<abi>` and `<pref>`, as well as the
`pref >= abi` requirement.
---
 llvm/docs/LangRef.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index d2a1821efd698..063f17896455d 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3240,12 +3240,15 @@ as follows:
     as :ref:`Non-Integral Pointer Type <nointptrtype>` s.  The ``0``
     address space cannot be specified as non-integral.
 
+``<abi>`` provides a minimum allowed alignment for a type, and
+``<pref>`` allows providing a more optimal alignment that should be used
+when possible. ``<pref>`` is an optional value that must be greater than
+or equal to ``<abi>``. If omitted, the preceding ``:`` should also be
+omitted and ``<pref>`` will be equal to ``<abi>``.
+
 Unless explicitly stated otherwise, on every specification that specifies
 an alignment, the value of the alignment must be in the range [1,2^16)
 and must be a power of two times the width of a byte.
-On every specification that takes a ``<abi>:<pref>``, specifying the
-``<pref>`` alignment is optional. If omitted, the preceding ``:``
-should be omitted too and ``<pref>`` will be equal to ``<abi>``.
 
 When constructing the data layout for a given target, LLVM starts with a
 default set of specifications which are then (possibly) overridden by
@@ -3261,8 +3264,8 @@ specifications are given in this list:
 -  ``i8:8:8`` - i8 is 8-bit (byte) aligned as mandated
 -  ``i16:16:16`` - i16 is 16-bit aligned
 -  ``i32:32:32`` - i32 is 32-bit aligned
--  ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
-   alignment of 64-bits
+-  ``i64:32:64`` - i64 has a required alignment of 32-bits but should be
+   aligned to 64-bits if possible.
 -  ``f16:16:16`` - half is 16-bit aligned
 -  ``f32:32:32`` - float is 32-bit aligned
 -  ``f64:64:64`` - double is 64-bit aligned

>From d2d1234c271572d35afb22f7b12282530355fc56 Mon Sep 17 00:00:00 2001
From: Trevor Gross <tgross at intrepidcs.com>
Date: Thu, 10 Jul 2025 19:53:55 -0400
Subject: [PATCH 2/3] Be more specific about what abi does

---
 llvm/docs/LangRef.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 063f17896455d..4fe965def11d4 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3240,15 +3240,23 @@ as follows:
     as :ref:`Non-Integral Pointer Type <nointptrtype>` s.  The ``0``
     address space cannot be specified as non-integral.
 
-``<abi>`` provides a minimum allowed alignment for a type, and
+``<abi>`` is a lower bound on what is required for a type to be
+considered aligned. This is used in various places, such as:
+
+- The alignment for loads and stores if none is explicitly given.
+- The alignment used to compute struct layout.
+- The alignment used to compute allocation sizes and thus
+  ``getelementptr`` offsets.
+- The alignment below which accesses are considered underaligned.
+
 ``<pref>`` allows providing a more optimal alignment that should be used
 when possible. ``<pref>`` is an optional value that must be greater than
 or equal to ``<abi>``. If omitted, the preceding ``:`` should also be
 omitted and ``<pref>`` will be equal to ``<abi>``.
 
-Unless explicitly stated otherwise, on every specification that specifies
-an alignment, the value of the alignment must be in the range [1,2^16)
-and must be a power of two times the width of a byte.
+Unless explicitly stated otherwise, every alignment specification is
+provided in bits and must be in the range [1,2^16). The value must be a
+power of times the width of a byte (i.e. ``align = 8 * 2^N``).
 
 When constructing the data layout for a given target, LLVM starts with a
 default set of specifications which are then (possibly) overridden by
@@ -3264,8 +3272,8 @@ specifications are given in this list:
 -  ``i8:8:8`` - i8 is 8-bit (byte) aligned as mandated
 -  ``i16:16:16`` - i16 is 16-bit aligned
 -  ``i32:32:32`` - i32 is 32-bit aligned
--  ``i64:32:64`` - i64 has a required alignment of 32-bits but should be
-   aligned to 64-bits if possible.
+-  ``i64:32:64`` - i64 is aligned at 32-bits but should be aligned to
+   64-bits if possible.
 -  ``f16:16:16`` - half is 16-bit aligned
 -  ``f32:32:32`` - float is 32-bit aligned
 -  ``f64:64:64`` - double is 64-bit aligned

>From 25d3736b3177bf9a37aacb60c80958bd3070d15c Mon Sep 17 00:00:00 2001
From: Trevor Gross <tmgross at umich.edu>
Date: Sun, 13 Jul 2025 14:30:33 -0400
Subject: [PATCH 3/3] Revert to existing list wording

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

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 4fe965def11d4..4ba52f66761a9 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3272,8 +3272,8 @@ specifications are given in this list:
 -  ``i8:8:8`` - i8 is 8-bit (byte) aligned as mandated
 -  ``i16:16:16`` - i16 is 16-bit aligned
 -  ``i32:32:32`` - i32 is 32-bit aligned
--  ``i64:32:64`` - i64 is aligned at 32-bits but should be aligned to
-   64-bits if possible.
+-  ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
+   alignment of 64-bits
 -  ``f16:16:16`` - half is 16-bit aligned
 -  ``f32:32:32`` - float is 32-bit aligned
 -  ``f64:64:64`` - double is 64-bit aligned