[docs][Statepoint] Add definitions for base and derived pointers

[oota-llvm.git] / docs / Statepoints.rst

diff --git a/docs/Statepoints.rst b/docs/Statepoints.rst
index 2b01374a9ec5cd3bf9d218be56362e61fec96b43..6f1a5a4671ddb509796e62dc20f8fa95df915c37 100644 (file)
--- a/docs/Statepoints.rst
+++ b/docs/Statepoints.rst
@@ -206,6 +206,23 @@ This example was taken from the tests for the :ref:`RewriteStatepointsForGC` uti
 
   opt -rewrite-statepoints-for-gc test/Transforms/RewriteStatepointsForGC/basics.ll -S | llc -debug-only=stackmaps
 
+Base & Derived Pointers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A base pointer is one which points to the base of an allocation (object).  A 
+derived pointer is one which is offset from a base pointer by some amount.  
+When relocating objects, a garbage collector needs to be able to relocate each 
+derived pointer associated with an allocation to the same offset from the new 
+address.    
+
+Derived pointers fall in to two categories: 
+ * "Interior derived pointers" remain within the bounds of the allocation 
+   they're associated with.  As a result, the base object can be found at 
+   runtime provided the bounds of allocations are known to the runtime system.
+ * "Exterior derived pointers" are outside the bounds of the associated object;
+   they may even fall within *another* allocations address range.  As a result,
+   there is no way for a garbage collector to determine which allocation they 
+   are associated with at runtime and compiler support is needed.
 
 GC Transitions
 ^^^^^^^^^^^^^^^^^^
@@ -567,7 +584,7 @@ The existing IR Verifier pass has been extended to check most of the
 local restrictions on the intrinsics mentioned in their respective
 documentation.  The current implementation in LLVM does not check the
 key relocation invariant, but this is ongoing work on developing such
-a verifier.  Please ask on llvmdev if you're interested in
+a verifier.  Please ask on llvm-dev if you're interested in
 experimenting with the current version.
 
 .. _statepoint-utilities:
@@ -698,7 +715,7 @@ If you are scheduling the RewriteStatepointsForGC pass late in the pass order,
 you should probably schedule this pass immediately before it.  The exception 
 would be if you need to preserve abstract frame information (e.g. for
 deoptimization or introspection) at safepoints.  In that case, ask on the 
-llvmdev mailing list for suggestions.
+llvm-dev mailing list for suggestions.
 
 
 Supported Architectures
@@ -715,8 +732,8 @@ tracked by performing a `bugzilla search
 <http://llvm.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Statepoint%20Bugs&list_id=64342>`_
 for [Statepoint] in the summary field. When filing new bugs, please
 use this tag so that interested parties see the newly filed bug.  As
-with most LLVM features, design discussions take place on `llvmdev
-<http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_, and patches
+with most LLVM features, design discussions take place on `llvm-dev
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_, and patches
 should be sent to `llvm-commits
-<http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_ for review.
+<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ for review.