From c289d4b13d5cf2f90bf368af4db74eb2b7220a29 Mon Sep 17 00:00:00 2001
From: Chris Lattner
Date: Sat, 3 Nov 2007 22:22:30 +0000
Subject: [PATCH] finish the 'Memory in LLVM' section
llvm-svn: 43667
---
docs/tutorial/LangImpl7.html | 60 +++++++++++++++++++++++++++++++-----
1 file changed, 53 insertions(+), 7 deletions(-)
diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html
index f80c0673fdd..ca0d2f06e03 100644
--- a/docs/tutorial/LangImpl7.html
+++ b/docs/tutorial/LangImpl7.html
@@ -238,17 +238,63 @@ cond_next:
ret i32 %X.01
}
+
-The mem2reg pass is guaranteed to work, and
+
The mem2reg pass implements the standard "iterated dominator frontier"
+algorithm for constructing SSA form and has a number of optimizations that speed
+up very common degenerate cases. mem2reg really is the answer for dealing with
+mutable variables, and we highly recommend that you depend on it. Note that
+mem2reg only works on variables in certain circumstances:
-which cases.
-
+
+- mem2reg is alloca-driven: it looks for allocas and if it can handle them, it
+promotes them. It does not apply to global variables or heap allocations.
-The final question you may be asking is: should I bother with this nonsense
-for my front-end? Wouldn't it be better if I just did SSA construction
-directly, avoiding use of the mem2reg optimization pass?
+
- mem2reg only looks for alloca instructions in the entry block of the
+function. Being in the entry block guarantees that the alloca is only executed
+once, which makes analysis simpler.
-Proven, well tested, debug info, etc.
+- mem2reg only promotes allocas whose uses are direct loads and stores. If
+the address of the stack object is passed to a function, or if any funny pointer
+arithmetic is involved, the alloca will not be promoted.
+
+- mem2reg only works on allocas of scalar values, and only if the array size
+of the allocation is 1 (or missing in the .ll file). mem2reg is not capable of
+promoting structs or arrays to registers. Note that the "scalarrepl" pass is
+more powerful and can promote structs, "unions", and arrays in many cases.
+
+
+
+
+All of these properties are easy to satisfy for most imperative languages, and
+we'll illustrated this below with Kaleidoscope. The final question you may be
+asking is: should I bother with this nonsense for my front-end? Wouldn't it be
+better if I just did SSA construction directly, avoiding use of the mem2reg
+optimization pass? In short, we strongly recommend that use you this technique
+for building SSA form, unless there is an extremely good reason not to. Using
+this technique is:
+
+
+- Proven and well tested: llvm-gcc and clang both use this technique for local
+mutable variables. As such, the most common clients of LLVM are using this to
+handle a bulk of their variables. You can be sure that bugs are found fast and
+fixed early.
+
+- Extremely Fast: mem2reg has a number of special cases that make it fast in
+common cases as well as fully general. For example, it has fast-paths for
+variables that are only used in a single block, variables that only have one
+assignment point, good heuristics to avoid insertion of unneeded phi nodes, etc.
+
+
+- Needed for debug info generation:
+Debug information in LLVM relies on having the address of the variable
+exposed to attach debug info to it. This technique dovetails very naturally
+with this style of debug info.
+
+
+If nothing else, this makes it much easier to get your front-end up and
+running, and is very simple to implement. Lets extend Kaleidoscope with mutable
+variables now!