diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/users_guide/8.8.1-notes.rst | 4 | ||||
| -rw-r--r-- | docs/users_guide/debugging.rst | 6 | ||||
| -rw-r--r-- | docs/users_guide/using-optimisation.rst | 54 |
3 files changed, 63 insertions, 1 deletions
diff --git a/docs/users_guide/8.8.1-notes.rst b/docs/users_guide/8.8.1-notes.rst index 252db777bc..66ecdf0015 100644 --- a/docs/users_guide/8.8.1-notes.rst +++ b/docs/users_guide/8.8.1-notes.rst @@ -14,6 +14,7 @@ Highlights The highlights, since the 8.6.1 release, are: - Many, many bug fixes. +- A new code layout algorithm for x86. Full details @@ -73,6 +74,9 @@ Compiler - The :ghc-flag:`-fllvm-pass-vectors-in-regs` flag is now deprecated as vector arguments are now passed in registers by default. +- The :ghc-flag:`-fblock-layout-cfg` flag enables a new code layout algorithm on x86. + This is enabled by default at :ghc-flag:`-O` and :ghc-flag:`-O2`. + Runtime system ~~~~~~~~~~~~~~ diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst index 6a4c7fe1a7..1ffdf21eba 100644 --- a/docs/users_guide/debugging.rst +++ b/docs/users_guide/debugging.rst @@ -475,7 +475,13 @@ These flags dump various phases of GHC's C-\\- pipeline. Dump the result of the C-\\- pipeline processing +.. ghc-flag:: -ddump-cfg-weights + :shortdesc: Dump the assumed weights of the CFG. + :type: dynamic + Dumps the CFG with weights used by the new block layout code. + Each CFG is dumped in dot format graph making it easy + to visualize them. LLVM code generator ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index da066e158c..0048478683 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -45,7 +45,7 @@ optimisation to be performed, which can have an impact on how much of your program needs to be recompiled when you change something. This is one reason to stick to no-optimisation when developing code. -**No ``-O*``-type option specified:** This is taken to mean “Please +**No ``-O*``-type option specified:** This is taken to mean “Please compile quickly; I'm not over-bothered about compiled-code quality.” So, for example, ``ghc -c Foo.hs`` @@ -219,6 +219,58 @@ by saying ``-fno-wombat``. This is mostly done during Cmm passes. However this can miss corner cases. So at -O2 we run the pass again at the asm stage to catch these. +.. ghc-flag:: -fblock-layout-cfg + :shortdesc: Use the new cfg based block layout algorithm. + :type: dynamic + :reverse: -fno-block-layout-cfg + :category: + + :default: off but enabled with :ghc-flag:`-O`. + + The new algorithm considers all outgoing edges of a basic blocks for + code layout instead of only the last jump instruction. + It also builds a control flow graph for functions, tries to find + hot code paths and place them sequentially leading to better cache utilization + and performance. + + This is expected to improve performance on average, but actual performance + difference can vary. + + If you find cases of significant performance regressions, which can + be traced back to obviously bad code layout please open a ticket. + +.. ghc-flag:: -fblock-layout-weights + :shortdesc: Sets edge weights used by the new code layout algorithm. + :type: dynamic + :category: + + This flag is hacker territory. The main purpose of this flag is to make + it easy to debug and tune the new code layout algorithm. There is no + guarantee that values giving better results now won't be worse with + the next release. + + If you feel your code warrants modifying these settings please consult + the source code for default values and documentation. But I strongly + advise against this. + +.. ghc-flag:: -fblock-layout-weightless + :shortdesc: Ignore cfg weights for code layout. + :type: dynamic + :reverse: -fno-block-layout-weightless + :category: + + :default: off + + When not using the cfg based blocklayout layout is determined either + by the last jump in a basic block or the heaviest outgoing edge of the + block in the cfg. + + With this flag enabled we use the last jump instruction in blocks. + Without this flags the old algorithm also uses the heaviest outgoing + edge. + + When this flag is enabled and :ghc-flag:`-fblock-layout-cfg` is disabled + block layout behaves the same as in 8.6 and earlier. .. ghc-flag:: -fcpr-anal :shortdesc: Turn on CPR analysis in the demand analyser. Implied by :ghc-flag:`-O`. |