[UnJ] Document loop metadata

[dmgreen]

Summary

Add some quick words for unroll and jam metadata to the language ref.

[Meinersbur]

llvm.loop.unroll.full.* has a section for each of its options. I think the ideas is so that the table of contents is a list of all recognized names (there is no llvm.loop.unroll_and_jam metadata)

[dmgreen]

Added some extra sections for each of the metadatas. Mostly copied from unroll. Also added details to Passes.rst.

[Meinersbur]

LGTM

docs/LangRef.rst

5181 ↗

(On Diff #156065)

[typo] uroll

5194 ↗

(On Diff #156065)

Did you mean llvm.loop.unroll.count?

5195 ↗

(On Diff #156065)

Did you mean the string llvm.loop.unroll_and_jam.count?

[dmgreen]

Thanks

llvm/trunk/docs/LangRef.rst

 This metadata suggests that the loop should be unrolled fully. The
 metadata has a single operand which is the string ``llvm.loop.unroll.full``.
 For example:
 
 .. code-block:: llvm
 
    !0 = !{!"llvm.loop.unroll.full"}
 
+'``llvm.loop.unroll_and_jam``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata
+above, but affect the unroll and jam pass. In addition any loop with
+``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will
+disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the
+unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam
+too.)
+
+The metadata for unroll and jam otherwise is the same as for ``unroll``.
+``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and
+``llvm.loop.unroll_and_jam.count`` do the same as for unroll.
+``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints
+and the normal safety checks will still be performed.
+
+'``llvm.loop.unroll_and_jam.count``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata suggests an unroll and jam factor to use, similarly to
+``llvm.loop.unroll.count``. The first operand is the string
+``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer
+specifying the unroll factor. For example:
+
+.. code-block:: llvm
+
+   !0 = !{!"llvm.loop.unroll_and_jam.count", i32 4}
+
+If the trip count of the loop is less than the unroll count the loop
+will be partially unroll and jammed.
+
+'``llvm.loop.unroll_and_jam.disable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata disables loop unroll and jamming. The metadata has a single
+operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example:
+
+.. code-block:: llvm
+
+   !0 = !{!"llvm.loop.unroll_and_jam.disable"}
+
+'``llvm.loop.unroll_and_jam.enable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata suggests that the loop should be fully unroll and jammed if the
+trip count is known at compile time and partially unrolled if the trip count is
+not known at compile time. The metadata has a single operand which is the
+string ``llvm.loop.unroll_and_jam.enable``.  For example:
+
+.. code-block:: llvm
+
+   !0 = !{!"llvm.loop.unroll_and_jam.enable"}
+
 '``llvm.loop.licm_versioning.disable``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This metadata indicates that the loop should not be versioned for the purpose
 of enabling loop-invariant code motion (LICM). The metadata has a single operand
 which is the string ``llvm.loop.licm_versioning.disable``. For example:
 
 .. code-block:: llvm

llvm/trunk/docs/Passes.rst

 Yet to be written.
 
 ``-count-aa``: Count Alias Analysis Query Responses
 ---------------------------------------------------
 
 A pass which can be used to count how many alias queries are being made and how
 the alias analysis implementation being used responds.
 
+.. _passes-da:
+
 ``-da``: Dependence Analysis
 ----------------------------
 
 Dependence analysis framework, which is used to detect dependences in memory
 accesses.
 
 ``-debug-aa``: AA use debugger
 ------------------------------

 
 ``-loop-unroll``: Unroll loops
 ------------------------------
 
 This pass implements a simple loop unroller.  It works best when loops have
 been canonicalized by the :ref:`indvars <passes-indvars>` pass, allowing it to
 determine the trip counts of loops easily.
 
+``-loop-unroll-and-jam``: Unroll and Jam loops
+----------------------------------------------
+
+This pass implements a simple unroll and jam classical loop optimisation pass.
+It transforms loop from:
+
+.. code-block:: c++
+
+  for i.. i+= 1              for i.. i+= 4
+    for j..                    for j..
+      code(i, j)                 code(i, j)
+                                 code(i+1, j)
+                                 code(i+2, j)
+                                 code(i+3, j)
+                             remainder loop
+
+Which can be seen as unrolling the outer loop and "jamming" (fusing) the inner
+loops into one. When variables or loads can be shared in the new inner loop, this
+can lead to significant performance improvements. It uses
+:ref:`Dependence Analysis <passes-da>` for proving the transformations are safe.
+
 ``-loop-unswitch``: Unswitch loops
 ----------------------------------
 
 This pass transforms loops that contain branches on loop-invariant conditions
 to have multiple loops.  For example, it turns the left into the right code:
 
 .. code-block:: c++