[LangRef] state that align assume op bundle may take an extra argument

[aqjune]

Summary

As discussed in D90529, this patch adds statements about "align"(i8* ptr, i64 a, i64 b).

Besides this, small non-functional edits are added:

• Small edits to assume op bundle's lexical grammar
• A clarification that align/nonnull also raises UB
• etc

[aqjune]

update

[jdoerfert]

I like the additions. Some suggestions inlinined. TBH, the fact that we now have "multiple kinds of arguments" is confusing.
If you agree, maybe we should speak of "operand bundle tag and modifiers" or "operand bundle elements" throughout.

llvm/docs/LangRef.rst

2252

2268–2269

2279–2286

[aqjune]

Address comments, minor update to the grammar

[aqjune]

update

[aqjune]

the fact that we now have "multiple kinds of arguments" is confusing.

I think it seems okay - the first argument being the value to hold and other arguments being the values passed to the attribute seems clear and explicit.
Unless there exists a case that does not fit in this rule, it looks good.

[aqjune]

gently ping

[Tyker]

seems good to me. but maybe other still have comments.

llvm/docs/LangRef.rst

 :ref:`function attribute <fnattrs>` holds for a certain value at a certain
 location. Operand bundles enable assumptions that are either hard or impossible
 to represent as a boolean argument of an :ref:`llvm.assume <int_assume>`.
 
 An assume operand bundle has the form:
 
 ::
 
-      "<tag>"([ <holds for value> [, <attribute argument>] ])
+      "<tag>"(<ty> <holds for value>{, <ty> <attribute argument>}*)
 
 * The tag of the operand bundle is usually the name of attribute that can be
   assumed to hold. It can also be `ignore`, this tag doesn't contain any
   information and should be ignored.
 * The first argument if present is the value for which the attribute hold.
-* The second argument if present is an argument of the attribute.
-
   If there are no arguments the attribute is a property of the call location.
+* The following argument(s) if present is argument(s) of the attribute.
 
-If the represented attribute expects a constant argument, the argument provided
-to the operand bundle should be a constant as well.
-
-For example:
+Just like for the argument of :ref:`llvm.assume <int_assume>`, if any of the
+provided guarantees are violated at runtime the behavior is undefined.
+This also applies to attributes whose violation in a function call is defined
+to yield poison, such as ``"nonnull"`` and ``"align"``.
+For example,
 
 .. code-block:: llvm
 
       call void @llvm.assume(i1 true) ["align"(i32* %val, i32 8)]
 
 allows the optimizer to assume that at location of call to
-:ref:`llvm.assume <int_assume>` ``%val`` has an alignment of at least 8.
+:ref:`llvm.assume <int_assume>` ``%val`` has an alignment of at least 8
+because it is otherwise undefined behavior.
+
+:ref:`llvm.assume <int_assume>`'s condition still has an effect even if
+operand bundles exist. For example,
 
 .. code-block:: llvm
 
       call void @llvm.assume(i1 %cond) ["cold"(), "nonnull"(i64* %val)]
 
-allows the optimizer to assume that the :ref:`llvm.assume <int_assume>`
-call location is cold and that ``%val`` may not be null.
+allows the optimizer to assume that ``%cond`` is true,
+the :ref:`llvm.assume <int_assume>` call location is cold, and ``%val`` is not
+null.
+
+``"align"`` optionally takes a second argument.
+``"align"(i8* ptr, i64 a, i64 ofs)`` is equivalent to GCC's
+``__builtin_assume_aligned(ptr, a, ofs)`` and states that ``ptr - ofs`` is
+``a``-bytes aligned.
 
-Just like for the argument of :ref:`llvm.assume <int_assume>`, if any of the
-provided guarantees are violated at runtime the behavior is undefined.
+If the represented attribute expects a constant argument, the argument provided
+to the operand bundle should be a constant as well.
+For example, ``"align"`` can only take a constant as its attribute argument.
 
 Even if the assumed property can be encoded as a boolean value, like
 ``nonnull``, using operand bundles to express the property can still have
 benefits:
 
 * Attributes that can be expressed via operand bundles are directly the
   property that the optimizer uses and cares about. Encoding attributes as
   operand bundles removes the need for an instruction sequence that represents