[llvm] IR: Add prefalign attribute for function definitions. (PR #155527)

[Peter Collingbourne via llvm-commits]

================
@@ -942,11 +944,24 @@ LLVM allows an explicit section to be specified for functions. If the
 target supports it, it will emit functions to the section specified.
 Additionally, the function can be placed in a COMDAT.
 
-An explicit alignment may be specified for a function. If not present,
-or if the alignment is set to zero, the alignment of the function is set
-by the target to whatever it feels convenient. If an explicit alignment
-is specified, the function is forced to have at least that much
-alignment. All alignments must be a power of 2.
+An explicit minimum alignment (``align``) may be specified for a
+function. If not present, or if the alignment is set to zero, the
+alignment of the function is set according to the preferred alignment
+rules described below. If an explicit minimum alignment is specified, the
+function is forced to have at least that much alignment. All alignments
+must be a power of 2.
+
+An explicit preferred alignment (``prefalign``) may also be specified
+for a function (definitions only, and must be a power of 2). If a
+function does not have a preferred alignment attribute, the preferred
+alignment is determined in a target-specific way. The final alignment
+of the function is determined in the following way: if the function
+size is less than the minimum alignment, the function's alignment will
+be at least the minimum alignment. Otherwise, if the function size is
+between the minimum alignment and the preferred alignment, the function's
+alignment will be at least the power of 2 greater than or equal to the
+function size. Otherwise, the function's alignment will be at least the
+preferred alignment.
----------------
pcc wrote:

I wanted this to describe the lower bound on the alignment (because e.g. non-ELF or -fno-function-sections can result in a higher alignment), but yeah, it's probably best just to say that it's a hint; the actual rules are too complex to specify here. Done.

https://github.com/llvm/llvm-project/pull/155527