8272439: G1: add documentation to G1CardSetInlinePtr

Co-authored-by: Thomas Schatzl <tschatzl@openjdk.org>
Reviewed-by: tschatzl, kbarrett

src/hotspot/share/gc/g1/g1CardSet.cpp

@@ -45,7 +45,7 @@
 G1CardSet::CardSetPtr G1CardSet::FullCardSet = (G1CardSet::CardSetPtr)-1;
 
 G1CardSetConfiguration::G1CardSetConfiguration() :
-  _inline_ptr_bits_per_card(HeapRegion::LogOfHRGrainBytes - CardTable::card_shift) {
+  _inline_ptr_bits_per_card(HeapRegion::LogCardsPerRegion) {
 
   // Array of Cards card set container size calculation
   _num_cards_in_array = G1RemSetArrayOfCardsEntries;

src/hotspot/share/gc/g1/g1CardSet.hpp

@@ -47,7 +47,10 @@ enum G1AddCardResult {
 };
 
 class G1CardSetConfiguration {
+  // Holds the number of bits required to cover the maximum card index for the
+  // regions covered by this card set.
   uint _inline_ptr_bits_per_card;
+
   uint _num_cards_in_array;
   uint _num_cards_in_howl_bitmap;
   uint _num_buckets_in_howl;

src/hotspot/share/gc/g1/g1CardSetContainers.hpp

@@ -36,6 +36,37 @@
 
 #include "runtime/thread.inline.hpp"
 
+// A helper class to encode a few card indexes within a CardSetPtr.
+//
+// The pointer value (either 32 or 64 bits) is split into two areas:
+//
+// - Header containing identifying tag and number of encoded cards.
+// - Data area containing the card indexes themselves
+//
+// The header starts (from LSB) with the identifying tag (two bits,
+// always 00), and three bits size. The size stores the number of
+// valid card indexes after the header.
+//
+// The data area makes up the remainder of the word, with card indexes
+// put one after another at increasing bit positions. The separate
+// card indexes use just enough space (bits) to represent the whole
+// range of cards needed for covering the whole range of values
+// (typically in a region). There may be unused space at the top of
+// the word.
+//
+// Example:
+//
+//   64 bit pointer size, with 8M-size regions (8M == 2^23)
+// -> 2^14 (2^23 / 2^9) cards; each card represents 512 bytes in a region
+// -> 14 bits per card; must have enough bits to hold the max card index
+// -> may encode up to 4 cards into it, using 61 bits (5 bits header + 4 * 14)
+//
+// M                                                     L
+// S                                                     S
+// B                                                     B
+// +------+         +---------------+--------------+-----+
+// |unused|   ...   |  card_index1  | card_index0  |SSS00|
+// +------+         +---------------+--------------+-----+
 class G1CardSetInlinePtr : public StackObj {
   friend class G1CardSetContainersTest;