For swift async code, we need to use a debug intrinsic that behaves like
an llvm.dbg.declare but can take any location type rather than just a
pointer or integer.

To solve this, a new debug instrinsic called llvm.dbg.declare_value has
been created, which behaves exactly like an llvm.dbg.declare but can
take non pointer and integer location types.

More information here:
https://discourse.llvm.org/t/rfc-introduce-new-llvm-dbg-coroframe-entry-intrinsic/88269

This is the first patch as part of a stack of patches, with the one
succeeding it being: https://github.com/llvm/llvm-project/pull/168134

Stop mentioning `unsafe-fp-math` related things in documents.

Factor out most of the DIExpression docs from LangRef.rst into
SourceLevelDebugging.rst

What remains in LangRef is just enough context to make sense of how
DIExpression-as-metadata fits into the IR, including some examples of
the DIExpression syntax.

The rest now lives in the SourceLevelDebugging document, which gives
more context to make sense of DIExpression-as-semantic-entity.

Use sections to clearly separate DWARF opcodes from LLVM internal-only
opcodes, where before the distinction was only explicit in the source
code.

Also make some other changes like fixing typos, using :ref: rather than
unchecked links, and rewording DW_OP_LLVM_entry_value.

This patch takes care of the highly mechanical part of proofreading
SourceLevelDebugging.rst, namely:

- hyphenating "32 bit value" and similar and
- hypenating "Objective C"

Try to give a more complete description of what we call a "fragment",
and how debug records interact when fragments are involved.

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>

As far as I understand, the first operand of dbg_declare should be a
pointer (inside a metadata wrapper). However, using a non-pointer is
currently not rejected, and we have some tests that use non-pointer
types. As far as I can tell, these tests either meant to use dbg_value
or are just incorrect hand-crafted tests.

Ran into this while trying to `fix` #134008.

The metadata was off-by-one in a couple of places, making the
explanatory text incorrect.

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.