Update Trac ticket URLs to point to GitLab
[ghc.git] / docs / users_guide / using-optimisation.rst
index fc958e0..9571c7e 100644 (file)
@@ -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``
 
@@ -88,20 +88,6 @@ So, for example, ``ghc -c Foo.hs``
     runtime or space *worse* if you're unlucky. They are normally turned
     on or off individually.
 
-.. ghc-flag:: -Odph
-    :shortdesc: Enable level 2 optimisations, set
-        ``-fmax-simplifier-iterations=20``
-        and ``-fsimplifier-phases=3``.
-    :type: dynamic
-    :category: optimization-levels
-
-    .. index::
-       single: optimise; DPH
-
-    Enables all ``-O2`` optimisation, sets
-    ``-fmax-simplifier-iterations=20`` and ``-fsimplifier-phases=3``.
-    Designed for use with :ref:`Data Parallel Haskell (DPH) <dph>`.
-
 We don't use a ``-O*`` flag for day-to-day work. We use ``-O`` to get
 respectable speed; e.g., when we want to measure something. When we want
 to go for broke, we tend to use ``-O2`` (and we go for lots of coffee
@@ -217,6 +203,75 @@ by saying ``-fno-wombat``.
     to their usage sites. It also inlines simple expressions like
     literals or registers.
 
+.. ghc-flag:: -fasm-shortcutting
+    :shortdesc: Enable shortcutting on assembly. Implied by :ghc-flag:`-O2`.
+    :type: dynamic
+    :reverse: -fno-asm-shortcutting
+    :category:
+
+    :default: off
+
+    This enables shortcutting at the assembly stage of the code generator.
+    In simpler terms shortcutting means if a block of instructions A only consists
+    of a unconditionally jump, we replace all jumps to A by jumps to the successor
+    of A.
+
+    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`.
     :type: dynamic
@@ -454,7 +509,7 @@ by saying ``-fno-wombat``.
     that were not visible earlier; and optimisations like
     :ghc-flag:`-fspec-constr` can create functions with unused arguments which
     are eliminated by late demand analysis. Improvements are modest, but
-    so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`.
+    so is the cost. See notes on the :ghc-wiki:`wiki page <LateDmd>`.
 
 .. ghc-flag:: -fliberate-case
     :shortdesc: Turn on the liberate-case transformation. Implied by :ghc-flag:`-O2`.
@@ -544,7 +599,7 @@ by saying ``-fno-wombat``.
         type error messages.
     :type: dynamic
     :reverse: -fno-max-relevant-bindings
-    :category:
+    :category: verbosity
 
     :default: 6
 
@@ -556,20 +611,6 @@ by saying ``-fno-wombat``.
     they may be numerous), but ``-fno-max-relevant-bindings`` includes
     them too.
 
-.. ghc-flag:: -fmax-valid-substitutions=⟨n⟩
-    :shortdesc: *default: 6.* Set the maximum number of valid substitutions for
-        typed holes to display in type error messages.
-    :type: dynamic
-    :reverse: -fno-max-valid-substitutions
-    :category:
-
-    :default: 6
-
-    The type checker sometimes displays a list of valid substitutions
-    for typed holes in error messages, but only up to some maximum number,
-    set by this flag. Turning it off with
-    ``-fno-max-valid-substitutions`` gives an unlimited number.
-
 .. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩
     :shortdesc: *default: 4.* Set the maximum number of patterns to display in
         warnings about non-exhaustive ones.
@@ -898,6 +939,22 @@ by saying ``-fno-wombat``.
     which they are called in this module. Note that specialisation must be
     enabled (by ``-fspecialise``) for this to have any effect.
 
+.. ghc-flag:: -flate-specialise
+    :shortdesc: Run a late specialisation pass
+    :type: dynamic
+    :reverse: -fno-late-specialise
+    :category:
+
+    :default: off
+
+    Runs another specialisation pass towards the end of the optimisation
+    pipeline. This can catch specialisation opportunities which arose from
+    the previous specialisation pass or other inlining.
+
+    You might want to use this if you are you have a type class method
+    which returns a constrained type. For example, a type class where one
+    of the methods implements a traversal.
+
 .. ghc-flag:: -fsolve-constant-dicts
     :shortdesc: When solving constraints, try to eagerly solve
         super classes using available dictionaries.
@@ -942,10 +999,62 @@ by saying ``-fno-wombat``.
 
     :default: off
 
-    Turn on the static argument transformation, which turns a recursive
-    function into a non-recursive one with a local recursive loop. See
-    Chapter 7 of `Andre Santos's PhD
-    thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__
+    Turn on the static argument transformation, which turns a recursive function
+    into a non-recursive one with a local recursive loop. See Chapter 7 of
+    `Andre Santos's PhD thesis
+    <https://www.microsoft.com/en-us/research/publication/compilation-transformation-non-strict-functional-languages/>`__.
+
+.. ghc-flag:: -fstg-lift-lams
+    :shortdesc: Enable late lambda lifting on the STG intermediate
+        language. Implied by :ghc-flag:`-O2`.
+    :type: dynamic
+    :reverse: -fno-stg-lift-lams
+    :category:
+
+    :default: on
+
+    Enables the late lambda lifting optimisation on the STG
+    intermediate language. This selectively lifts local functions to
+    top-level by converting free variables into function parameters.
+
+.. ghc-flag:: -fstg-lift-lams-known
+    :shortdesc: Allow turning known into unknown calls while performing
+        late lambda lifting.
+    :type: dynamic
+    :reverse: -fno-stg-lift-lams-known
+    :category:
+
+    :default: off
+
+    Allow turning known into unknown calls while performing
+    late lambda lifting. This is deemed non-beneficial, so it's
+    off by default.
+
+.. ghc-flag:: -fstg-lift-lams-non-rec-args
+    :shortdesc: Create top-level non-recursive functions with at most <n>
+        parameters while performing late lambda lifting.
+    :type: dynamic
+    :reverse: -fno-stg-lift-lams-non-rec-args-any
+    :category:
+
+    :default: 5
+
+    Create top-level non-recursive functions with at most <n> parameters
+    while performing late lambda lifting. The default is 5, the number of
+    available parameter registers on x86_64.
+
+.. ghc-flag:: -fstg-lift-lams-rec-args
+    :shortdesc: Create top-level recursive functions with at most <n>
+        parameters while performing late lambda lifting.
+    :type: dynamic
+    :reverse: -fno-stg-lift-lams-rec-args-any
+    :category:
+
+    :default: 5
+
+    Create top-level recursive functions with at most <n> parameters
+    while performing late lambda lifting. The default is 5, the number of
+    available parameter registers on x86_64.
 
 .. ghc-flag:: -fstrictness
     :shortdesc: Turn on strictness analysis.
@@ -956,8 +1065,9 @@ by saying ``-fno-wombat``.
 
     :default: on
 
-    Switch on the strictness analyser. The
-    implementation is described in the paper `Theory and Practice of Demand Analysis in Haskell`<https://www.microsoft.com/en-us/research/wp-content/uploads/2017/03/demand-jfp-draft.pdf>`__.
+    Switch on the strictness analyser. The implementation is described in the
+    paper `Theory and Practice of Demand Analysis in Haskell
+    <https://www.microsoft.com/en-us/research/wp-content/uploads/2017/03/demand-jfp-draft.pdf>`__.
 
     The strictness analyser figures out when arguments and variables in
     a function can be treated 'strictly' (that is they are always
@@ -1129,40 +1239,18 @@ by saying ``-fno-wombat``.
     determines if a function definition will be kept around at all for
     potential inlining.
 
-.. ghc-flag:: -fvectorisation-avoidance
-    :shortdesc: Enable vectorisation avoidance. Always enabled by default.
-    :type: dynamic
-    :reverse: -fno-vectorisation-avoidance
-    :category:
-
-    :default: on
-
-    .. index::
-       single: -fvectorisation-avoidance
-
-    Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
-
-    Enable the *vectorisation* avoidance optimisation.
-    This optimisation only works when used in combination with the
-    ``-fvectorise`` transformation.
-
-    While vectorisation of code using DPH is often a big win, it can
-    also produce worse results for some kinds of code. This optimisation
-    modifies the vectorisation transformation to try to determine if a
-    function would be better of unvectorised and if so, do just that.
-
-.. ghc-flag:: -fvectorise
-    :shortdesc: Enable vectorisation of nested data parallelism
+.. ghc-flag:: -fbinary-blob-threshold=⟨n⟩
+    :shortdesc: *default: 500K.* Tweak assembly generator for binary blobs.
     :type: dynamic
-    :reverse: -fno-vectorise
-    :category:
+    :category: optimization
 
-    :default: off
+    :default: 500000
 
-    Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
+    The native code-generator can either dump binary blobs (e.g. string
+    literals) into the assembly file (by using ".asciz" or ".string" assembler
+    directives) or it can dump them as binary data into a temporary file which
+    is then included by the assembler (using the ".incbin" assembler directive).
 
-    Enable the *vectorisation* optimisation
-    transformation. This optimisation transforms the nested data
-    parallelism code of programs using DPH into flat data parallelism.
-    Flat data parallel programs should have better load balancing,
-    enable SIMD parallelism and friendlier cache behaviour.
+    This flag sets the size (in bytes) threshold above which the second approach
+    is used. You can disable the second approach entirely by setting the
+    threshold to 0.