Implement cDAC TraverseLoaderHeap via Loader contract

[Copilot]

Implements ISOSDacInterface13::TraverseLoaderHeap (with and without kind) in the managed cDAC stack via the Loader contract. Adds separate cDAC types for LoaderHeap and ExplicitControlLoaderHeap, with a LoaderHeapKind enum embedded in GetFirstLoaderHeapBlock.

Description

C++ VM

• loaderheap.h: forward-declares cdac_data<T>, adds friend struct cdac_data<UnlockedLoaderHeapBaseTraversable>, and provides a cdac_data<UnlockedLoaderHeapBaseTraversable> specialization exposing FirstBlock — matching the pattern used in arraylist.h and loaderallocator.hpp.
• datadescriptor.inc: two separate cDAC types (LoaderHeap, ExplicitControlLoaderHeap) each with a FirstBlock field via cdac_data<UnlockedLoaderHeapBaseTraversable>::FirstBlock; LoaderHeapBlock fields via direct offsetof (public struct members).

Managed contracts

• LoaderHeapKind enum (Normal = 0, ExplicitControl = 1) in ILoader.cs; GetFirstLoaderHeapBlock takes a LoaderHeapKind and dispatches to Data.LoaderHeap or Data.ExplicitControlLoaderHeap accordingly — unknown kinds throw NotImplementedException.
• New Data/ExplicitControlLoaderHeap.cs (IData<T>) reads FirstBlock from the ExplicitControlLoaderHeap cDAC type.
• DataType.ExplicitControlLoaderHeap added.

Legacy DAC (SOSDacImpl.cs)

TraverseLoaderHeap (no-kind) and TraverseLoaderHeapWithKind implemented independently via the same ILoader contract methods — no cross-dependency. kind maps to LoaderHeapKind; out-of-range values return E_NOTIMPL.

Tests

28 unit tests covering empty heap, single block, and multi-block scenarios across both heap kinds and 4 pointer-size variants.

Docs

Loader.md updated with LoaderHeapKind enum, updated GetFirstLoaderHeapBlock signature, ExplicitControlLoaderHeap data descriptor row, and revised algorithm pseudocode for both dispatch paths.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[dotnet-policy-service]

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

[Copilot]

Pull request overview

Implements ISOSDacInterface13::TraverseLoaderHeap in the managed cDAC stack using the Loader contract, adding new cDAC data descriptors/types for loader heaps and blocks so SOS can enumerate heap blocks via the contract layer.

Changes:

• Add LoaderHeap / ExplicitControlLoaderHeap / LoaderHeapBlock cDAC types (native + managed) and LoaderHeapKind dispatch in ILoader.
• Implement TraverseLoaderHeap (kind + no-kind) in SOSDacImpl using the ILoader APIs and update COM interface callback signatures.
• Add unit tests and update design docs for the new traversal APIs/descriptors.

Reviewed changes

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

Show a summary per file

File	Description
src/native/managed/cdac/tests/LoaderHeapTests.cs	Adds unit tests for normal/explicit-control loader heap traversal.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Legacy/SOSDacImpl.cs	Implements TraverseLoaderHeap using the managed ILoader contract (with DEBUG cross-validation).
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Legacy/ISOSDacInterface.cs	Updates TraverseLoaderHeap callback signatures to typed unmanaged function pointers.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/LoaderHeapBlock.cs	Adds managed IData<> model for LoaderHeapBlock fields.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/LoaderHeap.cs	Adds managed IData<> model for normal loader heap FirstBlock.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ExplicitControlLoaderHeap.cs	Adds managed IData<> model for explicit-control heap FirstBlock.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Loader_1.cs	Implements new ILoader APIs for loader heap traversal.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/DataType.cs	Adds new DataType entries for loader heap descriptors.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Contracts/ILoader.cs	Introduces LoaderHeapKind and new loader heap traversal APIs.
src/coreclr/vm/datadescriptor/datadescriptor.inc	Adds native cDAC descriptors for LoaderHeap, ExplicitControlLoaderHeap, and LoaderHeapBlock.
src/coreclr/inc/loaderheap.h	Exposes FirstBlock offset(s) for cDAC via cdac_data<> specializations.
docs/design/datacontracts/Loader.md	Documents the new loader heap traversal APIs and descriptors.
docs/design/datacontracts/GC.md	Fixes a spelling issue in GC contract docs (with one remaining typo noted).

[Copilot]

Pull request overview

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

[max-charlamb]

We should also rebase/merge on top of main and fix any conflicts or problems that arise.

[rcj1]

@jkotas adding the virtual destructor did not cause the correct offsetof() to be picked up by the cDAC in, for example, LoaderAllocator. DavidWr has indicated that it is not reliable / platform dependent whether this will be optimized out.

[jkotas]

@jkotas adding the virtual destructor did not cause the correct offsetof() to be picked up by the cDAC in, for example, LoaderAllocator. DavidWr has indicated that it is not reliable / platform dependent whether this will be optimized out.

Ok.

I think we are still exposed to the fragility of offsetof and multiple inheritance as copilot pointed it in #125129 (comment) . If it is not causing observable issues, we can leave it like that.

[noahfalk]

From what I can see, this LoaderHeapKind appears to have no impact on the final result. Both kinds derive from UnlockedLoaderHeapBaseTraversable and the m_pFirstBlock pointer that we need is also a member of that type. Let me know if I am missing something.

I'm thinking we should drop this kind argument from the API. If we did I'm guessing a number of other things would change too:

• change the cDac contract to depend on a single UnlockedLoaderHeapBaseTraversable::m_pFirst field instead of per-derived type definitions of the same field.
• get rid of the kind enum
• Reduce the two IData types down to a single one for the base class
• Change SOSDacInterface13.TraverseLoaderHeap impl to ignore the kind argument from the caller

[jkotas]

From what I can see, this LoaderHeapKind appears to have no impact on the final result

Unfortunately, it does have an impact as discussed above. Loader heap implementation uses C++ multiple inheritance that introduces multiple different this pointers for the same object.

I agree that it would be nice to do what you are proposing. We would have to get the multiple inheritance under control first.

[noahfalk]

Ah I walked into the midst unaware!

What if we removed the multiple inheritance with a pattern like this:

class LoaderHeapBackout final : public ILoaderHeapBackout
{
   LoaderHeap* m_owner;
   void RealBackoutMem(...) override { m_owner->RealBackoutMem(...); }
};
   
class UnlockedLoaderHeapBase : public UnlockedLoaderHeapBaseTraversable
{
   LoaderHeapBackout m_backout; // pass out the address of this field when an
                                // ILoaderHeapBackout is needed.
};

IMO the conceptual simplification to data contract would be worth doing a small runtime refactor.