[docs] Restructure description of records created by Statepoints

The previous text was hard to understand even for me and I wrote it.  Hopefully the new structure makes it a bit more clear what's going on.  If anyone has word smithing suggestion or clarification questions, please let me know.



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@257847 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 23 insertions, 12 deletions

diff --git a/docs/Statepoints.rst b/docs/Statepoints.rst
index ea9bf0ea701..084aa62a5cb 100644
--- a/docs/Statepoints.rst
+++ b/docs/Statepoints.rst
@@ -572,19 +572,30 @@ Each statepoint generates the following Locations:
   and reported only if a) the value is constant at the call site, and b) 
   the constant can be represented with less than 64 bits (assuming zero 
   extension to the original bitwidth).
-* Variable number of Locations pairs, one pair for each pointer or vector
-  of pointers which needs relocated.  The first Location in each pair 
-  describes the base pointer for the object.  The second is the derived
-  pointer actually being relocated.  It is guaranteed that the base pointer
-  must also appear explicitly as a relocation pair if used after the
-  statepoint. There may be fewer pairs then gc parameters in the IR
+* Variable number of relocation records, each of which consists of 
+  exactly two Locations.  Relocation records are described in detail
+  below.
+
+Each relocation record provides sufficient information for a collector to 
+relocate one or more derived pointers.  Each record consists of a pair of 
+Locations.  The second element in the record represents the pointer (or 
+pointers) which need updated.  The first element in the record provides a 
+pointer to the base of the object with which the pointer(s) being relocated is
+associated.  This information is required for handling generalized derived 
+pointers since a pointer may be outside the bounds of the original allocation,
+but still needs to be relocated with the allocation.  Additionally:
+
+* It is guaranteed that the base pointer must also appear explicitly as a 
+  relocation pair if used after the statepoint. 
+* There may be fewer relocation records then gc parameters in the IR
   statepoint. Each *unique* pair will occur at least once; duplicates
-  are possible.  Location pairs may either be of pointer size, in 
-  which case they describe a single pointer being relocated and its 
-  base, or a multiple of pointer size.  In the later case, the Location
-  must be interpreted as describing a sequence of pointers and their 
-  corresponding base pointers. Both Locations in a pair can be assumed 
-  to be of the same size.  
+  are possible.  
+* The Locations within each record may either be of pointer size or a 
+  multiple of pointer size.  In the later case, the record must be 
+  interpreted as describing a sequence of pointers and their corresponding 
+  base pointers. If the Location is of size N x sizeof(pointer), then
+  there will be N records of one pointer each contained within the Location.
+  Both Locations in a pair can be assumed to be of the same size.
 
 Note that the Locations used in each section may describe the same
 physical location.  e.g. A stack slot may appear as a deopt location,