Add debug information for runtime async methods #120303

jakobbotsch · 2025-10-01T19:35:35Z

Add new JIT-EE API to report back debug information about the generated state machine and continuations
Refactor debug info storage on VM side to be more easily extensible. The new format has either a thin or fat header. The fat header is used when we have either uninstrumented bounds, patchpoint info, rich debug info or async debug info, and stores the blob sizes of all of those components in addition to the bounds and vars. It is indicated by the first field (size of bounds) having value 0, which is an uncommon value for this field.
Add new async debug information to the storage on the VM side
Set target method desc for async resumption stubs, to be used for mapping from continuations back to the async IL function that it will resume.
Implement new format in R2R as well, bump R2R major version (might as well do this now as we expect to need to store async debug info in R2R during .NET 11 anyway)

- Add new JIT-EE API to report back debug information about the generated state machine and continuations - Refactor debug info storage on VM side to be more easily extensible. The new format has either a thin or fat header. The fat header is used when we have either uninstrumented bounds, patchpoint info, rich debug info or async debug info, and stores the blob sizes of all of those components in addition to the bounds and vars. - Add new async debug information to the storage on the VM side - Set get target method desc for async resumption stubs, to be used for mapping from continuations back to the async IL function that it will resume.

dotnet-policy-service · 2025-10-01T19:36:36Z

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

jakobbotsch · 2025-10-01T19:39:17Z

src/coreclr/inc/cordebuginfo.h

+        // Offset in continuation's data where this variable is stored
+        uint32_t Offset;


We probably need to include GCData offset here too, but I expect that we will end up with customized continuation layouts during .NET 11 that gets rid of the Data/GCData split, so I designed some of these types around that expectation. It also should be possible to derive the GCData offset by iterating the vars linearly, so we can probably make do with that for now.

Storing variables in arrays may work well for some scenarios, like AOT, which is sensitive to generation of types or GC layouts.

I think uint32_t Offset; may still work if it means "if Offset is greater than GCData length, subtract the length of GCData and continue in non-GC data"

Just in case we may end up using more than one shape, perhaps add some versioning/flavor marker in the AsyncSuspensionPoint?

I think uint32_t Offset; may still work if it means "if Offset is greater than GCData length, subtract the length of GCData and continue in non-GC data"

For some values we have data stored in both Data and GCData arrays, and to reconstruct the value we need both offsets. Perhaps we can just do 2x 16-bit offsets in this field until we get tailored continuation layouts. I think it's something to investigate further once we look at actually implementing the diagnostics that access the continuation values.

Just in case we may end up using more than one shape, perhaps add some versioning/flavor marker in the AsyncSuspensionPoint?

I expect we stabilize on something during .NET 11, so if we change it after I think we can take an R2R version update at the same time as well. If we do it like that we can version based on R2R module version (it's already what we do in DebugInfo.cs).

jakobbotsch · 2025-10-02T10:20:48Z

src/coreclr/vm/debuginfostore.cpp

    CONTRACTL
    {
-        NOTHROW;
+        THROWS;


RestorePatchpointInfo is called from JitPatchpointWorker, which has STANDARD_VM_CONTRACT. I think throwing should be ok, since we only throw here on an internal inconsistency in the compressed data when encountered by NibbleReader. That's consistent with the other Restore routines and saves us having to write separate decoding routines for the patchpoint info.

jakobbotsch · 2025-10-02T10:43:33Z

src/coreclr/vm/debuginfostore.h

 };

-#define DebugInfoBoundsHasInstrumentedBounds 0xFFFFFFFF
+#define DebugInfoFat 0


Switched this to 0 since encoding 0xFFFFFFFF takes up a full 6 bytes, and the value 0 is not a common value for cbBounds (JIT never reports empty bounds over all 1+ million methods in our SPMI collections, I suspect we always have at minimum a prolog bound)

Although I am somewhat worried it is possible to see this from the R2R path. I wonder if we should update R2R major version and teach crossgen2 to produce the fat header if necessary. We'll probably need to encode the debug info in R2R anyway during .NET 11, so I guess we might as well take that update now.

@davidwrighton Any thoughts on this?

Updating the R2R major version, and such is the thing to do.

jakobbotsch · 2025-10-02T12:58:03Z

src/coreclr/vm/codeman.cpp

+    CompressDebugInfo::RestoreRichDebugInfo(
+        fpNew, pNewData,
+        pDebugInfo,
+        ppInlineTree, pNumInlineTree,
+        ppRichMappings, pNumRichMappings);
+
+    return TRUE;
+}


I figured I might as well hook this one up in ReadyToRunJitManager too since the format now technically allows for R2R images that contain the rich debug info, eeven if crossgen2 doesn't produce it.

…mental APIs in async tests

jakobbotsch · 2025-10-02T15:00:06Z

.github/prompts/add-new-jit-ee-api.prompt.md

 ---
 mode: 'agent'
-tools: ['githubRepo', 'codebase', 'terminalLastCommand']
+tools: ['fetch', 'codebase', 'runCommands', 'usages', 'search', 'think']


Updating these tools based on @EgorBo's instructions (I used the prompt to add the JIT-EE boilerplate, but the agent was not making the changes automatically without allowing it access to these tools)

src/coreclr/inc/cordebuginfo.h

VSadov · 2025-10-03T07:05:55Z

src/coreclr/inc/cordebuginfo.h

+        // Index of inline tree node containing the IL offset (0 for root)
+        uint32_t Inlinee;
+        // IL offset that resulted in the creation of the suspension point.
+        uint32_t ILOffset;


if we care about size, can IL offsets inside a method be uint16_t ?

I don't think there is a 2^16 size limit on IL, but in any case we do not care about size in these data types. The actual storage of these is compressed in the VM, so when these values are small, they consume little space.

VSadov · 2025-10-03T07:07:02Z

src/coreclr/inc/cordebuginfo.h

+    struct AsyncInfo
+    {
+        // Number of suspension points in the method.
+        uint32_t NumSuspensionPoints;


can this be uint16_t?

Same reason as above I don't think we need to limit this.

Copilot

Pull Request Overview

This PR adds a new JIT-EE API reportAsyncDebugInfo to report debug information for runtime async methods. The implementation enables the JIT to provide suspension point and continuation variable information back to the VM for improved debugging of async methods.

Key changes:

Adds new reportAsyncDebugInfo API to the JIT-EE interface with structures for async debug information
Refactors debug info storage format to support extensible "fat headers" for additional debug data
Bumps ReadyToRun major version to 17 to accommodate the new debug info format

Reviewed Changes

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

Show a summary per file

File	Description
src/tests/async/Directory.Build.props	Adds SYSLIB5007 warning suppression for async tests
src/coreclr/vm/jitinterface.h	Adds reportAsyncDebugInfo method declaration and member variables for async debug data
src/coreclr/vm/jitinterface.cpp	Implements reportAsyncDebugInfo method and integrates async debug info into compression
src/coreclr/vm/debuginfostore.h	Adds structures and methods for handling async debug info in the new fat header format
src/coreclr/vm/debuginfostore.cpp	Implements compression/decompression of async debug info and fat header logic
src/coreclr/vm/codeman.h	Adds GetAsyncDebugInfo virtual method to IJitManager and implementations
src/coreclr/vm/codeman.cpp	Implements async debug info retrieval across different JIT managers
src/coreclr/tools/superpmi/*	Updates SuperPMI shims to handle the new reportAsyncDebugInfo API
src/coreclr/tools/aot/*	Adds ReadyToRun support for fat header format and async debug info
src/coreclr/jit/*	Implements async transformation debug info collection and reporting
src/coreclr/inc/*	Updates interface definitions, version numbers, and adds async debug structures

src/coreclr/tools/superpmi/superpmi/icorjitinfo.cpp

src/coreclr/tools/Common/JitInterface/CorInfoImpl.cs

src/coreclr/jit/lclvars.cpp

src/coreclr/tools/aot/ILCompiler.ReadyToRun/JitInterface/CorInfoImpl.ReadyToRun.cs

jakobbotsch added 3 commits October 1, 2025 14:54

Set target method desc for resumption stubs

b7bb968

Add JIT-EE boilerplate

d5d0864

github-actions bot added the area-CodeGen-coreclr CLR JIT compiler in src/coreclr/src/jit and related components such as SuperPMI label Oct 1, 2025

jakobbotsch changed the title ~~Add debug information for runtime async information~~ Add debug information for runtime async methods Oct 1, 2025

dotnet-policy-service bot assigned jakobbotsch Oct 1, 2025

jakobbotsch commented Oct 1, 2025

View reviewed changes

jakobbotsch added 8 commits October 1, 2025 21:42

Update managed view

6addd0e

Remove TODOs

6a5bf19

Leaf transition

262260a

Comment

4e2a829

Delete unused enum

820afa9

Restore comment

3621eae

Fix osx build

f597424

Fix GCC build

6bb6cee

am11 added the runtime-async label Oct 1, 2025

build-analysis bot mentioned this pull request Oct 2, 2025

"We stopped hearing from agent Azure Pipelines 32. Verify the agent machine is running and has a healthy network connection" dotnet/dnceng#1886

Open

3 tasks

Change sentinel value, fix contract

f580e3f

jakobbotsch commented Oct 2, 2025

View reviewed changes

jakobbotsch added 3 commits October 2, 2025 13:41

Bump R2R

55b9522

Clean up

c9c64be

Expose async debug info accessor APIs

db77446

jakobbotsch commented Oct 2, 2025

View reviewed changes

jakobbotsch added 5 commits October 2, 2025 16:18

Missed bumping R2R version for naot

c808390

Fix reverse mapping to IL local nums

3ec5160

Fix monotonicity for async vars

bb12c77

Code style

bf3364b

Fix JIT-EE prompt tools from Egor's instructions, allow use of experi…

b49f38f

…mental APIs in async tests

jakobbotsch commented Oct 2, 2025

View reviewed changes

noahfalk reviewed Oct 3, 2025

View reviewed changes

src/coreclr/inc/cordebuginfo.h Show resolved Hide resolved

VSadov reviewed Oct 3, 2025

View reviewed changes

jakobbotsch marked this pull request as ready for review October 3, 2025 08:29

jakobbotsch requested a review from MichalStrehovsky as a code owner October 3, 2025 08:29

Copilot AI review requested due to automatic review settings October 3, 2025 08:29

Copilot AI reviewed Oct 3, 2025

View reviewed changes

jakobbotsch requested review from noahfalk, davidwrighton, VSadov and tommcdon October 3, 2025 08:38

Address feedback, make comment less misleading

d1bf49f

build-analysis bot mentioned this pull request Oct 3, 2025

AppHost tests fail with "Failure extracting contents of the application bundle." #119249

Open

agocke requested review from jkoritzinsky, eduardo-vp and jtschuster October 3, 2025 17:17

		// Offset in continuation's data where this variable is stored
		uint32_t Offset;

Add debug information for runtime async methods #120303

Are you sure you want to change the base?

Add debug information for runtime async methods #120303

Conversation

jakobbotsch commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dotnet-policy-service bot commented Oct 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakobbotsch Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakobbotsch commented Oct 1, 2025 •

edited

Loading

jakobbotsch Oct 3, 2025 •

edited

Loading