[cDAC] RuntimeSignatureDecoder and centralized Signature contract (2/5)

[max-charlamb]

Summary

Part 2 of 5 stacked PRs splitting #126408. Builds on #127395 (merged).

This PR adds a cDAC ECMA-335 signature decoder that closely mirrors System.Reflection.Metadata.SignatureDecoder and supports the two runtime-only extensions used in CoreCLR-internal signatures: ELEMENT_TYPE_INTERNAL (0x21) and ELEMENT_TYPE_CMOD_INTERNAL (0x22). The decoder is then used by both the Signature contract (for field signatures) and the StackWalk contract (for signature-based GC reference scanning of transition frames).

What this PR contains

RuntimeSignatureDecoder (SRM-aligned polyfill):

• RuntimeSignatureDecoder<TType, TGenericContext> -- readonly struct mirroring SRM's SignatureDecoder<TType, TGenericContext> (DecodeType, DecodeFieldSignature, DecodeMethodSignature, DecodeLocalSignature, all taking ref BlobReader).
• IRuntimeSignatureTypeProvider<TType, TGenericContext> -- superset of SRM's ISignatureTypeProvider adding GetInternalType(TargetPointer) and GetInternalModifiedType(TargetPointer, TType, bool) for the two runtime-only encodings.
• SignatureTypeProvider (the existing field-signature provider) implements IRuntimeSignatureTypeProvider so internal types in field signatures resolve via RuntimeTypeSystem.GetTypeHandle.

Signature-based GC reference scanning in StackWalk:

• GcSignatureTypeProvider (internal, in StackWalkHelpers) classifies each method-signature parameter as Ref, Interior, Other (value type or larger-than-slot), or None.
• A new GcSignatureContext(TypeHandle classContext, MethodDescHandle methodContext) record struct is plumbed through RuntimeSignatureDecoder<GcTypeKind, GcSignatureContext> so ELEMENT_TYPE_VAR / ELEMENT_TYPE_MVAR placeholders resolve to the method's actual class / method instantiation -- matching native SigTypeContext-driven PeekElemTypeNormalized behavior.
• GcScanner.PromoteCallerStack constructs the provider per call and walks the TransitionBlock using a reserved-slot count derived from IsInstance / return-buffer / RequiresInstArg / IsAsyncMethod / ARM64 x8, reporting each parameter slot as a GC reference, interior pointer, or skip.
• Signature acquisition mirrors native MethodDesc::GetSig: prefers IsStoredSigMethodDesc (dynamic, EEImpl, array methods) before falling back to the metadata token, so caller-stack roots of dynamic and array-method transition frames are handled. Stored sigs are pinned with an inline fixed block and read via a BlobReader, matching the existing SigFormat.cs pattern.
• This is the cDAC equivalent of native TransitionFrame::PromoteCallerStack and is used for PrestubMethodFrame, CallCountingHelperFrame, and the StubDispatchFrame / ExternalMethodFrame fallback when no GCRefMap is available.

Signature contract surface stays minimal:

• ISignatureDecoder continues to expose only DecodeFieldSignature(BlobHandle, ModuleHandle, TypeHandle).
• GC-specific decoding lives entirely inside the StackWalk contract; the Signature contract has no GC dependencies.

cDAC documentation:

• docs/design/datacontracts/SignatureDecoder.md -- describes RuntimeSignatureDecoder, IRuntimeSignatureTypeProvider, and the ELEMENT_TYPE_INTERNAL / CMOD_INTERNAL extensions; refreshed DecodeFieldSignature code sample.
• docs/design/datacontracts/StackWalk.md -- new "Signature-Based Scanning" section under GC stack reference scanning, covering GcSignatureTypeProvider (with module scoping, GcSignatureContext, and enum normalization), the PromoteCallerStack algorithm, the reserved-slot table, and limitations vs. native.

Testing

• Build: clean, 0 warnings / 0 errors.
• 1921 / 1921 cDAC unit tests pass.
• Behavioral verification against the legacy DAC happens via the GC-stress verification harness introduced later in the PR series.

Note

This PR description was created with AI assistance from Copilot.

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @tommcdon, @dotnet/dotnet-diag
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

This PR is part of the cDAC signature-decoding refactor, introducing a custom RuntimeSignatureDecoder capable of handling runtime-internal signature element types (ELEMENT_TYPE_INTERNAL / ELEMENT_TYPE_CMOD_INTERNAL) and centralizing GC-oriented signature decoding behind the ISignatureDecoder contract.

Changes:

• Added RuntimeSignatureDecoder plus signature-reader abstractions (ISignatureReader, span/blob-backed readers) to support decoding from different signature sources.
• Extended the ISignatureDecoder contract with DecodeMethodSignatureForGC(...) and promoted GcTypeKind to a public abstraction.
• Updated stack GC scanning (GcScanner) and signature type providers to route decoding through the centralized contract API.

Reviewed changes

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

Show a summary per file

File	Description
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/GC/GcScanner.cs	Switches caller-signature decoding to the ISignatureDecoder.DecodeMethodSignatureForGC contract API.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/SignatureTypeProvider.cs	Updates the type provider to implement IRuntimeSignatureTypeProvider and adds internal-type callbacks.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/SignatureReaders.cs	Introduces abstractions for reading signature bytes from spans and metadata blobs.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/SignatureDecoder_1.cs	Adds module-scoped GC provider caching and implements DecodeMethodSignatureForGC using RuntimeSignatureDecoder.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/RuntimeSignatureDecoder.cs	New runtime-aware ECMA-335-ish signature decoder with support for internal runtime element types.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/GcSignatureTypeProvider.cs	Moves/updates GC classification provider to implement the runtime-aware provider interface and classify internal types via RTS.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Contracts/ISignatureDecoder.cs	Extends the public contract surface with GcTypeKind and DecodeMethodSignatureForGC.

Comments suppressed due to low confidence (1)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/GcSignatureTypeProvider.cs:26

• GcSignatureTypeProvider stores _target and _moduleHandle but never uses either of them (the implementation uses the target method parameter instead). This is dead state that should be removed, or the implementation should consistently use the stored fields if they're intended for future module/target-scoped behavior.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Signature/SignatureTypeProvider.cs:25

• The private field _target is assigned in the constructor but never read in this type, which will trigger CS0414 (and in this repo, warnings are treated as errors by default). Please remove _target (and its assignment) or start using it (e.g., for validation) to avoid build breaks.

    private readonly Target _target;
    private readonly Contracts.ModuleHandle _moduleHandle;
    private readonly Contracts.ILoader _loader;
    private readonly Contracts.IRuntimeTypeSystem _runtimeTypeSystem;

    public SignatureTypeProvider(Target target, Contracts.ModuleHandle moduleHandle)
    {
        _target = target;
        _moduleHandle = moduleHandle;
        _loader = target.Contracts.Loader;
        _runtimeTypeSystem = target.Contracts.RuntimeTypeSystem;

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/GC/GcScanner.cs:380

• isValueTypeThis is always initialized to false and never updated, so this is never reported with GC_CALL_INTERIOR even for value-type instance methods. Since you already resolve the declaring TypeHandle earlier, it seems like this should be computed (e.g., via IRuntimeTypeSystem.IsValueType(typeHandle)) and included in the existing try/catch alongside RequiresInstArg / IsAsyncMethod.

        bool hasThis = methodSig.Header.IsInstance;
        bool hasRetBuf = methodSig.ReturnType is GcTypeKind.Other;
        bool requiresInstArg = false;
        bool isAsync = false;
        bool isValueTypeThis = false;

        try
        {
            requiresInstArg = rts.RequiresInstArg(mdh);
            isAsync = rts.IsAsyncMethod(mdh);
        }
        catch
        {
        }

        PromoteCallerStackHelper(transitionBlock, methodSig, hasThis, hasRetBuf,
            requiresInstArg, isAsync, isValueTypeThis, scanContext);
    }

[Copilot]

Pull request overview

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

[jkotas]

This talks a lot about the APIs. The data contract description should be centered on the data contract (what the bytes in memory mean). In this case, it should say that it is the ECMA-335 signature format with two additional internal element types.

The APIs are secondary for the data contract docs. We use the APIs and pseudo in the data contract docs just because of it is easier to use for explanation than English. The APIs do not have to be documented in detail.

[max-charlamb]

I reworked the entire markdown to follow these guidelines

[jkotas]

I am not sure "polyfill" is the right term to use. Polyfill implements a new feature for an old version of the underlying system, so that you can use the same API regardless of whether your app runs on old or new version.

I would call it "clone with added support for the internal element types".

[max-charlamb]

Updated description

[jkotas]

The comment on these says "[cDAC] [RuntimeTypeSystem]: Contract depends on the values of ELEMENT_TYPE_INTERNAL and ELEMENT_TYPE_CMOD_INTERNAL.". Should it be updated to mention this contract?

[max-charlamb]

Added [Signature] in addition to the existing comment.

[jkotas]

Naming nit: Should this be called "Signature" or "RuntimeSignature"?

Other data contract names describe the data, not the thing used to crack the data. For example, the GC info data contract is called GCInfo. It is not called GCInfoDecoder (a component that is used to crack the data).

[max-charlamb]

Renamed to "Signature"

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Contracts/ISignature.cs:16

• The PR description still refers to "ISignatureDecoder" as the contract surface, but the code here renames the contract to ISignature/Signature. Please update the PR description (and any other narrative docs outside this repo, if applicable) to match the new contract name to avoid confusion for reviewers and downstream consumers.

[jkotas]

Suggested change

Tag `3` in the `TypeDefOrRefOrSpec` encoding (ECMA-335 §II.23.2.8) is reserved and decoders throw `BadImageFormatException` when they encounter it.

This is duplicating ECMA-335 §II.23.2

[jkotas]

Suggested change

	This contract describes the format of method, field, and local-variable signatures stored in target memory. Signatures use the ECMA-335 §II.23.2 format with two CoreCLR-internal element types added by the runtime.
	This contract describes the format of method, field, and local-variable signatures stored in target memory. Signatures use the ECMA-335 §II.23.2 format with CoreCLR-internal element types added by the runtime.

Chances are we are going to add a third one. Avoid hardcoding "two" in the text to make future proof.

[jkotas]

Should we track these TODOs as issues?