From 49e41c517966af290a6115bbc57878f1033ad1e9 Mon Sep 17 00:00:00 2001
From: Dan Gohman <gohman@apple.com>
Date: Wed, 15 Dec 2010 18:45:20 +0000
Subject: Document some more AliasAnalysis infrastructure limitations.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@121874 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/AliasAnalysis.html | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/AliasAnalysis.html b/docs/AliasAnalysis.html
index 8fbb29f..7610f8b 100644
--- a/docs/AliasAnalysis.html
+++ b/docs/AliasAnalysis.html
@@ -31,7 +31,7 @@
     <li><a href="#chaining"><tt>AliasAnalysis</tt> chaining behavior</a></li>
     <li><a href="#updating">Updating analysis results for transformations</a></li>
     <li><a href="#implefficiency">Efficiency Issues</a></li>
-    <li><a href="#passmanager">Pass Manager Issues</a></li>
+    <li><a href="#limitations">Limtations</a></li>
     </ul>
   </li>
 
@@ -523,13 +523,13 @@ method as possible (within reason).</p>
 
 <!-- ======================================================================= -->
 <div class="doc_subsection">
-  <a name="passmanager">Pass Manager Issues</a>
+  <a name="limitations">Limitations</a>
 </div>
 
 <div class="doc_text">
 
-<p>PassManager support for alternative AliasAnalysis implementation
-has some issues.</p>
+<p>The AliasAnalysis infrastructure has several limitations which make
+writing a new <tt>AliasAnalysis</tt> implementation difficult.</p>
 
 <p>There is no way to override the default alias analysis. It would
 be very useful to be able to do something like "opt -my-aa -O2" and
@@ -558,6 +558,40 @@ silently route alias analysis queries directly to
 passes between each pass, which prevents the use of <tt>FunctionPass</tt>
 alias analysis passes.</p>
 
+<p>The <tt>AliasAnalysis</tt> API does have functions for notifying
+implementations when values are deleted or copied, however these
+aren't sufficient. There are many other ways that LLVM IR can be
+modified which could be relevant to <tt>AliasAnalysis</tt>
+implementations which can not be expressed.</p>
+
+<p>The <tt>AliasAnalysisDebugger</tt> utility seems to suggest that
+<tt>AliasAnalysis</tt> implementations can expect that they will be
+informed of any relevant <tt>Value</tt> before it appears in an
+alias query. However, popular clients such as <tt>GVN</tt> don't
+support this, and are known to trigger errors when run with the
+<tt>AliasAnalysisDebugger</tt>.</p>
+
+<p>Due to several of the above limitations, the most obvious use for
+the <tt>AliasAnalysisCounter</tt> utility, collecting stats on all
+alias queries in a compilation, doesn't work, even if the
+<tt>AliasAnalysis</tt> implementations don't use <tt>FunctionPass</tt>.
+There's no way to set a default, much less a default sequence,
+and there's no way to preserve it.</p>
+
+<p>The <tt>AliasSetTracker</tt> class (which is used by <tt>LICM</tt>
+makes a non-deterministic number of alias queries. This can cause stats
+collected by <tt>AliasAnalysisCounter</tt> to have fluctuations among
+identical runs, for example. Another consequence is that debugging
+techniques involving pausing execution after a predetermined number
+of queries can be unreliable.</p>
+
+<p>Many alias queries can be reformulated in terms of other alias
+queries. When multiple <tt>AliasAnalysis</tt> queries are chained together,
+it would make sense to start those queries from the beginning of the chain,
+with care taken to avoid infinite looping, however currently an
+implementation which wants to do this can only start such queries
+from itself.</p>
+
 </div>
 
 <!-- *********************************************************************** -->
-- 
cgit v1.1