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

[via llvm-commits]

Author: Trevor Gross
Date: 2025-07-16T18:04:53+02:00
New Revision: 78b9128250c9fe5c7f9e460a27cc28c6450fd8fd

URL: https://github.com/llvm/llvm-project/commit/78b9128250c9fe5c7f9e460a27cc28c6450fd8fd
DIFF: https://github.com/llvm/llvm-project/commit/78b9128250c9fe5c7f9e460a27cc28c6450fd8fd.diff

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

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

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index a5a5070a43a36..2759e18301d58 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3240,12 +3240,24 @@ as follows:
     as :ref:`Non-Integral Pointer Type <nointptrtype>` s.  The ``0``
     address space cannot be specified as non-integral.
 
-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>``.
+``<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, primarily for ``alloca`` and the alignment of global variables. It 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, every alignment specification is provided in
+bits and must be in the range [1,2^16). The value must be a power of two 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