[LangRef] Document the difference between <abi> and <pref>

[tgross35]

Document how LLVM expects to use <abi> and <pref>, as well as the pref >= abi requirement.

[llvmbot]

@llvm/pr-subscribers-llvm-ir

Author: Trevor Gross (tgross35)

Changes

Document how LLVM expects to use <abi> and <pref>, as well as the pref >= abi requirement.

---

Full diff: https://github.com/llvm/llvm-project/pull/147929.diff

1 Files Affected:

• (modified) llvm/docs/LangRef.rst (+8-5)

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

[nikic]

"minimum allowed alignment" isn't really accurate in that you can use lower alignments, they'll just be considered unaligned.

The ABI alignment is used in various places:

• The default alignment for loads and stores when no explicit alignment is given in textual IR.
• 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.
• ...

[tgross35]

I'll update to mention this. Are there any more specific cases of pref that should be mentioned?

[efriedma-quic]

"pref" align is primarily used for allocas and global variables.

[tgross35]

Updated to mention this

[nikic]

I'd keep the old wording here.

[nikic]

LGTM