Route QCall exceptions through marshalling

docs/design/coreclr/botr/corelib.md

@@ -77,29 +77,29 @@ QCalls should be implemented with a C-style method signature. This makes it easi
 Do not replicate the comments into your actual QCall implementation. This is for illustrative purposes.
 
 ```CSharp
-class Foo
+partial class Foo
 {
-    // All QCalls should have the following DllImport attribute
-    [DllImport(RuntimeHelpers.QCall, EntryPoint = "Foo_BarInternal", CharSet = CharSet.Unicode)]
-
-    // QCalls should always be static extern.
-    private static extern bool BarInternal(int flags, string inString, StringHandleOnStack retString);
+    // QCalls that use BEGIN_QCALL must use the hidden last parameter error handler.
+    [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
+    [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Foo_BarInternal", StringMarshalling = StringMarshalling.Utf16)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static partial bool BarInternal(int flags, string inString, StringHandleOnStack retString);
 
     // Many QCalls have a thin managed wrapper around them to perform
     // as much work prior to the transition as possible. An example would be
     // argument validation which is easier in managed than native code.
-    public string Bar(int flags)
+    public string Bar(int flags, string inString)
     {
         if (flags != 0)
             throw new ArgumentException("Invalid flags");
 
-        string retString = null;
+        string? retString = null;
         // The strings are returned from QCalls by taking address
-        // of a local variable using StringHandleOnStack
-        if (!BarInternal(flags, this.Id, new StringHandleOnStack(ref retString)))
+        // of a local variable using StringHandleOnStack.
+        if (!BarInternal(flags, inString, new StringHandleOnStack(ref retString)))
             FatalError();
 
-        return retString;
+        return retString!;
     }
 }
 ```
@@ -114,7 +114,8 @@ The QCall entrypoint has to be registered in tables in [vm\qcallentrypoints.cpp]
 
 ```C++
 // All QCalls should be free functions and tagged with QCALLTYPE and extern "C"
-extern "C" BOOL QCALLTYPE Foo_BarInternal(int flags, LPCWSTR wszString, QCall::StringHandleOnStack retString)
+extern "C" BOOL QCALLTYPE Foo_BarInternal(
+    int flags, LPCWSTR wszString, QCall::StringHandleOnStack retString, QCallExceptionStatus* qcallError)
 {
     // All QCalls should have QCALL_CONTRACT.
     // It is alias for THROWS; GC_TRIGGERS; MODE_PREEMPTIVE.
@@ -132,7 +133,7 @@ extern "C" BOOL QCALLTYPE Foo_BarInternal(int flags, LPCWSTR wszString, QCall::S
     BOOL retVal = FALSE;
 
     // The body has to be enclosed in BEGIN_QCALL/END_QCALL macro.
-    // It is necessary for exception handling.
+    // It initializes qcallError and captures exceptions for the managed error handler.
     BEGIN_QCALL;
 
     // Argument validation would ideally be in managed, but in some cases
@@ -158,6 +159,9 @@ extern "C" BOOL QCALLTYPE Foo_BarInternal(int flags, LPCWSTR wszString, QCall::S
 }
 ```
 
+QCalls that return before entering `BEGIN_QCALL`, including no-op fast paths and code excluded
+by platform conditionals, must explicitly set `*qcallError = 0` before returning.
+
 ## FCall functional behavior
 
 FCalls allow more flexibility in terms of passing object references around, but with higher code complexity and more opportunities to make mistakes. Additionally, for any FCall of non-trivial length, explicitly poll for whether a garbage collection must occur. Failing to do so will lead to starvation issues if managed code repeatedly calls the FCall method in a tight loop, because FCalls execute while the thread only allows the GC to run in a cooperative manner.

src/coreclr/System.Private.CoreLib/System.Private.CoreLib.csproj

@@ -205,6 +205,7 @@
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\AsyncHelpers.ValueTaskSourceContinuation.cs" />
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\AsyncHelpers.RuntimeAsyncYielder.cs" />
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\AsyncProfiler.CoreCLR.cs" />
+    <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\QCallExceptionStatus.cs" />
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\RuntimeAsyncTaskContinuation.cs" />
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\RuntimeHelpers.CoreCLR.cs" />
     <Compile Include="$(BclSourcesRoot)\System\Runtime\CompilerServices\StaticsHelpers.cs" />

src/coreclr/System.Private.CoreLib/src/Internal/Runtime/CompilerHelpers/ThrowHelpers.cs

@@ -11,6 +11,7 @@ namespace Internal.Runtime.CompilerHelpers
     internal static unsafe partial class ThrowHelpers
     {
         [DoesNotReturn]
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ExceptionNative_ThrowAmbiguousResolutionException")]
         private static partial void ThrowAmbiguousResolutionException(MethodTable* targetType, MethodTable* interfaceType, void* methodDesc);
 
@@ -25,6 +26,7 @@ internal static void ThrowAmbiguousResolutionException(
         }
 
         [DoesNotReturn]
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ExceptionNative_ThrowEntryPointNotFoundException")]
         private static partial void ThrowEntryPointNotFoundException(MethodTable* targetType, MethodTable* interfaceType, void* methodDesc);
 
@@ -39,6 +41,7 @@ internal static void ThrowEntryPointNotFoundException(
         }
 
         [DoesNotReturn]
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ExceptionNative_ThrowMethodAccessException")]
         private static partial void ThrowMethodAccessExceptionInternal(void* caller, void* callee);
 
@@ -53,6 +56,7 @@ internal static void ThrowMethodAccessException(
         }
 
         [DoesNotReturn]
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ExceptionNative_ThrowFieldAccessException")]
         private static partial void ThrowFieldAccessExceptionInternal(void* caller, void* callee);
 
@@ -67,6 +71,7 @@ internal static void ThrowFieldAccessException(
         }
 
         [DoesNotReturn]
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ExceptionNative_ThrowClassAccessException")]
         private static partial void ThrowClassAccessExceptionInternal(void* caller, void* callee);
 

src/coreclr/System.Private.CoreLib/src/Internal/VersionResilientHashCode.CoreCLR.cs

@@ -13,6 +13,7 @@ namespace Internal
     /// </summary>
     internal static partial class VersionResilientHashCode
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "VersionResilientHashCode_TypeHashCode")]
         private static partial int TypeHashCode(QCallTypeHandle typeHandle);
 

src/coreclr/System.Private.CoreLib/src/System/AppContext.CoreCLR.cs

@@ -16,6 +16,7 @@ private static bool IsKnownHostProperty(string name)
                     or "PLATFORM_RESOURCE_ROOTS"
                     or "APP_PATHS";
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "AppContext_TryGetHostPropertyValue", StringMarshalling = StringMarshalling.Utf16)]
         [return: MarshalAs(UnmanagedType.Bool)]
         private static partial bool TryGetHostPropertyValue(string name, StringHandleOnStack retValue);

src/coreclr/System.Private.CoreLib/src/System/ArgIterator.cs

@@ -39,6 +39,7 @@ public ArgIterator(RuntimeArgumentHandle arglist)
             Init(ThisPtr, cookie);
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ArgIterator_Init")]
         private static partial void Init(ArgIterator* thisPtr, IntPtr cookie);
 
@@ -55,6 +56,7 @@ public ArgIterator(RuntimeArgumentHandle arglist, void* ptr)
             Init(ThisPtr, cookie, ptr);
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ArgIterator_Init2")]
         private static partial void Init(ArgIterator* thisPtr, IntPtr cookie, void* ptr);
 
@@ -81,6 +83,7 @@ public TypedReference GetNextArg()
             return result;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ArgIterator_GetNextArg")]
         private static partial void GetNextArg(ArgIterator* thisPtr, TypedReference* pResult);
 
@@ -116,6 +119,7 @@ public TypedReference GetNextArg(RuntimeTypeHandle rth)
             return result;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ArgIterator_GetNextArg2")]
         private static partial void GetNextArg(ArgIterator* thisPtr, QCallTypeHandle rth, TypedReference* pResult);
 
@@ -141,6 +145,7 @@ public RuntimeTypeHandle GetNextArgType()
             return RuntimeTypeHandle.FromIntPtr(GetNextArgType(ThisPtr));
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ArgIterator_GetNextArgType")]
         private static partial IntPtr GetNextArgType(ArgIterator* thisPtr);
 

src/coreclr/System.Private.CoreLib/src/System/Array.CoreCLR.cs

@@ -15,6 +15,7 @@ namespace System
     // IList<U> and IReadOnlyList<U>, where T : U dynamically.  See the SZArrayHelper class for details.
     public abstract partial class Array : ICloneable, IList, IStructuralComparable, IStructuralEquatable
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Array_CreateInstance")]
         private static unsafe partial void InternalCreate(QCallTypeHandle type, int rank, int* pLengths, int* pLowerBounds,
             [MarshalAs(UnmanagedType.Bool)] bool fromArrayType, ObjectHandleOnStack retArray);
@@ -35,6 +36,7 @@ private static unsafe Array InternalCreateFromArrayType(RuntimeType arrayType, i
             return retArray!;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Array_Ctor")]
         private static unsafe partial void Ctor(MethodTable* pArrayMT, uint dwNumArgs, int* pArgList, ObjectHandleOnStack retArray);
 
@@ -349,6 +351,7 @@ internal sealed unsafe partial class ArrayInitializeCache : RuntimeType.IGeneric
         {
             internal readonly delegate*<ref byte, void> ConstructorEntrypoint;
 
+            [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
             [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Array_GetElementConstructorEntrypoint")]
             private static partial delegate*<ref byte, void> GetElementConstructorEntrypoint(QCallTypeHandle arrayType);
 

src/coreclr/System.Private.CoreLib/src/System/CLRConfig.cs

@@ -15,6 +15,7 @@ internal static bool GetBoolValue(string switchName, out bool exist)
             return GetConfigBoolValue(switchName, out exist);
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ClrConfig_GetConfigBoolValue", StringMarshalling = StringMarshalling.Utf16)]
         [return: MarshalAs(UnmanagedType.Bool)]
         private static partial bool GetConfigBoolValue(string configSwitchName, [MarshalAs(UnmanagedType.Bool)] out bool exist);

src/coreclr/System.Private.CoreLib/src/System/ComAwareWeakReference.CoreCLR.cs

@@ -9,6 +9,7 @@ namespace System
 {
     internal sealed partial class ComAwareWeakReference
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ComWeakRefToObject")]
         private static partial void ComWeakRefToObject(IntPtr pComWeakRef, ObjectHandleOnStack retRcw);
 
@@ -38,6 +39,7 @@ internal static bool PossiblyComObject(object target)
 #endif // FEATURE_COMINTEROP
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ObjectToComWeakRef")]
         private static partial IntPtr ObjectToComWeakRef(ObjectHandleOnStack retRcw);
 

src/coreclr/System.Private.CoreLib/src/System/Delegate.CoreCLR.cs

@@ -532,6 +532,7 @@ private struct BindToMethodDetails
             public GCHandle loaderAllocatorGCHandle; // The loader allocator needed if the delegate needs to keep it alive
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_BindToMethodName", StringMarshalling = StringMarshalling.Utf8)]
         [return: MarshalAs(UnmanagedType.Bool)]
         private static partial bool BindToMethodName(MethodTable* pDelegateMT, MethodTable *pTargetMT, QCallTypeHandle methodType, string method, DelegateBindingFlags flags, ObjectHandleOnStack targetParameter, out BindToMethodDetails bindToMethodDetails);
@@ -567,6 +568,7 @@ private bool BindToMethodInfo(object? target, IRuntimeMethodInfo method, Runtime
             return ret;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_BindToMethodInfo")]
         [return: MarshalAs(UnmanagedType.Bool)]
         private static partial bool BindToMethodInfo(MethodTable* pDelegateMT, MethodTable *pTargetMT, RuntimeMethodHandleInternal method, QCallTypeHandle methodType, DelegateBindingFlags flags, ObjectHandleOnStack targetParameter, out BindToMethodDetails bindToMethodDetails);
@@ -640,12 +642,14 @@ private void DelegateConstruct(object target, IntPtr method)
                 _target = target;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_Construct")]
         private static partial void Construct(MethodTable* pDelegateMT, MethodTable* pTargetMT, IntPtr method, out BindToMethodDetails bindToMethodDetails);
 
         [MethodImpl(MethodImplOptions.InternalCall)]
         private static extern unsafe void* GetMulticastInvoke(MethodTable* pMT);
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_GetMulticastInvokeSlow")]
         private static unsafe partial void* GetMulticastInvokeSlow(MethodTable* pMT);
 
@@ -681,6 +685,7 @@ private static unsafe IRuntimeMethodInfo CreateMethodInfo(MethodDesc* methodDesc
             return methodInfo!;
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_CreateMethodInfo")]
         private static unsafe partial void CreateMethodInfo(MethodDesc* methodDesc, ObjectHandleOnStack retMethodInfo);
 
@@ -691,6 +696,7 @@ private static unsafe IRuntimeMethodInfo CreateMethodInfo(MethodDesc* methodDesc
             return GetMethodDesc(ObjectHandleOnStack.Create(ref instance));
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_GetMethodDesc")]
         private static unsafe partial MethodDesc* GetMethodDesc(ObjectHandleOnStack instance);
 
@@ -887,6 +893,7 @@ internal static IntPtr AdjustTarget(object target, IntPtr methodPtr)
             }
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_AdjustTarget")]
         private static partial IntPtr AdjustTarget(MethodTable* targetMT, IntPtr methodPtr);
 
@@ -896,6 +903,7 @@ internal void InitializeVirtualCallStub(IntPtr methodPtr)
             InitializeVirtualCallStub(ObjectHandleOnStack.Create(ref d), methodPtr);
         }
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Delegate_InitializeVirtualCallStub")]
         private static partial void InitializeVirtualCallStub(ObjectHandleOnStack d, IntPtr methodPtr);
 

src/coreclr/System.Private.CoreLib/src/System/Diagnostics/Debugger.cs

@@ -11,6 +11,7 @@ namespace System.Diagnostics
 {
     public static partial class Debugger
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "DebugDebugger_Break")]
         private static partial void BreakInternal();
 
@@ -83,6 +84,7 @@ static void NotifyOfCrossThreadDependencySlow()
         // Posts a custom notification for the attached debugger.  If there is no
         // debugger attached, has no effect.  The debugger may or may not
         // report the notification depending on its settings.
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "DebugDebugger_CustomNotification")]
         private static partial void CustomNotification(ObjectHandleOnStack data);
 

src/coreclr/System.Private.CoreLib/src/System/Diagnostics/StackFrame.CoreCLR.cs

@@ -56,6 +56,7 @@ private void BuildStackFrame(int skipFrames, bool needFileInfo)
         private static bool AppendStackFrameWithoutMethodBase(StringBuilder sb) => false;
 #pragma warning restore IDE0060
 
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "StackFrame_GetMethodDescFromNativeIP")]
         private static partial RuntimeMethodHandleInternal GetMethodDescFromNativeIP(IntPtr ip);
 

src/coreclr/System.Private.CoreLib/src/System/Diagnostics/StackTrace.CoreCLR.cs

@@ -9,6 +9,7 @@ namespace System.Diagnostics
 {
     public partial class StackTrace
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "StackTrace_GetStackFramesInternal")]
         private static partial void GetStackFramesInternal(ObjectHandleOnStack sfh, [MarshalAs(UnmanagedType.Bool)] bool fNeedFileInfo, ObjectHandleOnStack e);
 

src/coreclr/System.Private.CoreLib/src/System/Enum.CoreCLR.cs

@@ -11,6 +11,7 @@ namespace System
 {
     public abstract partial class Enum
     {
+        [ErrorHandler(typeof(QCallExceptionStatusMarshaller), ErrorLocation.HiddenLastParameter)]
         [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "Enum_GetValuesAndNames")]
         private static partial void GetEnumValuesAndNames(QCallTypeHandle enumType, ObjectHandleOnStack values, ObjectHandleOnStack names, Interop.BOOL getNames);