[PATCH] D74209: [AssumeBundle] Add documentation for assume operand bundles

[Tyker via Phabricator via llvm-commits]

Tyker created this revision.
Tyker added reviewers: jdoerfert, fhahn.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

sorry ahead of time for all the typos.


https://reviews.llvm.org/D74209

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -2102,6 +2102,51 @@
 generated code.  For more details, see :ref:`GC Transitions
 <gc_transition_args>`.
 
+.. _assume_opbundles:
+
+Assume Operand Bundles
+^^^^^^^^^^^^^^^^^^^^^^
+
+Operand bundles on an :ref:`llvm.assume <int_assume>` allows representing
+assumptions that an attribute holds for a certain value at a certain position.
+This allows representing assumptions that are either hard or not possible to
+represent via a boolean check.
+
+* The tag of the operand bundle is the attribute that can be assumed to hold.
+* 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 is no arguments the attribute is a property of the path
+
+For example:
+
+.. code-block:: llvm
+
+      call void @llvm.assume(i1 true) ["align"(i32* %val, i32 8)]
+
+allows the optimizer to assume that ``%val`` has an alignment of at least 8
+at this point 
+
+.. code-block:: llvm
+
+      call void @llvm.assume(i1 true) ["cold"()]
+
+allows the optimizer to assume that the path is cold.
+
+If the provided guarantee is incorrect the behavior is undefined.
+
+Even if the property can be represented as a boolean property like ``nonnull``.
+Using operand bundles to express the property still have benefits:
+
+* Attributes that can be expressed via operand bundles are directly the
+  property that the optimizer uses and cares about. So the optimizer doesn't
+  need to deduce the property from an arbitrary expression. The optimizer may
+  not have every canonicalizations to deduce the property from any arbitrary
+  expressions that check the property.
+* Expressing the property using operand bundles make detecting that the value
+  is used in an :ref:`llvm.assume <int_assume>` easier. Which can minimize the
+  impact of adding a use to the value.
+
 .. _moduleasm:
 
 Module-Level Inline Assembly
@@ -17532,10 +17577,14 @@
 condition is true. This information can then be used in simplifying other parts
 of the code.
 
+For operand bundles on an ``llvm.assume`` see
+:ref:`assume operand bundles <assume_opbundles>`.
+
 Arguments:
 """"""""""
 
-The condition which the optimizer may assume is always true.
+The argument of the call is the condition which the optimizer may assume is
+always true.
 
 Semantics:
 """"""""""


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D74209.243122.patch
Type: text/x-patch
Size: 2475 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200207/1ad3c800/attachment.bin>