Key changes:
 * Adds a new rule for forall-coercions over coercion variables, which
was implemented but conspicuously missing from the spec.
 * Adds treatment for FunCo.
 * Adds treatment for ForAllTy over coercion variables.
 * Improves commentary (including restoring a Note lost in
03d48526) in the source.

No changes to running code.

Previously, if we had a [W] (a :: k1) ~ (rhs :: k2), we would
spit out a [D] k1 ~ k2 and part the W as irreducible, hoping for
a unification. But we needn't do this. Instead, we now spit out
a [W] co :: k2 ~ k1 and then use co to cast the rhs of the original
Wanted. This means that we retain the connection between the
spat-out constraint and the original.

The problem with this new approach is that we cannot use the
casted equality for substitution; it's too like wanteds-rewriting-
wanteds. So, we forbid CTyEqCans that mention coercion holes.

All the details are in Note [Equalities with incompatible kinds]
in TcCanonical.

There are a few knock-on effects, documented where they occur.

While debugging an error in this patch, Simon and I ran into
infelicities in how patterns and matches are printed; we made
small improvements.

This patch includes mitigations for #17828, which causes spurious
pattern-match warnings. When #17828 is fixed, these lines should
be removed.

This read causes NULL dereferencing when len is 0.

Fixes #17909

In the reproducer in #17909 this bug is triggered as follows:

- SimplOpt.dealWithStringLiteral is called with a single-char string
  ("=" in #17909)

- tailFS gets called on the FastString of the single-char string.

- tailFS checks the length of the string, which is 1, and calls
  mkFastStringByteString on the tail of the ByteString, which is an
  empty ByteString as the original ByteString has only one char.

- ByteString's unsafeUseAsCStringLen returns (NULL, 0) for the empty
  ByteString, which is passed to mkFastStringWith.

- mkFastStringWith gets hash of the NULL pointer via hashStr, which
  fails on empty strings because of this bug.

Metric Decrease:
    ManyConstructors
    T12707
    T13035
    T1969

In #17911, Simon recognised many warnings stemming from over-long list
unions while coverage checking Cabal's `LicenseId` module.

This patch introduces a new `PmAltConSet` type which uses a `UniqDSet`
instead of an association list for `ConLike`s. For `PmLit`s, it will
still use an assocation list, though, because a similar map data
structure would entail a lot of busy work.

Fixes #17911.

The old entry had a heavy focus on how things had been. Which is
not what I generally look for in a user guide.

I also added a small section on behaviour of nested safe ffi calls.

[skip-ci]

We thought we needed to update the manual, but the fix for #16502
actually brings the implementation in line with the manual. So we
just alert users of how to update their code.

All the details are in new Note [Datatype return kinds] in
TcTyClsDecls.

Test case: typecheck/should_fail/T17021{,b}
           typecheck/should_compile/T17021a

Updates haddock submodule

This is consistent with the interface file behavior where we omit
HsNoCafRefs annotations with -fomit-interface-pragmas (implied by -O0).

ModDetails and ModIface are just different representations of the same
thing, so they really need to be in sync. This patch does the right
thing and does not need too much explanation, but here's an example of a
problem not doing this causes in !2842:

    -- MyInteger.hs
    module MyInteger
      ( MyInteger (MyInteger)
      , ToMyInteger (toMyInteger)
      ) where

    newtype MyInteger = MyInteger Integer

    class ToMyInteger a where
      toMyInteger :: a -> MyInteger

    instance ToMyInteger Integer where
      toMyInteger = MyInteger {- . succ -}

    -- Main.hs
    module Main
      ( main
      ) where

    import MyInteger (MyInteger (MyInteger), toMyInteger)

    main :: IO ()
    main = do
      let (MyInteger i) = (id . toMyInteger) (41 :: Integer)
      print i

If I build this with -O0, without this fix, we generate a ModDetails with
accurate LFInfo for toMyInteger (MyInteger.$fToMyIntegerInteger) which says that
it's a LFReEntrant with arity 1. This means in the use site (Main) we tag the
value:

    R3 = MyInteger.$fToMyIntegerInteger_closure + 1;
    R2 = GHC.Base.id_closure;
    R1 = GHC.Base.._closure;
    Sp = Sp - 16;
    call stg_ap_ppp_fast(R4, R3, R2, R1) args: 24, res: 0, upd: 24;

Now we change the definition by uncommenting the `succ` part and it becomes a thunk:

    MyInteger.$fToMyIntegerInteger [InlPrag=INLINE (sat-args=0)]
      :: MyInteger.ToMyInteger GHC.Integer.Type.Integer
    [GblId[DFunId(nt)]] =
        {} \u [] $ctoMyInteger_rEA;

and its LFInfo is now LFThunk. This change in LFInfo makes a difference in the
use site: we can no longer tag it.

But becuase the interface fingerprint does not change (because ModIface does not
change) we don't rebuild Main and tag the thunk.

(1.2% increase in allocations when building T12545 on armv7 because we
generate more code without CafInfos)

Metric Increase:
    T12545

This patch makes mapType use the successful idiom described
in TyCoRep
   Note [Specialising foldType]

I have not yet changed any functions to use mapType, though there
may be some suitable candidates.

This patch should be a no-op in terms of functionality but,
because it inlines the mapper itself, I'm hoping that there may
be some modest perf improvements.

Metric Decrease:
    T5631
    T5642
    T3064
    T9020
    T14683
    hie002
    haddock.Cabal
    haddock.base
    haddock.compiler

Right now, in the output of -ddump-timings to a file, you can't tell what the units are:

```
CodeGen [TemplateTestImports]: alloc=22454880 time=14.597
```

I believe bytes/milliseconds are the correct units, but confirmation would be appreciated. I'm basing it off of this snippet from `withTiming'`:

```
when (verbosity dflags >= 2 && prtimings == PrintTimings)
  $ liftIO $ logInfo dflags (defaultUserStyle dflags)
      (text "!!!" <+> what <> colon <+> text "finished in"
       <+> doublePrec 2 time
       <+> text "milliseconds"
       <> comma
       <+> text "allocated"
       <+> doublePrec 3 (realToFrac alloc / 1024 / 1024)
       <+> text "megabytes")
```

which implies time is in milliseconds, and allocations in bytes (which divided by 1024 would be KB, and again would be MB)

The test operator "==" is a Bash extension and produces a wrong result
if /bin/sh is not Bash.

- Remove an invalid assumption about GC checking what_next field. The GC
  doesn't care about what_next at all, if a TSO is reachable then all
  its pointers are followed (other than global_tso, which is only
  followed by compacting GC).

- Remove checkSTACK in checkTSO: TSO stacks will be visited in
  checkHeapChain, or checkLargeObjects etc.

- Add an assertion in checkTSO to check that the global_link field is
  sane.

- Did some refactor to remove forward decls in checkGlobalTSOList and
  added braces around single-statement if statements.

Update submodule: haddock

Fixes #17785

Here's how the problem occurs:

- In generation 0 we have a TSO that is finished (i.e. it has no more
  work to do or it is killed).

- The TSO only becomes reachable after collectDeadWeakPtrs().

- After collectDeadWeakPtrs() we switch to WeakDone phase where we don't
  move TSOs to different lists anymore (like the next gen's thread list
  or the resurrected_threads list).

- So the TSO will never be moved to a generation's thread list, but it
  will be promoted to generation 1.

- Generation 1 collected via mark-compact, and because the TSO is
  reachable it is marked, and its `global_link` field, which is bogus at
  this point (because the TSO is not in a list), will be threaded.

- Chaos ensues.

In other words, when these conditions hold:

- A TSO is reachable only after collectDeadWeakPtrs()
- It's finished (what_next is ThreadComplete or ThreadKilled)
- It's retained by mark-compact collector (moving collector doesn't
  evacuate the global_list field)

We end up doing random mutations on the heap because the TSO's
global_list field is not valid, but it still looks like a heap pointer
so we thread it during compacting GC.

The fix is simple: when we traverse old_threads lists to resurrect
unreachable threads the threads that won't be resurrected currently
stays on the old_threads lists. Those threads will never be visited
again by MarkWeak so we now reset the global_list fields. This way
compacting GC does not thread pointers to nowhere.

Testing
-------

The reproducer in #17785 is quite large and hard to build, because of
the dependencies, so I'm not adding a regression test.

In my testing the reproducer would take a less than 5 seconds to run,
and once in every ~5 runs would fail with a segfault or an assertion
error. In other cases it also fails with a test failure. Because the
tests never fail with the bug fix, assuming the code is correct, this
also means that this bug can sometimes lead to incorrect runtime
results.

After the fix I was able to run the reproducer repeatedly for about an
hour, with no runtime crashes or test failures.

To run the reproducer clone the git repo:

    $ git clone https://github.com/osa1/streamly --branch ghc-segfault

Then clone primitive and atomic-primops from their git repos and point
to the clones in cabal.project.local. The project should then be
buildable using GHC HEAD. Run the executable `properties` with `+RTS -c
-DZ`.

In addition to the reproducer above I run the test suite using:

    $ make slowtest EXTRA_HC_OPTS="-debug -with-rtsopts=-DS \
        -with-rtsopts=-c +RTS -c -RTS" SKIPWAY='nonmoving nonmoving_thr'

This enables compacting GC always in both GHC when building the test
programs and when running the test programs, and also enables sanity
checking when running the test programs. These set of flags are not
compatible for all tests so there are some failures, but I got the same
set of failures with this patch compared to GHC HEAD.

This flag undoes the effect of a previous "-haddock" flag.  Having both flags makes it easier
for build systems to enable Haddock parsing in a set of global flags, but then disable it locally for
specific targets (e.g., third-party packages whose comments don't pass the validation in the latest GHC).

I added the flag to expected-undocumented-flags.txt since `-haddock` was alreadyin that list.

This patch disentangles a bit more DynFlags from the native code
generator (CmmToAsm).

In more details:

- add a new NCGConfig datatype in GHC.CmmToAsm.Config which contains the
  configuration of a native code generation session
- explicitly pass NCGConfig/Platform arguments when necessary
- as a consequence `sdocWithPlatform` is gone and there are only a few
  `sdocWithDynFlags` left
- remove the use of `unsafeGlobalDynFlags` from GHC.CmmToAsm.CFG
- remove `sdocDebugLevel` (now we pass the debug level via NCGConfig)

There are still some places where DynFlags is used, especially because
of pretty-printing (CLabel), because of Cmm helpers (such as
`cmmExprType`) and because of `Outputable` instance for the
instructions. These are left for future refactoring as this patch is
already big.

Also fix the markup in the general note at the top of the module.  Haddock
(usability trade-off), does not support multi-line emphasised text.

From the notes.ghc.drop list found using weeder in #17713

Currently, the names of cost centres must be quoted or
be lowercase identifiers.

Fixes #17916.

The submodule has already been bumped to contain the fix.

Before this patch, tcDataDefn used to call tcLookupTcTyCon twice in a row:
	1. in bindTyClTyVars itself
	2. in the continuation passed to it

Now bindTyClTyVars passes the TcTyCon to the continuation, making
the second lookup unnecessary.

As noted in #17912, `open` system calls were `safe` rather than
`interruptible`. Consequently, the program could not be interrupted with
SIGINT if stuck in a slow open operation. Fix this by marking
`c_safe_open` as interruptible.

This patch is just refactoring: no change in
behaviour.

I removed the rather complicated
    checkConstraintsTcS
    checkTvConstraintsTcS

in favour of simpler functions
    emitImplicationTcS
    emitTvImplicationTcS
    pushLevelNoWorkList

The last of these is a little strange, but overall
it's much better I think.

Ticket #17841 showed that we can get a kind error
in a class signature, but lack an enclosing implication
that binds its skolems.

This patch

* Adds the wrapping implication: the new call to
  checkTvConstraints in tcClassDecl1

* Simplifies the API to checkTvConstraints, which
  was not otherwise called at all.

* Simplifies TcErrors.report_unsolved by *not*
  initialising the TidyEnv from the typechecker lexical
  envt.  It's enough to do so from the free vars of the
  unsolved constraints; and we get silly renamings if
  we add variables twice: once from the lexical scope
  and once from the implication constraint.

Closes #16144.

This patch improves the way that CSE combines identical
alternatives.  See #17901.

I'm still not happy about the duplication between CSE.combineAlts
and GHC.Core.Utils.combineIdenticalAlts; see the Notes with those
functions.  But this patch is a step forward.

Metric Decrease:
    T12425
    T5642

No change in functionality.  Just seems tidier (and signficantly more
efficient) to deal with ticks directly than to call stripTicksTopE.

nonmovingSweep already clears the bitmap in the sweep loop. There is no
reason to do so a second time.

The non-moving collector would previously walk the entire filled segment
list during the preparatory pause. However, this is far more work than
is strictly necessary. We can rather get away with merely collecting the
allocators' filled segment list heads and process the lists themselves
during the concurrent phase. This can significantly reduce the maximum
gen1 GC pause time in programs with high rates of long-lived allocations.

Previously it was possible to override the stage0 C compiler via `CC_STAGE0`,
but you couldn't override `ld` or `ar` in stage0.  This change allows overriding them
by setting `LD_STAGE0` or `AR_STAGE0`, respectively.

Our team uses this feature internally to take more control of our GHC build
and make it run more hermetically.