[llvm] [LangRef/DataLayout] Spell out requirements for alignment values (PR #104705)
Sergei Barannikov via llvm-commits
llvm-commits at lists.llvm.org
Sun Aug 18 08:14:36 PDT 2024
https://github.com/s-barannikov updated https://github.com/llvm/llvm-project/pull/104705
>From 7c8791337aeb57e0e457079ecac949422c6e9f69 Mon Sep 17 00:00:00 2001
From: Sergei Barannikov <barannikov88 at gmail.com>
Date: Thu, 15 Aug 2024 23:16:55 +0300
Subject: [PATCH 1/5] [LangRef/DataLayout] Spell out requirements for alignment
values
For 'p' the added wording matches the implementation.
For 'i', 'f', 'v' the implementation also allows 0 for <pref> component,
making 'i16:16:0' valid, for example. 'Fi0', 'Fn0' and 'S0' are also
currently accepted. This is likely unintentional. There are no tests
in the codebase that rely on this behavior, so the added wording
prohibits zero alignments for these specifications.
For 'a', the implementation currently allows 0 for both <abi> and <pref>
components. The added wording prohibits specifying zero for <pref>
with the same justification as above. Zero <abi> is used in tests,
and the example at the end of the section suggests that this is valid,
so that is left unchanged.
This effectively prohibits zero alignments everywhere except for
the <abi> component of aggregate specification.
---
llvm/docs/LangRef.rst | 19 +++++++++++++++++--
1 file changed, 17 insertions(+), 2 deletions(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 5e5e9b9e8a93b1..ea4fb6030161aa 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3030,8 +3030,10 @@ as follows:
``S<size>``
Specifies the natural alignment of the stack in bits. Alignment
promotion of stack variables is limited to the natural stack
- alignment to avoid dynamic stack realignment. The stack alignment
- must be a multiple of 8-bits. If omitted, the natural stack
+ alignment to avoid dynamic stack realignment.
+ The stack alignment must be must be in the range [1,2^16)
+ and must be a power of two times the byte width.
+ If omitted, the natural stack
alignment defaults to "unspecified", which does not prevent any
alignment promotions.
``P<address space>``
@@ -3065,16 +3067,22 @@ as follows:
are in bits. The address space, ``n``, is optional, and if not specified,
denotes the default address space 0. The value of ``n`` must be
in the range [1,2^24).
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
``i<size>:<abi>[:<pref>]``
This specifies the alignment for an integer type of a given bit
``<size>``. The value of ``<size>`` must be in the range [1,2^24).
``<pref>`` is optional and defaults to ``<abi>``.
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
For ``i8``, the ``<abi>`` value must equal 8,
that is, ``i8`` must be naturally aligned.
``v<size>:<abi>[:<pref>]``
This specifies the alignment for a vector type of a given bit
``<size>``. The value of ``<size>`` must be in the range [1,2^24).
``<pref>`` is optional and defaults to ``<abi>``.
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
``f<size>:<abi>[:<pref>]``
This specifies the alignment for a floating-point type of a given bit
``<size>``. Only values of ``<size>`` that are supported by the target
@@ -3082,9 +3090,14 @@ as follows:
or 128 (different flavors of long double) are also supported on some
targets. The value of ``<size>`` must be in the range [1,2^24).
``<pref>`` is optional and defaults to ``<abi>``.
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
``a:<abi>[:<pref>]``
This specifies the alignment for an object of aggregate type.
``<pref>`` is optional and defaults to ``<abi>``.
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
+ The value of ``<<abi>>` may also be zero meaning one byte alignment.
``F<type><abi>``
This specifies the alignment for function pointers.
The options for ``<type>`` are:
@@ -3093,6 +3106,8 @@ as follows:
of functions, and is a multiple of ``<abi>``.
* ``n``: The alignment of function pointers is a multiple of the explicit
alignment specified on the function, and is a multiple of ``<abi>``.
+ The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
+ and must be powers of two times the byte width.
``m:<mangling>``
If present, specifies that llvm names are mangled in the output. Symbols
prefixed with the mangling escape character ``\01`` are passed through
>From b5150ad054011cb56b5c7e2e0a7d0a149dfb4527 Mon Sep 17 00:00:00 2001
From: Sergei Barannikov <barannikov88 at gmail.com>
Date: Sun, 18 Aug 2024 16:37:35 +0300
Subject: [PATCH 2/5] fix typo
---
llvm/docs/LangRef.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index ea4fb6030161aa..16ddd9b2a3720d 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3097,7 +3097,7 @@ as follows:
``<pref>`` is optional and defaults to ``<abi>``.
The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
and must be powers of two times the byte width.
- The value of ``<<abi>>` may also be zero meaning one byte alignment.
+ The value of ``<abi>`` may also be zero meaning one byte alignment.
``F<type><abi>``
This specifies the alignment for function pointers.
The options for ``<type>`` are:
>From 416c78cd55eea79702795d48eee669cc1de4719b Mon Sep 17 00:00:00 2001
From: Sergei Barannikov <barannikov88 at gmail.com>
Date: Sun, 18 Aug 2024 16:47:57 +0300
Subject: [PATCH 3/5] Try to fix CI error
---
llvm/docs/LangRef.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 16ddd9b2a3720d..665d312012e5d2 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3106,6 +3106,7 @@ as follows:
of functions, and is a multiple of ``<abi>``.
* ``n``: The alignment of function pointers is a multiple of the explicit
alignment specified on the function, and is a multiple of ``<abi>``.
+
The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
and must be powers of two times the byte width.
``m:<mangling>``
>From 2ffb292dcbe6bd9740c70796004c53f4d8b0b2a0 Mon Sep 17 00:00:00 2001
From: Sergei Barannikov <barannikov88 at gmail.com>
Date: Sun, 18 Aug 2024 17:52:35 +0300
Subject: [PATCH 4/5] Avoid text duplication
---
llvm/docs/LangRef.rst | 32 ++++++++------------------------
1 file changed, 8 insertions(+), 24 deletions(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 665d312012e5d2..557df8a8f562ed 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3030,10 +3030,7 @@ as follows:
``S<size>``
Specifies the natural alignment of the stack in bits. Alignment
promotion of stack variables is limited to the natural stack
- alignment to avoid dynamic stack realignment.
- The stack alignment must be must be in the range [1,2^16)
- and must be a power of two times the byte width.
- If omitted, the natural stack
+ alignment to avoid dynamic stack realignment. If omitted, the natural stack
alignment defaults to "unspecified", which does not prevent any
alignment promotions.
``P<address space>``
@@ -3059,45 +3056,32 @@ as follows:
Defaults to the default address space of 0.
``p[n]:<size>:<abi>[:<pref>][:<idx>]``
This specifies the *size* of a pointer and its ``<abi>`` and
- ``<pref>``\erred alignments for address space ``n``. ``<pref>`` is optional
- and defaults to ``<abi>``. The fourth parameter ``<idx>`` is the size of the
+ ``<pref>``\erred alignments for address space ``n``.
+ The fourth parameter ``<idx>`` is the size of the
index that used for address calculation, which must be less than or equal
to the pointer size. If not
specified, the default index size is equal to the pointer size. All sizes
are in bits. The address space, ``n``, is optional, and if not specified,
denotes the default address space 0. The value of ``n`` must be
in the range [1,2^24).
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
``i<size>:<abi>[:<pref>]``
This specifies the alignment for an integer type of a given bit
``<size>``. The value of ``<size>`` must be in the range [1,2^24).
- ``<pref>`` is optional and defaults to ``<abi>``.
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
For ``i8``, the ``<abi>`` value must equal 8,
that is, ``i8`` must be naturally aligned.
``v<size>:<abi>[:<pref>]``
This specifies the alignment for a vector type of a given bit
``<size>``. The value of ``<size>`` must be in the range [1,2^24).
- ``<pref>`` is optional and defaults to ``<abi>``.
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
``f<size>:<abi>[:<pref>]``
This specifies the alignment for a floating-point type of a given bit
``<size>``. Only values of ``<size>`` that are supported by the target
will work. 32 (float) and 64 (double) are supported on all targets; 80
or 128 (different flavors of long double) are also supported on some
targets. The value of ``<size>`` must be in the range [1,2^24).
- ``<pref>`` is optional and defaults to ``<abi>``.
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
``a:<abi>[:<pref>]``
This specifies the alignment for an object of aggregate type.
- ``<pref>`` is optional and defaults to ``<abi>``.
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
- The value of ``<abi>`` may also be zero meaning one byte alignment.
+ In addition to the usual requirements for alignment values,
+ the value of ``<abi>`` may also be zero meaning one byte alignment.
``F<type><abi>``
This specifies the alignment for function pointers.
The options for ``<type>`` are:
@@ -3106,9 +3090,6 @@ as follows:
of functions, and is a multiple of ``<abi>``.
* ``n``: The alignment of function pointers is a multiple of the explicit
alignment specified on the function, and is a multiple of ``<abi>``.
-
- The values of ``<abi>`` and ``<pref>`` must be in the range [1,2^16)
- and must be powers of two times the byte width.
``m:<mangling>``
If present, specifies that llvm names are mangled in the output. Symbols
prefixed with the mangling escape character ``\01`` are passed through
@@ -3139,6 +3120,9 @@ 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>``.
>From 27a55a45395a9835e7017d76d60a52da309ec8b4 Mon Sep 17 00:00:00 2001
From: Sergei Barannikov <barannikov88 at gmail.com>
Date: Sun, 18 Aug 2024 18:14:23 +0300
Subject: [PATCH 5/5] Minor wording change
---
llvm/docs/LangRef.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 557df8a8f562ed..ffc0259060ea27 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3081,7 +3081,7 @@ as follows:
``a:<abi>[:<pref>]``
This specifies the alignment for an object of aggregate type.
In addition to the usual requirements for alignment values,
- the value of ``<abi>`` may also be zero meaning one byte alignment.
+ the value of ``<abi>`` can also be zero, which means one byte alignment.
``F<type><abi>``
This specifies the alignment for function pointers.
The options for ``<type>`` are:
More information about the llvm-commits
mailing list