docs/AnalyzerRegions.txt

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.