[llvm] ac994f8 - [MemorySSA] Document details regarding MemorySSA's precision.

[Alina Sbirlea via llvm-commits]

Author: Alina Sbirlea
Date: 2021-12-13T16:49:24-08:00
New Revision: ac994f831cb7ec7f589d13ef4be53c53b9102899

URL: https://github.com/llvm/llvm-project/commit/ac994f831cb7ec7f589d13ef4be53c53b9102899
DIFF: https://github.com/llvm/llvm-project/commit/ac994f831cb7ec7f589d13ef4be53c53b9102899.diff

LOG: [MemorySSA] Document details regarding MemorySSA's precision.

Added: 
    

Modified: 
    llvm/docs/MemorySSA.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/MemorySSA.rst b/llvm/docs/MemorySSA.rst
index b5c2bad975573..b8e8af7b3c67b 100644
--- a/llvm/docs/MemorySSA.rst
+++ b/llvm/docs/MemorySSA.rst
@@ -399,6 +399,29 @@ have to query something to disambiguate further anyway.
 
 As a result, LLVM partitions to one variable.
 
+Precision in practice
+^^^^^^^^^^^^^^^^^^^^^
+
+In practice, there are implementation details in LLVM that also affect the
+results' precision provided by MemorySSA. For example, AliasAnalysis has various
+caps, or restrictions on looking through phis which can affect what MemorySSA
+can infer. Changes made by 
diff erent passes may make MemorySSA either "overly
+optimized" (it can provide a more acccurate result than if it were recomputed
+from scratch), or "under optimized" (it could infer more if it were recomputed).
+This can lead to challenges to reproduced results in isolation with a single pass
+when the result relies on the state aquired by MemorySSA due to being updated by
+multiple subsequent passes.
+Passes that use and update MemorySSA should do so through the APIs provided by the
+MemorySSAUpdater, or through calls on the Walker.
+Direct optimizations to MemorySSA are not permitted.
+There is currently a single, narrowly scoped exception where DSE (DeadStoreElimination)
+updates an optimized access of a store, after a traversal that guarantees the
+optimization is correct. This is solely allowed due to the traversals and inferences
+being beyond what MemorySSA does and them being "free" (i.e. DSE does them anyway).
+This exception is set under a flag ("-dse-optimize-memoryssa") and can be disabled to
+help reproduce optimizations in isolation.
+
+
 Use Optimization
 ^^^^^^^^^^^^^^^^