From 2e9c7244b9f46e3396ea0a3475418eae814db742 Mon Sep 17 00:00:00 2001
From: Evan Cheng <evan.cheng@apple.com>
Date: Wed, 14 Dec 2011 21:32:14 +0000
Subject: Add high level description of MachineInstr bundles.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@146589 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/CodeGenerator.html | 83 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

(limited to 'docs')

diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html
index f42af12720..345eb7ced5 100644
--- a/docs/CodeGenerator.html
+++ b/docs/CodeGenerator.html
@@ -50,6 +50,7 @@
     <li><a href="#machinebasicblock">The <tt>MachineBasicBlock</tt>
                                      class</a></li>
     <li><a href="#machinefunction">The <tt>MachineFunction</tt> class</a></li>
+    <li><a href="#machineinstrbundle"><tt>MachineInstr Bundles</tt></a></li>
     </ul>
   </li>
   <li><a href="#mc">The "MC" Layer</a>
@@ -761,6 +762,88 @@ ret
 
 </div>
 
+<!-- ======================================================================= -->
+<h3>
+  <a name="machineinstrbundle"><tt>MachineInstr Bundles</tt></a>
+</h3>
+
+<div>
+
+<p>LLVM code generator can model sequences of instructions as MachineInstr
+   bundles. A MI bundle can model a VLIW group / pack which contains an
+   arbitrary number of parallel instructions. It can also be used to model
+   a sequential list of instructions (potentially with data dependencies) that
+   cannot be legally separated (e.g. ARM Thumb2 IT blocks).</p>
+
+<p>Conceptually a MI bundle is a MI with a number of other MIs nested within:
+</p>
+
+<div class="doc_code">
+<pre>
+--------------
+|   Bundle   | ---------
+--------------          \
+       |           ----------------
+       |           |      MI      |
+       |           ----------------
+       |                   |
+       |           ----------------
+       |           |      MI      |
+       |           ----------------
+       |                   |
+       |           ----------------
+       |           |      MI      |
+       |           ----------------
+       |
+--------------
+|   Bundle   | --------
+--------------         \
+       |           ----------------
+       |           |      MI      |
+       |           ----------------
+       |                   |
+       |           ----------------
+       |           |      MI      |
+       |           ----------------
+       |                   |
+       |                  ...
+       |
+--------------
+|   Bundle   | --------
+--------------         \
+       |
+      ...
+</pre>
+</div>
+
+<p> MI bundle support does not change the physical representations of
+    MachineBasicBlock and MachineInstr. All the MIs (including top level and
+    nested ones) are stored as sequential list of MIs. The "bundled" MIs are
+    marked with the 'InsideBundle' flag. A top level MI with the special BUNDLE
+    opcode is used to represent the start of a bundle. It's legal to mix BUNDLE
+    MIs with indiviual MIs that are not inside bundles nor represent bundles.
+</p>
+
+<p> MachineInstr passes should operate on a MI bundle as a single unit. Member
+    methods have been taught to correctly handle bundles and MIs inside bundles.
+    The MachineBasicBlock iterator has been modified to skip over bundled MIs to
+    enforce the bundle-as-a-single-unit concept. An alternative iterator
+    instr_iterator has been added to MachineBasicBlock to allow passes to
+    iterate over all of the MIs in a MachineBasicBlock, including those which
+    are nested inside bundles. The top level BUNDLE instruction must have the
+    correct set of register MachineOperand's that represent the cumulative
+    inputs and outputs of the bundled MIs.</p>
+
+<p> Packing / bundling of MachineInstr's should be done as part of the register
+    allocation super-pass. More specifically, the pass which determines what
+    MIs should be bundled together must be done after code generator exits SSA
+    form (i.e. after two-address pass, PHI elimination, and copy coalescing).
+    Bundles should only be finalized (i.e. adding BUNDLE MIs and input and
+    output register MachineOperands) after virtual registers have been
+    rewritten into physical registers. This requirement eliminates the need to
+    add virtual register operands to BUNDLE instructions which would effectively
+    double the virtual register def and use lists.</p>
+
 </div>
 
 <!-- *********************************************************************** -->
-- 
cgit v1.2.3-18-g5258