Merge branch 'main' of github.com:dotnet/runtime into reject-non-zero

Author: buyaa-n

docs/coding-guidelines/api-guidelines/nullability.md

@@ -67,7 +67,7 @@ However, for existing virtual APIs that do not have any such strong guarantee do
 4. How common is it in the case of (3) for such invocations to then dereference the result rather than passing it off to something else that accepts a `T?`?
 
 `Object.ToString` is arguably the most extreme case.  Answering the above questions:
-1. It is fairly easy in any reasonably-sized code base to find cases, intentional or otherwise, where `ToString` returns `null` in some cases (we've found examples in dotnet/corefx, dotnet/roslyn, NuGet/NuGet.Client, dotnet/aspnetcore, and so on).  One of the most prevalent conditions for this are types that just return the value in a string field which may contain its default value of `null`, and in particular for structs where a ctor may not have even had a chance to run and validate an input.  Guidance in the docs suggests that `ToString` shouldn't return `null` or `string.Empty`, but even the docs don't follow its own guidance.
+1. It is fairly easy in any reasonably-sized code base to find cases, intentional or otherwise, where `ToString` returns `null` in some cases (we've found examples in dotnet/runtime, dotnet/roslyn, NuGet/NuGet.Client, dotnet/aspnetcore, and so on).  One of the most prevalent conditions for this are types that just return the value in a string field which may contain its default value of `null`, and in particular for structs where a ctor may not have even had a chance to run and validate an input.  Guidance in the docs suggests that `ToString` shouldn't return `null` or `string.Empty`, but even the docs don't follow its own guidance.
 2. Thousands upon thousands of types we don't control override this method today.
 3. It's common for helper routines to invoke via the base `object.ToString`, but many `ToString` uses are actually on derived types.  This is particularly true when working in a code base that both defines a type and consumes its `ToString`.
 4. Based on examination of several large code bases, we believe it to be relatively rare that the result of an `Object.ToString` call (made on the base) to be directly dereferenced.  It's much more common to pass it to another method that accepts `string?`, such as `String.Concat`, `String.Format`, `Console.WriteLine`, logging utilities, and so on.  And while we advocate that `ToString` results shouldn't be assumed to be in a particular machine-readable format and parsed, it's certainly the case that code bases do, such as using `Substring` on the result, but in such cases, the caller needs to understand the format of what's being rendered, which generally means they're working with a derived type rather than calling through the base `Object.ToString`.

docs/design/coreclr/jit/JitOptimizerTodoAssessment.md

@@ -49,7 +49,7 @@ the code quality improvements, though most have issues associated with them.
 We may well be able to find some additional benchmarks or real-world-code with some looking,
 though it may be the case that current performance-sensitive code avoids structs.
 
-There's also work going on in corefx to use `Span<T>` more broadly.  We should
+There's also work going on to use `Span<T>` more broadly.  We should
 make sure we are expanding our span benchmarks appropriately to track and
 respond to any particular issues that come out of that work.
 

docs/design/coreclr/jit/object-stack-allocation.md

@@ -83,7 +83,7 @@ with version reseliency.
 **Pros:**
 * ILLInk can afford to spend more time for escape analysis.
 * For self-contained apps, ILLink has access to all of application's code and can do full interprocedural analysis.
-* ILLink is already a part of System.Private.CoreLib and CoreFX build toolchain so the assemblies built there can benefit
+* ILLink is already a part of System.Private.CoreLib and core libraries build toolchain so the assemblies built there can benefit
 from this.
 
 **Cons:**

docs/design/datacontracts/Object.md

@@ -0,0 +1,53 @@
+# Contract Object
+
+This contract is for getting information about well-known managed objects
+
+## APIs of contract
+
+``` csharp
+// Get the method table address for the object
+TargetPointer GetMethodTableAddress(TargetPointer address);
+
+// Get the string corresponding to a managed string object. Error if address does not represent a string.
+string GetStringValue(TargetPointer address);
+```
+
+## Version 1
+
+Data descriptors used:
+| Data Descriptor Name | Field | Meaning |
+| --- | --- | --- |
+| `Object` | `m_pMethTab` | Method table for the object |
+| `String` | `m_FirstChar` | First character of the string - `m_StringLength` can be used to read the full string (encoded in UTF-16) |
+| `String` | `m_StringLength` | Length of the string in characters (encoded in UTF-16) |
+
+Global variables used:
+| Global Name | Type | Purpose |
+| --- | --- | --- |
+| `ObjectToMethodTableUnmask` | uint8 | Bits to clear for converting to a method table address |
+| `StringMethodTable` | TargetPointer | The method table for System.String |
+
+``` csharp
+TargetPointer GetMethodTableAddress(TargetPointer address)
+{
+    TargetPointer mt = _targetPointer.ReadPointer(address + /* Object::m_pMethTab offset */);
+    return mt.Value & ~target.ReadGlobal<byte>("ObjectToMethodTableUnmask");
+}
+
+string GetStringValue(TargetPointer address)
+{
+    TargetPointer mt = GetMethodTableAddress(address);
+    TargetPointer stringMethodTable = target.ReadPointer(target.ReadGlobalPointer("StringMethodTable"));
+    if (mt != stringMethodTable)
+        throw new ArgumentException("Address does not represent a string object", nameof(address));
+
+    // Validates the method table
+    _ = target.Contracts.RuntimeTypeSystem.GetTypeHandle(mt);
+
+    Data.String str = _target.ProcessedData.GetOrAdd<Data.String>(address);
+    uint length = target.Read<uint>(address + /* String::m_StringLength offset */);
+    Span<byte> span = stackalloc byte[(int)length * sizeof(char)];
+    target.ReadBuffer(address + /* String::m_FirstChar offset */, span);
+    return new string(MemoryMarshal.Cast<byte, char>(span));
+}
+```

docs/design/datacontracts/RuntimeTypeSystem.md

@@ -4,10 +4,11 @@ This contract is for exploring the properties of the runtime types of values on
 
 ## APIs of contract
 
+### TypeHandle
+
 A `TypeHandle` is the runtime representation of the type information about a value which is represented as a TypeHandle.
 Given a `TargetPointer` address, the `RuntimeTypeSystem` contract provides a `TypeHandle` for querying the details of the `TypeHandle`.
 
-
 ``` csharp
 struct TypeHandle
 {
@@ -28,6 +29,8 @@ internal enum CorElementType
 A `TypeHandle` is the runtime representation of the type information about a value.  This can be constructed from the address of a `TypeHandle` or a `MethodTable`.
 
 ``` csharp
+partial interface IRuntimeTypeSystem : IContract
+{
     #region TypeHandle inspection APIs
     public virtual TypeHandle GetTypeHandle(TargetPointer targetPointer);
 
@@ -73,10 +76,35 @@ A `TypeHandle` is the runtime representation of the type information about a val
     public virtual bool IsFunctionPointer(TypeHandle typeHandle, out ReadOnlySpan<TypeHandle> retAndArgTypes, out byte callConv);
 
     #endregion TypeHandle inspection APIs
+}
+```
+
+### MethodDesc
+
+A `MethodDesc` is the runtime representation of a managed method (either from IL, from reflection emit, or generated by the runtime).
+
+```csharp
+struct MethodDescHandle
+{
+    // no public properties or constructors
+
+    internal TargetPointer Address { get; }
+}
+```
+
+```csharp
+partial interface IRuntimeTypeSystem : IContract
+{
+    public virtual MethodDescHandle GetMethodDescHandle(TargetPointer methodDescPointer);
+
+    public virtual TargetPointer GetMethodTable(MethodDescHandle methodDesc);
+}
 ```
 
 ## Version 1
 
+### TypeHandle
+
 The `MethodTable` inspection APIs are implemented in terms of the following flags on the runtime `MethodTable` structure:
 
 ``` csharp
@@ -233,7 +261,11 @@ static class RuntimeTypeSystem_1_Helpers
 }
 ```
 
-The contract depends on the global pointer value `FreeObjectMethodTablePointer`.
+The contract depends on the following globals
+
+| Global name | Meaning |
+| --- | --- |
+| `FreeObjectMethodTablePointer` | A pointer to the address of a `MethodTable` used by the GC to indicate reclaimed memory
 
 The contract additionally depends on these data descriptors
 
@@ -251,6 +283,7 @@ The contract additionally depends on these data descriptors
 | `EEClass` | `InternalCorElementType` | An InternalCorElementType uses the enum values of a CorElementType to indicate some of the information about the type of the type which uses the EEClass In particular, all reference types are CorElementType.Class, Enums are the element type of their underlying type and ValueTypes which can exactly be represented as an element type are represented as such, all other values types are represented as CorElementType.ValueType. |
 | `EEClass` | `MethodTable` | Pointer to the canonical MethodTable of this type |
 | `EEClass` | `NumMethods` | Count of methods attached to the EEClass |
+| `EEClass` | `NumNonVirtualSlots` | Count of non-virtual slots for the EEClass |
 | `EEClass` | `CorTypeAttr` | Various flags |
 | `ArrayClass` | `Rank` | Rank of the associated array MethodTable |
 | `TypeDesc` | `TypeAndFlags` | The lower 8 bits are the CorElementType of the `TypeDesc`, the upper 24 bits are reserved for flags |
@@ -523,3 +556,28 @@ The contract additionally depends on these data descriptors
         return true;
     }
 ```
+
+### MethodDesc
+
+The version 1 `MethodDesc` APIs depend on the `MethodDescAlignment` global and the `MethodDesc` and `MethodDescChunk` data descriptors.
+
+| Global name | Meaning |
+| --- | --- |
+| `MethodDescAlignment` | `MethodDescChunk` trailing data is allocated in multiples of this constant.  The size (in bytes) of each `MethodDesc` (or subclass) instance is a multiple of this constant.
+
+
+In the runtime a `MethodDesc` implicitly belongs to a single `MethodDescChunk` and some common data is shared between method descriptors that belong to the same chunk.  A single method table
+will typically have multiple chunks.  There are subkinds of MethodDescs at runtime of varying sizes (but the sizes must be mutliples of `MethodDescAlignment`) and each chunk contains method descriptors of the same size.
+
+We depend on the following data descriptors:
+| Data Descriptor Name | Field | Meaning |
+| --- | --- | --- |
+| `MethodDesc` | `ChunkIndex` | Offset of this `MethodDesc` relative to the end of its containing `MethodDescChunk` - in multiples of `MethodDescAlignment`
+| `MethodDesc` | `Slot` | The method's slot
+| `MethodDesc` | `Flags` | The method's flags
+| `MethodDescChunk` | `MethodTable` | The method table set of methods belongs to
+| `MethodDescChunk` | `Next` | The next chunk of methods
+| `MethodDescChunk` | `Size` | The size of this `MethodDescChunk`  following this `MethodDescChunk` header, minus 1. In multiples of `MethodDescAlignment`
+| `MethodDescChunk` | `Count` | The number of `MethodDesc` entries in this chunk, minus 1.
+
+**TODO(cdac)**

docs/design/features/AssemblyLoadContext.ContextualReflection.md

@@ -22,7 +22,7 @@ Using `pluginDependency` to determine the `AssemblyLoadContext` used for loading
 ### Failing Scenarios
 #### Xunit story
 
-We have been working on building a test harness in Xunit for running the CoreFX test suite inside `AssemblyLoadContext`s (each test case in its own context).  This has proven to be somewhat difficult due to Xunit being a very reflection heavy codebase with tons of instances of types, assemblies, etc. being converted to strings and then fed through `Activator`.  One of the main learnings is that it is not always obvious what will stay inside the “bounds” of an `AssemblyLoadContext` and what won’t.  The basic rule of thumb is that any `Assembly.Load()` will result in the assembly being loaded onto the `AssemblyLoadContext` of the calling code, so if code loaded by an ALC calls `Assembly.Load(...)`, the resulting assembly will be within the “bounds” of the ALC.  This unfortunately breaks down in some cases, specifically when code calls `Activator` which lives in `System.Private.CoreLib` which is always shared.
+We have been working on building a test harness in Xunit for running the core libraries test suite inside `AssemblyLoadContext`s (each test case in its own context).  This has proven to be somewhat difficult due to Xunit being a very reflection heavy codebase with tons of instances of types, assemblies, etc. being converted to strings and then fed through `Activator`.  One of the main learnings is that it is not always obvious what will stay inside the “bounds” of an `AssemblyLoadContext` and what won’t.  The basic rule of thumb is that any `Assembly.Load()` will result in the assembly being loaded onto the `AssemblyLoadContext` of the calling code, so if code loaded by an ALC calls `Assembly.Load(...)`, the resulting assembly will be within the “bounds” of the ALC.  This unfortunately breaks down in some cases, specifically when code calls `Activator` which lives in `System.Private.CoreLib` which is always shared.
 
 #### System.Xaml
 This problem also manifests when using an `Object` deserialization framework which allows specifying assembly qualified type names.

docs/design/features/arm64-intrinsics.md

@@ -263,9 +263,6 @@ To facilitate incremental progress, initial intrinsic API for a given `static cl
 
 As intrinsic support is added test coverage must be extended to provide basic testing.
 
-Tests should be added as soon as practical.  CoreCLR Implementation and CoreFX API will need to be merged before tests
-can be merged.
-
 ## LSRA changes to allocate contiguous register ranges
 
 Some ARM64 instructions will require allocation of contiguous blocks of registers.  These are likely limited to load and

docs/design/features/host-error-codes.md

@@ -31,7 +31,7 @@ Note that the exit code returned by running an application via `dotnet.exe` or `
 | `LibHostInvalidArgs`                  | `0x80008092` | `-2147450734`          | `146`         | Arguments to `hostpolicy` are invalid. This is used in three unrelated places in the `hostpolicy`, but in all cases it means the component calling `hostpolicy` did something wrong: <ul><li> Command line arguments for the app - the failure would typically mean that wrong argument was passed or such. For example if the application main assembly is not specified on the command line. On its own this should not happen as `hostfxr` should have parsed and validated all command line arguments. </li><li> `hostpolicy` context's `get_delegate` - if the requested delegate enum value is not recognized. Again this would mean `hostfxr` passed the wrong value. </li><li> `corehost_resolve_component_dependencies` - if something went wrong initializing `hostpolicy` internal structures. Would happen for example when the `component_main_assembly_path` argument is wrong. </li></ul> |
 | `InvalidConfigFile`                   | `0x80008093` | `-2147450733`          | `147`         | The `.runtimeconfig.json` file is invalid. The reasons for this failure can be among these: <ul><li> Failure to read from the file </li><li> Invalid JSON </li><li> Invalid value for a property (for example number for property which requires a string) </li><li> Missing required property </li><li> Other inconsistencies (for example `rollForward` and `applyPatches` are not allowed to be specified in the same config file) </li><li> Any of the above failures reading the `.runtimecofig.dev.json` file </li><li> Self-contained `.runtimeconfig.json` used in `hostfxr_initialize_for_runtime_config`. Note that missing `.runtimconfig.json` is not an error (means self-contained app). This error code is also used when there is a problem reading the CLSID map file in `comhost`. </li></ul> |
 | `AppArgNotRunnable`                   | `0x80008094` | `-2147450732`          | `148`         | Used internally when the command line for `dotnet.exe` doesn't contain path to the application to run. In such case the command line is considered to be a CLI/SDK command. This error code should never be returned to external caller. |
-| `AppHostExeNotBoundFailure`           | `0x80008095` | `-2147450731`          | `149`         | `apphost` failed to determine which application to run. This can mean: <ul><li> The `apphost` binary has not been imprinted with the path to the app to run (so freshly built `apphost.exe` from the branch will fail to run like this) </li><li> The `apphost` is a bundle (single-file exe) and it failed to extract correctly. </li></ul> |
+| `AppHostExeNotBoundFailure`           | `0x80008095` | `-2147450731`          | `149`         | `apphost` failed to determine which application to run. This can mean: <ul><li> The `apphost` binary has not been imprinted with the path to the app to run (so freshly built `apphost.exe` from the branch will fail to run like this) </li><li> The `apphost` is a bundle (single-file exe) and it failed to extract correctly. </li><li>The `apphost` binary has been imprinted with invalid .NET search options</li></ul> |
 | `FrameworkMissingFailure`             | `0x80008096` | `-2147450730`          | `150`         | It was not possible to find a compatible framework version. This originates in `hostfxr` (`resolve_framework_reference`) and means that the app specified a reference to a framework in its `.runtimeconfig.json` which could not be resolved. The failure to resolve can mean that no such framework is available on the disk, or that the available frameworks don't match the minimum version specified or that the roll forward options specified excluded all available frameworks. Typically this would be used if a 3.0 app is trying to run on a machine which has no 3.0 installed. It would also be used for example if a 32bit 3.0 app is running on a machine which has 3.0 installed but only for 64bit. |
 | `HostApiFailed`                       | `0x80008097` | `-2147450729`          | `151`         | Returned by `hostfxr_get_native_search_directories` if the `hostpolicy` could not calculate the `NATIVE_DLL_SEARCH_DIRECTORIES`. |
 | `HostApiBufferTooSmall`               | `0x80008098` | `-2147450728`          | `152`         | Returned when the buffer specified to an API is not big enough to fit the requested value. Can be returned from: <ul><li> `hostfxr_get_runtime_properties` </li><li> `hostfxr_get_native_search_directories` </li><li> `get_hostfxr_path` </li></ul> |

docs/design/features/hw-intrinsics.md

@@ -10,11 +10,7 @@ There is a design document for the Arm64 intrinsics: https://github.com/dotnet/r
 
 ## Overview
 
-The reference assemblies for the hardware intrinsics live in corefx, but all of the implementation is in the coreclr repo:
-
-* The C# implementation lives in coreclr/System.Private.CoreLib/shared/System/Runtime/Intrinsics. These are little more than skeleton methods that are only compiled if needed for indirect invocation.
-
-  * Note that they are mirrored to other repositories, including corefx, corert and mono.
+* The C# implementation lives in src/libraries/System.Private.CoreLib/shared/System/Runtime/Intrinsics. These are little more than skeleton methods that are only compiled if needed for indirect invocation.
 
 ## C# Implementation
 

docs/design/specs/Memory-model.md

@@ -188,7 +188,7 @@ void ThreadFunc1()
 }
 
 // thread #2
-void ThreadFunc1()
+void ThreadFunc2()
 {
     while (true)
     {
@@ -197,7 +197,7 @@ void ThreadFunc1()
 }
 
 // thread #3
-void ThreadFunc2()
+void ThreadFunc3()
 {
     MyClass localObj = obj;
     if (localObj != null)