[cdac] RuntimeTypeSystem contract; rename ContainsPointers -> Contain…

…sGCPointers (dotnet#103444)

* Implement GetThreadStoreData in cDAC

* [dac] Return canonical MethodTable instead of EEClass

   Instead of storing the EEClass pointer in DacpMethodTableData, store the canonical method table instead.

   Correspondingly, update GetMethodTableForEEClass to expect a canonical method table pointer instead of an EEClass

   Also update cDAC to do likewise

* document GetMethodTableData string baseSize adjustment

* Apply suggestions from code review

Co-Authored-By: Aaron Robinson <[email protected]>

* [vm] rename ContainsPointers flag to ContainsGCPointers

   also rename getter/setter methods in MethodTable

* code style suggestions from code review

* DAC: always set wNumVirtuals and wNumVtableSlots to 0

   This information can be retreived from the MethodTable using normal lldb/windbg primitives and doesn't need to be part of the DAC API contract

* Remove NumVirtuals and NumVtableSlots from RuntimeTypeSystem.md

   Co-authored-by: Jan Kotas <[email protected]>

* "untrusted" -> "non-validated"

* pull test target helpers out

   goal is to be able to use this for testing contracts that depend on some data in the heap

* Add one FreeObjectMethodTable unit test

* validate that a mock system object is a valid method table

* code review feedback and more tests:

   1. rename AttrClass data descriptor field to CorTypeAttr
   2. fixup HasComponentSize / RawGetComponentSize comments and code
   3. update "system.object" mock methodtable with more field values
   4. update "system.string" mock methodtable with more field values

* Update src/coreclr/gc/env/gcenv.object.h

   Co-authored-by: Elinor Fung <[email protected]>

* Update src/native/managed/cdacreader/src/Contracts/Metadata_1.MethodTableFlags.cs

   Co-authored-by: Elinor Fung <[email protected]>

* move non-validated MethodTable handling to a separate class

* clear up ComponentSize contract spec and impl

* rename Metadata -> RuntimeTypeSystem

* add validation failure test; change validation to throw InvalidOperationException

* Update src/native/managed/cdacreader/src/Contracts/RuntimeTypeSystem_1.cs

   Co-authored-by: Jan Kotas <[email protected]>

* Add a generic instance test

* add array instance test

---------

Co-authored-by: Elinor Fung <[email protected]>
Co-authored-by: Aaron Robinson <[email protected]>
Co-authored-by: Jan Kotas <[email protected]>

docs/design/datacontracts/RuntimeTypeSystem.md

@@ -0,0 +1,224 @@
+# Contract RuntimeTypeSystem
+
+This contract is for exploring the properties of the runtime types of values on the managed heap or on the stack in a .NET process.
+
+## APIs of contract
+
+A `MethodTable` is the runtime representation of the type information about a value.  Given a `TargetPointer` address, the `RuntimeTypeSystem` contract provides a `MethodTableHandle` for querying the `MethodTable`.
+
+``` csharp
+struct MethodTableHandle
+{
+    // no public properties or constructors
+
+    internal TargetPointer Address { get; }
+}
+```
+
+``` csharp
+    #region MethodTable inspection APIs
+    public virtual MethodTableHandle GetMethodTableHandle(TargetPointer targetPointer);
+
+    public virtual TargetPointer GetModule(MethodTableHandle methodTable);
+    // A canonical method table is either the MethodTable itself, or in the case of a generic instantiation, it is the
+    // MethodTable of the prototypical instance.
+    public virtual TargetPointer GetCanonicalMethodTable(MethodTableHandle methodTable);
+    public virtual TargetPointer GetParentMethodTable(MethodTableHandle methodTable);
+
+    public virtual uint GetBaseSize(MethodTableHandle methodTable);
+    // 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(MethodTableHandle methodTable);
+
+    // True if the MethodTable is the sentinel value associated with unallocated space in the managed heap
+    public virtual bool IsFreeObjectMethodTable(MethodTableHandle methodTable);
+    public virtual bool IsString(MethodTableHandle methodTable);
+    // True if the MethodTable represents a type that contains managed references
+    public virtual bool ContainsGCPointers(MethodTableHandle methodTable);
+    public virtual bool IsDynamicStatics(MethodTableHandle methodTable);
+    public virtual ushort GetNumMethods(MethodTableHandle methodTable);
+    public virtual ushort GetNumInterfaces(MethodTableHandle methodTable);
+
+    // Returns an ECMA-335 TypeDef table token for this type, or for its generic type definition if it is a generic instantiation
+    public virtual uint GetTypeDefToken(MethodTableHandle methodTable);
+    // Returns the ECMA 335 TypeDef table Flags value (a bitmask of TypeAttributes) for this type,
+    // or for its generic type definition if it is a generic instantiation
+    public virtual uint GetTypeDefTypeAttributes(MethodTableHandle methodTable);
+    #endregion MethodTable inspection APIs
+```
+
+## Version 1
+
+The `MethodTable` inspection APIs are implemented in terms of the following flags on the runtime `MethodTable` structure:
+
+``` csharp
+internal partial struct RuntimeTypeSystem_1
+{
+    // The lower 16-bits of the MTFlags field are used for these flags,
+    // if WFLAGS_HIGH.HasComponentSize is unset
+    [Flags]
+    internal enum WFLAGS_LOW : uint
+    {
+        GenericsMask = 0x00000030,
+        GenericsMask_NonGeneric = 0x00000000,   // no instantiation
+
+        StringArrayValues = GenericsMask_NonGeneric,
+    }
+
+    // Upper bits of MTFlags
+    [Flags]
+    internal enum WFLAGS_HIGH : uint
+    {
+        Category_Mask = 0x000F0000,
+        Category_Array = 0x00080000,
+        Category_Array_Mask = 0x000C0000,
+        Category_Interface = 0x000C0000,
+        ContainsGCPointers = 0x01000000,
+        HasComponentSize = 0x80000000, // This is set if lower 16 bits is used for the component size,
+                                       // otherwise the lower bits are used for WFLAGS_LOW
+    }
+
+    [Flags]
+    internal enum WFLAGS2_ENUM : uint
+    {
+        DynamicStatics = 0x0002,
+    }
+
+    // Encapsulates the MethodTable flags v1 uses
+    internal struct MethodTableFlags
+    {
+        public uint MTFlags { get; }
+        public uint MTFlags2 { get; }
+        public uint BaseSize { get; }
+
+        public WFLAGS_LOW GetFlag(WFLAGS_LOW mask) { ... /* mask & lower 16 bits of MTFlags */ }
+        public WFLAGS_HIGH GetFlag(WFLAGS_HIGH mask) { ... /* mask & upper 16 bits of MTFlags */ }
+
+        public WFLAGS2_ENUM GetFlag(WFLAGS2_ENUM mask) { ... /* mask & MTFlags2*/ }
+
+        private bool TestFlagWithMask(WFLAGS_LOW mask, WFLAGS_LOW flag)
+        {
+            if (IsStringOrArray)
+            {
+                return (WFLAGS_LOW.StringArrayValues & mask) == flag;
+            }
+            else
+            {
+                return (FlagsLow & mask) == flag;
+            }
+        }
+
+        public ushort ComponentSizeBits => (ushort)(MTFlags & 0x0000ffff); // only meaningful if HasComponentSize is set
+
+        public bool HasComponentSize => GetFlag(WFLAGS_HIGH.HasComponentSize) != 0;
+        public bool IsInterface => GetFlag(WFLAGS_HIGH.Category_Mask) == WFLAGS_HIGH.Category_Interface;
+        public bool IsString => HasComponentSize && !IsArray && ComponentSizeBits == 2;
+        public bool IsArray => GetFlag(WFLAGS_HIGH.Category_Array_Mask) == WFLAGS_HIGH.Category_Array;
+        public bool IsStringOrArray => HasComponentSize;
+        public ushort ComponentSize => HasComponentSize ? ComponentSizeBits : (ushort)0;
+        public bool HasInstantiation => !TestFlagWithMask(WFLAGS_LOW.GenericsMask, WFLAGS_LOW.GenericsMask_NonGeneric);
+        public bool ContainsGCPointers => GetFlag(WFLAGS_HIGH.ContainsGCPointers) != 0;
+        public bool IsDynamicStatics => GetFlag(WFLAGS2_ENUM.DynamicStatics) != 0;
+    }
+
+    [Flags]
+    internal enum EEClassOrCanonMTBits
+    {
+        EEClass = 0,
+        CanonMT = 1,
+        Mask = 1,
+    }
+}
+```
+
+Internally the contract has a `MethodTable_1` struct that depends on the `MethodTable` data descriptor
+
+```csharp
+internal struct MethodTable_1
+{
+    internal RuntimeTypeSystem_1.MethodTableFlags Flags { get; }
+    internal ushort NumInterfaces { get; }
+    internal ushort NumVirtuals { get; }
+    internal TargetPointer ParentMethodTable { get; }
+    internal TargetPointer Module { get; }
+    internal TargetPointer EEClassOrCanonMT { get; }
+    internal MethodTable_1(Data.MethodTable data)
+    {
+        Flags = new RuntimeTypeSystem_1.MethodTableFlags
+        {
+            MTFlags = data.MTFlags,
+            MTFlags2 = data.MTFlags2,
+            BaseSize = data.BaseSize,
+        };
+        NumInterfaces = data.NumInterfaces;
+        NumVirtuals = data.NumVirtuals;
+        EEClassOrCanonMT = data.EEClassOrCanonMT;
+        Module = data.Module;
+        ParentMethodTable = data.ParentMethodTable;
+    }
+}
+```
+
+The contract depends on the global pointer value `FreeObjectMethodTablePointer`.
+The contract additionally depends on the `EEClass` data descriptor.
+
+```csharp
+    private readonly Dictionary<TargetPointer, MethodTable_1> _methodTables;
+
+    internal TargetPointer FreeObjectMethodTablePointer {get; }
+
+    public MethodTableHandle GetMethodTableHandle(TargetPointer methodTablePointer)
+    {
+        ... // validate that methodTablePointer points to something that looks like a MethodTable.
+        ... // read Data.MethodTable from methodTablePointer.
+        ... // create a MethodTable_1 and add it to _methodTables.
+        return MethodTableHandle { Address = methodTablePointer }
+    }
+
+    internal static EEClassOrCanonMTBits GetEEClassOrCanonMTBits(TargetPointer eeClassOrCanonMTPtr)
+    {
+        return (EEClassOrCanonMTBits)(eeClassOrCanonMTPtr & (ulong)EEClassOrCanonMTBits.Mask);
+    }
+
+    public uint GetBaseSize(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].Flags.BaseSize;
+
+    public uint GetComponentSize(MethodTableHandle methodTableHandle) => GetComponentSize(_methodTables[methodTableHandle.Address]);
+
+    private TargetPointer GetClassPointer(MethodTableHandle methodTableHandle)
+    {
+        ... // if the MethodTable stores a pointer to the EEClass, return it
+            // otherwise the MethodTable stores a pointer to the canonical MethodTable
+            // in that case, return the canonical MethodTable's EEClass.
+            // Canonical MethodTables always store an EEClass pointer.
+    }
+
+    private Data.EEClass GetClassData(MethodTableHandle methodTableHandle)
+    {
+        TargetPointer eeClassPtr = GetClassPointer(methodTableHandle);
+        ... // read Data.EEClass data from eeClassPtr
+    }
+
+
+    public TargetPointer GetCanonicalMethodTable(MethodTableHandle methodTableHandle) => GetClassData(methodTableHandle).MethodTable;
+
+    public TargetPointer GetModule(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].Module;
+    public TargetPointer GetParentMethodTable(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].ParentMethodTable;
+
+    public bool IsFreeObjectMethodTable(MethodTableHandle methodTableHandle) => FreeObjectMethodTablePointer == methodTableHandle.Address;
+
+    public bool IsString(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].Flags.IsString;
+    public bool ContainsGCPointers(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].Flags.ContainsGCPointers;
+
+    public uint GetTypeDefToken(MethodTableHandle methodTableHandle)
+    {
+        MethodTable_1 methodTable = _methodTables[methodTableHandle.Address];
+        return (uint)(methodTable.Flags.GetTypeDefRid() | ((int)TableIndex.TypeDef << 24));
+    }
+
+    public ushort GetNumMethods(MethodTableHandle methodTableHandle) => GetClassData(methodTableHandle).NumMethods;
+
+    public ushort GetNumInterfaces(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].NumInterfaces;
+
+    public uint GetTypeDefTypeAttributes(MethodTableHandle methodTableHandle) => GetClassData(methodTableHandle).CorTypeAttr;
+
+    public bool IsDynamicStatics(MethodTableHandle methodTableHandle) => _methodTables[methodTableHandle.Address].Flags.IsDynamicStatics;
+```

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

@@ -654,7 +654,7 @@ internal unsafe struct MethodTable
         private const uint enum_flag_IsByRefLike = 0x00001000;
 
         // WFLAGS_HIGH_ENUM
-        private const uint enum_flag_ContainsPointers = 0x01000000;
+        private const uint enum_flag_ContainsGCPointers = 0x01000000;
         private const uint enum_flag_ContainsGenericVariables = 0x20000000;
         private const uint enum_flag_HasComponentSize = 0x80000000;
         private const uint enum_flag_HasTypeEquivalence = 0x02000000;
@@ -707,7 +707,7 @@ internal unsafe struct MethodTable
 
         public bool HasComponentSize => (Flags & enum_flag_HasComponentSize) != 0;
 
-        public bool ContainsGCPointers => (Flags & enum_flag_ContainsPointers) != 0;
+        public bool ContainsGCPointers => (Flags & enum_flag_ContainsGCPointers) != 0;
 
         public bool NonTrivialInterfaceCast => (Flags & enum_flag_NonTrivialInterfaceCast) != 0;
 

src/coreclr/debug/daccess/dacimpl.h

@@ -1232,6 +1232,8 @@ class ClrDataAccess
     HRESULT GetThreadDataImpl(CLRDATA_ADDRESS threadAddr, struct DacpThreadData *threadData);
     HRESULT GetThreadStoreDataImpl(struct DacpThreadStoreData *data);
     HRESULT GetNestedExceptionDataImpl(CLRDATA_ADDRESS exception, CLRDATA_ADDRESS *exceptionObject, CLRDATA_ADDRESS *nextNestedException);
+    HRESULT GetMethodTableDataImpl(CLRDATA_ADDRESS mt, struct DacpMethodTableData *data);
+    HRESULT GetMethodTableForEEClassImpl (CLRDATA_ADDRESS eeClassReallyMT, CLRDATA_ADDRESS *value);
 
     BOOL IsExceptionFromManagedCode(EXCEPTION_RECORD * pExceptionRecord);
 #ifndef TARGET_UNIX