Skip to content

Commit

Permalink
Replace remaining instances of COMPlus with DOTNET (#82985)
Browse files Browse the repository at this point in the history
* Replace remaining instances of COMPlus with DOTNET

* Fix heading in RyuJIT tutorial
  • Loading branch information
am11 authored Mar 5, 2023
1 parent a64420c commit 3b63eb1
Show file tree
Hide file tree
Showing 82 changed files with 265 additions and 267 deletions.
2 changes: 1 addition & 1 deletion docs/coding-guidelines/clr-code-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -1162,7 +1162,7 @@ These declare whether a function or callee deals with the case "GetThread() == N

EE_THREAD_REQUIRED simply asserts that GetThread() != NULL.

EE_THREAD_NOT_REQUIRED is a noop by default. You must "set COMPlus_EnforceEEThreadNotRequiredContracts=1" for this to be enforced. Setting the envvar forces a C version of GetThread() to be used, instead of the optimized assembly versions. This C GetThread() always asserts in an EE_THREAD_NOT_REQUIRED scope regardless of whether there actually is an EE Thread available or not. The reason is that if you claim you don't require an EE Thread, then you have no business asking for it (even if you get lucky and there happens to be an EE Thread available).
EE_THREAD_NOT_REQUIRED is a noop by default. You must "set DOTNET_EnforceEEThreadNotRequiredContracts=1" for this to be enforced. Setting the envvar forces a C version of GetThread() to be used, instead of the optimized assembly versions. This C GetThread() always asserts in an EE_THREAD_NOT_REQUIRED scope regardless of whether there actually is an EE Thread available or not. The reason is that if you claim you don't require an EE Thread, then you have no business asking for it (even if you get lucky and there happens to be an EE Thread available).

Of course, there are exceptions to this. In particular, if there is a clear code path for GetThread() == NULL, then it's ok to call GetThread() in an EE_THREAD_NOT_REQUIRED scope. You declare your intention by using GetThreadNULLOk():

Expand Down
6 changes: 3 additions & 3 deletions docs/coding-guidelines/clr-jit-coding-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1457,15 +1457,15 @@ Note that periodically we do need to go through and remove FEATURE_* defines tha

It is generally discouraged to permanently disable code by commenting it out or by putting `#if 0` around it, in an attempt to keep it around for reference. This reduces the hygiene of the code base over time and such disabled code is rarely actually useful. Instead, such disabled code should be entirely deleted. If you do disable code without deleting it, then you must add a comment as to why the code is disabled, and why it is better to leave the code disabled than it is to delete it.

One exception is that it is often useful to `#if 0` code that is useful for debugging an area, but is not otherwise useful. Even in this case, however, it is probably better to introduce a COMPlus_* variable to enable the special debugging mode.
One exception is that it is often useful to `#if 0` code that is useful for debugging an area, but is not otherwise useful. Even in this case, however, it is probably better to introduce a DOTNET_* variable to enable the special debugging mode.

### <a name="14.1.3"></a>14.1.3 Debug code

Use `#ifdef DEBUG` for debug-only code. Do not use `#ifdef _DEBUG` (with a leading underscore).

Use the `INDEBUG(x)` macro (and related macros) judiciously, for code that only runs in DEBUG, to avoid `#ifdef`s.

Use the `JITDUMP(x)` macro for printing things to the JIT dump output. Note that these things will only get printed when the `verbose` variable is set, which is when `COMPlus_JitDump=*` or when `COMPlus_JitDump=XXX` and we are JITting function XXX. Do not use `JITDUMP` for all output in a debug-only function that might be useful to call from the debugger. In that case, define a function that uses `printf` (which is a JIT-specific implementation of this function), which can be called from the debugger, and invoke that function like this:
Use the `JITDUMP(x)` macro for printing things to the JIT dump output. Note that these things will only get printed when the `verbose` variable is set, which is when `DOTNET_JitDump=*` or when `DOTNET_JitDump=XXX` and we are JITting function XXX. Do not use `JITDUMP` for all output in a debug-only function that might be useful to call from the debugger. In that case, define a function that uses `printf` (which is a JIT-specific implementation of this function), which can be called from the debugger, and invoke that function like this:

```c++
DBEXEC(verbose, MyDumpFunction());
Expand All @@ -1486,7 +1486,7 @@ This could be written on fewer lines as:
JITDUMP("*************** In genGenerateCode()\n");
```
However, the former is preferred because it is trivial to set an unconditional breakpoint on the "printf" that triggers when we are compiling the function that matches what COMPlus_JitDump is set to – a very common debugging technique. Note that conditional breakpoints could be used, but they are more cumbersome, and are very difficult to get right in windbg.
However, the former is preferred because it is trivial to set an unconditional breakpoint on the "printf" that triggers when we are compiling the function that matches what DOTNET_JitDump is set to – a very common debugging technique. Note that conditional breakpoints could be used, but they are more cumbersome, and are very difficult to get right in windbg.
If many back-to-back JITDUMP statements are going to be used it is preferred that they be written using printf().
Expand Down
4 changes: 2 additions & 2 deletions docs/design/coreclr/botr/guide-for-porting.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ The process follows the following strategy
getting some code to work is a prerequisite for handling more complex
scenarios. When doing initial bringup, configuring the Gen0 budget of the GC
to be a large number so that the GC does not attempt to run during most
tests is very useful. (Set `COMPlus_GCgen0size=99999999`)
tests is very useful. (Set `DOTNET_GCgen0size=99999999`)

- Once basic code is executing, the focus shifts to enabling the GC to work.
In this initial phase, the correct choice is to enable conservative GC
Expand Down Expand Up @@ -137,7 +137,7 @@ Stage 4 Focus on stress
really works.

- See the various test passes done in CI, but most critically GCStress testing
is needed. See documentation around use of the ComPlus_GCStress environment
is needed. See documentation around use of the DOTNET_GCStress environment
variable.

Stage 5 productization
Expand Down
20 changes: 9 additions & 11 deletions docs/design/coreclr/botr/xplat-minidump-generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,20 +56,18 @@ NOTE: Core dump generation in docker containers require the ptrace capability (-

Any configuration or policy is set with environment variables which are passed as options to the _createdump_ utility.

Starting with .NET 7.0 or greater the below environment variables can be prefixed with DOTNET_ or COMPlus_.

Environment variables supported:

- `COMPlus_DbgEnableMiniDump`: if set to "1", enables this core dump generation. The default is NOT to generate a dump.
- `COMPlus_DbgMiniDumpType`: See below. Default is "2" MiniDumpWithPrivateReadWriteMemory.
- `COMPlus_DbgMiniDumpName`: if set, use as the template to create the dump path and file name. See "Dump name formatting" for how the dump name can be formatted. The default is _/tmp/coredump.%p_.
- `COMPlus_CreateDumpDiagnostics`: if set to "1", enables the _createdump_ utilities diagnostic messages (TRACE macro).
- `COMPlus_CreateDumpVerboseDiagnostics`: if set to "1", enables the _createdump_ utilities verbose diagnostic messages (TRACE_VERBOSE macro).
- `COMPlus_CreateDumpLogToFile`: if set, it is the path of the file to write the _createdump_ diagnostic messages.
- `COMPlus_EnableCrashReport`: In .NET 6.0 or greater, if set to "1", createdump also generates a json formatted crash report which includes information about the threads and stack frames of the crashing application. The crash report name is the dump path/name with _.crashreport.json_ appended.
- `COMPlus_EnableCrashReportOnly`: In .NET 7.0 or greater, same as COMPlus_EnableCrashReport except the core dump is not generated.
- `DOTNET_DbgEnableMiniDump`: if set to "1", enables this core dump generation. The default is NOT to generate a dump.
- `DOTNET_DbgMiniDumpType`: See below. Default is "2" MiniDumpWithPrivateReadWriteMemory.
- `DOTNET_DbgMiniDumpName`: if set, use as the template to create the dump path and file name. See "Dump name formatting" for how the dump name can be formatted. The default is _/tmp/coredump.%p_.
- `DOTNET_CreateDumpDiagnostics`: if set to "1", enables the _createdump_ utilities diagnostic messages (TRACE macro).
- `DOTNET_CreateDumpVerboseDiagnostics`: if set to "1", enables the _createdump_ utilities verbose diagnostic messages (TRACE_VERBOSE macro).
- `DOTNET_CreateDumpLogToFile`: if set, it is the path of the file to write the _createdump_ diagnostic messages.
- `DOTNET_EnableCrashReport`: In .NET 6.0 or greater, if set to "1", createdump also generates a json formatted crash report which includes information about the threads and stack frames of the crashing application. The crash report name is the dump path/name with _.crashreport.json_ appended.
- `DOTNET_EnableCrashReportOnly`: In .NET 7.0 or greater, same as DOTNET_EnableCrashReport except the core dump is not generated.

COMPlus_DbgMiniDumpType values:
DOTNET_DbgMiniDumpType values:


|Value|Minidump Enum|Description|
Expand Down
2 changes: 1 addition & 1 deletion docs/design/coreclr/jit/JitOptimizerPlanningGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ worth investing in.
collect profiles and correlate them with that machine code. This could
benefit any developers doing performance analysis of their own code.
The JIT team has discussed this, options include building something on top of
the profiler APIs, enabling COMPlus_JitDisasm in release builds, and shipping
the profiler APIs, enabling DOTNET_JitDisasm in release builds, and shipping
with or making easily available an alt jit that supports JitDisasm.
- Hardware companies maintain optimization/performance guides for their ISAs.
Should we maintain one for MSIL and/or C# (and/or F#)? If we hosted such a
Expand Down
4 changes: 2 additions & 2 deletions docs/design/coreclr/jit/hot-cold-splitting.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The below sections describe various improvements made to the JIT's hot/cold spli

Without runtime support for hot/cold splitting in .NET as of summer 2022, testing the JIT's existing hot/cold splitting
support is not as simple as turning the feature on. A new "fake" splitting mode, enabled by the
`COMPlus_JitFakeProcedureSplitting` environment variable, removes this dependency on runtime support. This mode allows
`DOTNET_JitFakeProcedureSplitting` environment variable, removes this dependency on runtime support. This mode allows
the JIT to execute its hot/cold splitting workflow without changing the runtime's behavior. This workflow proceeds as
follows:

Expand All @@ -41,7 +41,7 @@ are adjacent, the JIT generates unwind info once for the entire function.
While enabling fake-splitting also enables `opts.compProcedureSplitting`, there is no guarantee the JIT will fake-split
a function unless `Compiler::fgDetermineFirstColdBlock` finds a splitting point; without PGO data, the JIT's heuristics
may be too conservative for extensive testing. To aid regression testing, the JIT also has a stress-splitting mode now,
under `COMPlus_JitStressProcedureSplitting`. When `opts.compProcedureSplitting` and stress-splitting are both enabled,
under `DOTNET_JitStressProcedureSplitting`. When `opts.compProcedureSplitting` and stress-splitting are both enabled,
the JIT splits every function after its first basic block; in other words, `fgFirstColdBlock` is always
`fgFirstBB->bbNext`. The rest of the hot/cold splitting workflow is the same: The JIT emits instructions to handle the
split code sections and, if fake-splitting, utilizes only one memory buffer.
Expand Down
10 changes: 5 additions & 5 deletions docs/design/coreclr/jit/lsra-detail.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,7 +552,7 @@ Loc RP# Name Type Action Reg │rax │rcx │rdx │rbx │rbp │rsi │rdi
- This is generally not required, as the block will
normally have a predecessor block that has already
been allocated. This facility is exercised by the 0x100
(`LSRA_BLOCK_BOUNDARY_LAYOUT`) or 0x200 (`LSRA_BLOCK_BOUNDARY_ROTATE`) settings of `COMPlus_JitStressRegs`.
(`LSRA_BLOCK_BOUNDARY_LAYOUT`) or 0x200 (`LSRA_BLOCK_BOUNDARY_ROTATE`) settings of `DOTNET_JitStressRegs`.

- At the end of a block, for any exposed uses that do not have downstream
`RefPosition`s (e.g. variables that are live across the backedge, so there is no
Expand Down Expand Up @@ -733,7 +733,7 @@ LinearScanAllocation(List<RefPosition> refPositions)

- Resolution of exception edges

- When `COMPlus_EnableEHWriteThru == 0`, any variable that's
- When `DOTNET_EnableEHWriteThru == 0`, any variable that's
live in to an exception region is always referenced on the stack.

- See [Enable EHWriteThru by default](#enable-ehwritethru-by-default).
Expand Down Expand Up @@ -962,7 +962,7 @@ The following dumps and debugging modes are provided:
LSRA Stress Modes
-----------------

The implementation uses the `COMPlus_JitStressRegs` environment variable.
The implementation uses the `DOTNET_JitStressRegs` environment variable.
The following are the stress modes associated with this variable. For
the most part they can be combined, though in some cases the values are
exclusive:
Expand Down Expand Up @@ -1201,7 +1201,7 @@ Issues [\#8552](https://github.com/dotnet/runtime/issues/8552) and [\#40264](htt

### Enable EHWriteThru by default

When `COMPlus_EnableEHWriteThru` is set, some performance regressions are observed. When an EH write-thru variable (i.e. one that is live into an exception region) is defined, its value is
When `DOTNET_EnableEHWriteThru` is set, some performance regressions are observed. When an EH write-thru variable (i.e. one that is live into an exception region) is defined, its value is
always stored, in addition to potentially remaining live in a register. This increases register
pressure which may result in worse code.

Expand Down Expand Up @@ -1381,7 +1381,7 @@ kill site.
## Test and Cleanup Issues

Issue [\#9767](https://github.com/dotnet/runtime/issues/9767) captures the issue that the
"spill always" stress mode, `LSRA_SPILL_ALWAYS`, `COMPlus_JitStressRegs=0x800` doesn't work properly.
"spill always" stress mode, `LSRA_SPILL_ALWAYS`, `DOTNET_JitStressRegs=0x800` doesn't work properly.

Issue [\#6261](https://github.com/dotnet/runtime/issues/6261) has to do with `RegOptional`
`RefPositions` that are marked as `copyReg` or `moveReg`. See the notes on this issue;
Expand Down
Loading

0 comments on commit 3b63eb1

Please sign in to comment.