You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/dotnet/runtime/labels/good%20first%20issue)
-**DO** generate code that looks as if a developer would write it manually.
13
+
-**DO** emit strings rather than using the Roslyn Syntax API for better performance.
14
+
-**DO** use consistent indentation and formatting in generated code.
15
+
-**DO** generators should use the [`IIncrementalGenerator`](https://learn.microsoft.com/dotnet/api/microsoft.codeanalysis.iincrementalgenerator) interface.
16
+
-**DO** set `<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>` in the source generator project and then don't use any of the banned APIs it lists.
17
+
-**DO** set `<IsRoslynComponent>true</IsRoslynComponent>` in the source generator project to enable debugging support in Visual Studio.
18
+
-**DO** disable the following Roslyn warning, `RS2008`, in the source generator project (that is, `<NoWarn>$(NoWarn);RS2008</NoWarn>`). The reported issue is handled differently in the runtime repo.
19
+
-**DO** emit diagnostics from a separate [analyzer](https://learn.microsoft.com/visualstudio/extensibility/getting-started-with-roslyn-analyzers). The analyzer and source generator can be in the same assembly.
20
+
-**DO** cache intermediate results to avoid redundant computation.
21
+
-**DO** consider the impact on build time and optimize accordingly.
22
+
-**DO** have separate projects for testing the generator and testing the code generated by the generator.
23
+
-**DO** use the Roslyn Testing SDK to test the generator (and any corresponding analyzers).
24
+
25
+
### DON'Ts
26
+
27
+
-**DON'T** use the Roslyn Syntax API for emitting source code.
28
+
-**DON'T** perform expensive operations during the generation process unless absolutely necessary.
29
+
-**DON'T** emit code that introduces runtime dependencies not explicitly referenced by the project.
30
+
-**DON'T** emit code that would trigger compiler warnings in normal usage scenarios.
31
+
-**DON'T** emit diagnostics from the generator itself, emit them from an [analyzer](https://learn.microsoft.com/visualstudio/extensibility/getting-started-with-roslyn-analyzers).
Copy file name to clipboardExpand all lines: docs/design/coreclr/botr/clr-abi.md
+5-35Lines changed: 5 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -322,33 +322,9 @@ Finally1:
322
322
323
323
Note that JIT64 does not implement this properly. The C# compiler used to always insert all necessary "step" blocks. The Roslyn C# compiler at one point did not, but then was changed to once again insert them.
324
324
325
-
## The PSPSym and funclet parameters
325
+
## Funclet parameters
326
326
327
-
The *PSPSym* (which stands for Previous Stack Pointer Symbol) is a pointer-sized local variable used to access locals from the main function body.
328
-
329
-
NativeAOT does not use PSPSym. For filter funclets the VM sets the frame register to be the same as the parent function. For second pass funclets the VM restores all non-volatile registers. The same convention is used across all platforms.
330
-
331
-
CoreCLR uses PSPSym for all platforms except x86: the frame pointer on x86 is always preserved when the handlers are invoked.
332
-
333
-
First, two definitions.
334
-
335
-
*Caller-SP* is the value of the stack pointer in a function's caller before the call instruction is executed. That is, when function A calls function B, Caller-SP for B is the value of the stack pointer immediately before the call instruction in A (calling B) was executed. Note that this definition holds for both AMD64, which pushes the return value when a call instruction is executed, and for ARM, which doesn't. For AMD64, Caller-SP is the address above the call return address.
336
-
337
-
*Initial-SP* is the initial value of the stack pointer after the fixed-size portion of the frame has been allocated. That is, before any "alloca"-type allocations.
338
-
339
-
The value stored in PSPSym is the value of Initial-SP for AMD64 or Caller-SP for other platforms, for the main function. The stack offset of the PSPSym is reported to the VM in the GC information header. The value reported in the GC information is the offset of the PSPSym from Initial-SP for AMD64 or Caller-SP for other platforms. (Note that both the value stored, and the way the value is reported to the VM, differs between architectures. In particular, note that most things in the GC information header are reported as offsets relative to Caller-SP, but PSPSym on AMD64 is one exception, and maybe the only exception.)
340
-
341
-
The VM uses the PSPSym to find other locals it cares about (such as the generics context in a funclet frame). The JIT uses it to re-establish the frame pointer register, so that the frame pointer is the same value in a funclet as it is in the main function body.
342
-
343
-
When a funclet is called, it is passed the *Establisher Frame Pointer*. For AMD64 this is true for all funclets and it is passed as the first argument in RCX, but for ARM and ARM64 this is only true for first pass funclets (currently just filters) and it is passed as the second argument in R1. The Establisher Frame Pointer is a stack pointer of an interesting "parent" frame in the exception processing system. For the CLR, it points either to the main function frame or a dynamically enclosing funclet frame from the same function, for the funclet being invoked. The value of the Establisher Frame Pointer is Initial-SP on AMD64, Caller-SP on x86, ARM, and ARM64.
344
-
345
-
Using the establisher frame, the funclet wants to load the value of the PSPSym. Since we don't know if the Establisher Frame is from the main function or a funclet, we design the main function and funclet frame layouts to place the PSPSym at an identical, small, constant offset from the Establisher Frame in each case. (This is also required because we only report a single offset to the PSPSym in the GC information, and that offset must be valid for the main function and all of its funclets). Then, the funclet uses this known offset to compute the PSPSym address and read its value. From this, it can compute the value of the frame pointer (which is a constant offset from the PSPSym value) and set the frame register to be the same as the parent function. Also, the funclet writes the value of the PSPSym to its own frame's PSPSym. This "copying" of the PSPSym happens for every funclet invocation, in particular, for every nested funclet invocation.
346
-
347
-
On ARM and ARM64, for all second pass funclets (finally, fault, catch, and filter-handler) the VM restores all non-volatile registers to their values within the parent frame. This includes the frame register (`R11`). Thus, the PSPSym is not used to recompute the frame pointer register in this case, though the PSPSym is copied to the funclet's frame, as for all funclets.
348
-
349
-
Catch, Filter, and Filter-handlers also get an Exception object (GC ref) as an argument (`REG_EXCEPTION_OBJECT`). On AMD64 it is the second argument and thus passed in RDX. On ARM and ARM64 this is the first argument and passed in R0.
350
-
351
-
(Note that the JIT64 source code contains a comment that says, "The current CLR doesn't always pass the correct establisher frame to the funclet. Funclet may receive establisher frame of funclet when expecting that of original routine." It indicates this is the reason that a PSPSym is required in all funclets as well as the main function, whereas if the establisher frame was correctly reported, the PSPSym could be omitted in some cases.)
327
+
Catch, Filter, and Filter-handlers get an Exception object (GC ref) as an argument (`REG_EXCEPTION_OBJECT`). On AMD64 it is passed in RCX (Windows ABI) or RSI (Unix ABI). On ARM and ARM64 this is the first argument and passed in R0.
352
328
353
329
## Funclet Return Values
354
330
@@ -374,11 +350,11 @@ Some definitions:
374
350
375
351
When an exception occurs, the VM is invoked to do some processing. If the exception is within a "try" region, it eventually calls a corresponding handler (which also includes calling filters). The exception location within a function might be where a "throw" instruction executes, the point of a processor exception like null pointer dereference or divide by zero, or the point of a call where the callee threw an exception but did not catch it.
376
352
377
-
On AMD64, all register values that existed at the exception point in the corresponding "try" region are trashed on entry to the funclet. That is, the only registers that have known values are those of the funclet parameters.
353
+
The VM sets the frame register to be the same as the parent function. This allows the funclets to access local variables using frame-relative addresses.
378
354
379
-
On ARM and ARM64, all registers are restored to their values at the exception point.
355
+
For filter funclets and on CoreCLR/AMD64 for all funclets, all other register values that existed at the exception point in the corresponding "try" region are trashed on entry to the funclet. That is, the only registers that have known values are those of the funclet parameters and the frame register.
380
356
381
-
On x86: TBD.
357
+
For other funclets on all platforms except CoreCLR/AMD64, all non-volatile registers are restored to their values at the exception point. The JIT codegen [does not take advantage of it currently](https://github.com/dotnet/runtime/pull/114630#issuecomment-2810210759).
382
358
383
359
### Registers on return from a funclet
384
360
@@ -696,12 +672,6 @@ x64 currently saves RBP, RSI and RDI while ARM64 saves just FP and LR.
696
672
697
673
However, EnC remap is not supported inside funclets. The stack layout of funclets does not matter for EnC.
698
674
699
-
## Considerations with regards to PSPSym
700
-
701
-
As explained previously in this document, on x64 we have Initial RSP == PSPSym. For EnC methods, as we disallow remappings after localloc (see below), we furthermore have RBP == PSPSym.
702
-
For ARM64 we have Caller SP == PSPSym and the FP points to the previously saved FP/LR pair. For EnC the JIT always sets up the stack frame so that the FP/LR pair is at Caller SP - 16 and does not save any additional callee saves.
703
-
These invariants allow the VM to compute new value of the frame pointer and PSPSym after the edit without any additional information. Note that the frame pointer and PSPSym do not change values or location on ARM64. However, EH may be added to a function in which case a new PSPSym needs to be materialized, even on ARM64. Location of PSPSym is found via GC info.
704
-
705
675
## Localloc
706
676
707
677
Localloc is allowed in EnC code, but remap is disallowed after the method has executed a localloc instruction. VM uses the invariants above (`RSP == RBP` on x64, `FP + 16 == SP + stack size` on ARM64) to detect whether localloc was executed by the method.
0 commit comments