This reverts commit a9d93ecf1f8d2cfe3f77851e0df179b386cff353.

This is part of a series of patches that tries to improve DILocation bug
detection in Debugify; see the review for more details. This is the patch
that adds the main feature, adding a set of `DebugLoc::get<Kind>`
functions that can be used for instructions with intentionally empty
DebugLocs to prevent Debugify from treating them as bugs, removing the
currently-pervasive false positives and allowing us to use Debugify (in
its original DI preservation mode) to reliably detect existing bugs and
regressions. This patch does not add uses of these functions, except for
once in Clang before optimizations, and in
`Instruction::dropLocation()`, since that is an obvious case that
immediately removes a set of false positives.

This patch introduces a new option `-preserve-merged-debug-info` to
preserve an arbitrary but deterministic version of debug information
when DILocations are merged. This is intended to be used in production
environments from which sample based profiles are derived such as
AutoFDO and MemProf.

With this patch we have see a 0.2% improvement on an internal workload
at Google when generating AutoFDO profiles. It also significantly
improves the ability for MemProf by preserving debug info for merged
call instructions used in the contextual profile.

---------

Co-authored-by: Krzysztof Pszeniczny <kpszeniczny@google.com>

Following discussions on PR #114231 this patch changes the policy on
merging locations, making the rule that new instructions should use a
merge of the locations of all the instructions whose output is produced
by the new instructions; in the case where only one instruction's output
is produced, as in most InstCombine optimizations, we use only that
instruction's location.

This PR modifies the examples of section "When to merge instruction
locations" in
[HowToUpdateDebugInfo](https://llvm.org/docs/HowToUpdateDebugInfo.html)
according to [the
discussion](https://discourse.llvm.org/t/debuginfo-merging-instruction-locations-of-hoisted-instructions/77357),
revise one misleading counterexample and refining the description of
hoisting identical instructions.

As we approach the state where support for debug intrinsics is dropping and
we print and use debug records by default, the documentation should be updated
to refer to debug records as the primary debug info representation, with
debug intrinsics being relegated to an optional alternative.

This patch performs a few updates:
- Replace references to intrinsics with references to records across all
the documentation.
- Replace intrinsics with records in code examples.
- Move debug records prior to debug intrinsics in the
SourceLevelDebugging document, and change text to refer to them as the
primary representation.
- Add release notes describing the change.

The Assignment Tracking debug-info feature is outlined in this RFC:

https://discourse.llvm.org/t/
  rfc-assignment-tracking-a-better-way-of-specifying-variable-locations-in-ir

Add documentation outlining the intent and design.

Debugify in OriginalDebugInfo mode, does (DebugInfo) collect-before-pass & check-after-pass
for each instruction, which is pretty expensive. When used to analyze DebugInfo losses
in large projects (like LLVM), this raises the build time unacceptably.
This patch introduces a limit for the number of processed functions per compile unit.
By default, the limit is set to UINT_MAX (practically unlimited), and by using the introduced
option  -debugify-func-limit  the limit could be set to any positive integer number.

Differential revision: https://reviews.llvm.org/D115714

    [Debugify][Original DI] Test dbg var loc preservation

    This is an improvement of [0]. This adds checking of
    original llvm.dbg.values()/declares() instructions in
    optimizations.

    We have picked a real issue that has been found with
    this (actually, picked one variable location missing
    from [1] and resolved the issue), and the result is
    the fix for that -- D100844.

    Before applying the D100844, using the options from [0]
    (but with this patch applied) on the compilation of GDB 7.11,
    the final HTML report for the debug-info issues can be found
    at [1] (please scroll down, and look for
    "Summary of Variable Location Bugs"). After applying
    the D100844, the numbers has improved a bit -- please take
    a look into [2].

    [0] https://llvm.org/docs/HowToUpdateDebugInfo.html#\
        test-original-debug-info-preservation-in-optimizations
    [1] https://djolertrk.github.io/di-check-before-adce-fix/
    [2] https://djolertrk.github.io/di-check-after-adce-fix/

    Differential Revision: https://reviews.llvm.org/D100845

The Unit test was failing because the pass from the test that
modifies the IR, in its runOnFunction() didn't return 'true',
so the expensive-check configuration triggered an assertion.

This reverts commit 76f375f3d9d6902820ffc21200e454926748c678.

This will be pushed again, after investigating a test failure:
https://lab.llvm.org/buildbot/#/builders/16/builds/11254