[cDAC] GC Contract (#118050)

* Modify cDAC datadescriptor spec to support sub-descriptors
* Modify cdac-build-tool to support sub-descriptors
* Implement GC sub-descriptor
* Implement cDAC GC API GetGCHeapData and GetGCHeapList
* gcinterface minor version bump

Author: max-charlamb

docs/design/datacontracts/GC.md

@@ -0,0 +1,83 @@
+# Contract GC
+
+This contract is for getting information about the garbage collector configuration and state.
+
+## APIs of contract
+
+
+```csharp
+    // Return an array of strings identifying the GC type.
+    // Current return values can include:
+    // "workstation" or "server"
+    // "segments" or "regions"
+    string[] GetGCIdentifiers();
+    // Return the number of GC heaps
+    uint GetGCHeapCount();
+    // Return true if the GC structure is valid, otherwise return false
+    bool GetGCStructuresValid();
+    // Return the maximum generation of the current GC
+    uint GetMaxGeneration();
+```
+
+## Version 1
+
+Data descriptors used:
+| Data Descriptor Name | Field | Meaning |
+| --- | --- | --- |
+| _(none)_ | | |
+
+Global variables used:
+| Global Name | Type | Purpose |
+| --- | --- | --- |
+| `GCIdentifiers` | string | CSV string containing identifiers of the GC. Current values are "server", "workstation", "regions", and "segments" |
+| `NumHeaps` | TargetPointer | Pointer to the number of heaps for server GC (int) |
+| `StructureInvalidCount` | TargetPointer | Pointer to the count of invalid GC structures (int) |
+| `MaxGeneration` | TargetPointer | Pointer to the maximum generation number (uint) |
+
+Contracts used:
+| Contract Name |
+| --- |
+| _(none)_ |
+
+
+Constants used:
+| Name | Type | Purpose | Value |
+| --- | --- | --- | --- |
+| `WRK_HEAP_COUNT` | uint | The number of heaps in the `workstation` GC type | `1` |
+
+```csharp
+GCHeapType GetGCIdentifiers()
+{
+    string gcIdentifiers = _target.ReadGlobalString("GCIdentifiers");
+    return gcIdentifiers.Split(", ");
+}
+
+uint GetGCHeapCount()
+{
+    string[] gcIdentifiers = GetGCIdentifiers()
+    if (gcType.Contains("workstation"))
+    {
+        return WRK_HEAP_COUNT;
+    }
+    if (gcType.Contains("server"))
+    {
+        TargetPointer pNumHeaps = target.ReadGlobalPointer("NumHeaps");
+        return (uint)target.Read<int>(pNumHeaps);
+    }
+
+    throw new NotImplementedException("Unknown GC heap type");
+}
+
+bool GetGCStructuresValid()
+{
+    TargetPointer pInvalidCount = target.ReadGlobalPointer("StructureInvalidCount");
+    int invalidCount = target.Read<int>(pInvalidCount);
+    return invalidCount == 0; // Structures are valid if the count of invalid structures is zero
+}
+
+uint GetMaxGeneration()
+{
+    TargetPointer pMaxGeneration = target.ReadGlobalPointer("MaxGeneration");
+    return target.Read<uint>(pMaxGeneration);
+}
+```

src/coreclr/clrdefinitions.cmake

@@ -170,6 +170,7 @@ if (FEATURE_ENABLE_NO_ADDRESS_SPACE_RANDOMIZATION)
   add_definitions(-DFEATURE_ENABLE_NO_ADDRESS_SPACE_RANDOMIZATION)
 endif(FEATURE_ENABLE_NO_ADDRESS_SPACE_RANDOMIZATION)
 if (NOT CLR_CMAKE_HOST_ANDROID)
+  set(FEATURE_SVR_GC 1)
   add_definitions(-DFEATURE_SVR_GC)
 endif(NOT CLR_CMAKE_HOST_ANDROID)
 add_definitions(-DFEATURE_SYMDIFF)

src/coreclr/debug/datadescriptor-shared/README.md

@@ -82,6 +82,12 @@ The build system uses a two-phase approach:
 - Defines a global string value
 - `stringValue` must be a compile-time string literal
 
+**`CDAC_GLOBAL_SUB_DESCRIPTOR(globalName, address)`**
+- Defines a reference to another contract descriptor
+- `address` must be a compile-time constant pointer to a pointer to a contract descriptor
+- Used for multi-contract scenarios where one contract references another
+- Example: `CDAC_GLOBAL_SUB_DESCRIPTOR(GC, &(g_gc_dac_vars.gc_descriptor))`
+
 
 ## Current Implementation
 

src/coreclr/debug/datadescriptor-shared/contractpointerdata.cpp

@@ -14,4 +14,3 @@ extern "C"
     #include "wrappeddatadescriptor.inc"
     };
 };
-

src/coreclr/debug/datadescriptor-shared/datadescriptor.cpp

@@ -3,6 +3,14 @@
 
 #include "datadescriptor.h"
 
+#ifndef DLLEXPORT
+#ifdef _MSC_VER
+#define DLLEXPORT __declspec(dllexport)
+#else
+#define DLLEXPORT __attribute__ ((visibility ("default")))
+#endif // _MSC_VER
+#endif // DLLEXPORT
+
 // begin blob definition
 
 extern "C"
@@ -52,7 +60,8 @@ struct GlobalStringSpec
 #define MAKE_GLOBALVALUELEN_NAME(globalname) CONCAT(cdac_string_pool_globalvalue__, globalname)
 
 // used to stringify the result of a macros expansion
-#define STRINGIFY(x) #x
+// __VA_ARGS__ is the argument list comma separated
+#define STRINGIFY(...) #__VA_ARGS__
 
 // define a struct where the size of each field is the length of some string.  we will use offsetof to get
 // the offset of each struct element, which will be equal to the offset of the beginning of that string in the
@@ -68,6 +77,7 @@ struct CDacStringPoolSizes
 #define CDAC_GLOBAL_STRING(name, stringval) DECL_LEN(MAKE_GLOBALLEN_NAME(name), sizeof(#name)) \
     DECL_LEN(MAKE_GLOBALVALUELEN_NAME(name), sizeof(STRINGIFY(stringval)))
 #define CDAC_GLOBAL_POINTER(name,value) DECL_LEN(MAKE_GLOBALLEN_NAME(name), sizeof(#name))
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(name,value) DECL_LEN(MAKE_GLOBALLEN_NAME(name), sizeof(#name))
 #define CDAC_GLOBAL(name,tyname,value) DECL_LEN(MAKE_GLOBALLEN_NAME(name), sizeof(#name)) \
     DECL_LEN(MAKE_GLOBALTYPELEN_NAME(name), sizeof(#tyname))
 #include "wrappeddatadescriptor.inc"
@@ -129,6 +139,15 @@ enum
 #include "wrappeddatadescriptor.inc"
 };
 
+// count the global sub-descriptors
+enum
+{
+    CDacBlobGlobalSubDescriptorsCount =
+#define CDAC_GLOBALS_BEGIN() 0
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(name,value) + 1
+#include "wrappeddatadescriptor.inc"
+};
+
 
 #define MAKE_TYPEFIELDS_TYNAME(tyname) CONCAT(CDacFieldsPoolTypeStart__, tyname)
 
@@ -178,6 +197,7 @@ struct CDacGlobalPointerIndex
 #define DECL_LEN(membername) char membername;
 #define CDAC_GLOBALS_BEGIN() DECL_LEN(cdac_global_pointer_index_start_placeholder__)
 #define CDAC_GLOBAL_POINTER(name,value) DECL_LEN(CONCAT(cdac_global_pointer_index__, name))
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(name,value) DECL_LEN(CONCAT(cdac_global_pointer_index__, name))
 #include "wrappeddatadescriptor.inc"
 #undef DECL_LEN
 };
@@ -204,6 +224,8 @@ struct BinaryBlobDataDescriptor
 
         uint32_t GlobalPointersStart;
         uint32_t GlobalStringValuesStart;
+
+        uint32_t GlobalSubDescriptorsStart;
         uint32_t NamesPoolStart;
 
         uint32_t TypeCount;
@@ -212,6 +234,7 @@ struct BinaryBlobDataDescriptor
         uint32_t GlobalLiteralValuesCount;
         uint32_t GlobalPointerValuesCount;
         uint32_t GlobalStringValuesCount;
+        uint32_t GlobalSubDescriptorsCount;
 
         uint32_t NamesPoolCount;
 
@@ -223,11 +246,13 @@ struct BinaryBlobDataDescriptor
     } Directory;
     uint32_t PlatformFlags;
     uint32_t BaselineName;
-    struct TypeSpec Types[CDacBlobTypesCount];
-    struct FieldSpec FieldsPool[CDacBlobFieldsPoolCount];
-    struct GlobalLiteralSpec GlobalLiteralValues[CDacBlobGlobalLiteralsCount];
-    struct GlobalPointerSpec GlobalPointerValues[CDacBlobGlobalPointersCount];
-    struct GlobalStringSpec GlobalStringValues[CDacBlobGlobalStringsCount];
+    // cpp does not allow zero-length arrays, so we add one extra element to allow having zero of a given type of descriptor
+    struct TypeSpec Types[CDacBlobTypesCount + 1];
+    struct FieldSpec FieldsPool[CDacBlobFieldsPoolCount + 1];
+    struct GlobalLiteralSpec GlobalLiteralValues[CDacBlobGlobalLiteralsCount + 1];
+    struct GlobalPointerSpec GlobalPointerValues[CDacBlobGlobalPointersCount + 1];
+    struct GlobalStringSpec GlobalStringValues[CDacBlobGlobalStringsCount + 1];
+    struct GlobalPointerSpec GlobalSubDescriptorValues[CDacBlobGlobalSubDescriptorsCount + 1];
     uint8_t NamesPool[sizeof(struct CDacStringPoolSizes)];
     uint8_t EndMagic[4];
 };
@@ -253,12 +278,14 @@ struct MagicAndBlob BlobDataDescriptor = {
             /* .GlobalLiteralValuesStart = */ offsetof(struct BinaryBlobDataDescriptor, GlobalLiteralValues),
             /* .GlobalPointersStart = */ offsetof(struct BinaryBlobDataDescriptor, GlobalPointerValues),
             /* .GlobalStringValuesStart = */ offsetof(struct BinaryBlobDataDescriptor, GlobalStringValues),
+            /* .GlobalSubDescriptorsStart = */ offsetof(struct BinaryBlobDataDescriptor, GlobalSubDescriptorValues),
             /* .NamesPoolStart = */ offsetof(struct BinaryBlobDataDescriptor, NamesPool),
             /* .TypeCount = */ CDacBlobTypesCount,
             /* .FieldsPoolCount = */ CDacBlobFieldsPoolCount,
             /* .GlobalLiteralValuesCount = */ CDacBlobGlobalLiteralsCount,
             /* .GlobalPointerValuesCount = */ CDacBlobGlobalPointersCount,
             /* .GlobalStringValuesCount = */ CDacBlobGlobalStringsCount,
+            /* .GlobalSubDescriptorsCount = */ CDacBlobGlobalSubDescriptorsCount,
             /* .NamesPoolCount = */ sizeof(struct CDacStringPoolSizes),
             /* .TypeSpecSize = */ sizeof(struct TypeSpec),
             /* .FieldSpecSize = */ sizeof(struct FieldSpec),
@@ -305,12 +332,18 @@ struct MagicAndBlob BlobDataDescriptor = {
 #include "wrappeddatadescriptor.inc"
         },
 
+        /* .GlobalSubDescriptorValues = */ {
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(name,value) { /* .Name = */ GET_GLOBAL_NAME(name), /* .PointerDataIndex = */ GET_GLOBAL_POINTER_INDEX(name) },
+#include "wrappeddatadescriptor.inc"
+        },
+
         /* .NamesPool = */ ("\0" // starts with a nul
 #define CDAC_BASELINE(name) name "\0"
 #define CDAC_TYPE_BEGIN(name) #name "\0"
 #define CDAC_TYPE_FIELD(tyname,membertyname,membername,offset) #membername "\0" #membertyname "\0"
 #define CDAC_GLOBAL_STRING(name,value) #name "\0" STRINGIFY(value) "\0"
 #define CDAC_GLOBAL_POINTER(name,value) #name "\0"
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(name,value) #name "\0"
 #define CDAC_GLOBAL(name,tyname,value) #name "\0" #tyname "\0"
 #include "wrappeddatadescriptor.inc"
                   ),

src/coreclr/debug/datadescriptor-shared/wrappeddatadescriptor.inc

@@ -40,6 +40,9 @@
 #ifndef CDAC_GLOBAL_STRING
 #define CDAC_GLOBAL_STRING(globalname,stringval)
 #endif
+#ifndef CDAC_GLOBAL_SUB_DESCRIPTOR
+#define CDAC_GLOBAL_SUB_DESCRIPTOR(globalname,addr)
+#endif
 #ifndef CDAC_GLOBALS_END
 #define CDAC_GLOBALS_END()
 #endif
@@ -58,4 +61,5 @@
 #undef CDAC_GLOBAL
 #undef CDAC_GLOBAL_POINTER
 #undef CDAC_GLOBAL_STRING
+#undef CDAC_GLOBAL_SUB_DESCRIPTOR
 #undef CDAC_GLOBALS_END

src/coreclr/dlls/mscoree/coreclr/CMakeLists.txt

@@ -73,6 +73,8 @@ if (NOT CLR_CMAKE_HOST_ARCH_WASM)
     set(LIB_CORDBEE cordbee_wks)
     set(LIB_INTEROP interop)
     set(LIB_CDAC_CONTRACT_DESCRIPTOR cdac_contract_descriptor)
+    set(LIB_CDAC_GC_WKS_DESCRIPTOR gc_wks_descriptor)
+    set(LIB_CDAC_GC_SVR_DESCRIPTOR gc_svr_descriptor)
 endif(NOT CLR_CMAKE_HOST_ARCH_WASM)
 
 if (CLR_CMAKE_HOST_UNIX AND NOT CLR_CMAKE_TARGET_ARCH_WASM)
@@ -104,8 +106,15 @@ set(CORECLR_LIBRARIES
     coreclrminipal
     gc_pal
     ${LIB_CDAC_CONTRACT_DESCRIPTOR}
+    ${LIB_CDAC_GC_WKS_DESCRIPTOR}
 )
 
+if (FEATURE_SVR_GC)
+    list(APPEND CORECLR_LIBRARIES
+        ${LIB_CDAC_GC_SVR_DESCRIPTOR}
+    )
+endif(FEATURE_SVR_GC)
+
 if(CLR_CMAKE_TARGET_ARCH_AMD64)
     list(APPEND CORECLR_LIBRARIES
         gc_vxsort

src/coreclr/gc/CMakeLists.txt

@@ -41,6 +41,7 @@ endif (CLR_CMAKE_TARGET_ARCH_AMD64)
 
 if (CLR_CMAKE_TARGET_WIN32)
   set(GC_HEADERS
+    env/cdacdata.h
     env/common.h
     env/etmdummy.h
     env/gcenv.base.h
@@ -104,19 +105,31 @@ list(APPEND GC_SOURCES ${GC_HEADERS})
 convert_to_absolute_path(GC_SOURCES ${GC_SOURCES})
 
 if(FEATURE_STANDALONE_GC)
-  # clrgcexp is build with standalone+regions
   if (CLR_CMAKE_TARGET_ARCH_ARM64 OR CLR_CMAKE_TARGET_ARCH_AMD64)
+    set(BUILD_EXP_GC 1)
+  endif()
+
+  # clrgcexp is build with standalone+regions
+  if (BUILD_EXP_GC)
     add_library_clr(clrgcexp SHARED ${GC_SOURCES})
     add_dependencies(clrgcexp eventing_headers)
     target_link_libraries(clrgcexp PRIVATE ${GC_LINK_LIBRARIES})
+    target_link_libraries(clrgcexp PRIVATE gcexp_dll_wks_descriptor)
+    if (FEATURE_SVR_GC)
+      target_link_libraries(clrgcexp PRIVATE gcexp_dll_svr_descriptor)
+    endif()
     target_compile_definitions(clrgcexp PRIVATE -DUSE_REGIONS)
     install_clr(TARGETS clrgcexp DESTINATIONS . COMPONENT runtime)
-  endif (CLR_CMAKE_TARGET_ARCH_ARM64 OR CLR_CMAKE_TARGET_ARCH_AMD64)
+  endif (BUILD_EXP_GC)
 
   # clrgc is build with standalone+segments
   add_library_clr(clrgc SHARED ${GC_SOURCES})
   add_dependencies(clrgc eventing_headers)
   target_link_libraries(clrgc PRIVATE ${GC_LINK_LIBRARIES})
+  target_link_libraries(clrgc PRIVATE gc_dll_wks_descriptor)
+  if(FEATURE_SVR_GC)
+    target_link_libraries(clrgc PRIVATE gc_dll_svr_descriptor)
+  endif()
   install_clr(TARGETS clrgc DESTINATIONS . COMPONENT runtime)
 
   add_definitions(-DBUILD_AS_STANDALONE)
@@ -134,6 +147,9 @@ if(FEATURE_STANDALONE_GC)
   include_directories(${CMAKE_CURRENT_SOURCE_DIR})
   include_directories(${CMAKE_CURRENT_SOURCE_DIR}/env)
 
+  add_definitions(-DGC_DESCRIPTOR)
+  add_subdirectory(datadescriptor)
+
   install_clr(TARGETS clrgc DESTINATIONS . sharedFramework COMPONENT runtime)
   if (CLR_CMAKE_TARGET_ARCH_ARM64 OR CLR_CMAKE_TARGET_ARCH_AMD64)
     install_clr(TARGETS clrgcexp DESTINATIONS . sharedFramework COMPONENT runtime)

src/coreclr/gc/datadescriptor/.editorconfig

@@ -0,0 +1,2 @@
+[contracts.jsonc]
+indent_size = 2

src/coreclr/gc/datadescriptor/CMakeLists.txt

@@ -0,0 +1,57 @@
+# cDAC GC contract descriptor
+
+# Up to four separate descriptors can be generated:
+# 1. gc_dll_wks_descriptor - WKS GC contract descriptor for the GC DLL
+# 2. gc_dll_svr_descriptor - SVR GC contract descriptor for the GC DLL (if FEATURE_SVR_GC is enabled)
+# 3. gcexp_dll_wks_descriptor - WKS GC contract descriptor for the GC EXP DLL (if BUILD_EXP_GC is enabled)
+# 4. gcexp_dll_svr_descriptor - SVR GC contract descriptor for the GC EXP DLL (if BUILD_EXP_GC and FEATURE_SVR_GC are enabled)
+
+add_library(gc_dll_wks_descriptor_interface INTERFACE)
+target_include_directories(gc_dll_wks_descriptor_interface INTERFACE
+    ${CMAKE_CURRENT_SOURCE_DIR})
+add_dependencies(gc_dll_wks_descriptor_interface eventing_headers)
+generate_data_descriptors(
+    LIBRARY_NAME gc_dll_wks_descriptor
+    CONTRACT_NAME "GCContractDescriptorWKS"
+    CONTRACT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/contracts.jsonc"
+    INTERFACE_TARGET gc_dll_wks_descriptor_interface)
+
+if (FEATURE_SVR_GC)
+  add_library(gc_dll_svr_descriptor_interface INTERFACE)
+  target_include_directories(gc_dll_svr_descriptor_interface INTERFACE
+      ${CMAKE_CURRENT_SOURCE_DIR})
+  add_dependencies(gc_dll_svr_descriptor_interface eventing_headers)
+  target_compile_definitions(gc_dll_svr_descriptor_interface INTERFACE -DSERVER_GC)
+  generate_data_descriptors(
+      LIBRARY_NAME gc_dll_svr_descriptor
+      CONTRACT_NAME "GCContractDescriptorSVR"
+      CONTRACT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/contracts.jsonc"
+      INTERFACE_TARGET gc_dll_svr_descriptor_interface)
+endif()
+
+if(BUILD_EXP_GC)
+  add_library(gcexp_dll_wks_descriptor_interface INTERFACE)
+  target_include_directories(gcexp_dll_wks_descriptor_interface INTERFACE
+      ${CMAKE_CURRENT_SOURCE_DIR})
+  add_dependencies(gcexp_dll_wks_descriptor_interface eventing_headers)
+  target_compile_definitions(gcexp_dll_wks_descriptor_interface INTERFACE -DUSE_REGIONS)
+  generate_data_descriptors(
+      LIBRARY_NAME gcexp_dll_wks_descriptor
+      CONTRACT_NAME "GCContractDescriptorWKS"
+      CONTRACT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/contracts.jsonc"
+      INTERFACE_TARGET gcexp_dll_wks_descriptor_interface)
+
+  if (FEATURE_SVR_GC)
+    add_library(gcexp_dll_svr_descriptor_interface INTERFACE)
+    target_include_directories(gcexp_dll_svr_descriptor_interface INTERFACE
+        ${CMAKE_CURRENT_SOURCE_DIR})
+    add_dependencies(gcexp_dll_svr_descriptor_interface eventing_headers)
+    target_compile_definitions(gcexp_dll_svr_descriptor_interface INTERFACE -DUSE_REGIONS)
+    target_compile_definitions(gcexp_dll_svr_descriptor_interface INTERFACE -DSERVER_GC)
+    generate_data_descriptors(
+        LIBRARY_NAME gcexp_dll_svr_descriptor
+        CONTRACT_NAME "GCContractDescriptorSVR"
+        CONTRACT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/contracts.jsonc"
+        INTERFACE_TARGET gcexp_dll_svr_descriptor_interface)
+  endif()
+endif()