Merge branch 'main' into opt-out-pooled

Author: jakobbotsch

docs/design/coreclr/botr/readytorun-format.md

@@ -413,6 +413,36 @@ which encodes an extra 4-byte representing the end RVA of the unwind info blob.
 |      4 |    4 | Unwind info end RVA (1 plus RVA of last byte)
 |      8 |    4 | GC info start RVA
 
+### RUNTIME_FUNCTION (wasm, size = 8 bytes)
+
+On WebAssembly, the `RUNTIME_FUNCTION` uses a virtual IP as the `BeginAddress` rather than an RVA
+into the image. The high bit of the `BeginAddress` field indicates whether the entry represents a
+funclet (1) or a main method body (0). The remaining 31 bits encode the virtual IP of the start of
+the function or funclet.
+
+| Offset | Size | Value
+|-------:|-----:|:-----
+|      0 |    4 | Virtual IP (bits 30:0) | IsFunclet flag (bit 31)
+|      4 |    4 | UnwindData RVA (GC info follows immediately after the unwind blob)
+
+The table is terminated by a sentinel entry with all bits set (`0xFFFFFFFF`), followed by a 4-byte
+value containing the minimum WebAssembly function table index for the image.
+
+### UnwindInfo (wasm)
+
+On WebAssembly, the unwind info blob associated with each `RUNTIME_FUNCTION` entry is encoded as
+two consecutive ULEB128 values:
+
+| Order | Encoding | Value
+|------:|:---------|:-----
+|     1 | ULEB128  | Frame size in bytes (the number of bytes to unwind from the stack)
+|     2 | ULEB128  | Virtual IP count divided by 2 (the number of virtual IPs logically present in the function, halved)
+
+The virtual IP count (after multiplying by 2) gives the span of virtual IPs covered by this
+function or funclet. All virtual IPs are forced to even numbers so that the runtime can force all virtual
+ips to have odd numbers and fit into the address space in a manner which cannot conflict with either interpreter
+IPs or PortableEntryPoint structures.
+
 ## ReadyToRunSectionType.MethodDefEntryPoints
 
 This section contains a native format sparse array (see 4 Native Format) that maps methoddef rows to

docs/design/datacontracts/RuntimeMutableTypeSystem.md

@@ -0,0 +1,84 @@
+# Contract RuntimeMutableTypeSystem
+
+This contract exposes runtime type system information about changes that occurred after the initial type load, such as from EnC or HotReload.
+
+## APIs of contract
+
+```csharp
+IEnumerable<TargetPointer> EnumerateAddedFieldDescs(TypeHandle typeHandle, bool staticFields);
+bool IsFieldDescEnCNew(TargetPointer fieldDescPointer);
+```
+
+## Version 1
+
+### Data descriptors
+
+| Data Descriptor Name   | Field                    | Meaning |
+| ---                    | ---                      | --- |
+| `Module`               | `EnCClassList`           | Address of the embedded `CUnorderedArray` (whose `CUnorderedArrayBase` portion holds `Count`/`Table`) holding the module's `EnCEEClassData*` entries. Optional: only present when EditAndContinue is configured. |
+| `UnorderedArrayBase`       | `Count`                  | Number of valid entries currently stored in the array. |
+| `UnorderedArrayBase`       | `Table`                  | Pointer to the backing storage holding the array's entries. |
+| `EnCEEClassData`       | `MethodTable`            | Pointer to the `MethodTable` whose EnC data is held by this entry. |
+| `EnCEEClassData`       | `AddedInstanceFields`    | Head of the linked list of `EnCAddedFieldElement` for added instance fields. |
+| `EnCEEClassData`       | `AddedStaticFields`      | Head of the linked list of `EnCAddedFieldElement` for added static fields. |
+| `EnCAddedFieldElement` | `Next`                   | Pointer to the next `EnCAddedFieldElement` in the linked list. |
+| `EnCAddedFieldElement` | `FieldDesc`              | Address of the embedded `EnCFieldDesc` (layout-compatible with `FieldDesc`). |
+| `FieldDesc`            | `DWord2`                 | Packed flags/offset word containing the field's offset; the EnC-new sentinel `FieldOffsetNewEnc` is stored here for fields that have been added but do not yet have storage assigned. |
+
+### Globals used
+
+| Global Name           | Type   | Purpose |
+| ---                   | ---    | --- |
+| `FieldOffsetNewEnc`   | uint   | Sentinel offset value stored in `FieldDesc::DWord2` for added fields whose storage has not yet been allocated. |
+
+### Required contracts
+
+| Contract            |
+| ---                 |
+| `IRuntimeTypeSystem` |
+| `ILoader`            |
+
+```csharp
+internal enum FieldDescFlags2 : uint
+{
+    OffsetMask = 0x07ffffff,
+}
+
+IEnumerable<TargetPointer> EnumerateAddedFieldDescs(TypeHandle typeHandle, bool staticFields)
+{
+    // get modulePtr and moduleHandle from typeHandle
+    // if there is no EnC data, yield break
+    TargetPointer classList = modulePtr + /* Module::EnCClassList offset */;
+    uint classListCount = target.Read<uint>(classList + /* UnorderedArrayBase::Count offset */);
+    TargetPointer classListTable = target.ReadPointer(classList + /* UnorderedArrayBase::Table offset */);
+    TargetPointer classDataPtr = TargetPointer.Null;
+
+    for (uint i = 0; i < classListCount; i++)
+    {
+        // search on EnC data for data that matches the method table
+        TargetPointer entry = target.ReadPointer(classListTable + i * target.PointerSize);
+        TargetPointer mt = target.ReadPointer(entry + /* EnCEEClassData::MethodTable offset */);
+        if (mt == typeHandle.Address)
+        {
+            classDataPtr = entry;
+            break;
+        }
+    }
+
+    // enumerate fields that have been added
+    TargetPointer node = staticFields ? target.ReadPointer(classDataPtr + /* EnCEEClassData::AddedStaticFields offset */)
+        : target.ReadPointer(classDataPtr + /* EnCEEClassData::AddedInstanceFields offset */);
+    while (node != TargetPointer.Null)
+    {
+        yield return node + /* EnCAddedFieldElement::FieldDesc offset */;
+        node = target.ReadPointer(node + /* EnCAddedFieldElement::Next offset */);
+    }
+}
+
+bool IsFieldDescEnCNew(TargetPointer fieldDescPointer)
+{
+    uint DWord2 = target.Read<uint>(fieldDescPointer + /* FieldDesc::DWord2 offset */);
+    uint offset = DWord2 & (uint)FieldDescFlags2.OffsetMask;
+    return offset == target.ReadGlobal<uint>("FieldOffsetNewEnc");
+}
+```

docs/design/datacontracts/RuntimeTypeSystem.md

@@ -51,6 +51,11 @@ partial interface IRuntimeTypeSystem : IContract
     public virtual TargetCodePointer GetSlot(TypeHandle typeHandle, uint slot);
 
     public virtual uint GetBaseSize(TypeHandle typeHandle);
+    // The number of bytes of instance fields stored in an object of this type on the GC heap.
+    // Equivalent to the native MethodTable::GetNumInstanceFieldBytes(), which is computed as
+    // GetBaseSize() minus the EEClass base-size padding (the trailing alignment/min-object-size
+    // bytes included in BaseSize but not occupied by actual instance fields).
+    public virtual uint GetNumInstanceFieldBytes(TypeHandle typeHandle);
     // The component size is only available for strings and arrays.  It is the size of the element type of the array, or the size of an ECMA 335 character (2 bytes)
     public virtual uint GetComponentSize(TypeHandle typeHandle);
 
@@ -276,8 +281,9 @@ TargetPointer GetMTOfEnclosingClass(TargetPointer fieldDescPointer);
 uint GetFieldDescMemberDef(TargetPointer fieldDescPointer);
 bool IsFieldDescThreadStatic(TargetPointer fieldDescPointer);
 bool IsFieldDescStatic(TargetPointer fieldDescPointer);
+bool IsFieldDescRVA(TargetPointer fieldDescPointer);
 uint GetFieldDescType(TargetPointer fieldDescPointer);
-uint GetFieldDescOffset(TargetPointer fieldDescPointer, FieldDefinition fieldDef);
+uint GetFieldDescOffset(TargetPointer fieldDescPointer, FieldDefinition? fieldDef);
 TargetPointer GetFieldDescStaticAddress(TargetPointer fieldDescPointer, bool unboxValueTypes = true);
 TargetPointer GetFieldDescThreadStaticAddress(TargetPointer fieldDescPointer, TargetPointer thread, bool unboxValueTypes = true);
 ```
@@ -581,6 +587,8 @@ Contracts used:
 
     public uint GetBaseSize(TypeHandle TypeHandle) => !typeHandle.IsMethodTable() ? (uint)0 : _methodTables[TypeHandle.Address].Flags.BaseSize;
 
+    public uint GetNumInstanceFieldBytes(TypeHandle TypeHandle) => !typeHandle.IsMethodTable() ? (uint)0 : _methodTables[TypeHandle.Address].Flags.BaseSize - GetClassData(TypeHandle).BaseSizePadding;
+
     public uint GetComponentSize(TypeHandle TypeHandle) =>!typeHandle.IsMethodTable() ? (uint)0 :  GetComponentSize(_methodTables[TypeHandle.Address]);
 
     public TargetPointer GetClassPointer(TypeHandle TypeHandle)
@@ -1189,7 +1197,7 @@ Contracts used:
 
 ### MethodDesc
 
-The version 1 `MethodDesc` APIs depend on the following globals:
+The `MethodDesc` APIs of RuntimeTypeSystem version 1 depend on the following globals:
 
 | Global name | Meaning |
 | --- | --- |
@@ -2072,7 +2080,14 @@ Getting a MethodDesc for a certain slot in a MethodTable
 
 ### FieldDesc
 
-The version 1 FieldDesc APIs depend on the following data descriptors:
+The FieldDesc APIs of RuntimeTypeSystem version 1 depend on the following globals:
+
+| Global name | Meaning |
+| --- | --- |
+| `FieldOffsetBigRVA` | Sentinel value of `FieldDesc::DWord2` indicating the field is an RVA static whose offset is too large to encode in the bitfield; the real offset must be read from the field's metadata (`FieldDefinition.GetRelativeVirtualAddress`). |
+| `FieldOffsetNewEnc` | Sentinel value of `FieldDesc`'s offset bitfield indicating the field was added via Edit-and-Continue and does not yet have backing storage. |
+
+The FieldDesc APIs of RuntimeTypeSystem version 1 depend on the following data descriptors:
 | Data Descriptor Name | Field | Meaning |
 | --- | --- | --- |
 | `FieldDesc` | `MTOfEnclosingClass` | Pointer to method table of enclosing class |
@@ -2085,6 +2100,7 @@ internal enum FieldDescFlags1 : uint
     TokenMask = 0xffffff,
     IsStatic = 0x1000000,
     IsThreadStatic = 0x2000000,
+    IsRVA = 0x4000000,
 }
 
 internal enum FieldDescFlags2 : uint
@@ -2116,18 +2132,26 @@ bool IsFieldDescStatic(TargetPointer fieldDescPointer)
     return (DWord1 & (uint)FieldDescFlags1.IsStatic) != 0;
 }
 
+bool IsFieldDescRVA(TargetPointer fieldDescPointer)
+{
+    uint DWord1 = target.Read<uint>(fieldDescPointer + /* FieldDesc::DWord1 offset */);
+    return (DWord1 & (uint)FieldDescFlags1.IsRVA) != 0;
+}
+
 uint GetFieldDescType(TargetPointer fieldDescPointer)
 {
     uint DWord2 = target.Read<uint>(fieldDescPointer + /* FieldDesc::DWord2 offset */);
     return (DWord2 & (uint)FieldDescFlags2.TypeMask) >> 27;
 }
 
-uint GetFieldDescOffset(TargetPointer fieldDescPointer)
+uint GetFieldDescOffset(TargetPointer fieldDescPointer, FieldDefinition? fieldDef)
 {
     uint DWord2 = target.Read<uint>(fieldDescPointer + /* FieldDesc::DWord2 offset */);
     if (DWord2 == _target.ReadGlobal<uint>("FieldOffsetBigRVA"))
     {
-        return (uint)fieldDef.GetRelativeVirtualAddress();
+        if (fieldDef is null)
+            throw new ArgumentNullException(nameof(fieldDef), "Field definition is required for big RVA fields");
+        return (uint)fieldDef.Value.GetRelativeVirtualAddress();
     }
     return DWord2 & (uint)FieldDescFlags2.OffsetMask;
 }

docs/design/datacontracts/StackWalk.md

@@ -67,6 +67,13 @@ DebuggerEvalData GetDebuggerEvalData(TargetPointer funcEvalFrameAddress);
 // Walks the stack and returns all GC references found on each frame.
 // This is the primary API for GC reference enumeration, used by SOSDacImpl.GetStackReferences.
 IReadOnlyList<StackReferenceData> WalkStackReferences(ThreadData threadData);
+
+// Returns a context for the thread, trying (in order): the debugger filter context,
+// the OS thread context, or a context derived from the explicit Frame chain.
+byte[] GetContext(ThreadData threadData, ThreadContextSource contextSource, uint contextFlags);
+
+// Returns the saved TargetContext pointer carried by the head Frame, if applicable.
+TargetPointer GetRedirectedContextPointer(ThreadData threadData);
 ```
 
 ## Version 1
@@ -577,6 +584,14 @@ IReadOnlyList<StackReferenceData> WalkStackReferences(ThreadData threadData)
 
 The implementation uses the same stack walk algorithm as `CreateStackWalk`, but integrates the GC-aware `Filter` directly (rather than consuming pre-generated frames) and performs GC reference enumeration at each frame. See [GC Stack Reference Scanning](#gc-stack-reference-scanning) for details.
 
+`GetContext` returns a thread context by trying three sources in order: (1) the debugger filter context from `ThreadData.DebuggerFilterContext` (when `ThreadContextSource.Debugger` is requested), (2) the OS thread context via `TryGetThreadContext`, or (3) a context derived from walking the explicit Frame chain (`Thread::Frame` linked list), returning the first frame that yields a usable context:
+* If the current Frame is an `InterpreterFrame`, clear the context and update it from the Frame. Return the resulting bytes.
+* Otherwise, clear the context and update it from the current Frame; accept the context when both the stack pointer and instruction pointer are non-zero (e.g. `RedirectedThreadFrame`, `InlinedCallFrame`, `DynamicHelperFrame`). Mark `RawContextFlags = FullContextFlags` so callers know SP/PC/FP are valid.
+
+If no Frame in the chain produces a usable context (thread is not running managed code), a zeroed context of the target architecture's size is returned.
+
+`GetRedirectedContextPointer` returns the saved `TargetContext` pointer carried by the head Frame when that Frame is a `RedirectedThreadFrame` (a `ResumableFrame`). Otherwise it returns `TargetPointer.Null`.
+
 ### GC Stack Reference Scanning
 
 `WalkStackReferences` scans the stack for GC references by walking through each frame and reporting live object references and interior pointers. The native equivalent is `DacStackReferenceWalker` which calls `GcStackCrawlCallBack` at each frame.

docs/design/datacontracts/Thread.md

@@ -53,6 +53,8 @@ record struct ThreadData (
     bool HasUnhandledException;
     TargetPointer NextThread;
     TargetPointer ThreadHandle;
+    bool IsInteropDebuggingHijacked;
+    TargetPointer DebuggerFilterContext;
 );
 ```
 
@@ -74,7 +76,6 @@ void ResetDebuggerControlledThreadState(TargetPointer thread, DebuggerControlled
 void GetStackLimitData(TargetPointer threadPointer, out TargetPointer stackBase, out TargetPointer stackLimit, out TargetPointer frameAddress);
 TargetPointer IdToThread(uint id);
 TargetPointer GetThreadLocalStaticBase(TargetPointer threadPointer, TargetPointer tlsIndexPtr);
-byte[] GetContext(TargetPointer threadPointer, ThreadContextSource contextSource, uint contextFlags);
 ```
 
 ## Version 1
@@ -131,6 +132,7 @@ The contract additionally depends on these data descriptors
 | `Thread` | `LinkNext` | Pointer to get next thread |
 | `Thread` | `ExceptionTracker` | Pointer to exception tracking information |
 | `Thread` | `DebuggerFilterContext` | Pointer to the debugger filter context for the thread |
+| `Thread` | `InteropDebuggingHijacked` | Whether the thread has been hijacked for interop debugging |
 | `Thread` | `RuntimeThreadLocals` | Pointer to some thread-local storage |
 | `Thread` | `ThreadLocalDataPtr` | Pointer to thread local data structure |
 | `Thread` | `ThreadHandle` | OS thread handle (optional, Windows only; readers should expect `TargetPointer.Null` on non-Windows targets) |
@@ -385,39 +387,4 @@ byte[] IThread.GetWatsonBuckets(TargetPointer threadPointer)
     return span.ToArray();
 }
 
-byte[] IThread.GetContext(TargetPointer threadPointer, ThreadContextSource contextSource, uint contextFlags)
-{
-    // Allocate a context buffer for the target platform
-    IPlatformAgnosticContext context = IPlatformAgnosticContext.GetContextForPlatform(target);
-    byte[] bytes = new byte[context.Size];
-
-    TargetPointer filterContext = TargetPointer.Null;
-
-    if (contextSource.HasFlag(ThreadContextSource.Debugger))
-        filterContext = target.ReadPointer(threadPointer + /* Thread::DebuggerFilterContext offset */);
-
-    if (filterContext != TargetPointer.Null)
-    {
-        // Use the filter context directly
-        target.ReadBuffer(filterContext, bytes);
-        return bytes;
-    }
-
-    // Try to read the OS thread context from the data target
-    ulong osId = target.ReadNUInt(threadPointer + /* Thread::OSId offset */);
-    if (target.TryGetThreadContext(osId, contextFlags, bytes))
-        return bytes;
-
-    // Derive a context from the explicit Frame chain stored in the Thread (sufficient for managed
-    // debugging stack walks). Walk the Frame chain and pick the first
-    // frame that yields a usable context:
-    //   * If it is an InterpreterFrame, fill the context from the top
-    //     InterpMethodContextFrame.
-    //   * Otherwise, update the context from the frame and accept it when both
-    //     StackPointer and InstructionPointer are non-zero. Mark the resulting
-    //     context flags as full so callers know SP/PC/FP are valid.
-    // If no frame supplies a usable context (thread is not running managed code),
-    // return a zeroed context.
-}
-
 ```

docs/design/features/host-runtime-information.md

@@ -78,6 +78,10 @@ List of directory paths to search for managed assemblies. Paths are delimited by
 
 List of directory paths corresponding to shared store paths and additional probing paths used by the host for [probing paths](./host-probing.md#probing-paths). Paths are delimited by a [platform-specific path separator](#path-separator).
 
+`SYSTEM_CORELIB_DIRECTORY`
+
+Absolute path to the directory containing `System.Private.CoreLib.dll`. When set, the runtime loads `System.Private.CoreLib` from this directory instead of looking for it beside `coreclr`. This is intended for hosts where `System.Private.CoreLib.dll` is not placed alongside `coreclr`. For hosts providing an assembly probe extension, a valid probe result takes precedence over this property. Otherwise, when this property is set, no fallback search is performed - if the file cannot be loaded from the specified directory, startup fails. Host is only allowed to specify directory since the runtime expects corelib to always be called `System.Private.CoreLib.dll`.
+
 ### Single-file
 
 `BUNDLE_EXTRACTION_PATH`

docs/project/list-of-diagnostics.md

@@ -274,7 +274,7 @@ The diagnostic id values reserved for .NET Libraries analyzer warnings are `SYSL
 |  __`SYSLIB1226`__ | 'JsonIgnoreCondition.Always' is not valid on type-level 'JsonIgnoreAttribute' annotations. |
 |  __`SYSLIB1227`__ | Union case types cannot be unambiguously classified by JSON value type. |
 |  __`SYSLIB1228`__ | Union type shape is not a valid C# union. |
-|  __`SYSLIB1229`__ | _`SYSLIB1220`-`SYSLIB1229` reserved for System.Text.Json.SourceGeneration._ |
+|  __`SYSLIB1229`__ | Open generic derived type could not be resolved for the polymorphic base type. |
 |  __`SYSLIB1230`__ | Deriving from a `GeneratedComInterface`-attributed interface defined in another assembly is not supported. |
 |  __`SYSLIB1231`__ | _`SYSLIB1230`-`SYSLIB1239` reserved for Microsoft.Interop.ComInterfaceGenerator._ |
 |  __`SYSLIB1232`__ | _`SYSLIB1230`-`SYSLIB1239` reserved for Microsoft.Interop.ComInterfaceGenerator._ |

eng/AcquireWasiSdk.targets

@@ -7,7 +7,7 @@
 -->
 <Project>
   <PropertyGroup>
-    <_WasiSdkVersion>25.0</_WasiSdkVersion>
+    <_WasiSdkVersion>33.0</_WasiSdkVersion>
     <_RuntimeLocalWasiSdkPath>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'wasi-sdk'))</_RuntimeLocalWasiSdkPath>    
   </PropertyGroup>
 

eng/Analyzers.targets

@@ -29,4 +29,16 @@
     <EditorConfigFiles Remove="$(RepositoryEngineeringDir)CodeAnalysis.src.globalconfig" />
     <EditorConfigFiles Include="$(RepositoryEngineeringDir)CodeAnalysis.test.globalconfig" />
   </ItemGroup>
+
+  <!-- PlatformDocAnalyzer: Enforce documentation conventions for platform-specific libraries.
+       Opt-in via EnablePlatformDocAnalyzer; src/libraries enables this by default for src projects. -->
+  <ItemGroup Condition="'$(EnablePlatformDocAnalyzer)' == 'true' and '$(MSBuildProjectExtension)' == '.csproj' and '$(RunAnalyzers)' != 'false'">
+    <ProjectReference Include="$(RepositoryEngineeringDir)analyzers\PlatformDocAnalyzer\PlatformDocAnalyzer.csproj"
+                      ReferenceOutputAssembly="false"
+                      OutputItemType="Analyzer"
+                      SetConfiguration="Configuration=$(LibrariesConfiguration)" />
+  </ItemGroup>
+
+  <Import Project="$(RepositoryEngineeringDir)analyzers\PlatformDocAnalyzer\PlatformDocAnalyzer.props"
+          Condition="'$(EnablePlatformDocAnalyzer)' == 'true' and '$(MSBuildProjectExtension)' == '.csproj' and '$(RunAnalyzers)' != 'false'" />
 </Project>