From 91823932bda4a288a66ef1ba157dbf2e644bfb60 Mon Sep 17 00:00:00 2001
From: David Green <david.green@arm.com>
Date: Thu, 19 Jul 2018 12:37:00 +0000
Subject: [PATCH] [UnJ] Document unroll and jam pass and loop metadata

Add some quick words for unroll and jam to the list of passes and add
unroll_and_jam metadata to the language ref.

Differential Revision: https://reviews.llvm.org/D49349



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@337448 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/LangRef.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/Passes.rst  | 23 +++++++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index 3fa30a2a7a5..df91c91cd31 100644
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -5180,6 +5180,59 @@ For example:
 
    !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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/Passes.rst b/docs/Passes.rst
index 39874e4c8a0..9ab214984d2 100644
--- a/docs/Passes.rst
+++ b/docs/Passes.rst
@@ -83,6 +83,8 @@ Yet to be written.
 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
 ----------------------------
 
@@ -825,6 +827,27 @@ 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
 ----------------------------------
 
-- 
2.11.0