[NativeAOT] Add cDAC data descriptor infrastructure

[max-charlamb]

Note

This PR was created with assistance from GitHub Copilot.

Summary

Adds the cDAC data descriptor infrastructure for NativeAOT, enabling diagnostic tools (cDAC reader, SOS) to inspect NativeAOT runtime state through the same contract-based mechanism used by CoreCLR.

Changes

Native data descriptor (datadescriptor.inc)

• Thread/ThreadStore: Thread state, OS ID, exception tracker, stack bounds, alloc context, transition frame, thread link
• EEAllocContext/GCAllocContext: Allocation pointer, limit, bytes allocated
• MethodTable (EEType): Flags, base size, related type, vtable slots, interfaces, hash code — with flag constants exposed via cdac_data<> friend pattern
• ExInfo: Exception linked list traversal
• StressLog/ThreadStressLog: Stress log infrastructure (guarded by STRESS_LOG)
• Globals: ThreadStore static pointer, free object MethodTable, GC bounds, thread state flags, object unmask, stress log
• Contracts: Thread (n1), Exception (c1), RuntimeTypeSystem (n1), StressLog (c2)
• Sub-descriptors: GC (workstation + server) and managed type descriptors

ILC managed type descriptor (ManagedDataDescriptorNode)

• Computes managed type field offsets at compile time in ILC
• Emits a ContractDescriptor (DotNetManagedContractDescriptor) with JSON-encoded type layouts using Utf8JsonWriter
• Types and fields discovered via [DataContract] attribute on types in MetadataManager.GetTypesWithEETypes()
• Type name mangling: System.Threading.Thread -> System_Threading_Thread
• Referenced by the native descriptor as a sub-descriptor via CDAC_GLOBAL_SUB_DESCRIPTOR
• Currently registers System.Threading.Thread fields (ManagedThreadId, Name)

GC sub-descriptor

• Enabled GC sub-descriptor for NativeAOT by setting GC_INTERFACE_*_VERSION before GC_Initialize
• Added GC_DESCRIPTOR compile definition (guarded on non-WASM)
• Linked both WKS and SVR GC descriptor objects into Runtime.ServerGC (ServerGC compiles both paths)
• Added #ifdef HEAP_ANALYZE guards in shared GC datadescriptor files (NativeAOT disables HEAP_ANALYZE)

Attribute-based type discovery

• [DataContract] attribute in System.Diagnostics namespace (internal, targets Class/Struct/Field)
• Applied to System.Threading.Thread fields in Thread.NativeAot.cs
• ILC scans for annotated types in GetTypesWithEETypes() ensuring only types with MethodTables are included

Build integration

• CMake integration using shared clrdatadescriptors.cmake infrastructure
• nativeaot_runtime_includes interface library captures all Runtime include paths for cross-target compilation
• Separate GC descriptor targets for workstation and server GC
• cdac-build-tool enabled for NativeAOT via ClrNativeAotSubset in runtime.proj
• Symbol export via --export-dynamic-symbol in Microsoft.NETCore.Native.targets (WASM excluded)
• Local copy of cdacdata.h template in Runtime/inc/ (matching GC pattern for self-contained builds)

Key design decisions

• Contract versions: n1 for NativeAOT-specific contracts, c1/c2 for contracts shared with CoreCLR (same version)
• ThreadStore: Uses SPTR_DECL/SPTR_IMPL for s_pThreadStore static member, matching CoreCLR pattern
• Singleton node: ManagedDataDescriptorNode does not override CompareToImpl — follows the ILC singleton pattern (base class throws on duplicates)
• SList: Unified slist.h shared between CoreCLR VM and NativeAOT Runtime

Validation

• Build: build.cmd clr.aot+libs -rc release — 0 errors, 0 warnings
• Symbol verified in Runtime.WorkstationGC.lib via dumpbin
• cDAC reader tests: 1586/1586 passed
• tools.cdac tests: All passed
• Dump inspection: All 3 sub-descriptors verified (main: 4 contracts/11 types/20 globals, managed: System_Threading_Thread with fields, GC: 1 contract/10 types/41 globals)

[dotnet-policy-service]

Tagging subscribers to this area: @agocke, @dotnet/ilc-contrib
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

Adds cDAC contract descriptor generation to the NativeAOT runtime, plus an ILC-emitted managed sub-descriptor so diagnostic tools can inspect NativeAOT runtime/managed state via the shared contract mechanism.

Changes:

• Integrates NativeAOT cDAC contract descriptor (and GC sub-descriptors) into the NativeAOT CMake build and runtime libraries.
• Introduces a managed type layout sub-descriptor emitted by ILC (DotNetManagedContractDescriptor) and wires it into the NativeAOT descriptor as a sub-descriptor.
• Exposes select private NativeAOT runtime offsets/constants to the descriptor via the cdac_data<T> friend pattern and exports the main contract descriptor symbol for diagnostics.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/coreclr/tools/aot/ILCompiler/Program.cs	Adds the managed descriptor root provider to ILC compilation roots.
src/coreclr/tools/aot/ILCompiler.Compiler/ILCompiler.Compiler.csproj	Includes new managed descriptor provider/node sources in the build.
src/coreclr/tools/aot/ILCompiler.Compiler/Compiler/ManagedDataDescriptorProvider.cs	Registers managed types to be described and roots the descriptor + JSON blob.
src/coreclr/tools/aot/ILCompiler.Compiler/Compiler/DependencyAnalysis/ManagedDataDescriptorNode.cs	Emits a ContractDescriptor-shaped symbol containing JSON type layout data.
src/coreclr/nativeaot/Runtime/threadstore.h	Exposes ThreadStore private offsets for descriptor generation via cdac_data<>.
src/coreclr/nativeaot/Runtime/inc/MethodTable.h	Exposes MethodTable offsets and flag constants for descriptor consumption via cdac_data<>.
src/coreclr/nativeaot/Runtime/datadescriptor/datadescriptor.inc	Defines the NativeAOT data descriptor types/globals/contracts and sub-descriptors.
src/coreclr/nativeaot/Runtime/datadescriptor/datadescriptor.h	Provides includes and declares the managed sub-descriptor symbol address for inclusion.
src/coreclr/nativeaot/Runtime/datadescriptor/CMakeLists.txt	Adds descriptor generation targets for NativeAOT runtime + GC (wks/svr).
src/coreclr/nativeaot/Runtime/RuntimeInstance.h	Exposes RuntimeInstance private offsets via cdac_data<>.
src/coreclr/nativeaot/Runtime/Full/CMakeLists.txt	Links the generated descriptor libraries into WorkstationGC/ServerGC runtime libs.
src/coreclr/nativeaot/Runtime/CMakeLists.txt	Adds the datadescriptor subdirectory to the NativeAOT runtime build (non-WASM).
src/coreclr/nativeaot/BuildIntegration/Microsoft.NETCore.Native.targets	Exports DotNetRuntimeContractDescriptor symbol for diagnostics on all OSes.

Comments suppressed due to low confidence (1)

src/coreclr/nativeaot/Runtime/datadescriptor/CMakeLists.txt:73

• target_compile_definitions entries should be raw preprocessor symbols (e.g., SERVER_GC), not compiler flags. Passing -DSERVER_GC here will typically result in an invalid definition being forwarded to the compiler. Use SERVER_GC (or SERVER_GC=1) instead.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

[github-actions]

Note

This review was generated by Copilot (Claude Opus 4.6) and validated against the codebase. Multi-model review: findings synthesized from Claude Opus 4.6 (primary), Claude Sonnet 4.5, and GPT-5.3-Codex sub-agents.

🤖 Copilot Code Review — PR #126972

Holistic Assessment

Motivation: This PR extends the cDAC data descriptor infrastructure to NativeAOT, enabling diagnostic tools (SOS/cDAC) to inspect NativeAOT runtime state. This is clearly needed — NativeAOT currently lacks parity with CoreCLR's diagnostic data contract support. The changes include StressLog descriptors, GC sub-descriptors, managed type layout emission via [DataContract], and CMake/build integration.

Approach: The approach is sound — it reuses CoreCLR's established datadescriptor infrastructure and adapts it to NativeAOT's different memory layout (e.g., Thread inherits RuntimeThreadLocals instead of pointing to it). The attribute consolidation (CdacType+CdacField → single DataContractAttribute) simplifies the API surface. The refactoring of ManagedDataDescriptorNode to discover types at emission time via MetadataManager.GetTypesWithEETypes() is cleaner than the old provider-driven approach.

Summary: ⚠️ Needs Human Review. The code is well-structured and follows established patterns, but a human reviewer should verify (1) whether ILC-mangled type names in the managed sub-descriptor are the intended design for future NativeAOT contract implementations, and (2) that the missing n1 contract implementations for Thread and RuntimeTypeSystem are tracked for follow-up.

---

Detailed Findings

✅ JSON Descriptor Format — Correct

The new ManagedDataDescriptorNode emits the object-with-sigil format: "TypeName": { "!": size, "Field": offset }. This matches the cDAC ContractDescriptorParser.TypeDescriptorConverter exactly — verified at ContractDescriptorParser.cs:23,108-157 where the "!" property is parsed as the type size sigil and numeric field values are parsed as offsets. The switch from StringBuilder to Utf8JsonWriter also properly handles JSON escaping.

✅ GC Version Pre-Initialization — Correct

Setting g_gc_dac_vars.major_version_number = GC_INTERFACE_MAJOR_VERSION and minor_version_number = GC_INTERFACE_MINOR_VERSION before GC_Initialize in gcheaputilities.cpp:75-76 matches the established CoreCLR pattern (src/coreclr/vm/gcheaputilities.cpp:397-398). The GC's PopulateDacVars reads these incoming values to decide which features to populate (v2/v4/v6/v8 gates at gc.cpp:8343-8346), then overwrites to its actual version (2, 8). This enables the v6+ code path that assigns gc_descriptor.

✅ Server GC Linking Both Descriptors — Correct

Runtime.ServerGC now links both nativeaot_gc_wks_descriptor and nativeaot_gc_svr_descriptor (Full/CMakeLists.txt:31). This is correct because gcload.cpp:114-132 shows that even with FEATURE_SVR_GC defined, the runtime can fall back to WKS GC at runtime (e.g., single-CPU machines), which sets gc_descriptor = &GCContractDescriptorWKS. The two libraries have distinct symbol names (GCContractDescriptorWKS vs GCContractDescriptorSVR), so no duplicate symbol conflict. The PR description confirms this: "gc.cpp declares extern symbols for both when FEATURE_SVR_GC is defined."

✅ CompareToImpl Removal — Safe

The base SortableDependencyNode.CompareToImpl throws NotImplementedException("Multiple nodes of this type are not supported") (SortableDependencyNode.cs:36-39), which is the correct singleton behavior. Since ManagedDataDescriptorNode is only instantiated once in ManagedDataDescriptorProvider, the default is appropriate.

✅ WASM/Browser Exclusion — Correct and Necessary

Adding '$(_targetOS)' != 'browser' to the DotNetRuntimeContractDescriptor export condition in Microsoft.NETCore.Native.targets:240 is necessary because the datadescriptor subdirectory is excluded for WASM (Runtime/CMakeLists.txt:343: if(NOT CLR_CMAKE_TARGET_ARCH_WASM)), so the symbol won't exist. Note: DotNetRuntimeDebugHeader (line 238) correctly does NOT have browser exclusion because DebugHeader.cpp is compiled for all targets including WASM. The GC_DESCRIPTOR define is also correctly guarded for non-WASM (CMakeLists.txt:293-295).

✅ HEAP_ANALYZE Guards — Correct

Adding #ifdef HEAP_ANALYZE / #endif guards around InternalRootArray, InternalRootArrayIndex, and HeapAnalyzeSuccess in both gc/datadescriptor/datadescriptor.h and datadescriptor.inc is correct — NativeAOT disables HEAP_ANALYZE, so these fields don't exist and referencing them would cause link errors.

✅ StressLog Hardcoded Enabled — Matches CoreCLR

CDAC_GLOBAL(StressLogEnabled, T_UINT8, 1) is correct because STRESS_LOG is always defined in NativeAOT (stressLog.h:43-45: "let's keep STRESS_LOG defined always..."). This matches CoreCLR's pattern: StressLogEnabled=1 inside #ifdef STRESS_LOG and =0 outside (vm/datadescriptor/datadescriptor.inc:1462,1470). Note: if stress logging is not configured at runtime, g_pStressLog will be null — the reader should handle this gracefully, same as CoreCLR.

✅ ThreadStore Static Pointer — Clean Refactor

Moving from RuntimeInstance.m_pThreadStore → ThreadStore::s_pThreadStore as a static member with SPTR_DECL/SPTR_IMPL aligns NativeAOT's cDAC descriptor with CoreCLR's approach. The initialization in RuntimeInstance::Initialize (RuntimeInstance.cpp:322) correctly sets ThreadStore::s_pThreadStore = pThreadStore after both objects are created.

⚠️ Managed Type Names via NameMangler — Verify Intent (advisory, not merge-blocking)

ManagedDataDescriptorNode.cs:125 uses nameMangler.GetMangledTypeName(type) for the JSON type names. For System.Private.CoreLib types, NativeAotNameMangler (NativeAotNameMangler.cs:285-365) produces assembly-prefixed sanitized names like S_P_CoreLib_System_Threading_Thread rather than simple cDAC names like "ManagedThread" (what the old [CdacType("ManagedThread")] attribute produced).

This is a deliberate design change per Jan Kotas's feedback ("Remove Name property — use actual type/field names only"), and no existing cDAC contracts currently reference managed types from this sub-descriptor, so nothing breaks today. However, future NativeAOT-specific contract implementations (registered under version n1) will need to look up types using these compiler-mangled names, which are compiler-internal and could potentially change between compiler versions. A human reviewer should confirm this is the intended long-term design — mangled names tie the contract implementations to ILC's name mangling scheme.

⚠️ Contract Versions n1 — No Registered Implementations (advisory, not merge-blocking)

The descriptor declares Thread: n1 and RuntimeTypeSystem: n1 (datadescriptor.inc:173,175), but the only registered contract implementations are for c1 (CoreCLRContracts.cs:38,40). The n prefix clearly indicates NativeAOT-specific versions — these contracts will need NativeAOT-specific reader implementations that know about the different field names (e.g., AllocContext instead of RuntimeThreadLocals, OSId via m_threadId instead of CoreCLR's layout).

The contracts that ARE registered work: Exception: c1 ✅ and StressLog: c2 ✅. A human reviewer should confirm the missing n1 implementations are tracked for follow-up work.

💡 DataContractAttribute Naming — Minor Confusion Risk

The new System.Diagnostics.DataContractAttribute (internal, NativeAOT-only) shares its unqualified name with System.Runtime.Serialization.DataContractAttribute (public, widely used for serialization). No runtime conflict exists (different namespaces, the new one is internal sealed), but the naming overlap could cause momentary confusion during code review or IDE navigation. This was explicitly chosen per reviewer feedback to "avoid CDAC abbreviation" and "move to System.Diagnostics namespace."

💡 _startHelper Field No Longer Exported

The old code included [CdacField("StartHelper")] on Thread._startHelper. The new code removes the [DataContract] annotation from this field (Thread.NativeAot.cs:37). This appears intentional — StartHelper is a runtime implementation detail not needed by diagnostic contracts.

Generated by Code Review for issue #126972 · ◷

[jkotas]

We can do #include "../../inc/cdacdata.h" instead

[jkotas]

Can we delete pRuntimeInstance->m_pThreadStore - it is redundant now

[jkotas]

Suggested change

	/// runtime metadata. When applied to a field of such a type, indicates ILC should
	/// runtime metadata or symbols. When applied to a field of such a type, indicates ILC should

[MichalStrehovsky]

I know this was added in response to the other review comment (before commit 0d09c17), but this name mangling also has properties you probably don't want, like if there is a conflict after we flatten and sanitize the names, we're going add numbers to these:

runtime/src/coreclr/tools/Common/Compiler/NativeAotNameMangler.cs

Lines 360 to 361 in 3ac6e13

	// Ensure that name is unique and update our tables accordingly.
	name = DisambiguateName(name, deduplicator);

Making the S_P_CoreLib prefix part of the contract is also not great. The previous name mangling was better because cDAC infra can be fully in control of what it supports and how it does it.