Add debug information for runtime async methods

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

@@ -1,23 +1,23 @@
 ---
 mode: 'agent'
-tools: ['githubRepo', 'codebase', 'terminalLastCommand']
+tools: ['fetch', 'codebase', 'runCommands', 'usages', 'search', 'think']
 description: 'Add a new API to the JIT-VM (aka JIT-EE) interface in the codebase.'
 ---
 
 #### 1 — Goal
 
-Implement **one** new JIT-VM (also known as JIT-EE) API and all supporting glue. 
+Implement **one** new JIT-VM (also known as JIT-EE) API and all supporting glue.
 The JIT-VM interface defines the APIs through which the JIT compiler communicates with the runtime (VM).
 
 #### 2 — Prerequisites for the model
 
 * You have full repo access
-* You may run scripts (e.g., `.sh` or `.bat`) 
+* You may run scripts (e.g., `.sh` or `.bat`)
 * Ask **clarifying questions** before the first code change if anything (signature, types, platform constraints) is unclear.
 
 #### 3 — Required user inputs
 
-Ask the user for a C-like signature of the new API if it's not provided. 
+Ask the user for a C-like signature of the new API if it's not provided.
 Suggest `<repo_root>/src/coreclr/tools/Common/JitInterface/ThunkGenerator/ThunkInput.txt` file as a reference. Example:
 
 ```
@@ -83,8 +83,8 @@ Use the correct directory for the script to run.
 +}
 ```
 
-6. Now implement the most complex part - SuperPMI. SuperPMI acts as a (de)serializer for JIT-VM queries in order 
-to then replay them without the actual VM to speed up jit-diffs and other scenarios. All parameters and return 
+6. Now implement the most complex part - SuperPMI. SuperPMI acts as a (de)serializer for JIT-VM queries in order
+to then replay them without the actual VM to speed up jit-diffs and other scenarios. All parameters and return
 values recorded/restored using special primitve types and helpers. We need to update the following files:
 
 * `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h`:
@@ -96,7 +96,7 @@ Go through each of them one by one.
 
 * `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h`:
 Define two `Agnostic_*` types for input arguments and another one for output parameters (return value, output arguments).
- Do not create them if one of the generics ones can be re-used such as `DLD`, `DD`, `DLDL`, etc. Use `DWORD*` 
+ Do not create them if one of the generics ones can be re-used such as `DLD`, `DD`, `DLDL`, etc. Use `DWORD*`
  like types for integers. Inspect the whole file to see how other APIs are defined.
 
 * `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/lwmlist.h`:
@@ -126,7 +126,7 @@ Now add a new element to `enum mcPackets` enum in the same file. Example:
 ```
 
 * `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.cpp`:
-Add the implementation of the 3 methods to `methodcontext.cpp` at the end of it. 
+Add the implementation of the 3 methods to `methodcontext.cpp` at the end of it.
 Consider other similar methods in the file for reference. Do not change implementations of other methods in the file. Example:
 
 ```diff

src/coreclr/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncHelpers.CoreCLR.cs

@@ -228,9 +228,8 @@ private interface IRuntimeAsyncTaskOps<T>
             static abstract void PostToSyncContext(T task, SynchronizationContext syncCtx);
         }
 
-        /// <summary>
-        /// Represents a wrapped runtime async operation.
-        /// </summary>
+        // Represents execution of a chain of suspended and resuming runtime
+        // async functions.
         private sealed class RuntimeAsyncTask<T> : Task<T>, ITaskCompletionAction
         {
             public RuntimeAsyncTask()
@@ -310,9 +309,8 @@ public static void PostToSyncContext(RuntimeAsyncTask<T> task, SynchronizationCo
             }
         }
 
-        /// <summary>
-        /// Represents a wrapped runtime async operation.
-        /// </summary>
+        // Represents execution of a chain of suspended and resuming runtime
+        // async functions.
         private sealed class RuntimeAsyncTask : Task, ITaskCompletionAction
         {
             public RuntimeAsyncTask()
@@ -377,33 +375,53 @@ public static void PostToSyncContext(RuntimeAsyncTask task, SynchronizationConte
 
         private static class RuntimeAsyncTaskCore
         {
+            private unsafe struct NextContinuationData
+            {
+                public NextContinuationData* Next;
+                public Continuation* NextContinuation;
+            }
+
+            // To be used for async stack walking
+            [ThreadStatic]
+            private static unsafe NextContinuationData* t_nextContinuation;
+
             public static unsafe void DispatchContinuations<T, TOps>(T task) where T : Task, ITaskCompletionAction where TOps : IRuntimeAsyncTaskOps<T>
             {
                 ExecutionAndSyncBlockStore contexts = default;
                 contexts.Push();
                 Continuation continuation = TOps.GetContinuationState(task);
 
+                ref NextContinuationData* nextContRef = ref t_nextContinuation;
+                NextContinuationData nextContinuationData;
+                nextContinuationData.Next = nextContRef;
+                nextContinuationData.NextContinuation = &continuation;
+
+                nextContRef = &nextContinuationData;
+
                 while (true)
                 {
                     try
                     {
-                        Continuation? newContinuation = continuation.Resume(continuation);
+                        Continuation? curContinuation = continuation;
+                        Debug.Assert(curContinuation != null);
+                        Debug.Assert(curContinuation.Next != null);
+                        continuation = curContinuation.Next;
+
+                        Continuation? newContinuation = curContinuation.Resume(curContinuation);
 
                         if (newContinuation != null)
                         {
-                            newContinuation.Next = continuation.Next;
+                            newContinuation.Next = continuation;
                             HandleSuspended<T, TOps>(task);
                             contexts.Pop();
+                            t_nextContinuation = nextContinuationData.Next;
                             return;
                         }
-
-                        Debug.Assert(continuation.Next != null);
-                        continuation = continuation.Next;
                     }
                     catch (Exception ex)
                     {
-                        Continuation nextContinuation = UnwindToPossibleHandler(continuation);
-                        if (nextContinuation.Resume == null)
+                        Continuation handlerContinuation = UnwindToPossibleHandler(continuation);
+                        if (handlerContinuation.Resume == null)
                         {
                             // Tail of AsyncTaskMethodBuilderT.SetException
                             bool successfullySet = ex is OperationCanceledException oce ?
@@ -412,6 +430,8 @@ public static unsafe void DispatchContinuations<T, TOps>(T task) where T : Task,
 
                             contexts.Pop();
 
+                            t_nextContinuation = nextContinuationData.Next;
+
                             if (!successfullySet)
                             {
                                 ThrowHelper.ThrowInvalidOperationException(ExceptionResource.TaskT_TransitionToFinal_AlreadyCompleted);
@@ -420,9 +440,8 @@ public static unsafe void DispatchContinuations<T, TOps>(T task) where T : Task,
                             return;
                         }
 
-                        nextContinuation.SetException(ex);
-
-                        continuation = nextContinuation;
+                        handlerContinuation.SetException(ex);
+                        continuation = handlerContinuation;
                     }
 
                     if (continuation.Resume == null)
@@ -431,6 +450,8 @@ public static unsafe void DispatchContinuations<T, TOps>(T task) where T : Task,
 
                         contexts.Pop();
 
+                        t_nextContinuation = nextContinuationData.Next;
+
                         if (!successfullySet)
                         {
                             ThrowHelper.ThrowInvalidOperationException(ExceptionResource.TaskT_TransitionToFinal_AlreadyCompleted);
@@ -442,6 +463,7 @@ public static unsafe void DispatchContinuations<T, TOps>(T task) where T : Task,
                     if (QueueContinuationFollowUpActionIfNecessary<T, TOps>(task, continuation))
                     {
                         contexts.Pop();
+                        t_nextContinuation = nextContinuationData.Next;
                         return;
                     }
                 }
@@ -451,10 +473,11 @@ private static Continuation UnwindToPossibleHandler(Continuation continuation)
             {
                 while (true)
                 {
-                    Debug.Assert(continuation.Next != null);
-                    continuation = continuation.Next;
                     if ((continuation.Flags & CorInfoContinuationFlags.CORINFO_CONTINUATION_NEEDS_EXCEPTION) != 0)
                         return continuation;
+
+                    Debug.Assert(continuation.Next != null);
+                    continuation = continuation.Next;
                 }
             }
 
@@ -575,7 +598,7 @@ private static bool QueueContinuationFollowUpActionIfNecessary<T, TOps>(T task,
             }
         }
 
-        // Change return type to ThunkTask<T?> -- no benefit since this is used for Task returning thunks only
+        // Change return type to RuntimeAsyncTask<T?> -- no benefit since this is used for Task returning thunks only
 #pragma warning disable CA1859
         // When a Task-returning thunk gets a continuation result
         // it calls here to make a Task that awaits on the current async state.

src/coreclr/inc/clrconfigvalues.h

@@ -715,7 +715,7 @@ RETAIL_CONFIG_DWORD_INFO(EXTERNAL_EnableRiscV64Zbb,             W("EnableRiscV64
 #endif
 
 // Runtime-async
-RETAIL_CONFIG_DWORD_INFO(UNSUPPORTED_RuntimeAsync, W("RuntimeAsync"), 0, "Enables runtime async method support")
+RETAIL_CONFIG_DWORD_INFO(UNSUPPORTED_RuntimeAsync, W("RuntimeAsync"), 1, "Enables runtime async method support")
 
 ///
 /// Uncategorized

src/coreclr/inc/cordebuginfo.h

@@ -431,4 +431,33 @@ class ICorDebugInfo
         // Source information about the IL instruction in the inlinee
         SourceTypes Source;
     };
+
+    struct AsyncContinuationVarInfo
+    {
+        // IL number of variable (or one of the special IL numbers, like TYPECTXT_ILNUM)
+        uint32_t VarNumber;
+        // Index in continuation's byte[] data where this variable is stored, or 0xFFFFFFFF if the
+        // variable does not have any byte[] data
+        uint32_t Offset;
+        // Index in continuation's object[] data where this variable's GC pointers are stored, or 0xFFFFFFFF
+        // if the variable does not have any GC pointers
+        uint32_t GCIndex;
+    };
+
+    struct AsyncSuspensionPoint
+    {
+        // Offset of this suspension point's resumption point.
+        uint32_t NativeResumeOffset;
+        // Logical return address of the async call (join point of synchronous and resuming paths)
+        uint32_t NativeJoinOffset;
+        // Count of AsyncContinuationVarInfo in array of locals starting where
+        // the previous suspension point's locals end.
+        uint32_t NumContinuationVars;
+    };
+
+    struct AsyncInfo
+    {
+        // Number of suspension points in the method.
+        uint32_t NumSuspensionPoints;
+    };
 };

src/coreclr/inc/corinfo.h

@@ -2912,6 +2912,16 @@ class ICorStaticInfo
             uint32_t                          numMappings         // [IN] Number of rich mappings
             ) = 0;
 
+    // Report async debug information to EE.
+    // The arrays are expected to be allocated with allocateArray
+    // and ownership is transferred to the EE with this call.
+    virtual void reportAsyncDebugInfo(
+            ICorDebugInfo::AsyncInfo*             asyncInfo,         // [IN] Async method information
+            ICorDebugInfo::AsyncSuspensionPoint*  suspensionPoints,  // [IN] Array of async suspension points, indexed by state number
+            ICorDebugInfo::AsyncContinuationVarInfo* vars,           // [IN] Array of async continuation variable info
+            uint32_t                              numVars            // [IN] Number of entries in the async vars array
+            ) = 0;
+
     // Report back some metadata about the compilation to the EE -- for
     // example, metrics about the compilation.
     virtual void reportMetadata(

src/coreclr/inc/icorjitinfoimpl_generated.h

@@ -453,6 +453,12 @@ void reportRichMappings(
           ICorDebugInfo::RichOffsetMapping* mappings,
           uint32_t numMappings) override;
 
+void reportAsyncDebugInfo(
+          ICorDebugInfo::AsyncInfo* asyncInfo,
+          ICorDebugInfo::AsyncSuspensionPoint* suspensionPoints,
+          ICorDebugInfo::AsyncContinuationVarInfo* vars,
+          uint32_t numVars) override;
+
 void reportMetadata(
           const char* key,
           const void* value,

src/coreclr/inc/jiteeversionguid.h

@@ -37,11 +37,11 @@
 
 #include <minipal/guid.h>
 
-constexpr GUID JITEEVersionIdentifier = { /* 3d2bdd20-eced-4a07-b9fb-227ce7f55fcd */
-    0x3d2bdd20,
-    0xeced,
-    0x4a07,
-    {0xb9, 0xfb, 0x22, 0x7c, 0xe7, 0xf5, 0x5f, 0xcd}
+constexpr GUID JITEEVersionIdentifier = { /* 421f544d-55cb-4e2a-a43d-c308a8c071d7 */
+    0x421f544d,
+    0x55cb,
+    0x4e2a,
+    {0xa4, 0x3d, 0xc3, 0x08, 0xa8, 0xc0, 0x71, 0xd7}
   };
 
 #endif // JIT_EE_VERSIONING_GUID_H

src/coreclr/inc/readytorun.h

@@ -19,10 +19,10 @@
 //  src/coreclr/nativeaot/Runtime/inc/ModuleHeaders.h
 // If you update this, ensure you run `git grep MINIMUM_READYTORUN_MAJOR_VERSION`
 // and handle pending work.
-#define READYTORUN_MAJOR_VERSION 16
+#define READYTORUN_MAJOR_VERSION 17
 #define READYTORUN_MINOR_VERSION 0x0000
 
-#define MINIMUM_READYTORUN_MAJOR_VERSION 16
+#define MINIMUM_READYTORUN_MAJOR_VERSION 17
 
 // R2R Version 2.1 adds the InliningInfo section
 // R2R Version 2.2 adds the ProfileDataInfo section
@@ -47,6 +47,7 @@
 // R2R Version 14 changed x86 code generation to use funclets
 // R2R Version 15 removes double to int/uint helper calls
 // R2R Version 16 replaces the compression format for debug boundaries with a new format that is smaller and more efficient to parse
+// R2R Version 17 adds support for producing "fat" debug information (that e.g. can include async debug info)
 
 struct READYTORUN_CORE_HEADER
 {

src/coreclr/jit/ICorJitInfo_names_generated.h

@@ -112,6 +112,7 @@ DEF_CLR_API(setBoundaries)
 DEF_CLR_API(getVars)
 DEF_CLR_API(setVars)
 DEF_CLR_API(reportRichMappings)
+DEF_CLR_API(reportAsyncDebugInfo)
 DEF_CLR_API(reportMetadata)
 DEF_CLR_API(allocateArray)
 DEF_CLR_API(freeArray)

src/coreclr/jit/ICorJitInfo_wrapper_generated.hpp

@@ -1067,6 +1067,17 @@ void WrapICorJitInfo::reportRichMappings(
     API_LEAVE(reportRichMappings);
 }
 
+void WrapICorJitInfo::reportAsyncDebugInfo(
+          ICorDebugInfo::AsyncInfo* asyncInfo,
+          ICorDebugInfo::AsyncSuspensionPoint* suspensionPoints,
+          ICorDebugInfo::AsyncContinuationVarInfo* vars,
+          uint32_t numVars)
+{
+    API_ENTER(reportAsyncDebugInfo);
+    wrapHnd->reportAsyncDebugInfo(asyncInfo, suspensionPoints, vars, numVars);
+    API_LEAVE(reportAsyncDebugInfo);
+}
+
 void WrapICorJitInfo::reportMetadata(
           const char* key,
           const void* value,