From f583014b5a5831b7225159b3e85b4604e6962af7 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Thu, 10 Jul 2025 05:52:50 -0400 Subject: [PATCH 1/4] [LangRef] Document the difference between `` and `` Document how LLVM expects to use `` and ``, 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 ` s. The ``0`` address space cannot be specified as non-integral. +```` provides a minimum allowed alignment for a type, and +```` allows providing a more optimal alignment that should be used +when possible. ```` is an optional value that must be greater than +or equal to ````. If omitted, the preceding ``:`` should also be +omitted and ```` will be equal to ````. + 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 ``:``, specifying the -```` alignment is optional. If omitted, the preceding ``:`` -should be omitted too and ```` will be equal to ````. 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 Date: Thu, 10 Jul 2025 19:53:55 -0400 Subject: [PATCH 2/4] 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 ` s. The ``0`` address space cannot be specified as non-integral. -```` provides a minimum allowed alignment for a type, and +```` 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. + ```` allows providing a more optimal alignment that should be used when possible. ```` is an optional value that must be greater than or equal to ````. If omitted, the preceding ``:`` should also be omitted and ```` will be equal to ````. -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 Date: Sun, 13 Jul 2025 14:30:33 -0400 Subject: [PATCH 3/4] 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 From 769a3872c4eae235ad0f247cd1a2354dd2fd235e Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 14 Jul 2025 20:07:38 -0400 Subject: [PATCH 4/4] Describe where `pref` is used, rewrap to 80 --- llvm/docs/LangRef.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 4ba52f66761a9..5e0f0014870aa 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -3240,23 +3240,24 @@ as follows: as :ref:`Non-Integral Pointer Type ` s. The ``0`` address space cannot be specified as non-integral. -```` is a lower bound on what is required for a type to be -considered aligned. This is used in various places, such as: +```` 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 used to compute allocation sizes and thus ``getelementptr`` + offsets. - The alignment below which accesses are considered underaligned. -```` allows providing a more optimal alignment that should be used -when possible. ```` is an optional value that must be greater than -or equal to ````. If omitted, the preceding ``:`` should also be -omitted and ```` will be equal to ````. +```` 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 ````. If omitted, +the preceding ``:`` should also be omitted and ```` will be equal to +````. -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``). +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