Imported Upstream version 2.0.0.11353upstream/2.0.0.11353

5 files changed, 1213 insertions, 0 deletions

diff --git a/Documentation/design-docs/assemblyloadcontext.md b/Documentation/design-docs/assemblyloadcontext.md
new file mode 100644
index 0000000000..6da430703c
--- /dev/null
+++ b/Documentation/design-docs/assemblyloadcontext.md
@@ -0,0 +1,86 @@
+**LoadContext** can be viewed as a container for assemblies, their code and data (e.g. statics). Whenever an assembly is loaded, it is loaded within a load context - independent of whether the load was triggered explicitly (e.g. via *Assembly.Load*), implicitly (e.g. resolving static assembly references from the manifest) or dynamically (by emitting code on the fly).
+
+This concept is not new to .NET Core but has existed since the days of .NET Framework (see [this](https://blogs.msdn.microsoft.com/suzcook/2003/05/29/choosing-a-binding-context/) for details) where it operated behind the scenes and not exposed for the developer to interact with, aside from loading your assembly in one based upon the API used to perform the load.
+
+In .NET Core, we have exposed a [managed API surface](https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Loader/ref/System.Runtime.Loader.cs) that developers can use to interact with it - to inspect loaded assemblies or create their own **LoadContext** instance. Here are some of the scenarios that motivated this work:
+
+* Ability to load multiple versions of the same assembly within a given process (e.g. for plugin frameworks)
+* Ability to load assemblies explicitly in a context isolated from that of the application.
+* Ability to override assemblies being resolved from application context.
+* Ability to have isolation of statics (as they are tied to the **LoadContext**)
+* Expose LoadContext as a first class concept for developers to interface with and not be a magic.
+
+## Types of LoadContext
+### Default LoadContext
+
+Every .NET Core app has a **LoadContext** instance created during .NET Core Runtime startup that we will refer to as the *Default LoadContext*. All application assemblies (including their transitive closure) are loaded within this **LoadContext** instance.
+
+### Custom LoadContext
+For scenarios that wish to have isolation between loaded assemblies, applications can create their own **LoadContext** instance by deriving from **System.Runtime.Loader.AssemblyLoadContext** type and loading the assemblies within that instance.
+
+Multiple assemblies with the same simple name cannot be loaded into a single load context (*Default* or *Custom*). Also, .Net Core ignores strong name token for assembly binding process.
+
+## How Load is attempted
+
+### Basics
+If an assembly *A1* triggers the load of an assembly *C1*, the latter's load is attempted within the **LoadContext** instance of the former (which is also known as the *RequestingAssembly* or *ParentAssembly*). 
+
+Dynamically generated assemblies add a slight twist since they do not have a *ParentAssembly/RequestingAssembly* per-se. Thus, they are associated with the load context of their *Creator Assembly* and any subsequent loads (static or dynamic) will use that load context.
+
+### Resolution Process
+If the assembly was already present in *A1's* context, either because we had successfully loaded it earlier, or because we failed to load it for some reason, we return the corresponding status (and assembly reference for the success case).
+
+However, if *C1* was not found in *A1's* context, the *Load* method override in *A1's* context is invoked. 
+
+* For *Custom LoadContext*, this override is an opportunity to load an assembly **before** the fallback (see below) to *Default LoadContext* is attempted to resolve the load. 
+
+* For *Default LoadContext*, this override always returns *null* since *Default Context* cannot override itself.
+
+If the *Load* method override does not resolve the load, fallback to *Default LoadContext* is attempted to resolve the load incase the assembly was already loaded there. If the operating context is *Default LoadContext*, there is no fallback attempted since it has nothing to fallback to.
+
+If the *Default LoadContext* fallback also did not resolve the load (or was not applicable), the *Resolving* event is invoked against *A1's* load context. This is the last oppurtunity to attempt to resolve the assembly load. If there are no subscribers for this event, or neither resolved the load, a *FileNotFoundException* is thrown.
+
+## PInvoke Resolution
+
+*Custom LoadContext* can override the **AssemblyLoadContext.LoadUnmanagedDll** method to intercept PInvokes from within the **LoadContext** instance so that can be resolved from custom binaries. If not overridden, or if the resolution is not able to resolve the PInvoke, the default PInvoke mechanism will be used as fallback.
+
+## Constraints
+
+* **System.Private.CoreLib.dll** is only loaded once, and into the **Default LoadContext**, during the .NET Core Runtime startup as it is a logical extension of the same. It cannot be loaded into **Custom LoadContext**.
+* Currently, custom **LoadContext** cannot be unloaded once created. This is a feature we are looking into for a future release.
+* If an attempt is made to load a [Ready-To-Run (R2R)](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/readytorun-overview.md) image from the same location in multiple load context's, then precompiled code can only be used from the first image that got loaded. The subsequent images will have their code JITted. This happens because subsequent loading binaries from the same location results in OS mapping them to the same memory as the previous one was mapped to and thus, could corrupt internal state information required for use precompiled code.
+
+## Tests
+
+Tests are present [here](https://github.com/dotnet/corefx/tree/master/src/System.Runtime.Loader).
+
+## API Surface
+
+Most of the **AssemblyLoadContext** [API surface](https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Loader/ref/System.Runtime.Loader.cs) is self-explanatory. Key APIs/Properties, though, are described below:
+
+### Default
+
+This property will return a reference to the *Default LoadContext*.
+
+### Load
+
+This method should be overriden in a *Custom LoadContext* if the intent is to override the assembly resolution that would be done during fallback to *Defaut LoadContext*
+
+### LoadFromAssemblyName
+
+This method can be used to load an assembly into a load context different from the load context of the currently executing assembly.
+
+### Resolving
+
+This event is raised to give the last oppurtunity to a *LoadContext* instance to attempt to resolve a requested assembly that has neither been resolved by **Load** method, nor by fallback to **Default LoadContext**.
+
+## Assembly Load APIs and LoadContext
+
+As part of .NET Standard 2.0 effort, certain assembly load APIs off the **Assembly** type, which were present in Desktop .NET Framework, have been brought back. The following maps the APIs to the load context in which they will load the assembly:
+
+* Assembly.Load - loads the assembly into the context of the assembly that triggers the load.
+* Assembly.LoadFrom - loads the assembly into the *Default LoadContext*
+* Assembly.LoadFile - creates a new (anonymous) load context to load the assembly into.
+* Assembly.Load(byte[]) - creates a new (anonymous) load context to load the assembly into.
+
+If you need to influence the load process or the load context in which assemblies are loaded, please look at the various Load* APIs exposed by **AssemblyLoadContext** [API surface](https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Loader/ref/System.Runtime.Loader.cs).
\ No newline at end of file
diff --git a/Documentation/design-docs/eh-writethru.md b/Documentation/design-docs/eh-writethru.md
new file mode 100644
index 0000000000..0afa5a7688
--- /dev/null
+++ b/Documentation/design-docs/eh-writethru.md
@@ -0,0 +1,378 @@
+# Exception Handling Write Through Optimization.
+
+Write through is an optimization done on local variables that live across exception handling flow like a handler, filter, or finally so that they can be enregistered - treated as a register candidate - throughout a method.  For each variable live across one of these constructs, the minimum requirement is that a store to the variables location on the stack is placed between a reaching definition and any point of control flow leading to the handler, as well as a load between any return from a filter or finally and an upward exposed use.  Conceptually this maintains the value of the variable on the stack across the exceptional flow which would kill any live registers.  This transformation splits a local variable into multiple enregisterable compiler temporaries backed by the local variable on the stack. For local vars that additionally have appearances within a eh construct, a load from the stack local is inserted to a temp that will be enregistered within the handler.
+
+## Motivation
+
+Historically the JIT has not done this transformation because exception handling was rare and thus the transformation was not worth the compile time.  Additionally it was easy to make the recomendation to users to remove EH from performance critical methods since they had control of where the EH appeared.  Neither of these points remain true as we increase our focus on cloud workloads.  The use of non-blocking async calls are common in performance critical paths for these workloads and async injects exception handling constructs to implement the feature.  This in combination with the long standing use of EH in 'foreach' and 'using' statements means that we are seeing EH constructs that are difficult for the user to manage or remove high in the profile (Techempower on Kestrel is a good example).  Given these cloud workloads doing the transformation would be a clear benefit.
+
+## Design
+
+The goal of the design is to preserve the constraints listed above - i.e. preserve a correct value on the stack for any local var that crosses an EH edge in the flow graph. To ensure that the broad set of global optimizations can act on the IR shape produced by this transformation and that phase ordering issues do not block enregistration opportunities the write through phase will be staged just prior to SSA build after morph and it will do a full walk of the IR rewriting appearances to proxies as well as inserting reloads at the appropriate blocks in the flow graph as indicated by EH control flow semantics. To preserve the needed values on the stack a store will also be inserted after every definition to copy the new value in the proxy back to the stack location.  This will leave non optimal number of stores (too many) but with the strategy that the more expensive analysis to eliminate/better place stores will be staged as a global optimization in a higher compilation tier.
+
+### Throughput
+
+To identify EH crossing local vars global liveness is necessary.  This comes at the significant cost of the liveness analysis.  To mitigate this the write through phase is staged immediately before SSA build for the global optimizer.  Since the typical case is that there is no EH, the liveness analysis in write through can be reused directly by SSA build.  For the case where EH local vars are present liveness today must be rebuilt for SSA since new local vars have been added, but incremental update to the RyuJIT liveness analysis can be implemented (worklist based live analysis) to improve the throughput.  Additionally the write through transformation does a full IR walk - also expensive - to replace EH local var appearances with proxies and insert transfers to and from the stack for EH flow, given this initial implementations may need to be staged as part of AOT (crossgen) compiles until tiering can move the more expensive analysis out of the startup path.
+
+### Algorithm
+On the IR directly before SSA build:
+- Run global liveness to identify local vars that cross EH boundaries (as a byproduct of this these local vars are marked "do not enregister")
+- Foreach EH local var create a new local var "proxy" that can be enregisterd.
+- Iterate each block in the flow graph doing the following:
+  * Foreach tree in block do a post order traversal and
+    - Replace all appearances of EH local vars with the defined proxy
+    - Insert a copy of proxy definition back to the EH local var (on the stack)
+  * If EH handler entry block insert reloads from EH local var to proxy at block head
+  * If finally or filter exit, insert reloads from EH local var to proxy at successor block heads
+- For method entry block, insert reloads from parameter EH local vars to proxies
+
+At end no proxy should be live across EH flow and all value updates will be written back to the stack location.
+
+## Next steps
+
+The initial prototype that produced the example bellow is currently being improved to make it production ready.  At the same time a more extensive suite of example tests are being developed. 
+
+- [X] Proof of concept prototype.
+- [ ] Production implementation of WriteThru phase.
+- [ ] Suite of optimization examples/regression tests.
+- [ ] Testing
+   * [ ] Full CI test pass.
+   * [ ] JIT benchmark diffs.
+   * [ ] Kestrel techempower numbers.
+
+## Example
+
+The following is a simple example that shows enregistration for a local var live, and modified, through a catch.
+
+#### Source code snippet
+
+```
+class Enreg01
+{
+    int val;
+    double dist;
+
+    public Enreg01(int x) {
+        val = x;
+        dist = (double)x;
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    public int foo(ref double d) { return (int)d; }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    public int Run()
+    {
+        int sum = val;
+
+        try {
+            TryValue(97);
+        }
+        catch (ValueException e)
+        {
+            Console.WriteLine("Catching {0}", Convert.ToString(e.x));
+            sum += val + e.x;
+            foo(ref dist);
+            sum += val;
+        }
+
+        return sum;
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    public int TryValue(int y) 
+    {
+        if (y == 97) 
+        {
+            Console.WriteLine("Throwing 97");
+            throw new ValueException(97);
+        }
+        else
+        {
+            return y;
+        }
+    }
+}
+```
+#### Post WriteThru GenTree nodes for Run() method
+
+The Run() contains the catch and is the only method the EH WriteThru modifies.
+
+```
+Creating enregisterable proxies:
+lvaGrabTemp returning 8 (V08 tmp5) (a long lifetime temp) called for  Add proxy for EH Write Thru..
+Creating proxy V08 for local var V00
+
+lvaGrabTemp returning 9 (V09 tmp6) (a long lifetime temp) called for  Add proxy for EH Write Thru..
+Creating proxy V09 for local var V01
+
+Trees after EH Write Thru
+
+---------------------------------------------------------------------------------------------------------------------------
+BBnum         descAddr ref try hnd preds           weight   [IL range]      [jump]      [EH region]         [flags]
+---------------------------------------------------------------------------------------------------------------------------
+BB01 [00000263A1C161B8]  1                              1   [000..007)                                     i label target 
+BB02 [00000263A1C162D0]  1  0    BB01                   1   [007..012)                 T0      try { }     keep i try label gcsafe 
+BB03 [00000263A1C16500]  2       BB02,BB04              1   [050..052)        (return)                     i label target gcsafe 
+++++ funclets follow
+BB04 [00000263A1C163E8]  0     0                        0   [012..050)-> BB03 ( cret )    H0 F catch { }   keep i rare label target gcsafe flet 
+-------------------------------------------------------------------------------------------------------------------------------------
+
+------------ BB01 [000..007), preds={} succs={BB02}
+
+***** BB01, stmt 1
+     (  3,  3) [000123] ------------             *  stmtExpr  void  (IL   ???...  ???)
+N001 (  3,  2) [000120] ------------             |  /--*  lclVar    ref    V00 this         
+N003 (  3,  3) [000122] -A------R---             \--*  =         ref   
+N002 (  1,  1) [000121] D------N----                \--*  lclVar    ref    V08 tmp5         
+
+***** BB01, stmt 2
+     ( 17, 13) [000005] ------------             *  stmtExpr  void  (IL 0x000...0x006)
+N007 (  3,  2) [000097] ------------             |     /--*  lclVar    int    V09 tmp6         
+N009 (  7,  5) [000098] -A------R---             |  /--*  =         int   
+N008 (  3,  2) [000096] D------N----             |  |  \--*  lclVar    int    V01 loc0         
+N010 ( 17, 13) [000099] -A-XG-------             \--*  comma     void  
+N004 (  6,  5) [000002] ---XG-------                |  /--*  indir     int   
+N002 (  1,  1) [000059] ------------                |  |  |  /--*  const     long   16 field offset Fseq[val]
+N003 (  4,  3) [000060] -------N----                |  |  \--*  +         byref 
+N001 (  3,  2) [000001] ------------                |  |     \--*  lclVar    ref    V08 tmp5         
+N006 ( 10,  8) [000004] -A-XG---R---                \--*  =         int   
+N005 (  3,  2) [000003] D------N----                   \--*  lclVar    int    V09 tmp6         
+
+------------ BB02 [007..012), preds={BB01} succs={BB03}
+
+***** BB02, stmt 3
+     ( 16, 10) [000013] ------------             *  stmtExpr  void  (IL 0x007...0x00F)
+N008 ( 16, 10) [000011] --C-G-------             \--*  call      int    Enreg01.TryIncrement
+N004 (  1,  1) [000009] ------------ this in rcx    +--*  lclVar    ref    V08 tmp5         
+N005 (  1,  1) [000010] ------------ arg1 in rdx    \--*  const     int    97
+
+------------ BB03 [050..052) (return), preds={BB02,BB04} succs={}
+
+***** BB03, stmt 4
+     (  3,  3) [000119] ------------             *  stmtExpr  void  (IL   ???...  ???)
+N001 (  3,  2) [000116] ------------             |  /--*  lclVar    int    V01 loc0         
+N003 (  3,  3) [000118] -A------R---             \--*  =         int   
+N002 (  1,  1) [000117] D------N----                \--*  lclVar    int    V09 tmp6         
+
+***** BB03, stmt 5
+     (  4,  3) [000017] ------------             *  stmtExpr  void  (IL 0x050...0x051)
+N002 (  4,  3) [000016] ------------             \--*  return    int   
+N001 (  3,  2) [000015] ------------                \--*  lclVar    int    V09 tmp6         
+
+------------ BB04 [012..050) -> BB03 (cret), preds={} succs={BB03}
+
+***** BB04, stmt 6
+     (  5,  4) [000021] ------------             *  stmtExpr  void  (IL 0x012...0x012)
+N001 (  1,  1) [000007] -----O------             |  /--*  catchArg  ref   
+N003 (  5,  4) [000020] -A---O--R---             \--*  =         ref   
+N002 (  3,  2) [000019] D------N----                \--*  lclVar    ref    V03 tmp0         
+
+***** BB04, stmt 7
+     (  3,  3) [000111] ------------             *  stmtExpr  void  (IL   ???...  ???)
+N001 (  3,  2) [000108] ------------             |  /--*  lclVar    ref    V00 this         
+N003 (  3,  3) [000110] -A------R---             \--*  =         ref   
+N002 (  1,  1) [000109] D------N----                \--*  lclVar    ref    V08 tmp5         
+
+***** BB04, stmt 8
+     (  3,  3) [000115] ------------             *  stmtExpr  void  (IL   ???...  ???)
+N001 (  3,  2) [000112] ------------             |  /--*  lclVar    int    V01 loc0         
+N003 (  3,  3) [000114] -A------R---             \--*  =         int   
+N002 (  1,  1) [000113] D------N----                \--*  lclVar    int    V09 tmp6         
+
+***** BB04, stmt 9
+     ( 59, 43) [000034] ------------             *  stmtExpr  void  (IL 0x013...0x037)
+N021 ( 59, 43) [000031] --CXG-------             \--*  call      void   System.Console.WriteLine
+N002 (  5, 12) [000066] ----G-------                |  /--*  indir     ref   
+N001 (  3, 10) [000065] ------------                |  |  \--*  const(h)  long   0xB3963070 "Catching {0}"
+N004 (  9, 15) [000076] -A--G---R-L- arg0 SETUP     +--*  =         ref   
+N003 (  3,  2) [000075] D------N----                |  \--*  lclVar    ref    V05 tmp2         
+N012 ( 20, 14) [000029] --CXG-------                |  /--*  call      ref    System.Convert.ToString
+N010 (  6,  8) [000028] ---XG------- arg0 in rcx    |  |  \--*  indir     int   
+N008 (  1,  4) [000067] ------------                |  |     |  /--*  const     long   140 field offset Fseq[x]
+N009 (  4,  6) [000068] -------N----                |  |     \--*  +         byref 
+N007 (  3,  2) [000027] ------------                |  |        \--*  lclVar    ref    V03 tmp0         
+N014 ( 24, 17) [000072] -ACXG---R-L- arg1 SETUP     +--*  =         ref   
+N013 (  3,  2) [000071] D------N----                |  \--*  lclVar    ref    V04 tmp1         
+N017 (  3,  2) [000073] ------------ arg1 in rdx    +--*  lclVar    ref    V04 tmp1          (last use)
+N018 (  3,  2) [000077] ------------ arg0 in rcx    \--*  lclVar    ref    V05 tmp2          (last use)
+
+***** BB04, stmt 10
+     ( 18, 19) [000044] ------------             *  stmtExpr  void  (IL 0x028...  ???)
+N014 (  1,  1) [000101] ------------             |     /--*  lclVar    int    V09 tmp6         
+N016 (  5,  4) [000102] -A------R---             |  /--*  =         int   
+N015 (  3,  2) [000100] D------N----             |  |  \--*  lclVar    int    V01 loc0         
+N017 ( 18, 19) [000103] -A-XG-------             \--*  comma     void  
+N010 (  6,  8) [000039] ---XG-------                |     /--*  indir     int   
+N008 (  1,  4) [000081] ------------                |     |  |  /--*  const     long   140 field offset Fseq[x]
+N009 (  4,  6) [000082] -------N----                |     |  \--*  +         byref 
+N007 (  3,  2) [000038] ------------                |     |     \--*  lclVar    ref    V03 tmp0          (last use)
+N011 ( 13, 15) [000041] ---XG-------                |  /--*  +         int   
+N005 (  4,  4) [000037] ---XG-------                |  |  |  /--*  indir     int   
+N003 (  1,  1) [000079] ------------                |  |  |  |  |  /--*  const     long   16 field offset Fseq[val]
+N004 (  2,  2) [000080] -------N----                |  |  |  |  \--*  +         byref 
+N002 (  1,  1) [000036] ------------                |  |  |  |     \--*  lclVar    ref    V08 tmp5         
+N006 (  6,  6) [000040] ---XG-------                |  |  \--*  +         int   
+N001 (  1,  1) [000035] ------------                |  |     \--*  lclVar    int    V09 tmp6         
+N013 ( 13, 15) [000043] -A-XG---R---                \--*  =         int   
+N012 (  1,  1) [000042] D------N----                   \--*  lclVar    int    V09 tmp6         
+
+***** BB04, stmt 11
+     ( 20, 14) [000051] ------------             *  stmtExpr  void  (IL 0x038...0x044)
+N013 ( 20, 14) [000049] --CXGO------             \--*  call      int    Enreg01.foo
+N007 (  1,  1) [000086] ------------                |     /--*  const     long   8 field offset Fseq[dist]
+N008 (  3,  3) [000087] ------------                |  /--*  +         byref 
+N006 (  1,  1) [000085] ------------                |  |  \--*  lclVar    ref    V08 tmp5         
+N009 (  5,  5) [000088] ---XGO-N---- arg1 in rdx    +--*  comma     byref 
+N005 (  2,  2) [000084] ---X-O-N----                |  \--*  nullcheck byte  
+N004 (  1,  1) [000083] ------------                |     \--*  lclVar    ref    V08 tmp5         
+N010 (  1,  1) [000045] ------------ this in rcx    \--*  lclVar    ref    V08 tmp5         
+
+***** BB04, stmt 12
+     ( 11, 10) [000058] ------------             *  stmtExpr  void  (IL 0x045...0x04D)
+N009 (  1,  1) [000105] ------------             |     /--*  lclVar    int    V09 tmp6         
+N011 (  5,  4) [000106] -A------R---             |  /--*  =         int   
+N010 (  3,  2) [000104] D------N----             |  |  \--*  lclVar    int    V01 loc0         
+N012 ( 11, 10) [000107] -A-XG-------             \--*  comma     void  
+N005 (  4,  4) [000054] ---XG-------                |     /--*  indir     int   
+N003 (  1,  1) [000094] ------------                |     |  |  /--*  const     long   16 field offset Fseq[val]
+N004 (  2,  2) [000095] -------N----                |     |  \--*  +         byref 
+N002 (  1,  1) [000053] ------------                |     |     \--*  lclVar    ref    V08 tmp5         
+N006 (  6,  6) [000055] ---XG-------                |  /--*  +         int   
+N001 (  1,  1) [000052] ------------                |  |  \--*  lclVar    int    V09 tmp6         
+N008 (  6,  6) [000057] -A-XG---R---                \--*  =         int   
+N007 (  1,  1) [000056] D------N----                   \--*  lclVar    int    V09 tmp6         
+
+```
+
+#### Post register allocation and code generation code
+
+```diff
+--- base.asmdmp	2017-03-28 20:40:36.000000000 -0700
++++ wt.asmdmp	2017-03-28 20:41:11.000000000 -0700
+@@ -1,78 +1,85 @@
+ *************** After end code gen, before unwindEmit()
+-G_M16307_IG01:        ; func=00, offs=000000H, size=0014H, gcVars=0000000000000000 {}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref, nogc <-- Prolog IG
++G_M16307_IG01:        ; func=00, offs=000000H, size=0017H, gcVars=0000000000000000 {}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref, nogc <-- Prolog IG
+ 
+ push     rbp
++push     r14
+ push     rdi
+ push     rsi
++push     rbx
+ sub      rsp, 48
+-lea      rbp, [rsp+40H]
+-mov      qword ptr [V07 rbp-20H], rsp
++lea      rbp, [rsp+50H]
++mov      qword ptr [V07 rbp-30H], rsp
+ mov      gword ptr [V00 rbp+10H], rcx
+ 
+-G_M16307_IG02:        ; offs=000014H, size=000AH, gcVars=0000000000000001 {V00}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref
++G_M16307_IG02:        ; offs=000017H, size=000AH, gcVars=0000000000000001 {V00}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref
+ 
+-mov      rcx, gword ptr [V00 rbp+10H]
+-mov      ecx, dword ptr [rcx+16]
+-mov      dword ptr [V01 rbp-14H], ecx
++mov      rsi, gword ptr [V00 rbp+10H]
++mov      edi, dword ptr [rsi+16]
++mov      dword ptr [V01 rbp-24H], edi
+ 
+-G_M16307_IG03:        ; offs=00001EH, size=000FH, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, byref
++G_M16307_IG03:        ; offs=000021H, size=000EH, gcrefRegs=00000040 {rsi}, byrefRegs=00000000 {}, byref
+ 
+-mov      rcx, gword ptr [V00 rbp+10H]
++mov      rcx, rsi     ; Elided reload in try region
+ mov      edx, 97
+ call     Enreg01:TryIncrement(int):int:this
+ nop      
+ 
+-G_M16307_IG04:        ; offs=00002DH, size=0003H, gcVars=0000000000000000 {}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref
++G_M16307_IG04:        ; offs=00002FH, size=0005H, gcVars=0000000000000000 {}, gcrefRegs=00000000 {}, byrefRegs=00000000 {}, gcvars, byref
+ 
+-mov      eax, dword ptr [V01 rbp-14H]
++mov      edi, dword ptr [V01 rbp-24H]
++mov      eax, edi
+ 
+-G_M16307_IG05:        ; offs=000030H, size=0008H, epilog, nogc, emitadd
++G_M16307_IG05:        ; offs=000034H, size=000BH, epilog, nogc, emitadd
+ 
+-lea      rsp, [rbp-10H]
++lea      rsp, [rbp-20H]
++pop      rbx
+ pop      rsi
+ pop      rdi
++pop      r14
+ pop      rbp
+ ret      
+ 
+-G_M16307_IG06:        ; func=01, offs=000038H, size=0014H, gcrefRegs=00000004 {rdx}, byrefRegs=00000000 {}, byref, funclet prolog, nogc
++G_M16307_IG06:        ; func=01, offs=00003FH, size=0017H, gcrefRegs=00000004 {rdx}, byrefRegs=00000000 {}, byref, funclet prolog, nogc
+ 
+ push     rbp
++push     r14 
+ push     rdi
+ push     rsi
++push     rbx 
+ sub      rsp, 48
+ mov      rbp, qword ptr [rcx+32]
+ mov      qword ptr [rsp+20H], rbp
+-lea      rbp, [rbp+40H]
++lea      rbp, [rbp+50H]
+ 
+-G_M16307_IG07:        ; offs=00004CH, size=005EH, gcVars=0000000000000001 {V00}, gcrefRegs=00000004 {rdx}, byrefRegs=00000000 {}, gcvars, byref, isz
++G_M16307_IG07:        ; offs=000056H, size=0054H, gcVars=0000000000000001 {V00}, gcrefRegs=00000004 {rdx}, byrefRegs=00000000 {}, gcvars, byref, isz
+ 
+ mov      rsi, rdx
+-mov      rcx, 0x18A3C473070
+-mov      rdi, gword ptr [rcx]
++mov      rcx, gword ptr [V00 rbp+10H]        ; Reload of proxy register
++mov      rdi, rcx                            ; Missed peep
++mov      ecx, dword ptr [V01 rbp-24H]        ; Reload of proxy register
++mov      ebx, ecx                            ; Missed peep
++mov      rcx, 0x263B3963070
++mov      r14, gword ptr [rcx]                ; Missed addressing mode
+ mov      ecx, dword ptr [rsi+140]
+ call     System.Convert:ToString(int):ref
+ mov      rdx, rax
+-mov      rcx, rdi
++mov      rcx, r14
+ call     System.Console:WriteLine(ref,ref)
+-mov      edx, dword ptr [V01 rbp-14H]        ; Elided stack access
+-mov      rcx, gword ptr [V00 rbp+10H]        ; Elided stack access
+-add      edx, dword ptr [rcx+16]
+-add      edx, dword ptr [rsi+140]
+-mov      dword ptr [V01 rbp-14H], edx        ; Elided stack access
+-mov      rdx, gword ptr [V00 rbp+10H]        ; Elided stack access
+-add      rdx, 8
+-mov      rcx, gword ptr [V00 rbp+10H]        ; Elided stack access
++add      ebx, dword ptr [rdi+16]
++add      ebx, dword ptr [rsi+140]
++lea      rdx, bword ptr [rdi+8]
++mov      rcx, rdi
+ call     Enreg01:foo(byref):int:this
+-mov      eax, dword ptr [V01 rbp-14H]        ; Elided stack access
+-mov      rdx, gword ptr [V00 rbp+10H]        ; Elided stack access
+-add      eax, dword ptr [rdx+16]
+-mov      dword ptr [V01 rbp-14H], eax        ; Elided stack access
++add      ebx, dword ptr [rdi+16]
++mov      dword ptr [V01 rbp-24H], ebx        ; Store of proxy register
+ lea      rax, G_M16307_IG04
+ 
+-G_M16307_IG08:        ; offs=0000AAH, size=0008H, funclet epilog, nogc, emitadd
++G_M16307_IG08:        ; offs=0000AAH, size=000BH, funclet epilog, nogc, emitadd
+ 
+ add      rsp, 48
++pop      rbx
+ pop      rsi
+ pop      rdi
++pop      r14
+ pop      rbp
+ ret 
+
+```
+
+Summary of diff:
+replaced 6 loads and 2 stores with 2 loads, 1 store, 2 push, 2 pop.
+
+ 
+
diff --git a/Documentation/design-docs/jit-call-morphing.md b/Documentation/design-docs/jit-call-morphing.md
new file mode 100644
index 0000000000..49fd8bf47c
--- /dev/null
+++ b/Documentation/design-docs/jit-call-morphing.md
@@ -0,0 +1,157 @@
+Morphing of call nodes in RyuJIT
+=========================
+
+Overview
+--------
+
+In C# and IL, and unlike C/C++, the evaluation order of the arguments for calls is strictly defined.
+Basically this is left to right in C# or the IL instruction ordering for IL.
+
+
+One issue that must be addressed is the problem of nested calls.  Consider `Foo(x[i], Bar(y))`.
+We first must evaluate `x[i]` and possibly set up the first argument for `Foo()`.  But immediately
+after that, we must set up `y` as first argument of `Bar()`.  Thus, when we evaluate `x[i]` we will
+need to hold that value someplace while we set up and call `Bar().`  Arguments that contain an
+assignment are another issue that we need to address.  Most cases of this are rare except for
+post/pre increment, perhaps like this: `Foo(j, a[j++])`.  Here `j` is updated via assignment
+when the second arg is evaluated, so the earlier uses of `j` would need to be evaluated and
+saved in a new LclVar.
+
+ 
+One simple approach would be to create new single definition, single use LclVars for every argument
+that is passed.  This would preserve the evaluation order.  However, it would potentially create
+hundreds of LclVar for moderately sized methods and that would overflow the limited number of
+tracked local variables in the JIT.  One observation is that many arguments to methods are
+either constants or LclVars and can be set up anytime we want. They usually will not need a
+new LclVar to preserve the order of evaluation rule.
+
+ 
+Each argument is an arbitrary expression tree.  The JIT tracks a summary of observable side-effects
+using a set of five bit flags in every GenTree node: `GTF_ASG`, `GTF_CALL`, `GTF_EXCEPT`, `GTF_GLOB_REF`,
+and `GTF_ORDER_SIDEEFF`.  These flags are propagated up the tree so that the top node has a particular
+flag set if any of its child nodes has the flag set.  Decisions about whether to evaluate arguments
+into temp LclVars are made by examining these flags on each of the arguments.
+
+
+*Our design goal for call sites is to create a few temp LclVars as possible, while preserving the
+order of evaluation rules of IL and C#.*
+
+
+Data Structures
+------------
+
+The most important data structure is the `GenTreeCall` node which represents a single
+call site and is created by the Importer when it sees a call in the IL.  It is also
+used for internal calls that the JIT needs such as helper calls.  Every `GT_CALL` node
+should have a `GTF_CALL` flag set on it.  Nodes that may be implemented using a function
+call also should have the `GTF_CALL` flag set on them. The arguments for a single call
+site are held by three fields in the `GenTreeCall`: `gtCallObjp`, `gtCallArgs`, and
+`gtCallLateArgs`.  The first one, `gtCallObjp`, contains the instance pointer ("this"
+pointer) when you are calling a method that takes an instance pointer, otherwise it is
+null.  The `gtCallArgs` contains all of the normal arguments in a null terminated `GT_LIST`
+format.  When the `GenTreeCall` is first created the `gtCallLateArgs` is null and is
+set up later when we call `fgMorphArgs()` during the global Morph of all nodes. To
+accurately record and track all of the information about call site arguments we create
+a `fgArgInfo` that records information and decisions that we make about how each argument
+for this call site is handled.  It has a dynamically sized array member `argTable` that
+contains details about each argument. This per-argument information is contained in the
+`fgArgTabEntry` struct.
+
+
+`FEATURE_FIXED_OUT_ARGS`
+-----------------
+
+All architectures support passing a limited number of arguments in registers and the
+additional arguments must be passed on the stack. There are two distinctly different
+approaches for passing arguments of the stack.  For the x86 architecture a push
+instruction is typically used to pass a stack based argument.  For all other architectures
+that we support we allocate the `lvaOutgoingArgSpaceVar`, which is a variable-sized
+stack based LclVar.  Its size is determined by the call site that has the largest
+requirement for stack based arguments.  The define `FEATURE_FIXED_OUT_ARGS` is 1 for
+architectures that use the outgoing arg space to pass their stack based arguments.
+There is only one outgoing argument space and any values stored there are considered
+to be killed by the very next call even if the next call doesn't take any stack based
+arguments. For x86, we can push some arguments on the stack for one call and leave
+them there while pushing some new arguments for a nested call.  Thus we allow nested
+calls for x86 but do not allow them for the other architectures.
+
+
+Rules for when Arguments must be evaluated into temp LclVars
+-----------------
+
+During the first Morph phase known as global Morph we call `fgArgInfo::ArgsComplete()`
+after we have completed building the `argTable` for `fgArgInfo` struct. This method
+applies the following rules:
+
+1. When an argument is marked as containing an assignment using `GTF_ASG`, then we
+force all previous non-constant arguments to be evaluated into temps.  This is very
+conservative, but at this phase of the JIT it is rare to have an assignment subtree
+as part of an argument. 
+2. When an argument is marked as containing a call using the `GTF_CALL` flag, then
+we force that argument and any previous argument that is marked with any of the
+`GTF_ALL_EFFECT` flags into temps.
+	* Additionally, for `FEATURE_FIXED_OUT_ARGS`, any previous stack based args that
+    we haven't marked as needing a temp but still need to store in the outgoing args
+    area is marked as needing a placeholder temp using `needPlace`.
+3. We force any arguments that use `localloc` to be evaluated into temps.
+4. We mark any address taken locals with the `GTF_GLOB_REF` flag. For two special
+cases we call `EvalToTmp()` and set up the temp in `fgMorphArgs`.  `EvalToTmp`
+records the tmpNum used and sets `isTmp` so that we handle it like the other temps.
+The special cases are for `GT_MKREFANY` and for a `TYP_STRUCT` argument passed by
+value when we can't optimize away the extra copy.
+
+
+Rules use to determine the order of argument evaluation
+-----------------
+
+After calling `ArgsComplete()` the `SortArgs()` method is called to determine the
+optimal way to evaluate the arguments.  This sorting controls the order that we place
+the nodes in the `gtCallLateArgs` list.
+
+1. We iterate over the arguments and move any constant arguments to be evaluated
+last and remove them from further consideration by marking them as processed.
+2. We iterate over the arguments and move any arguments that contain calls to be evaluated first and remove them from further consideration by marking them as processed.
+3. We iterate over the arguments and move arguments that must be evaluated into
+temp LclVars to be after the ones that contain calls.
+4. We iterate over the arguments and move arguments that are simple LclVar or
+LclFlds and put them before the constant args.
+5. If there are any remaining arguments, we evaluate them from the most complex
+to the least complex.
+
+
+Evaluating Args into new LclVar temps and the creation of the LateArgs
+-----------------
+
+After calling `SortArgs()`, the `EvalArgsToTemps()` method is called to create
+the temp assignments and to populate the LateArgs list. Arguments that are
+marked with `needTmp == true`.
+
+1. We create an assignment using `gtNewTempAssign`. This assignment replaces
+the original argument in the `gtCallArgs` list.  After we create the assignment
+the argument is marked as `isTmp`.  The new assignment is marked with the
+`GTF_LATE_ARG` flag. 
+2. Arguments that are already marked with `isTmp` are treated similarly as
+above except we don't create an assignment for them.
+3. A `TYP_STRUCT` argument passed by value will have `isTmp` set to true
+and will use a `GT_COPYBLK` or a `GT_COPYOBJ` to perform the assignment of the temp.
+4. The assignment node or the CopyBlock node is referred to as `arg1 SETUP` in the JitDump.
+
+
+Argument that are marked with `needTmp == false`.
+-----------------
+
+1. If this is an argument that is passed in a register, then the existing
+node is moved to the `gtCallLateArgs` list and a new `GT_ARGPLACE` (placeholder)
+node replaces it in the `gtArgList` list.
+2. Additionally, if `needPlace` is true (only for `FEATURE_FIXED_OUT_ARGS`)
+then the existing node is moved to the `gtCallLateArgs` list and a new
+`GT_ARGPLACE` (placeholder) node replaces it in the `gtArgList` list.
+3. Otherwise the argument is left in the `gtCallArgs` and it will be
+evaluated into the outgoing arg area or pushed on the stack.
+
+After the Call node is fully morphed the LateArgs list will contain the arguments
+passed in registers as well as additional ones for `needPlace` marked
+arguments whenever we have a nested call for a stack based argument.
+When `needTmp` is true the LateArg will be a LclVar that was created
+to evaluate the arg (single-def/single-use).  When `needTmp` is false
+the LateArg can be an arbitrary expression tree.
diff --git a/Documentation/design-docs/jump-stubs.md b/Documentation/design-docs/jump-stubs.md
new file mode 100644
index 0000000000..86bf0ac134
--- /dev/null
+++ b/Documentation/design-docs/jump-stubs.md
@@ -0,0 +1,518 @@
+# Jump Stubs
+
+## Overview
+
+On 64-bit platforms (AMD64 (x64) and ARM64), we have a 64-bit address
+space. When the CLR formulates code and data addresses, it generally
+uses short (<64 bit) relative addresses, and attempts to pack all code
+and data relatively close together at runtime, to reduce code size. For
+example, on x64, the JIT generates 32-bit relative call instruction
+sequences, which can refer to a target address +/- 2GB from the source
+address, and which are 5 bytes in size: 1 byte for opcode and 4 bytes
+for a 32-bit IP-relative offset (called a rel32 offset). A call sequence
+with a full 64-bit target address requires 12 bytes, and in addition
+requires a register. Jumps have the same characteristics as calls: there
+are rel32 jumps as well.
+
+In case the short relative address is insufficient to address the target
+from the source address, we have two options: (1) for data, we must
+generate full 64-bit sized addresses, (2) for code, we insert a "jump
+stub", so the short relative call or jump targets a "jump stub" which
+then jumps directly to the target using a full 64-bit address (and
+trashes a register to load that address). Since calls are so common, and
+the need for full 64-bit call sequences so rare, using this design
+drastically improves code size. The need for jump stubs only arises when
+jumps of greater than 2GB range (on x64; 128MB on arm64) are required.
+This only happens when the amount of code in a process is very large,
+such that all the related code can't be packed tightly together, or the
+address space is otherwise tightly packed in the range where code is
+normally allocated, once again preventing from packing code together.
+
+An important issue arises, though: these jump stubs themselves must be
+allocated within short relative range of the small call or jump
+instruction. If that doesn't occur, we encounter a fatal error
+condition, if we have no way for the already generated instruction to
+reach its intended target.
+
+ARM64 has a similar issue: it has a 28-bit relative branch that is the
+preferred branch instruction. The JIT always generates this instruction,
+and requires the VM to generate jump stubs if required. However, the VM
+does not use this form in any of its stubs; it always uses large form
+branches. The remainder of this document will only describe the AMD64
+case.
+
+This document will describe the design and implementation of jump stubs,
+their various users, the design of their allocation, and how we can
+address the problem of failure to allocate required jump stubs (which in
+this document I call "mitigation"), for each case.
+
+## Jump stub creation and management
+
+A jump stub looks like this:
+```
+mov rax, <8-byte address>
+jmp rax
+```
+
+It is 12 bytes in size. Note that it trashes the RAX register. Since it
+is normally used to interpose on a call instruction, and RAX is a
+callee-trashed (volatile) register for amd64 (for both Windows and Linux
+/ System V ABI), this is not a problem. For calls with custom calling
+conventions, like profiler hooks, the VM is careful not to use jump
+stubs that might interfere with those conventions.
+
+Jump stub creation goes through the function `rel32UsingJumpStub()`. It
+takes the rel32 data address, the target address, and computes the
+offset from the source to the target address, and returns this offset.
+Note that the source, or "base", address is the address of the rel32
+data plus 4 bytes, which it assumes due to the rules of the x86/x64
+instruction set which state that the "base" address for computing a
+branch offset is the instruction pointer value, or address, of the
+following instruction, which is the rel32 address plus 4.
+
+If the offset doesn't fit, it computes the allowed address range (e.g.,
+[low ... high]) where a jump stub must be located to create a legal
+rel32 offset, and calls `ExecutionManager::jumpStub()` to create or find
+an appropriate jump stub.
+
+Jump stubs are allocated in the loader heap associated with a particular
+use: either the `LoaderCodeHeap` for normal code, or the `HostCodeHeap`
+for DynamicMethod / LCG functions. Dynamic methods cannot share jump
+stubs, to support unloading individual methods and reclaiming their
+memory. For normal code, jump stubs are reused. In fact, we maintain a
+hash table mapping from jump stub target to the jump stub itself, and
+look up in this table to find a jump stub to reuse.
+
+In case there is no space left for a jump stub in any existing code heap
+in the correct range, a new code heap is attempted to be created in the
+range required by the new jump stub, using the function
+`ClrVirtualAllocWithinRange()`. This function walks the acceptable address
+space range, using OS virtual memory query/allocation APIs, to find and
+allocate a new block of memory in the acceptable range. If this function
+can't find and allocate space in the required range, we have, on AMD64,
+one more fallback: if an emergency jump stub reserve was created using
+the `COMPlus_NGenReserveForjumpStubs` configuration (see below), we
+attempt to find an appropriate, in range, allocation from that emergency
+pool. If all attempts fail to create an allocation in the appropriate
+range, we encounter a fatal error (and tear down the process), with a
+distinguished "out of memory within range" message (using the
+`ThrowOutOfMemoryWithinRange()` function).
+
+## Jump stub allocation failure mitigation
+
+Several strategies have already been created to attempt to lessen the
+occurrence of jump stub allocation failure. The following CLR
+configuration variables are relevant (these can be set in the registry
+as well as the environment, as usual):
+
+* `COMPlus_CodeHeapReserveForJumpStubs`. This value specifies a percentage
+of every code heap to reserve for jump stubs. When a non-jump stub
+allocation in the code heap would eat into the reserved percentage, a
+new code heap is allocated instead, leaving some buffer in the existing
+code heap. The default value is 2.
+* `COMPlus_NGenReserveForjumpStubs`. This value, when non-zero, creates an
+"emergency jump stub reserve". For each NGEN image loaded, an emergency
+jump stub reserve space is calculated by multiplying this number, as a
+percentage, against the loaded native image size. This amount of space
+is allocated, within rel32 range of the NGEN image. An allocation
+granularity for these emergency code heaps exceeds the specific
+requirement, but multiple NGEN images can share the same jump stub
+emergency space heap if it is in range. If an emergency jump stub space
+can't be allocated, the failure is ignored (hopefully in this case any
+required jump stub will be able to be allocated somewhere else). When
+looking to allocate jump stubs, the normal mechanisms for finding jump
+stub space are followed, and only if they fail to find appropriate space
+are the emergency jump stub reserve heaps tried. The default value is
+zero.
+* `COMPlus_BreakOnOutOfMemoryWithinRange`. When set to 1, this breaks into
+the debugger when the specific jump stub allocation failure condition
+occurs.
+
+The `COMPlus_NGenReserveForjumpStubs` mitigation is described publicly
+here:
+https://support.microsoft.com/en-us/help/3152158/out-of-memory-exception-in-a-managed-application-that-s-running-on-the-64-bit-.net-framework.
+(It also mentions, in passing, `COMPlus_CodeHeapReserveForJumpStubs`, but
+only to say not to use it.)
+
+## Jump stubs and the JIT
+
+As the JIT generates code on AMD64, it starts by generating all data and
+code addresses as rel32 IP-relative offsets. At the end of code
+generation, the JIT determines how much code will be generated, and
+requests buffers from the VM to hold the generated artifacts: a buffer
+for the "hot" code, a buffer for the "cold" code (only used in the case
+of hot/cold splitting during NGEN), and a buffer for the read-only data
+(see `ICorJitInfo::allocMem()`). The VM finds allocation space in either
+existing code heaps, or in newly created code heaps, to satisfy this
+request. It is only at this point that the actual addresses where the
+generated code will live is known. Note that the JIT has finalized the
+exact generated code sequences in the function before calling
+`allocMem()`. Then, the JIT issues (or "emits") the generated instruction
+bytes into the provided buffers, as well as telling the VM about
+exception handling ranges, GC information, and debug information.
+When the JIT emits an instruction that includes a rel32 offset (as well
+as for other cases of global pointer references), it calls the VM
+function `ICorJitInfo::recordRelocation()` to tell the VM the address of
+the rel32 data and the intended target address of the rel32 offset. How
+this is handled in the VM depends on whether we are JIT-compiling, or
+compiling for NGEN.
+
+For JIT compilation, the function `CEEJitInfo::recordRelocation()`
+determines the actual rel32 value to use, and fills in the rel32 data in
+the generated code buffer. However, what if the offset doesn't fit in a
+32-bit rel32 space?
+
+Up to this point, the VM has allowed the JIT to always generate rel32
+addresses. It is allowed by the JIT calling
+`ICorJitInfo::getRelocTypeHint()`. If this function returns
+`IMAGE_REL_BASED_REL32`, then the JIT generates a rel32 address. The first
+time in the lifetime of the process when recordRelocation() fails to
+compute an offset that fits in a rel32 space, the VM aborts the
+compilation, and restarts it in a mode where
+`ICorJitInfo::getRelocTypeHint()` never returns `IMAGE_REL_BASED_REL32`.
+That is, the VM never allows the JIT to generate rel32 addresses. This
+is "rel32 overflow" mode. However, this restriction only applies to data
+addresses. The JIT will then load up full 64-bit data addresses in the
+code (which are also subject to relocation), and use those. These 64-bit
+data addresses are guaranteed to reach the entire address space.
+
+The JIT continues to generate rel32 addresses for call instructions.
+After the process is in rel32 overflow mode, if the VM gets a
+`ICorJitInfo::recordRelocation()` that overflows rel32 space, it assumes
+the rel32 address is for a call instruction, and it attempts to build a
+jump stub, and patch the rel32 with the offset to the generated jump
+stub.
+
+Note that in rel32 overflow mode, most call instructions are likely to
+still reach their intended target with a rel32 offset, so jump stubs are
+not expected to be required in most cases.
+
+If this attempt to create a jump stub fails, then the generated code
+cannot be used, and we hit a fatal error; we have no mechanism currently
+to recover from this failure, or to prevent it.
+
+There are several problems with this system:
+1. Because the VM doesn't know whether a `IMAGE_REL_BASED_REL32`
+relocation is for data or for code, in the normal case (before "rel32
+overflow" mode), it assumes the worst, that it is for data. It's
+possible that if all rel32 data accesses fit, and only code offsets
+don't fit, and the VM could distinguish between code and data
+references, that we could generate jump stubs for the too-large code
+offsets, and never go into "rel32 overflow" mode that leads to
+generating 64-bit data addresses.
+2. We can't stress jump stub creation functionality for JIT-generated
+code because the JIT generates `IMAGE_REL_BASED_REL32` relocations for
+intra-function jumps and calls that it expects and, in fact, requires,
+not be replaced with jump stubs, because it doesn't expect the register
+used by jump stubs (RAX) to be trashed.
+3. We don't have any mechanism to recover if a jump stub can't be
+allocated.
+
+In the NGEN case, rel32 calls are guaranteed to always reach, as PE
+image files are limited to 2GB in size, meaning a rel32 offset is
+sufficient to reach from any location in the image to any other
+location. In addition, all control transfers to locations outside the
+image go through indirection stubs. These stubs themselves might require
+jump stubs, as described later.
+
+### Failure mitigation
+
+There are several possible mitigations for JIT failure to allocate jump
+stubs.
+1. When we get into "rel32 overflow" mode, the JIT could always generate
+large calls, and never generate rel32 offsets. This is obviously
+somewhat expensive, as every external call, such as every call to a JIT
+helper, would increase from 5 to 12 bytes. Since it would only occur
+once you are in "rel32 overflow" mode, you already know that the process
+is quite large, so this is perhaps justifiable, though also perhaps
+could be optimized somewhat. This is very simple to implement.
+2. Note that you get into "rel32 overflow" mode even for data addresses.
+It would be useful to verify that the need for large data addresses
+doesn't happen much more frequently than large code addresses.
+3. An alternative is to have two separate overflow modes: "data rel32
+overflow" and "code rel32 overflow", as follows:
+   1. "data rel32 overflow" is entered by not being able to generate a
+      rel32 offset for a data address. Restart the compile, and all subsequent
+      data addresses will be large.
+   2. "code rel32 overflow" is entered by not being able to generate a
+      rel32 offset or jump stub for a code address. Restart the compile, and
+      all subsequent external call/jump sequences will be large.
+      These could be independent, which would require distinguishing code and
+      data rel32 to the VM (which might be useful for other reasons, such as
+      enabling better stress modes). Or, we could layer them: "data rel32
+      overflow" would be the current "rel32 overflow" we have today, which we
+      must enter before attempting to generate a jump stub. If a jump stub
+      fails to be created, we fail and retry the compilation again, enter
+      "code rel32 overflow" mode, and all subsequent code (and data) addresses
+      would be large. We would need to add the ability to communicate this new
+      mode from the VM to the JIT, implement large call/jump generation in the
+      JIT, and implement another type of retry in the VM.
+4. Another alternative: The JIT could determine the total number of
+unique external call/jump targets from a function, and report that to
+the VM. Jump stub space for exactly this number would be allocated,
+perhaps along with the function itself (such as at the end), and only if
+we are in a "rel32 overflow" mode. Any jump stub required would come
+from this space (and identical targets would share the same jump stub;
+note that sharing is optional). Since jump stubs would not be shared
+between functions, this requires more space than the current jump stub
+system but would be guaranteed to work and would only kick in when we
+are already experiencing large system behavior.
+
+## Other jump stub creation paths
+
+The VM has several other locations that dynamically generate code or
+patch previously generated code, not related to the JIT generating code.
+These also must use the jump stub mechanism to possibly create jump
+stubs for large distance jumps. The following sections describe these
+cases.
+
+## ReJIT
+
+ReJIT is a CLR profiler feature, currently only implemented for x86 and
+amd64, that allows a profiler to request a function be re-compiled with
+different IL, given by the profiler, and have that newly compiled code
+be used instead of the originally compiled IL. This happens within a
+live process. A single function can be ReJIT compiled more than once,
+and in fact, any number of times. The VM currently implements the
+transfer of control to the ReJIT compiled function by replacing the
+first five bytes of the generated code of the original function with a
+"jmp rel32" to the newly generated code. Call this the "jump patch"
+space. One fundamental requirement for this to work is that every
+function (a) be at least 5 bytes long, and (b) the first 5 bytes of a
+function (except the first, which is the address of the function itself)
+can't be the target of any branch. (As an implementation detail, the JIT
+currently pads the function prolog out to 5 bytes with NOP instructions,
+if required, even if there is enough code following the prolog to
+satisfy the 5-byte requirement if those non-prolog bytes are also not
+branch targets.)
+
+If the newly ReJIT generated code is at an address that doesn't fit in a
+rel32 in the "jmp rel32" patch, then a jump stub is created.
+
+The JIT only creates the required jump patch space if the
+`CORJIT_FLG_PROF_REJIT_NOPS` flag is passed to the JIT. For dynamic
+compilation, this flag is only passed if a profiler is attached and has
+also requested ReJIT services. Note that currently, to enable ReJIT, the
+profiler must be present from process launch, and must opt-in to enable
+ReJIT at process launch, meaning that all JIT generated functions will
+have the jump patch space under these conditions. There will never be a
+mix of functions with and without jump patch space in the process if a
+profiler has enabled ReJIT. A desirable future state from the profiler
+perspective would be to support profiler attach-to-process and ReJIT
+(with function swapping) at any time thereafter. This goal may or may
+not be achieved via the jump stamp space design.
+
+All NGEN and Ready2Run images are currently built with the
+`CORJIT_FLG_PROF_REJIT_NOPS` flag set, to always enable ReJIT using native
+images.
+
+A single function can be ReJIT compiled many times. Only the last ReJIT
+generated function can be active; the previous compilations consume
+address space in the process, but are not collected until the AppDomain
+unloads. Each ReJIT event must update the "jmp rel32" patch to point to
+the new function, and thus each ReJIT event might require a new jump
+stub.
+
+If a situation arises where a single function is ReJIT compiled many
+times, and each time requires a new jump stub, it's possible that all
+jump stub space near the original function can be consumed simply by the
+"leaked" jump stubs created by all the ReJIT compilations for a single
+function. The "leaked" ReJIT compiled functions (since they aren't
+collected until AppDomain unload) also make it more likely that "close"
+code heap address space gets filled up.
+
+### Failure mitigation
+
+A simple mitigation would be to increase the size of the required
+function jump patch space from 5 to 12 bytes. This is a two line change
+in the `CodeGen::genPrologPadForReJit()` function in the JIT. However,
+this would increase the size of all NGEN and Ready2Run images. Note that
+many managed code functions are very small, with very small prologs, so
+this could significantly impact code size (the change could easily be
+measured). For JIT-generated code, where the additional size would only
+be added once a profiler has enabled ReJIT, it seems like the additional
+code size would be easily justified.
+
+Note that a function has at most one active ReJIT companion function.
+When that ReJIT function is no longer used (and thus never again used),
+the associated jump stub is also "leaked", and never used again. We
+could reserve space for a single jump stub for each function, to be used
+by ReJIT, and then, if a jump stub is required for ReJIT, always use
+that space. The JIT could pad the function end by 12 bytes when the
+`CORJIT_FLG_PROF_REJIT_NOPS` flag is passed, and the ReJIT patching code
+could use this reserved space any time it required a jump stub. This
+would require 12 bytes extra bytes to be allocated for every function
+generated when the `CORJIT_FLG_PROF_REJIT_NOPS` flag is passed. These 12
+bytes could also be allocated at the end of the code heap, in the
+address space, but not in the normal working set.
+
+For NGEN and Ready2Run, this would require 12 bytes for every function
+in the image. This is quite a bit more space than the suggested
+mitigation of increasing prolog padding to 12 bytes but only if
+necessary (meaning, only if they aren't already 12 bytes in size).
+Alternatively, NGEN could allocate this space itself in the native
+image, putting it in some distant jump stub data area or section that
+would be guaranteed to be within range (due to the 2GB PE file size
+limitation) but wouldn't consume physical memory unless needed. This
+option would require more complex logic to allocate and find the
+associated jump stub during ReJIT. This would be similar to the JIT
+case, above, of reserving the jump stub in a distant portion of the code
+heap.
+
+## NGEN
+
+NGEN images are built with several tables of code addresses that must be
+patched when the NGEN image is loaded.
+
+### CLR Helpers
+
+During NGEN, the JIT generates either direct or indirect calls to CLR
+helpers. Most are direct calls. When NGEN constructs the PE file, it
+causes these all to branch to (or through, in the case of indirect
+calls) the helper table. When a native image is loaded, it replaces the
+helper number in the table with a 5-byte "jmp rel32" sequence. If the
+rel32 doesn't fit, a jump stub is created. Note that each helper table
+entry is allocated with 8 bytes (only 5 are needed for "jmp rel32", but
+presumably 8 bytes are reserved to improve alignment.)
+
+The code for filling out the helper table is `Module::LoadHelperTable()`.
+
+#### Failure mitigation
+
+A simple fix is to change NGEN to reserve 12 bytes for each direct call
+table entry, to accommodate the 12-byte jump stub sequence. A 5-byte
+"jmp rel32" sequence could still be used, if it fits, but the full 12
+bytes would be used if necessary.
+
+There are fewer than 200 helpers, so a maximum additional overhead would
+be about `200 * (12 - 8) = 800` bytes. That is by far a worst-case
+scenario. Mscorlib.ni.dll itself has 72 entries in the helper table.
+System.XML.ni.dll has 51 entries, which would lead to 288 and 204 bytes
+of additional space, out of 34MB and 12MB total NI file size,
+respectively.
+
+An alternative is to change all helper calls in NGEN to be indirect:
+```
+call [rel32]
+```
+where the [rel32] offset points to an 8-byte address stored in the
+helper table. This method is already used by exactly one helper on
+AMD64: `CORINFO_HELP_STOP_FOR_GC`, in particular because this helper
+doesn't allow us to trash RAX, as required by jump stubs.
+Similarly, Ready2Run images use:
+```
+call [rel32]
+```
+for "hot" helpers and:
+```
+call [rel32]
+```
+to a shared:
+```
+jmp [rel32]
+```
+for cold helpers. We could change NGEN to use the Ready2Run scheme.
+
+Alternatively, we might handle all NGEN jump stub issues by reserving a
+section in the image for jump stubs that reserves virtual address space
+but does not increase the size of the image (in C++ this is the ".bss"
+section). The size of this section could be calculated precisely from
+all the required possible jump stub contributions to the image. Then,
+the jump stub code would allocate jump stubs from this space when
+required for a NGEN image.
+
+### Cross-module inherited methods
+
+Per the comments on `VirtualMethodFixupWorker()`, in an NGEN image,
+virtual slots inherited from cross-module dependencies point to jump
+thunks. The jump thunk invokes code to ensure the method is loaded and
+has a stable entry point, at which point the jump thunk is replaced by a
+"jmp rel32" to that stable entrypoint. This is represented by
+`CORCOMPILE_VIRTUAL_IMPORT_THUNK`. This can require a jump stub.
+
+Similarly, `CORCOMPILE_EXTERNAL_METHOD_THUNK` represents another kind of
+jump thunk in the NGEN image that also can require a jump stub.
+
+#### Failure mitigation
+
+Both external method thunks could be changed to reserve 12 bytes instead
+of just 5 for the jump thunk, to provide for space required for any
+potential jump stub.
+
+## Precode
+
+Precodes are used as temporary entrypoints for functions that will be
+JIT compiled. They are also used for temporary entrypoints in NGEN
+images for methods that need to be restored (i.e., the method code has
+external references that need to be loaded before the code runs). There
+exists `StubPrecode`, `FixupPrecode`, `RemotingPrecode`, and
+`ThisPtrRetBufPrecode`. Each of these generates a rel32 jump and/or call
+that might require a jump stub.
+
+StubPrecode is the "normal" general case. FixupPrecode is the most
+common, and has been heavily size optimized. Each FixupPrecode is 8
+bytes. Generated code calls the FixupPrecode address. Initially, the
+precode invokes code to generate or fix up the method being called, and
+then "fix up" the FixupPrecode itself to jump directly to the native
+code. This final code will be a "jmp rel32", possibly via a jump stub.
+DynamicMethod / LCG uses FixupPrecode. This code path has been found to
+fail in large customer installations.
+
+### Failure mitigation
+
+An implementation has been made which changes the allocation of
+FixupPrecode to pre-allocate space for jump stubs, but only in the case
+of DynamicMethod. (See https://github.com/dotnet/coreclr/pull/9883).
+Currently, FixupPrecode are allocated in "chunks", that share a
+MethodDesc pointer. For LCG, each chunk will have an additional set of
+bytes allocated, to reserve space for one jump stub per FixupPrecode in
+the chunk. When the FixupPrecode is patched, for LCG methods it will use
+the pre-allocated space if a jump stub is required.
+
+For the non-LCG, non-FixupPrecode cases, we need a different solution.
+It would be easy to similarly allocate additional space for each type of
+precode with the precode itself. This might prove expensive. An
+alternative would be to ensure, by design, that somehow shared jump stub
+space is available, perhaps by reserving it in a shared area when the
+precode is allocated, and falling back to a mechanism where the precode
+reserves its own jump stub space if shared jump stub space cannot be
+allocated.
+
+A possibly better implementation would be to reserve, but not allocate,
+jump stub space at the end of the code heap, similar to how
+CodeHeapReserveForJumpStubs works, but instead the reserve amount should
+be computed precisely.
+
+## Ready2Run
+
+There are several DynamicHelpers class methods, used by Ready2Run, which
+may create jump stubs (not all do, but many do). The helpers are
+allocated dynamically when the helper in question is needed.
+
+### Failure mitigation
+
+These helpers could easily be changed to allocate additional, reserved,
+unshared space for a potential jump stub, and that space could be used
+when creating the rel32 offset.
+
+## Compact entrypoints
+
+The compact entrypoints implementation might create jump stubs. However,
+compact entrypoints are not enabled for AMD64 currently.
+
+## Stress modes
+
+Setting `COMPlus_ForceRelocs=1` forces jump stubs to be created in all
+scenarios except for JIT generated code. As described previously, the
+VM doesn't know when the JIT is reporting a rel32 data address or code
+address, and in addition the JIT reports relocations for intra-function
+jumps and calls for which it doesn't expect the register used by the
+jump stub to be trashed, thus we don't force jump stubs to be created
+for all JIT-reported jumps or calls.
+
+We should improve the communication between the JIT and VM such that we
+can reliably force jump stub creation for every rel32 call or jump. In
+addition, we should make sure to enable code to stress the creation of
+jump stubs for every mitigation that is implemented whether that be
+using the existing `COMPlus_ForceRelocs` configuration, or the creation of
+a new configuration option.
diff --git a/Documentation/design-docs/lsra-throughput.md b/Documentation/design-docs/lsra-throughput.md
new file mode 100644
index 0000000000..4fd704c763
--- /dev/null
+++ b/Documentation/design-docs/lsra-throughput.md
@@ -0,0 +1,74 @@
+Improving LSRA Throughput
+=========================
+
+There are a number of ways in which the current implementation of linear scan register allocation (LSRA) is sub-optimal:
+* I'm not certain that the extra pass that enumerates the nodes before the current `TreeNodeInfoInit` pass must be separate.
+  Further investigation is needed.
+* The identification of opportunities for "containment" (i.e. where the computation of a node's result can be folded into the parent,
+such as a load or store) is done during `Lowering` and communicated to the register allocator via a `gtLsraInfo` field on the node, that
+is otherwise unused, and is basically duplicated when the `RefPosition`s are built for the node.
+  * A more efficient representation of "containment" could allow this to remain in `Lowering`, where existing transformations already
+    take into account the parent context.
+    * This would also have the additional benefit of simplifying the containment check, which is done at least once for each node
+      (at the beginning of `CodeGen::genCodeForTreeNode()`), and then additionally when considering whether the operands of the current
+      node are contained.
+  * Alternatively, the containment analysis could be done during the building of `RefPosition`s, though see below.
+* Similarly, the specification of register requirements is done during the final pass of `Lowering`, and fundamentally requires more
+  space (it must specify register masks for sources, destination and any internal registers). In addition, the requirement for a new
+  register definition (the destination of the node, or any internal registers) is independent of the parent, so this could be done in
+  `LinearScan::buildRefPositionsForNode()` without having to do a dual traversal, unlike the identification of contained nodes.
+* After building `RefPositions`, they are traversed in order to set the last use bits.
+  This is done separately because there are currently inconsistencies between the gtNext/gtPrev links and the actual order of codegen.
+  Once this is resolved, the lastUse bits should be set prior to register allocation by the liveness pass (#7256).
+* The `RefPosition`s are all created prior to beginning the register allocation pass. However, they are only really needed in advance
+  for the lclVars, which, unlike the "tree temps", have multiple definitions and may be live across basic blocks.
+  The `RefPositions`s for the tree temps could potentially be allocated on-the-fly, saving memory and probably improving locality (#7257).
+* The loop over all the candidate registers in `LinearScan::tryAllocateFreeReg()` and in `LinearScan::allocateBusyReg()` could be
+  short-circuited when a register is found that has the best possible score. Additionally, in the case of MinOpts, it could potentially
+  short-circuit as soon as a suitable candidate is found, though one would want to weight the throughput benefit against the code
+  quality impact. 
+
+Representing Containedness
+==========================
+My original plan for this was to combine all of the functionality of the current `TreeNodeInfoInit` pass with the building of `RefPositions`,
+and eliminate `gtLsraInfo`.
+The idea was to later consider pulling the containment analysis back into the first phase of `Lowering`.
+However, after beginning down that path (extracting the `TreeNodeInfoInit` methods into separate lsra{arch}.cpp files), I realized that
+there would be a great deal of throw-away work to put the containment analysis into `LinearScan`, only to potentially pull it out later.
+
+Furthermore, the representation of containedness is not very clean:
+* `Lowering` first communicates this as a combination of implicit knowledge of a node's behavior and its `gtLsraInfo.dstCount`.
+* Later, during `CodeGen`, it is determined by combining similar implicit node characteristics with the presence or absence of a register.
+
+I propose instead to do the following:
+* Add a flag to each node to indicate whether or not it is a tree root.
+  * To free up such a flag, I propose to eliminate `GTF_REG_VAL` for the non-`LEGACY_BACKEND`. Doing so will require some additional cleanup,
+    but in the process a number of hacks can be eliminated that are currently there to workaround the fact that the emitter was designed
+    to work with a code generator that dynamically assigned registers, and set that flag when the code had been generated to put it in a
+    register, unlike the RyuJIT backend, which assigns the registers before generating code.
+* Define new register values:
+  * `REG_UNK` is assigned by `Lowering` when a register is required.
+  * `REG_OPT` is assigned by `Lowering` when a register is optional at both definition and use.
+  * `REG_OPT_USE` is assigned by `Lowering` when a register is required at the definition, but optional at the use.
+  * I don't know if we need `REG_OPT_DEF`, but that could be added as well.
+* Having done this, we can greatly simplify `IsContained()`.
+
+It may be more effective to use the extra bit for an actual `GTF_CONTAINED` flag, and that is something we might want to consider
+eventually, but initially it is easier to simplify the containedness check using `GTF_TREE_ROOT` without having to change all the
+places that currently mark nodes as contained.
+
+Combining Containedness Analysis with Lowering
+==============================================
+Once we've changed containedness to use the above representation, we can move the code to set it into the first pass of `Lowering`.
+There are likely to be some phase ordering challenges, but I don't think they will be prohibitive.
+
+Eliminating gtLsraInfo
+======================
+Issue #7225.
+
+After the containedness changes above, all that remains to communicate via `gtLsraInfo` is the register requirements.
+This step would still use the `TreeNodeInfo` data structure and the `TreeNodeInfoInit()` methods, but they would be called as
+each node is handled by `LinearScan::buildRefPositionsForNode()`.
+
+
+