diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/botr/xplat-minidump-generation.md | 2 | ||||
| -rw-r--r-- | Documentation/building/debugging-instructions.md | 7 | ||||
| -rw-r--r-- | Documentation/building/linux-instructions.md | 5 | ||||
| -rw-r--r-- | Documentation/building/unix-test-instructions.md | 5 | ||||
| -rw-r--r-- | Documentation/design-docs/eh-writethru.md | 100 | ||||
| -rw-r--r-- | Documentation/design-docs/first-class-structs.md | 2 | ||||
| -rw-r--r-- | Documentation/dummy.txt | 1 | ||||
| -rw-r--r-- | Documentation/project-docs/ci-trigger-phrases.md | 17 | ||||
| -rw-r--r-- | Documentation/project-docs/clr-configuration-knobs.md | 3 | ||||
| -rw-r--r-- | Documentation/project-docs/contributing-workflow.md | 24 | ||||
| -rw-r--r-- | Documentation/project-docs/dotnet-standards.md | 2 | ||||
| -rw-r--r-- | Documentation/project-docs/garbage-collector-guidelines.md | 33 | ||||
| -rw-r--r-- | Documentation/project-docs/performance-guidelines.md | 9 |
13 files changed, 167 insertions, 43 deletions
diff --git a/Documentation/botr/xplat-minidump-generation.md b/Documentation/botr/xplat-minidump-generation.md index 78660b659c..03cd517a4a 100644 --- a/Documentation/botr/xplat-minidump-generation.md +++ b/Documentation/botr/xplat-minidump-generation.md @@ -62,6 +62,7 @@ Environment variables supported: -n, --normal - create minidump (default). -h, --withheap - create minidump with heap. -t, --triage - create triage minidump. + -u, --full - create full core dump. -d, --diag - enable diagnostic messages. # Testing # @@ -73,7 +74,6 @@ The test plan is to modify the SOS tests in the (still) private debuggertests re - Do we need a full memory dump option? It would not use the _DAC_ to get the memory regions but all the readable memory from the shared module list. Do we include the shared modules' code? - May need more than just the pid for decorating dump names for docker containers because I think the _pid_ is always 1. - Do we need all the memory mappings from `/proc/$pid/maps` in the PT\_LOAD sections even though the memory is not actually in the dump? They have a file offset/size of 0. Full dumps generated by the system or _gdb_ do have these un-backed regions. -- Don't know how to get the proper size/range of the non-main thread stacks. Currently uses 4 pages around the stack pointer. The main thread has a memory region in `/proc/$pid/maps`. - There is no way to get the signal number, etc. that causes the abort from the _createdump_ utility using _ptrace_ or a /proc file. It would have to be passed from CoreCLR on the command line. - Do we need the "dynamic" sections of each shared module in the core dump? It is part of the "link_map" entry enumerated when gathering the _DSO_ information. - There may be more versioning and/or build id information needed to be added to the dump. diff --git a/Documentation/building/debugging-instructions.md b/Documentation/building/debugging-instructions.md index 72f198bde9..1a3b0234c9 100644 --- a/Documentation/building/debugging-instructions.md +++ b/Documentation/building/debugging-instructions.md @@ -136,10 +136,3 @@ Loading Linux core dumps with lldb 3.7 doesn't work. lldb 3.7 loads OS X and Fre just fine. lldb 3.8 loads all the platform's core dumps without problem. For more information on SOS commands see: https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx - -Debugging Mscorlib and/or managed application -============================================= - -To step into and debug managed code of Mscorlib.dll (or the managed application being executed by the runtime you built), using Visual Studio, is something that will be supported with Visual Studio 2015. We are actively working to enable this support. - -Until then, you can use [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) (an extension to WinDbg to support managed debugging) to step in and debug the generated managed code. This is what we do on the .NET Runtime team as well :) diff --git a/Documentation/building/linux-instructions.md b/Documentation/building/linux-instructions.md index bacbe6d2f0..fecf2c9b60 100644 --- a/Documentation/building/linux-instructions.md +++ b/Documentation/building/linux-instructions.md @@ -30,6 +30,7 @@ Install the following packages for the toolchain: - libcurl4-openssl-dev - libssl-dev - uuid-dev +- libnuma-dev (optional, enables numa support) In order to get lldb-3.6 on Ubuntu 14.04, we need to add an additional package source: @@ -50,14 +51,14 @@ For other version of Debian/Ubuntu, please visit http://apt.llvm.org/. Then install the packages you need: ``` -ellismg@linux:~$ sudo apt-get install cmake llvm-3.5 clang-3.5 lldb-3.6 lldb-3.6-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev uuid-dev +ellismg@linux:~$ sudo apt-get install cmake llvm-3.5 clang-3.5 lldb-3.6 lldb-3.6-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev uuid-dev libnuma-dev ``` You now have all the required components. If you are using Fedora, then you will need to install the following packages: -`$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libuuid-devel libicu-devel` +`$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libuuid-devel libicu-devel numactl-devel` Git Setup --------- diff --git a/Documentation/building/unix-test-instructions.md b/Documentation/building/unix-test-instructions.md index 563c3e8c68..96546a0249 100644 --- a/Documentation/building/unix-test-instructions.md +++ b/Documentation/building/unix-test-instructions.md @@ -6,7 +6,7 @@ CoreCLR tests **Building** -Build CoreCLR and CoreFX. Refer to building instructions in the respective repository. +Build CoreCLR on [Windows](https://github.com/dotnet/coreclr/blob/master/Documentation/building/windows-instructions.md) & [Unix](https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md), and CoreFX on [Unix](https://github.com/dotnet/corefx/blob/master/Documentation/building/unix-instructions.md). To build only the tests, on the Windows machine: @@ -18,7 +18,6 @@ The following instructions assume that on the Unix machine: - The CoreCLR repo is cloned at `~/coreclr` - The CoreFX repo is cloned at `~/corefx` - The Windows clone of the CoreCLR repo is mounted at `/media/coreclr` -- The Windows clone of the CoreFX repo is mounted at `/media/corefx` Tests currently need to be built on Windows and copied over to the Unix machine for testing. Copy the test build over to the Unix machine: @@ -35,7 +34,7 @@ Run tests (`Debug` may be replaced with `Release` or `Checked`, depending on whi > --testRootDir=~/test/Windows_NT.x64.Debug > --testNativeBinDir=~/coreclr/bin/obj/Linux.x64.Debug/tests > --coreClrBinDir=~/coreclr/bin/Product/Linux.x64.Debug -> --mscorlibDir=/media/coreclr/bin/Product/Linux.x64.Debug +> --mscorlibDir=~/coreclr/bin/Product/Linux.x64.Debug > --coreFxBinDir=~/corefx/bin/runtime/netcoreapp-Linux-Debug-x64 > ``` diff --git a/Documentation/design-docs/eh-writethru.md b/Documentation/design-docs/eh-writethru.md index 0afa5a7688..311ca2cd91 100644 --- a/Documentation/design-docs/eh-writethru.md +++ b/Documentation/design-docs/eh-writethru.md @@ -1,36 +1,113 @@ # 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. +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 an enregisterable compiler temporary backed by +the local variable on the stack. For local vars that additionally have +appearances within an 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. +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). It's also good to consider +that in MSIL, basic operations can raise semantically meaningful exceptions +(unlike say C++, where an explicit throw is required to raise an exception) so +injected handlers can end up pessimizing a number of local variables in the +method. Given this combination of issues in cloud workloads doing the +transformation should 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. +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. + +There are a number of wrinkles informing this design based on how the JIT models EH: +- The jit does not explicitly model the exception flow, so a given block and + even a given statement within a block may have multiple exception-raising sites. +- For statements within protected regions, and for all variables live into any + reachable handler, the jit assumes all definitions within the region can + potentially reach uses in the handlers, since the exact interleaving of + definition points and exception points is not known. Hence every definition + is a reaching definition, even both values back from to back stores with no + read of the variable in between. +- The jit does not model which handlers are reachable from a given protected region, + so considers a variable live into a handler if it is live into any handler in the method. + +It is posible to do better than the "store every definition" approch outlined +in the design, but the expectation is that this would require posibly +modifying the model in the JIT and staging more throughput intensive analyses. +With these considerations this design was selected and further improvements +left to future optimization. ### 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. +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") +- 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 + * 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. +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. +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. @@ -42,7 +119,8 @@ The initial prototype that produced the example bellow is currently being improv ## Example -The following is a simple example that shows enregistration for a local var live, and modified, through a catch. +The following is a simple example that shows enregistration for a local var +live, and modified, through a catch. #### Source code snippet diff --git a/Documentation/design-docs/first-class-structs.md b/Documentation/design-docs/first-class-structs.md index fd6a3762c4..f7bd9b6fb4 100644 --- a/Documentation/design-docs/first-class-structs.md +++ b/Documentation/design-docs/first-class-structs.md @@ -21,7 +21,7 @@ Struct-Related Issues in RyuJIT The following issues illustrate some of the motivation for improving the handling of value types (structs) in RyuJIT: -* VSO Bug 98404: .NET JIT x86 - poor code generated for value type initialization +* [\#11407 [RyuJIT] Fully enregister structs that fit into a single register when profitable](https://github.com/dotnet/coreclr/issues/11407), also VSO Bug 98404: .NET JIT x86 - poor code generated for value type initialization * This is a simple test case that should generate simply `xor eax; ret` on x86 and x64, but instead generates many unnecessary copies. It is addressed by full enregistration of structs that fit into a register: diff --git a/Documentation/dummy.txt b/Documentation/dummy.txt new file mode 100644 index 0000000000..ec583fd0ac --- /dev/null +++ b/Documentation/dummy.txt @@ -0,0 +1 @@ +Thursday, April 20, 2017 10:00:00 AM
\ No newline at end of file diff --git a/Documentation/project-docs/ci-trigger-phrases.md b/Documentation/project-docs/ci-trigger-phrases.md index dd0e981ead..f57be03262 100644 --- a/Documentation/project-docs/ci-trigger-phrases.md +++ b/Documentation/project-docs/ci-trigger-phrases.md @@ -11,7 +11,10 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Windows_NT x64 Release Priority 1 Build & Test:** "test Windows_NT pri1" - **Windows_NT x64 Release IL RoundTrip Build & Test:** "test Windows_NT ilrt" -- **Windows_NT x64 Release Long-Running GC Build & Test:**: "test Windows_NT x64 Release longgc" +- **Windows_NT x64 Release Long-Running GC Build & Test:**: "test Windows_NT Release longgc" +- **Windows_NT x64 Release GC Simulator:**: "test Windows_NT Release gcsimulator" +- **Windows_NT x64 Release Standalone GC:**: "test Windows_NT Release standalone_gc" +- **Windows_NT x64 Release GC Reliability Framework:**: "test Windows_NT Release gc_reliability_framework" - **Windows_NT x64 Release Ready-To-Run Priority 0 Build & Test:** "test Windows_NT Release r2r" - **Windows_NT x64 Checked Ready-To-Run Priority 0 Build & Test:** "test Windows_NT Checked r2r" - **Windows_NT x64 Release Ready-To-Run Priority 1 Build & Test:** "test Windows_NT Release pri1r2r" @@ -69,6 +72,8 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Windows_NT x64 Checked GCStress=0xc JitStress=2 Build & Test:** "test Windows_NT gcstress0xc_jitstress2" - **Windows_NT x64 Checked GCStress=0xc MinOpts Heap Verify 1 Build & Test:** "test Windows_NT gcstress0xc_minopts_heapverify1" - **Windows_NT x64 Checked Long-Running GC Build & Test:**: "test Windows_NT x64 Checked longgc" +- **Windows_NT x64 Checked Standalone GC:**: "test Windows_NT Checked standalone_gc" +- **Windows_NT x64 Checked GC Reliability Framework:**: "test Windows_NT Checked gc_reliability_framework" - **Windows_NT x64 Formatting:**: "test Windows_NT formatting" - **Windows_NT x64 Checked CoreFX Baseline Build & Test:** "test Windows_NT corefx_baseline" - **Windows_NT x64 Checked CoreFX MinOpts Build & Test:** "test Windows_NT corefx_minopts" @@ -166,6 +171,11 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Ubuntu x64 Release Priority 1 Build & Test:** "test Ubuntu pri1" - **Ubuntu x64 Release IL RoundTrip Build & Test:** "test Ubuntu ilrt" - **Ubuntu x64 Release Long-Running GC Build & Test:**: "test Ubuntu Release longgc" +- **Ubuntu x64 Release GC Simulator:**: "test Ubuntu Release gcsimulator" +- **Ubuntu x64 Release Standalone GC:**: "test Ubuntu Release standalone_gc" +- **Ubuntu x64 Checked Standalone GC:**: "test Ubuntu Checked standalone_gc" +- **Ubuntu x64 Release GC Reliability Framework:**: "test Ubuntu Release gc_reliability_framework" +- **Ubuntu x64 Checked GC Reliability Framework:**: "test Ubuntu Checked gc_reliability_framework" - **Ubuntu x64 Release Ready-To-Run Priority 0 Build & Test:** "test Ubuntu Release r2r" - **Ubuntu x64 Checked Ready-To-Run Priority 0 Build & Test:** "test Ubuntu Checked r2r" - **Ubuntu x64 Release Ready-To-Run Priority 1 Build & Test:** "test Ubuntu Release pri1r2r" @@ -248,6 +258,11 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **OSX x64 Release Priority 1 Build & Test:** "test OSX pri1" - **OSX x64 Release IL RoundTrip Build & Test:** "test OSX ilrt" - **OSX x64 Release Long-Running GC Build & Test:**: "test OSX Release longgc" +- **OSX x64 Release GC Simulator:**: "test OSX10.12 Release gcsimulator" +- **OSX x64 Release Standalone GC:**: "test OSX10.12 Release standalone_gc" +- **OSX x64 Checked Standalone GC:**: "test OSX10.12 Checked standalone_gc" +- **OSX x64 Release GC Reliability Framework:**: "test OSX10.12 Release gc_reliability_framework" +- **OSX x64 Checked GC Reliability Framework:**: "test OSX10.12 Checked gc_reliability_framework" - **OSX x64 Release Ready-To-Run Priority 0 Build & Test:** "test OSX Release r2r" - **OSX x64 Checked Ready-To-Run Priority 0 Build & Test:** "test OSX Checked r2r" - **OSX x64 Release Ready-To-Run Priority 1 Build & Test:** "test OSX Release pri1r2r" diff --git a/Documentation/project-docs/clr-configuration-knobs.md b/Documentation/project-docs/clr-configuration-knobs.md index 63f094b8ee..3787666174 100644 --- a/Documentation/project-docs/clr-configuration-knobs.md +++ b/Documentation/project-docs/clr-configuration-knobs.md @@ -303,9 +303,6 @@ Name | Description | Type | Class | Default Value | Flags `StackSamplingNumMethods` | Number of evolving methods to track as hot and JIT them in the background at a given point of execution. | DWORD | UNSUPPORTED | 32 | `AltJitNgen` | Enables AltJit for NGEN and selectively limits it to the specified methods. | STRING | INTERNAL | | REGUTIL_default `JitNoCMOV` | | DWORD | INTERNAL | 0 | REGUTIL_default -`UseRyuJIT` | Set to 1 by .NET 4.6 installer to indicate RyuJIT should be used, not JIT64. | DWORD | INTERNAL | 0 | IgnoreEnv / IgnoreHKCU / IgnoreConfigFiles -`useLegacyJit` | Set to 1 to do all JITing with compatjit.dll. Only applicable to x64. | DWORD | EXTERNAL | 0 | -`DisableNativeImageLoadList` | Refuse to load native images corresponding to one of the assemblies on this semicolon-delimited list of assembly names. | STRING | EXTERNAL | | REGUTIL_default `JitValNumCSE` | Enables ValNum CSE for the specified methods | STRING | INTERNAL | | REGUTIL_default `JitLexicalCSE` | Enables Lexical CSE for the specified methods | STRING | INTERNAL | | REGUTIL_default `JitNoCSE` | | DWORD | INTERNAL | 0 | REGUTIL_default diff --git a/Documentation/project-docs/contributing-workflow.md b/Documentation/project-docs/contributing-workflow.md index ff21143d7a..3634802a10 100644 --- a/Documentation/project-docs/contributing-workflow.md +++ b/Documentation/project-docs/contributing-workflow.md @@ -83,24 +83,24 @@ Suggested Workflow We use and recommend the following workflow: 1. Create an issue for your work. - - You can skip this step for trivial changes. - - Reuse an existing issue on the topic, if there is one. - - Use [CODE_OWNERS.TXT](https://github.com/dotnet/coreclr/blob/master/CODE_OWNERS.TXT) to find relevant maintainers and @ mention them to ask for feedback on your issue. - - Get agreement from the team and the community that your proposed change is a good one. - - If your change adds a new API, follow the [API Review Process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md). - - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person. + - You can skip this step for trivial changes. + - Reuse an existing issue on the topic, if there is one. + - Use [CODE_OWNERS.TXT](https://github.com/dotnet/coreclr/blob/master/CODE_OWNERS.TXT) to find relevant maintainers and @ mention them to ask for feedback on your issue. + - Get agreement from the team and the community that your proposed change is a good one. + - If your change adds a new API, follow the [API Review Process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md). + - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person. 2. Create a personal fork of the repository on GitHub (if you don't already have one). 3. Create a branch off of master (`git checkout -b mybranch`). - - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue. - - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork. + - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue. + - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork. 4. Make and commit your changes. - - Please follow our [Commit Messages](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing-workflow.md#commit-messages) guidance. + - Please follow our [Commit Messages](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing-workflow.md#commit-messages) guidance. 5. Add new tests corresponding to your change, if applicable. 6. Build the repository with your changes. - - Make sure that the builds are clean. - - Make sure that the tests are all passing, including your new tests. + - Make sure that the builds are clean. + - Make sure that the tests are all passing, including your new tests. 7. Create a pull request (PR) against the upstream repository's **master** branch. - - Push your changes to your fork on GitHub (if you haven't already). + - Push your changes to your fork on GitHub (if you haven't already). Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged. diff --git a/Documentation/project-docs/dotnet-standards.md b/Documentation/project-docs/dotnet-standards.md index 452c703f0a..d7268369d7 100644 --- a/Documentation/project-docs/dotnet-standards.md +++ b/Documentation/project-docs/dotnet-standards.md @@ -49,7 +49,7 @@ ECMA 372 - C++/CLI The C++/CLI language was standardized as [ECMA 372](http://www.ecma-international.org/publications/standards/Ecma-372.htm) in 2005. -EMCA 372 is supported by the .NET Framework, but not .NET Core. +ECMA 372 is supported by the .NET Framework, but not .NET Core. **ECMA 372 Resources** diff --git a/Documentation/project-docs/garbage-collector-guidelines.md b/Documentation/project-docs/garbage-collector-guidelines.md index 66d4c69b9f..1981c8ab6f 100644 --- a/Documentation/project-docs/garbage-collector-guidelines.md +++ b/Documentation/project-docs/garbage-collector-guidelines.md @@ -26,12 +26,43 @@ Required Testing: Validation of the behavior of the affected APIs. ## Stress Testing ## Stress testing must run for at least **48 hours** against a debug build. -Instructions for running stress are located in the repo at tests\src\GC\Stress\stress_run_readme.txt. +Stress testing for checked and release builds can be done on pull requests with The .NET CI infrastructure. +A stress run can be requested using the trigger phrase: + +``` +@dotnet_bot test <platform> <flavor> gc_reliability_framework +``` + +This will run the stress framework for the default amount of time (15 hours) on the given platform and build flavor. ## Functional Testing ## A functional test run executes the same code as a stress run, but only runs for 30 minutes. Instructions for running stress are located in the repo at tests\src\GC\Stress\stress_run_readme.txt. +It is recommended that you run at least some of the below PR-triggered CI jobs: + +``` +@dotnet_bot test Windows_NT Checked longgc +@dotnet_bot test OSX10.12 Checked longgc +@dotnet_bot test Ubuntu Checked longgc +@dotnet_bot test Windows_NT Checked standalone_gc +@dotnet_bot test OSX10.12 Checked standalone_gc +@dotnet_bot test Ubuntu Checked standalone_gc +``` + +The "Long GC" tests are a series of GC tests whose running time is too long or memory usage is too high to run with +the rest of the Priority 0 unit tests. The "Standalone GC" build mode builds and runs the GC in a semi-standalone manner +(see https://github.com/dotnet/coreclr/projects/3). + +You may also wish to run the GC Simulator tests. They may take up to 24 hours to complete and are known to sometimes fail on Ubuntu +due to poor interactions with the Linux OOM killer. However, they have proven to be quite useful in finding bugs in the past: + +``` +@dotnet_bot test Windows_NT Release gcsimulator +@dotnet_bot test Ubuntu Release gcsimulator +@dotnet_bot test OSX10.12 Release gcsimulator +``` + ## Performance Testing ## Coming soon. diff --git a/Documentation/project-docs/performance-guidelines.md b/Documentation/project-docs/performance-guidelines.md index f9c5e17c91..a2e15d5e01 100644 --- a/Documentation/project-docs/performance-guidelines.md +++ b/Documentation/project-docs/performance-guidelines.md @@ -50,5 +50,14 @@ Capturing a trace using PerfView will allow you to: PerfView is available at the [Microsoft Download Center](http://www.microsoft.com/en-us/download/details.aspx?id=28567 "Microsoft Download Center"). The help documentation is quite substantial and can help you get started. Clicking the blue links throughout PerfView's UI will also take you to the appropriate help topic. It is also recommended that you watch the [PerfView Tutorial Videos](http://channel9.msdn.com/Series/PerfView-Tutorial). +# Running the CoreCLR Performance Tests on Windows # +1. The first step to running the performance tests locally is to do a release build of CoreCLR and all of the performance tests. You can do this with the command `build.cmd x64 Release`, this will of course build the x64 runtime, and you should use x86 if you want to test x86. + +2. After building the runtime you will need to generate a core root that contains all of the binaries we just built along with the required dependencies. This can be done with the command `tests\runtest.cmd Release x64 GenerateLayoutOnly`, with the same caveat that x86 should be used if that is the platform that you are testing. + +3. Now we need to actually run the performance tests. You can do that with the following command that should be run from the root of your repo `tests\scripts\run-xunit-perf.cmd -arch x64 -configuration Release -testBinLoc bin\tests\Windows_NT.x64.Release\Jit\Performance\CodeQuality`. This will run all of the tests in the JIT CodeQuality directory as the script will walk all sub-directories and look for tests to run. If you want to just run a single test, pass the path of the single test that you want to run. + +4. Navigate to the `sandbox` directory in the root of your repo. Inside that directory you will find a bunch of files that follow the name Perf-*.md. These will contain the results, formatted as Markdown files, for each test that was run. + # Additional Help # If you have questions, run into any issues, or would like help with any performance related topics, please feel free to post a question. Someone from the .NET performance team will be happy to help. |