Document object reference variants used in SubstrateVM

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/heap/ReferenceAccess.java

@@ -32,9 +32,43 @@
 import org.graalvm.word.Pointer;
 import org.graalvm.word.UnsignedWord;
 
+import com.oracle.svm.core.config.ObjectLayout;
+
 /**
  * Means for accessing object references, explicitly distinguishing between compressed and
  * uncompressed references.
+ * <p>
+ * <p>
+ * SubstrateVM uses the following object reference variants:
+ * <p>
+ * <ol>
+ * <li>-H:-SpawnIsolates (explicitly disabled isolates support)
+ * <ul>
+ * <li>Regular reference: <code>address64 = val64</code>
+ * <li>Reference to hub: <code>address64 = val64 & GC-bits_bitmask</code>
+ * </ul>
+ * <blockquote>where <code>GC-bits_bitmask</code> is
+ * <code>~{@link ObjectHeader#getReservedBitsMask()}</code></blockquote> <br>
+ * <li>-H:+SpawnIsolates and -H:-UseCompressedReferences (CE default)
+ * <ul>
+ * <li>Regular reference: <code>address64 = val64 + r14</code>
+ * <li>Reference to hub:
+ * <code>address64 = ((val64 >>> num_GC_bits) << objectAlignmentBits) + r14</code>
+ * </ul>
+ * <blockquote>where <code>objectAlignmentBits</code> is defined by
+ * <code>Integer.bitCount({@link ObjectLayout#getAlignment()} - 1)</code></blockquote> <br>
+ * <li>-H:+SpawnIsolates and -H:+UseCompressedReferences (EE default)
+ * <ul>
+ * <li>Regular reference: <code>address64 = (val32 << compressShift) + r14</code>
+ * <li>Reference to hub: <code>address64 = ((val32 >>> num_GC_bits) << compressShift) + r14</code>
+ * <br>
+ * </ul>
+ * <blockquote>where <code>compressShift</code> is defined by
+ * {@link CompressEncoding#getShift()}</blockquote>
+ * </ol>
+ * <br>
+ * <blockquote> In 2. and 3. <code>num_GC_bits</code> is
+ * <code>Integer.bitCount({@link ObjectHeader#getReservedBitsMask()})</code> </blockquote>
  */
 public interface ReferenceAccess {
     @Fold