diff options
4 files changed, 18 insertions, 18 deletions
diff --git a/Documentation/botr/ryujit-overview.md b/Documentation/botr/ryujit-overview.md index 95e8980424..afbd1a0bfd 100644 --- a/Documentation/botr/ryujit-overview.md +++ b/Documentation/botr/ryujit-overview.md @@ -490,22 +490,22 @@ Exception handling information is captured in an `EHblkDsc` for each exception h # Dumps and Other Tools -The behavior of the JIT can be controlled via a number of configuration variables. These are declared in [inc/clrconfigvalues.h](https://github.com/dotnet/coreclr/blob/master/src/inc/clrconfigvalues.h). When used as an environment variable, the string name generally has “COMPLUS_” prepended. When used as a registry value name, the configuration name is used directly. +The behavior of the JIT can be controlled via a number of configuration variables. These are declared in [inc/clrconfigvalues.h](https://github.com/dotnet/coreclr/blob/master/src/inc/clrconfigvalues.h). When used as an environment variable, the string name generally has “COMPlus_” prepended. When used as a registry value name, the configuration name is used directly. ## Setting configuration variables These can be set in one of three ways: -* Setting the environment variable `COMPLUS_<flagname>`. For example, the following will set the `JitDump` flag so that the compilation of all methods named ‘Main’ will be dumped: +* Setting the environment variable `COMPlus_<flagname>`. For example, the following will set the `JitDump` flag so that the compilation of all methods named ‘Main’ will be dumped: - set COMPLUS_JitDump=Main + set COMPlus_JitDump=Main * Setting the registry key `HKCU\Software\Microsoft\.NETFramework`, Value `<flagName>`, type `REG_SZ` or `REG_DWORD` (depending on the flag). * Setting the registry key `HKLM\Software\Microsoft\.NETFramework`, Value `<flagName>`, type `REG_SZ` or `REG_DWORD` (depending on the flag). ## Specifying method names -The complete syntax for specifying a single method name (for a flag that takes a method name, such as `COMPLUS_JitDump`) is: +The complete syntax for specifying a single method name (for a flag that takes a method name, such as `COMPlus_JitDump`) is: [[<Namespace>.]<ClassName>::]<MethodName>[([<types>)] @@ -527,14 +527,14 @@ The wildcard character ‘*’ can be used for <ClassName> and <MethodName>. In Below are some of the most useful `COMPLUS` variables. Where {method-list} is specified in the list below, you can supply a space-separated list of either fully-qualified or simple method names (the former is useful when running something that has many methods of the same name), or you can specific ‘*’ to mean all methods. -* `COMPLUS_JitDump`={method-list} – dump lots of useful information about what the JIT is doing (see below). -* `COMPLUS_JitDisasm`={method-list} – dump a disassembly listing of each method. -* `COMPLUS_JitDiffableDasm` – set to 1 to tell the JIT to avoid printing things like pointer values that can change from one invocation to the next, so that the disassembly can be more easily compared. -* `COMPLUS_JitGCDump`={method-list} – dump the GC information. -* `COMPLUS_JitUnwindDump`={method-list} – dump the unwind tables. -* `COMPLUS_JitEHDump`={method-list} – dump the exception handling tables. -* `COMPLUS_JitTimeLogFile`={file name} – this specifies a log file to which timing information is written. -* `COMPLUS_JitTimeLogCsv`={file name} – this specifies a log file to which summary timing information can be written, in CSV form. +* `COMPlus_JitDump`={method-list} – dump lots of useful information about what the JIT is doing (see below). +* `COMPlus_JitDisasm`={method-list} – dump a disassembly listing of each method. +* `COMPlus_JitDiffableDasm` – set to 1 to tell the JIT to avoid printing things like pointer values that can change from one invocation to the next, so that the disassembly can be more easily compared. +* `COMPlus_JitGCDump`={method-list} – dump the GC information. +* `COMPlus_JitUnwindDump`={method-list} – dump the unwind tables. +* `COMPlus_JitEHDump`={method-list} – dump the exception handling tables. +* `COMPlus_JitTimeLogFile`={file name} – this specifies a log file to which timing information is written. +* `COMPlus_JitTimeLogCsv`={file name} – this specifies a log file to which summary timing information can be written, in CSV form. See also: [CLR Configuration Knobs](../project-docs/clr-configuration-knobs.md) @@ -573,7 +573,7 @@ The tree nodes are indented to represent the parent-child relationship. Binary o Tree nodes are identified by their `gtTreeID`. This field only exists in DEBUG builds, but is quite useful for debugging, since all tree nodes are created from the routine `gtNewNode` (in [src/jit/gentree.cpp](https://github.com/dotnet/coreclr/blob/master/src/jit/gentree.cpp)). If you find a bad tree and wish to understand how it got corrupted, you can place a conditional breakpoint at the end of `gtNewNode` to see when it is created, and then a data breakpoint on the field that you believe is corrupted. -The trees are connected by line characters (either in ASCII, by default, or in slightly more readable Unicode when `COMPLUS_JitDumpAscii=0` is specified), to make it a bit easier to read. +The trees are connected by line characters (either in ASCII, by default, or in slightly more readable Unicode when `COMPlus_JitDumpAscii=0` is specified), to make it a bit easier to read. N037 ( 0, 0) [000391] ----------L- arg0 SETUP │ ┌──▌ argPlace ref REG NA $1c1 N041 ( 2, 8) [000389] ------------ │ │ ┌──▌ const(h) long 0xB410A098 REG rcx $240 diff --git a/Documentation/coding-guidelines/clr-code-guide.md b/Documentation/coding-guidelines/clr-code-guide.md index 42731d38b1..54e0f49794 100644 --- a/Documentation/coding-guidelines/clr-code-guide.md +++ b/Documentation/coding-guidelines/clr-code-guide.md @@ -1084,7 +1084,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 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). 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(): diff --git a/Documentation/coding-guidelines/clr-jit-coding-conventions.md b/Documentation/coding-guidelines/clr-jit-coding-conventions.md index ddd5cd4822..6b53b473b6 100644 --- a/Documentation/coding-guidelines/clr-jit-coding-conventions.md +++ b/Documentation/coding-guidelines/clr-jit-coding-conventions.md @@ -1454,7 +1454,7 @@ 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 COMPlus_* variable to enable the special debugging mode. ### <a name="14.1.3"/>14.1.3 Debug code @@ -1462,7 +1462,7 @@ Use `#ifdef DEBUG` for debug-only code. Do not use `#ifdef _DEBUG` (with a leadi 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; or when `COMPLUS_NgenDump=*` or `COMPLUS_NgenDump=XXX` and we are NGENing 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 `COMPlus_JitDump=*` or when `COMPlus_JitDump=XXX` and we are JITting function XXX; or when `COMPlus_NgenDump=*` or `COMPlus_NgenDump=XXX` and we are NGENing 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()); @@ -1483,7 +1483,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 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. If many back-to-back JITDUMP statements are going to be used it is preferred that they be written using printf(). diff --git a/Documentation/project-docs/clr-complus-conf-docgen.sh b/Documentation/project-docs/clr-complus-conf-docgen.sh index b686dca0ab..d50743f0c1 100644 --- a/Documentation/project-docs/clr-complus-conf-docgen.sh +++ b/Documentation/project-docs/clr-complus-conf-docgen.sh @@ -33,7 +33,7 @@ EOF INFO="This Document is machine-generated from commit $COMMIT on ${DATE}. It might be out of date." read -r -d '' HEADER << "EOF" -When using these configurations from environment variables, the variable need to have `ComPlus_` prefix in its name. e.g. To set DumpJittedMethods to 1, add `ComPlus_DumpJittedMethods=1` to envvars. +When using these configurations from environment variables, the variable need to have `COMPlus_` prefix in its name. e.g. To set DumpJittedMethods to 1, add `COMPlus_DumpJittedMethods=1` to envvars. See also [CLR Configurations](clr-configurations.md) for instructions. |