Check in some design documents to centralize ideas around region store and the

analysis engine.

llvm-svn: 67747

clang/lib/Analysis/Design.txt

@@ -0,0 +1,53 @@
+Symbolic Region
+
+A symbolic region is a map of the concept of symbolic values into the domain of
+regions. It is the way that we represent symbolic pointers. Whenever a symbolic
+pointer value is needed, a symbolic region is created to represent it.
+
+A symbolic region has no type. It wraps a SymbolData. But sometimes we have type
+information associated with a symbolic region. For this case, a TypedViewRegion
+is created to layer the type information on top of the symbolic region. The
+reason we do not carry type information with the symbolic region is that
+the symbolic regions can have no type. To be consistent, we don't let them to
+carry type information.
+
+Like a symbolic pointer, a symbolic region may be NULL, has unknown extent, and
+represents a generic chunk of memory.
+
+We plan not to use loc::SymbolVal in RegionStore and remove it gradually.
+
+Pointer Casts
+
+Pointer casts allow people to impose different 'views' onto a chunk of memory.
+
+Usually we have two kinds of casts. One kind of casts cast down with in the type
+hierarchy. It imposes more specific views onto more generic memory regions. The
+other kind of casts cast up with in the type hierarchy. It strips away more
+specific views on top of the more generic memory regions. 
+
+We simulate the down casts by layering another TypedViewRegion on top of the
+original region. We simulate the up casts by striping away the top
+TypedViewRegion. Down casts is usually simple. For up casts, if the there is no
+TypedViewRegion to be stripped, we return the original region. If the underlying
+region is of the different type than the cast-to type, we flag an error state.
+
+For toll-free bridging casts, we return the original region.
+
+Region Bindings
+
+The following region kinds are boundable: VarRegion, CompoundLiteralRegion,
+StringRegion, ElementRegion, FieldRegion, and ObjCIvarRegion.
+
+When binding regions, we perform canonicalization on element regions and field
+regions. This is because we can have different views on the same region, some of
+which are essentially the same view with different sugar type names.
+
+To canonicalize a region, we get the canonical types for all TypedViewRegions
+along the way up to the root region, and make new TypedViewRegions with those
+canonical types.
+
+All bindings and retrievings are done on the canonicalized regions.
+
+Canonicalization is transparent outside the region store manager, and more
+specifically, unaware outside the Bind() and Retrieve() method. We don't need to
+consider region canonicalization when doing pointer cast.