Merge remote-tracking branch 'upstream/main' into interlockedgeneric

docs/design/datacontracts/DacStreams.md

@@ -0,0 +1,66 @@
+# Contract DacStreams
+
+This contract is for getting information from the streams embedded into a dump file as it crashes
+
+## APIs of contract
+
+``` csharp
+// Return string corresponding to type system data structure if it exists, or null otherwise
+string StringFromEEAddress(TargetPointer address);
+```
+
+## Version 1
+
+Global variables used
+| Global Name | Type | Purpose |
+| --- | --- | --- |
+| MiniMetaDataBuffAddress | TargetPointer | Identify where the mini metadata stream exists |
+| MiniMetaDataBuffMaxSize | uint | Identify where the size of the mini metadata stream |
+
+Magic numbers
+| Name | Value |
+| --- | --- |
+| MiniMetadataSignature | 0x6d727473 |
+| EENameStreamSignature | 0x614e4545 |
+
+The format of the MiniMetadataStream begins with a Streams header, which has 3 fields
+
+| Field | Type | Offset | Meaning |
+| --- | --- | --- | --- |
+| MiniMetadataSignature| uint | 0 | Magic value used to identify that there are streams |
+| TotalSize | uint | 4 | Total size of the entire set of MiniMetadata streams including this header |
+| Count of Streams | uint | 8 | Number of streams in the MiniMetadata |
+
+The concept is that each stream simply follows the previous stream in the buffer.
+There is no padding, so the data is not expected to be aligned within the buffer.
+NOTE: At the moment there is only 1 supported stream type, so Count of Streams can only be 1.
+
+The `EENameStream` is structured as a header, plus a series of null-terminated utf8 strings, and pointers.
+
+The EENameStream header
+| Field | Type | Offset | Meaning |
+| --- | --- | --- | --- |
+| EENameStreamSignature | uint | 0 | Magic value used to identify that the bytes immediately following are an `EENameStream` |
+| CountOfNames | uint | 4 | Number of names encoded |
+
+EENameStream entry
+| Field | Type | Offset | Meaning |
+| --- | --- | --- | --- |
+| Pointer | pointer | 0 | Pointer to type system structure |
+| String | null-terminated UTF-8 sting | 4 or 8 based on target pointer size | Pointer to type system structure |
+
+Following the EENameStream header, there are CountOfNames entries. Each entry begins with a target pointer sized block which identifies a particular type system data structure, followed by a utf8 encoded null-terminated string.
+
+``` csharp
+string StringFromEEAddress(TargetPointer address)
+{
+    TargetPointer miniMetaDataBuffAddress = _target.Read<uint>(_target.ReadGlobalPointer(Constants.Globals.MiniMetaDataBuffAddress));
+    uint miniMetaDataBuffMaxSize = _target.Read<uint>(_target.ReadGlobalPointer(Constants.Globals.MiniMetaDataBuffMaxSize));
+
+    // Parse MiniMetadataStream according the the format described above to produce a dictionary from pointer to string from the EENameStream.
+    // Then lookup in the dictionary, to produce a result if it was present in the table.
+    // In general, since this api is intended for fallback scenarios, implementations of this api should attempt
+    // to return null instead of producing errors.
+    // Since in normal execution of the runtime no stream is constructed, it is normal when examining full dumps and live process state without a stream encoded.
+}
+```

docs/design/datacontracts/Loader.md

@@ -26,6 +26,75 @@ record struct ModuleLookupTables(
     TargetPointer MethodDefToDesc,
     TargetPointer TypeDefToMethodTable,
     TargetPointer TypeRefToMethodTable);
+
+internal struct EcmaMetadataSchema
+{
+    public EcmaMetadataSchema(string metadataVersion, bool largeStringHeap, bool largeBlobHeap, bool largeGuidHeap, int[] rowCount, bool[] isSorted, bool variableSizedColumnsAre4BytesLong)
+    {
+        MetadataVersion = metadataVersion;
+        LargeStringHeap = largeStringHeap;
+        LargeBlobHeap = largeBlobHeap;
+        LargeGuidHeap = largeGuidHeap;
+
+        _rowCount = rowCount;
+        _isSorted = isSorted;
+
+        VariableSizedColumnsAreAll4BytesLong = variableSizedColumnsAre4BytesLong;
+    }
+
+    public readonly string MetadataVersion;
+
+    public readonly bool LargeStringHeap;
+    public readonly bool LargeBlobHeap;
+    public readonly bool LargeGuidHeap;
+
+    // Table data, these structures hold MetadataTable.Count entries
+    private readonly int[] _rowCount;
+    public readonly ReadOnlySpan<int> RowCount => _rowCount;
+
+    private readonly bool[] _isSorted;
+    public readonly ReadOnlySpan<bool> IsSorted => _isSorted;
+
+    // In certain scenarios the size of the tables is forced to be the maximum size
+    // Otherwise the size of columns should be computed based on RowSize/the various heap flags
+    public readonly bool VariableSizedColumnsAreAll4BytesLong;
+}
+
+internal class TargetEcmaMetadata
+{
+    public TargetEcmaMetadata(EcmaMetadataSchema schema,
+                        TargetSpan[] tables,
+                        TargetSpan stringHeap,
+                        TargetSpan userStringHeap,
+                        TargetSpan blobHeap,
+                        TargetSpan guidHeap)
+    {
+        Schema = schema;
+        _tables = tables;
+        StringHeap = stringHeap;
+        UserStringHeap = userStringHeap;
+        BlobHeap = blobHeap;
+        GuidHeap = guidHeap;
+    }
+
+    public EcmaMetadataSchema Schema { get; init; }
+
+    private TargetSpan[] _tables;
+    public ReadOnlySpan<TargetSpan> Tables => _tables;
+    public TargetSpan StringHeap { get; init; }
+    public TargetSpan UserStringHeap { get; init; }
+    public TargetSpan BlobHeap { get; init; }
+    public TargetSpan GuidHeap { get; init; }
+}
+
+[Flags]
+internal enum AvailableMetadataType
+{
+    None = 0,
+    ReadOnly = 1,
+    ReadWriteSavedCopy = 2,
+    ReadWrite = 4
+}
 ```
 
 ``` csharp
@@ -36,13 +105,31 @@ TargetPointer GetLoaderAllocator(ModuleHandle handle);
 TargetPointer GetThunkHeap(ModuleHandle handle);
 TargetPointer GetILBase(ModuleHandle handle);
 TargetPointer GetMetadataAddress(ModuleHandle handle, out ulong size);
+AvailableMetadataType GetAvailableMetadataType(ModuleHandle handle);
+TargetPointer GetReadWriteSavedMetadataAddress(ModuleHandle handle, out ulong size);
+TargetEcmaMetadata GetReadWriteMetadata(ModuleHandle handle);
 ModuleLookupTables GetLookupTables(ModuleHandle handle);
 ```
 
 ## Version 1
 
 Data descriptors used:
-- `Module`
+| Data Descriptor Name | Field | Meaning |
+| --- | --- | --- |
+| `Module` | `Assembly` | Assembly of the Module |
+| `Module` | `Base` | Pointer to start of PE file in memory |
+| `Module` | `Flags` | Assembly of the Module |
+| `Module` | `LoaderAllocator` | LoaderAllocator of the Module |
+| `Module` | `ThunkHeap` | Pointer to the thunk heap |
+| `Module` | `DynamicMetadata` | Pointer to saved metadata for reflection emit modules |
+| `Module` | `FieldDefToDescMap` | Mapping table |
+| `Module` | `ManifestModuleReferencesMap` | Mapping table |
+| `Module` | `MemberRefToDescMap` | Mapping table |
+| `Module` | `MethodDefToDescMap` | Mapping table |
+| `Module` | `TypeDefToMethodTableMap` | Mapping table |
+| `Module` | `TypeRefToMethodTableMap` | Mapping table |
+| `DynamicMetadata` | `Size` | Size of the dynamic metadata blob (as a 32bit uint) |
+| `DynamicMetadata` | `Data` | Start of dynamic metadata data array |
 
 ``` csharp
 ModuleHandle GetModuleHandle(TargetPointer modulePointer)
@@ -94,6 +181,32 @@ TargetPointer GetMetadataAddress(ModuleHandle handle, out ulong size)
     return baseAddress + rva;
 }
 
+AvailableMetadataType ILoader.GetAvailableMetadataType(ModuleHandle handle)
+{
+    Data.Module module = _target.ProcessedData.GetOrAdd<Data.Module>(handle.Address);
+
+    AvailableMetadataType flags = AvailableMetadataType.None;
+
+    TargetPointer dynamicMetadata = target.ReadPointer(handle.Address + /* Module::DynamicMetadata offset */);
+
+    if (dynamicMetadata != TargetPointer.Null)
+        flags |= AvailableMetadataType.ReadWriteSavedCopy;
+    else
+        flags |= AvailableMetadataType.ReadOnly;
+
+    return flags;
+}
+
+TargetPointer ILoader.GetReadWriteSavedMetadataAddress(ModuleHandle handle, out ulong size)
+{
+    Data.Module module = _target.ProcessedData.GetOrAdd<Data.Module>(handle.Address);
+    TargetPointer dynamicMetadata = target.ReadPointer(handle.Address + /* Module::DynamicMetadata offset */);
+
+    size = target.Read<uint>(handle.Address + /* DynamicMetadata::Size offset */);
+    TargetPointer result = handle.Address + /* DynamicMetadata::Data offset */;
+    return result;
+}
+
 ModuleLookupTables GetLookupTables(ModuleHandle handle)
 {
     return new ModuleLookupTables(