Fixes #17900; fixes #20195.

The existing "can_fail" and "has_side_effects" primop attributes
that previously governed this were used in inconsistent and
confusingly-documented ways, especially with regard to raising
exceptions.  This patch replaces them with a single "effect"
attribute, which has four possible values: NoEffect, CanFail,
ThrowsException, and ReadWriteEffect.  These are described in
Note [Classifying primop effects].

A substantial amount of related documentation has been re-drafted
for clarity and accuracy.

In the process of making this attribute format change for literally
every primop, several existing mis-classifications were detected and
corrected.  One of these mis-classifications was tagToEnum#, which
is now considered CanFail; this particular fix is known to cause a
regression in performance for derived Enum instances.  (See #23782.)
Fixing this is left as future work.

New primop attributes "cheap" and "work_free" were also added,
and used in the corresponding parts of GHC.Core.Utils.

In view of their actual meaning and uses, `primOpOkForSideEffects`
and `exprOkForSideEffects` have been renamed to `primOpOkToDiscard`
and `exprOkToDiscard`, respectively.

Metric Increase:
    T21839c