Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikic merged 4 commits into from
Jul 16, 2025
Merged

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

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f583014
[LangRef] Document the difference between `<abi>` and `<pref>`
tgross35 Jul 10, 2025
d2d1234
Be more specific about what abi does
tgross35 Jul 10, 2025
25d3736
Revert to existing list wording
tgross35 Jul 13, 2025
769a387
Describe where `pref` is used, rewrap to 80
tgross35 Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions llvm/docs/LangRef.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3240,12 +3240,23 @@ 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
Copy link
Contributor

@nikic nikic Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.
  • ...

Copy link
Contributor Author

@tgross35 tgross35 Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

@efriedma-quic efriedma-quic Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@tgross35 tgross35 Jul 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to mention this

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, 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
Expand All @@ -3261,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 ABI alignment of 32-bits but preferred
alignment of 64-bits
- ``i64:32:64`` - i64 is aligned at 32-bits but should be aligned to
Copy link
Contributor

@nikic nikic Jul 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd keep the old wording here.

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
Expand Down
Loading