Implement cDAC memory region APIs (GetHandleTableMemoryRegions, GetGCBookkeepingMemoryRegions, GetGCFreeRegions)

docs/design/datacontracts/GC.md

@@ -116,6 +116,33 @@ public readonly struct GCOomData
     HandleType[] GetHandleTypes(uint[] types);
     // Gets the global allocation context pointer and limit
     void GetGlobalAllocationContext(out TargetPointer allocPtr, out TargetPointer allocLimit);
+
+    // Gets handle table memory regions (segments)
+    IReadOnlyList<GCMemoryRegionData> GetHandleTableMemoryRegions();
+    // Gets GC bookkeeping memory regions (card table info linked list)
+    IReadOnlyList<GCMemoryRegionData> GetGCBookkeepingMemoryRegions();
+    // Gets GC free regions (free region lists and freeable segments)
+    IReadOnlyList<GCMemoryRegionData> GetGCFreeRegions();
+```
+
+```csharp
+public enum FreeRegionKind
+{
+    FreeUnknownRegion = 0,
+    FreeGlobalHugeRegion = 1,
+    FreeGlobalRegion = 2,
+    FreeRegion = 3,
+    FreeSohSegment = 4,
+    FreeUohSegment = 5,
+}
+
+public readonly struct GCMemoryRegionData
+{
+    public TargetPointer Start { get; init; }
+    public ulong Size { get; init; }
+    public ulong ExtraData { get; init; }
+    public int Heap { get; init; }
+}
 ```
 
 ## Version 1
@@ -175,6 +202,13 @@ Data descriptors used:
 | `TableSegment` | RgAllocation | GC | Circular block-list links per block |
 | `TableSegment` | RgValue | GC | Start of handle value storage |
 | `TableSegment` | RgUserData | GC | Auxiliary per-block metadata (e.g. secondary handle blocks) |
+| `CardTableInfo` | Recount | GC | Reference count for the card table |
+| `CardTableInfo` | Size | GC | Total size of the bookkeeping allocation |
+| `CardTableInfo` | NextCardTable | GC | Pointer to the next card table in the linked list |
+| `RegionFreeList` | HeadFreeRegion | GC | Head of the free region segment list |
+| `GCHeap` | FreeableSohSegment | GC | Head of the freeable SOH segment linked list (server builds, background GC) |
+| `GCHeap` | FreeableUohSegment | GC | Head of the freeable UOH segment linked list (server builds, background GC) |
+| `GCHeap` | FreeRegions | GC | Start of the per-heap free region list array (server builds, region GC) |
 | `GCAllocContext` | AllocBytes | VM | Number of bytes allocated on SOH by this context |
 | `GCAllocContext` | AllocBytesLoh | VM | Number of bytes allocated not on SOH by this context |
 | `EEAllocContext` | GCAllocationContext | VM | The `GCAllocContext` struct within an `EEAllocContext` |
@@ -229,6 +263,15 @@ Global variables used:
 | `FeatureJavaMarshal` | byte | VM | Non-zero when Java marshal support is enabled |
 | `GlobalAllocContext` | TargetPointer | VM | Pointer to the global `EEAllocContext` |
 | `TotalCpuCount` | uint | GC | Number of available processors |
+| `HandleSegmentSize` | uint | GC | Size of each handle table segment allocation |
+| `CardTableInfoSize` | uint | GC | Size of the `dac_card_table_info` structure |
+| `CountFreeRegionKinds` | uint | GC | Number of free region kinds (basic, large, huge) |
+| `GlobalFreeHugeRegions` | TargetPointer | GC | Pointer to the global free huge region list |
+| `GlobalRegionsToDecommit` | TargetPointer | GC | Pointer to the global regions-to-decommit array |
+| `BookkeepingStart` | TargetPointer | GC | Pointer to the bookkeeping start address |
+| `GCHeapFreeableSohSegment` | TargetPointer | GC | Pointer to the freeable SOH segment head (workstation builds) |
+| `GCHeapFreeableUohSegment` | TargetPointer | GC | Pointer to the freeable UOH segment head (workstation builds) |
+| `GCHeapFreeRegions` | TargetPointer | GC | Pointer to the free regions array (workstation builds) |
 
 Contracts used:
 | Contract Name |
@@ -740,3 +783,156 @@ void IGC.GetGlobalAllocationContext(out TargetPointer allocPtr, out TargetPointe
     allocLimit = target.ReadPointer(globalAllocContextAddress + /* EEAllocContext::GCAllocationContext offset */ + /* GCAllocContext::Limit offset */);
 }
 ```
+
+GetHandleTableMemoryRegions
+```csharp
+IReadOnlyList<GCMemoryRegionData> IGC.GetHandleTableMemoryRegions()
+{
+    List<GCMemoryRegionData> regions = new();
+    uint handleSegmentSize = /* global value "HandleSegmentSize" */;
+    uint tableCount = isServerGC
+        ? /* global value "TotalCpuCount" */
+        : 1;
+
+    // Safety caps matching native DAC
+    const int MaxHandleTableRegions = 8192;
+    const int MaxBookkeepingRegions = 32;
+    const int MaxSegmentListIterations = 2048;
+
+    int maxRegions = MaxHandleTableRegions;
+    TargetPointer handleTableMap = target.ReadGlobalPointer("HandleTableMap");
+    while (handleTableMap != TargetPointer.Null && maxRegions >= 0)
+    {
+        TargetPointer bucketsPtr = target.ReadPointer(handleTableMap + /* HandleTableMap::BucketsPtr offset */);
+        foreach (/* read global variable "InitialHandleTableArraySize" bucketPtrs starting at bucketsPtr */)
+        {
+            if (bucketPtr == TargetPointer.Null) continue;
+            TargetPointer table = target.ReadPointer(bucketPtr + /* HandleTableBucket::Table offset */);
+            for (uint j = 0; j < tableCount; j++)
+            {
+                TargetPointer htPtr = target.ReadPointer(table + j * target.PointerSize);
+                if (htPtr == TargetPointer.Null) continue;
+                TargetPointer segList = target.ReadPointer(htPtr + /* HandleTable::SegmentList offset */);
+                if (segList == TargetPointer.Null) continue;
+                TargetPointer seg = segList;
+                TargetPointer first = seg;
+                do
+                {
+                    regions.Add(new GCMemoryRegionData { Start = seg, Size = handleSegmentSize, Heap = (int)j });
+                    seg = target.ReadPointer(seg + /* TableSegment::NextSegment offset */);
+                } while (seg != TargetPointer.Null && seg != first);
+            }
+        }
+        handleTableMap = target.ReadPointer(handleTableMap + /* HandleTableMap::Next offset */);
+        maxRegions--;
+    }
+    return regions;
+}
+```
+
+GetGCBookkeepingMemoryRegions
+```csharp
+IReadOnlyList<GCMemoryRegionData> IGC.GetGCBookkeepingMemoryRegions()
+{
+    List<GCMemoryRegionData> regions = new();
+    TargetPointer bkGlobal = target.ReadGlobalPointer("BookkeepingStart");
+    if (bkGlobal == TargetPointer.Null) throw E_FAIL;
+    TargetPointer bookkeepingStart = target.ReadPointer(bkGlobal);
+    if (bookkeepingStart == TargetPointer.Null) throw E_FAIL;
+
+    uint cardTableInfoSize = /* global value "CardTableInfoSize" */;
+    uint recount = target.ReadNUInt(bookkeepingStart + /* CardTableInfo::Recount offset */);
+    ulong size = target.ReadNUInt(bookkeepingStart + /* CardTableInfo::Size offset */);
+    if (recount != 0 && size != 0)
+        regions.Add(new GCMemoryRegionData { Start = bookkeepingStart, Size = size });
+
+    TargetPointer next = target.ReadPointer(bookkeepingStart + /* CardTableInfo::NextCardTable offset */);
+    TargetPointer firstNext = next;
+    int maxRegions = MaxBookkeepingRegions;
+    // Compare next > cardTableInfoSize to guard against underflow when subtracting
+    // cardTableInfoSize. Matches native DAC: `while (next > card_table_info_size)`.
+    while (next != TargetPointer.Null && next > cardTableInfoSize && maxRegions > 0)
+    {
+        TargetPointer ctAddr = next - cardTableInfoSize;
+        recount = target.ReadNUInt(ctAddr + /* CardTableInfo::Recount offset */);
+        size = target.ReadNUInt(ctAddr + /* CardTableInfo::Size offset */);
+        if (recount != 0 && size != 0)
+            regions.Add(new GCMemoryRegionData { Start = ctAddr, Size = size });
+        next = target.ReadPointer(ctAddr + /* CardTableInfo::NextCardTable offset */);
+        if (next == firstNext) break;
+        maxRegions--;
+    }
+    return regions;
+}
+```
+
+GetGCFreeRegions
+```csharp
+IReadOnlyList<GCMemoryRegionData> IGC.GetGCFreeRegions()
+{
+    List<GCMemoryRegionData> regions = new();
+    uint countFreeRegionKinds = min(/* global value "CountFreeRegionKinds" */, 16);
+    uint regionFreeListSize = /* size of RegionFreeList data descriptor */;
+
+    // Global free huge regions
+    if (target.TryReadGlobalPointer("GlobalFreeHugeRegions", out TargetPointer? globalHuge))
+        AddFreeList(globalHuge, FreeGlobalHugeRegion, regions);
+
+    // Global regions to decommit
+    if (target.TryReadGlobalPointer("GlobalRegionsToDecommit", out TargetPointer? globalDecommit))
+        for (int i = 0; i < countFreeRegionKinds; i++)
+            AddFreeList(globalDecommit + i * regionFreeListSize, FreeGlobalRegion, regions);
+
+    if (isServerGC)
+    {
+        // For each server heap: enumerate per-heap free regions + freeable segments
+        for each heap in server heaps:
+            TargetPointer freeRegionsBase = heapAddress + /* GCHeap::FreeRegions offset */;
+            if (freeRegionsBase != TargetPointer.Null)
+                for (int j = 0; j < countFreeRegionKinds; j++)
+                    AddFreeList(freeRegionsBase + j * regionFreeListSize, FreeRegion, regions, heapIndex);
+            TargetPointer sohSeg = target.ReadPointer(heapAddress + /* GCHeap::FreeableSohSegment offset */);
+            AddSegmentList(sohSeg, FreeSohSegment, regions, heapIndex);
+            TargetPointer uohSeg = target.ReadPointer(heapAddress + /* GCHeap::FreeableUohSegment offset */);
+            AddSegmentList(uohSeg, FreeUohSegment, regions, heapIndex);
+    }
+    else
+    {
+        // Workstation: use globals for free regions and freeable segments
+        if (target.TryReadGlobalPointer("GCHeapFreeRegions", out TargetPointer? freeRegions))
+            for (int i = 0; i < countFreeRegionKinds; i++)
+                AddFreeList(freeRegions + i * regionFreeListSize, FreeRegion, regions);
+        if (target.TryReadGlobalPointer("GCHeapFreeableSohSegment", out TargetPointer? soh))
+            AddSegmentList(target.ReadPointer(soh), FreeSohSegment, regions);
+        if (target.TryReadGlobalPointer("GCHeapFreeableUohSegment", out TargetPointer? uoh))
+            AddSegmentList(target.ReadPointer(uoh), FreeUohSegment, regions);
+    }
+    return regions;
+}
+
+void AddFreeList(TargetPointer freeListAddr, FreeRegionKind kind, List<GCMemoryRegionData> regions, int heap = 0)
+{
+    TargetPointer headFreeRegion = target.ReadPointer(freeListAddr + /* RegionFreeList::HeadFreeRegion offset */);
+    if (headFreeRegion != TargetPointer.Null)
+        AddSegmentList(headFreeRegion, kind, regions, heap);
+}
+
+void AddSegmentList(TargetPointer start, FreeRegionKind kind, List<GCMemoryRegionData> regions, int heap = 0)
+{
+    int iterationMax = MaxSegmentListIterations;
+    TargetPointer curr = start;
+    while (curr != TargetPointer.Null)
+    {
+        TargetPointer mem = target.ReadPointer(curr + /* HeapSegment::Mem offset */);
+        if (mem != TargetPointer.Null)
+        {
+            TargetPointer committed = target.ReadPointer(curr + /* HeapSegment::Committed offset */);
+            ulong size = (mem < committed) ? committed - mem : 0;
+            regions.Add(new GCMemoryRegionData { Start = mem, Size = size, ExtraData = kind, Heap = heap });
+        }
+        curr = target.ReadPointer(curr + /* HeapSegment::Next offset */);
+        if (curr == start) break;
+        if (iterationMax-- <= 0) break;
+    }
+}
+```

src/coreclr/gc/datadescriptor/datadescriptor.h

@@ -76,6 +76,19 @@ struct cdac_data<GC_NAMESPACE::gc_heap>
     GC_HEAP_FIELD(CompactReasons, compact_reasons_per_heap)
     GC_HEAP_FIELD(ExpandMechanisms, expand_mechanisms_per_heap)
     GC_HEAP_FIELD(InterestingMechanismBits, interesting_mechanism_bits_per_heap)
+    /* For use in GCFreeRegions APIs */
+#ifdef BACKGROUND_GC
+    GC_HEAP_FIELD(FreeableSohSegment, freeable_soh_segment)
+    GC_HEAP_FIELD(FreeableUohSegment, freeable_uoh_segment)
+#endif // BACKGROUND_GC
+#ifdef USE_REGIONS
+    GC_HEAP_FIELD(FreeRegions, free_regions)
+
+    static constexpr decltype(&GC_NAMESPACE::gc_heap::global_free_huge_regions) GlobalFreeHugeRegions = &GC_NAMESPACE::gc_heap::global_free_huge_regions;
+    static constexpr decltype(&GC_NAMESPACE::gc_heap::global_regions_to_decommit) GlobalRegionsToDecommit = &GC_NAMESPACE::gc_heap::global_regions_to_decommit;
+#endif // USE_REGIONS
+
+    static constexpr decltype(&GC_NAMESPACE::gc_heap::bookkeeping_start) BookkeepingStart = &GC_NAMESPACE::gc_heap::bookkeeping_start;
 };
 
 template<>

src/coreclr/gc/datadescriptor/datadescriptor.inc

@@ -34,6 +34,13 @@ CDAC_TYPE_FIELD(GCHeap, /*pointer*/, InterestingData, cdac_data<GC_NAMESPACE::gc
 CDAC_TYPE_FIELD(GCHeap, /*pointer*/, CompactReasons, cdac_data<GC_NAMESPACE::gc_heap>::CompactReasons)
 CDAC_TYPE_FIELD(GCHeap, /*pointer*/, ExpandMechanisms, cdac_data<GC_NAMESPACE::gc_heap>::ExpandMechanisms)
 CDAC_TYPE_FIELD(GCHeap, /*pointer*/, InterestingMechanismBits, cdac_data<GC_NAMESPACE::gc_heap>::InterestingMechanismBits)
+#ifdef BACKGROUND_GC
+CDAC_TYPE_FIELD(GCHeap, /*pointer*/, FreeableSohSegment, cdac_data<GC_NAMESPACE::gc_heap>::FreeableSohSegment)
+CDAC_TYPE_FIELD(GCHeap, /*pointer*/, FreeableUohSegment, cdac_data<GC_NAMESPACE::gc_heap>::FreeableUohSegment)
+#endif // BACKGROUND_GC
+#ifdef USE_REGIONS
+CDAC_TYPE_FIELD(GCHeap, /*pointer*/, FreeRegions, cdac_data<GC_NAMESPACE::gc_heap>::FreeRegions)
+#endif // USE_REGIONS
 CDAC_TYPE_END(GCHeap)
 #endif // SERVER_GC
 
@@ -104,6 +111,18 @@ CDAC_TYPE_FIELD(TableSegment, /*uint8_t[]*/, RgValue, offsetof(TableSegment, rgV
 CDAC_TYPE_FIELD(TableSegment, /*uint8_t[]*/, RgUserData, offsetof(TableSegment, rgUserData))
 CDAC_TYPE_END(TableSegment)
 
+CDAC_TYPE_BEGIN(CardTableInfo)
+CDAC_TYPE_SIZE(sizeof(dac_card_table_info))
+CDAC_TYPE_FIELD(CardTableInfo, /*uint32*/, Recount, offsetof(dac_card_table_info, recount))
+CDAC_TYPE_FIELD(CardTableInfo, /*nuint*/, Size, offsetof(dac_card_table_info, size))
+CDAC_TYPE_FIELD(CardTableInfo, /*pointer*/, NextCardTable, offsetof(dac_card_table_info, next_card_table))
+CDAC_TYPE_END(CardTableInfo)
+
+CDAC_TYPE_BEGIN(RegionFreeList)
+CDAC_TYPE_SIZE(sizeof(dac_region_free_list))
+CDAC_TYPE_FIELD(RegionFreeList, /*pointer*/, HeadFreeRegion, offsetof(dac_region_free_list, head_free_region))
+CDAC_TYPE_END(RegionFreeList)
+
 CDAC_TYPES_END()
 
 CDAC_GLOBALS_BEGIN()
@@ -125,6 +144,11 @@ CDAC_GLOBAL(HandleBlocksPerSegment, /*uint32*/, HANDLE_BLOCKS_PER_SEGMENT)
 CDAC_GLOBAL(HandleMaxInternalTypes, /*uint32*/, HANDLE_MAX_INTERNAL_TYPES)
 CDAC_GLOBAL(HandlesPerBlock, /*uint32*/, HANDLE_HANDLES_PER_BLOCK)
 CDAC_GLOBAL(BlockInvalid, /*uint8*/, BLOCK_INVALID)
+CDAC_GLOBAL(HandleSegmentSize, /*uint32*/, HANDLE_SEGMENT_SIZE)
+CDAC_GLOBAL(CardTableInfoSize, /*uint32*/, (uint32_t)sizeof(dac_card_table_info))
+#ifdef USE_REGIONS
+CDAC_GLOBAL(CountFreeRegionKinds, /*uint32*/, (uint32_t)FREE_REGION_KINDS)
+#endif // USE_REGIONS
 
 
 #ifndef SERVER_GC
@@ -149,9 +173,21 @@ CDAC_GLOBAL_POINTER(GCHeapInterestingData, cdac_data<GC_NAMESPACE::gc_heap>::Int
 CDAC_GLOBAL_POINTER(GCHeapCompactReasons, cdac_data<GC_NAMESPACE::gc_heap>::CompactReasons)
 CDAC_GLOBAL_POINTER(GCHeapExpandMechanisms, cdac_data<GC_NAMESPACE::gc_heap>::ExpandMechanisms)
 CDAC_GLOBAL_POINTER(GCHeapInterestingMechanismBits, cdac_data<GC_NAMESPACE::gc_heap>::InterestingMechanismBits)
+#ifdef BACKGROUND_GC
+CDAC_GLOBAL_POINTER(GCHeapFreeableSohSegment, cdac_data<GC_NAMESPACE::gc_heap>::FreeableSohSegment)
+CDAC_GLOBAL_POINTER(GCHeapFreeableUohSegment, cdac_data<GC_NAMESPACE::gc_heap>::FreeableUohSegment)
+#endif // BACKGROUND_GC
+#ifdef USE_REGIONS
+CDAC_GLOBAL_POINTER(GCHeapFreeRegions, cdac_data<GC_NAMESPACE::gc_heap>::FreeRegions)
+#endif // USE_REGIONS
 #endif // !SERVER_GC
 
 CDAC_GLOBAL_POINTER(HandleTableMap, &g_HandleTableMap)
+CDAC_GLOBAL_POINTER(BookkeepingStart, cdac_data<GC_NAMESPACE::gc_heap>::BookkeepingStart)
+#ifdef USE_REGIONS
+CDAC_GLOBAL_POINTER(GlobalFreeHugeRegions, cdac_data<GC_NAMESPACE::gc_heap>::GlobalFreeHugeRegions)
+CDAC_GLOBAL_POINTER(GlobalRegionsToDecommit, cdac_data<GC_NAMESPACE::gc_heap>::GlobalRegionsToDecommit)
+#endif // USE_REGIONS
 
 #ifdef SERVER_GC
 #define GC_TYPE server

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Contracts/IGC.cs

@@ -98,6 +98,24 @@ public readonly struct GCOomData
     public bool LohP { get; init; }
 }
 
+public enum FreeRegionKind
+{
+    FreeUnknownRegion = 0,
+    FreeGlobalHugeRegion = 1,
+    FreeGlobalRegion = 2,
+    FreeRegion = 3,
+    FreeSohSegment = 4,
+    FreeUohSegment = 5,
+}
+
+public readonly struct GCMemoryRegionData
+{
+    public TargetPointer Start { get; init; }
+    public ulong Size { get; init; }
+    public ulong ExtraData { get; init; }
+    public int Heap { get; init; }
+}
+
 public interface IGC : IContract
 {
     static string IContract.Name { get; } = nameof(GC);
@@ -128,6 +146,10 @@ public interface IGC : IContract
     HandleType[] GetHandleTypes(uint[] types) => throw new NotImplementedException();
 
     void GetGlobalAllocationContext(out TargetPointer allocPtr, out TargetPointer allocLimit) => throw new NotImplementedException();
+
+    IReadOnlyList<GCMemoryRegionData> GetHandleTableMemoryRegions() => throw new NotImplementedException();
+    IReadOnlyList<GCMemoryRegionData> GetGCBookkeepingMemoryRegions() => throw new NotImplementedException();
+    IReadOnlyList<GCMemoryRegionData> GetGCFreeRegions() => throw new NotImplementedException();
 }
 
 public readonly struct GC : IGC

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/DataType.cs

@@ -171,4 +171,6 @@ public enum DataType
     HandleTableBucket,
     HandleTable,
     TableSegment,
+    CardTableInfo,
+    RegionFreeList,
 }

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Constants.cs

@@ -153,6 +153,15 @@ public static class Globals
         public const string HandlesPerBlock = nameof(HandlesPerBlock);
         public const string BlockInvalid = nameof(BlockInvalid);
         public const string TotalCpuCount = nameof(TotalCpuCount);
+        public const string HandleSegmentSize = nameof(HandleSegmentSize);
+        public const string CardTableInfoSize = nameof(CardTableInfoSize);
+        public const string CountFreeRegionKinds = nameof(CountFreeRegionKinds);
+        public const string GlobalFreeHugeRegions = nameof(GlobalFreeHugeRegions);
+        public const string GlobalRegionsToDecommit = nameof(GlobalRegionsToDecommit);
+        public const string BookkeepingStart = nameof(BookkeepingStart);
+        public const string GCHeapFreeableSohSegment = nameof(GCHeapFreeableSohSegment);
+        public const string GCHeapFreeableUohSegment = nameof(GCHeapFreeableUohSegment);
+        public const string GCHeapFreeRegions = nameof(GCHeapFreeRegions);
     }
     public static class FieldNames
     {

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/GC/GCHeapWKS.cs

@@ -32,6 +32,13 @@ public GCHeapWKS(Target target)
         CompactReasons = target.ReadGlobalPointer(Constants.Globals.GCHeapCompactReasons);
         ExpandMechanisms = target.ReadGlobalPointer(Constants.Globals.GCHeapExpandMechanisms);
         InterestingMechanismBits = target.ReadGlobalPointer(Constants.Globals.GCHeapInterestingMechanismBits);
+
+        if (target.TryReadGlobalPointer(Constants.Globals.GCHeapFreeableSohSegment, out TargetPointer? freeableSohSegPtr))
+            FreeableSohSegment = target.ReadPointer(freeableSohSegPtr.Value);
+        if (target.TryReadGlobalPointer(Constants.Globals.GCHeapFreeableUohSegment, out TargetPointer? freeableUohSegPtr))
+            FreeableUohSegment = target.ReadPointer(freeableUohSegPtr.Value);
+        if (target.TryReadGlobalPointer(Constants.Globals.GCHeapFreeRegions, out TargetPointer? freeRegionsPtr))
+            FreeRegions = freeRegionsPtr.Value;
     }
 
     public TargetPointer MarkArray { get; }
@@ -57,4 +64,8 @@ public GCHeapWKS(Target target)
     public TargetPointer CompactReasons { get; }
     public TargetPointer ExpandMechanisms { get; }
     public TargetPointer InterestingMechanismBits { get; }
+
+    public TargetPointer? FreeableSohSegment { get; }
+    public TargetPointer? FreeableUohSegment { get; }
+    public TargetPointer? FreeRegions { get; }
 }