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
merged 4 commits into from
Jul 16, 2025
Merged

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

Changes from all 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
24 changes: 18 additions & 6 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,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
Copy link
Contributor

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

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

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

Choose a reason for hiding this comment

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

Updated to mention this

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