[DebugInfo][Docs] Remove `dbg.addr` from docs

[jryans]

Summary

Part of dbg.addr removal
Discussed in https://discourse.llvm.org/t/what-is-the-status-of-dbg-addr/62898

[Orlando]

SGTM

I wonder if it's worth leaving a dbg.addr section in here as a migration guide for front ends that use it (or perhaps a release note would be sufficient - we should probably include a release note either way).

Additionally IMO it could be worth writing up another discourse post with a title that conveys the intention to remove dbg.addr to ensure no one feels caught out, linking to the existing discourse discussion. YMMV.

llvm/docs/SourceLevelDebugging.rst

203–204

I guess we should update the docs to use opaque pointers in these examples (e.g. metadata ptr %buffer) but that is probably something for a seperate patch, since there are parts that need updating other than the bits you're touching here.

[jryans]

In D144792#4154663, @Orlando wrote:

I wonder if it's worth leaving a dbg.addr section in here as a migration guide for front ends that use it (or perhaps a release note would be sufficient - we should probably include a release note either way).

I wasn't sure what the common practice around migration docs was... I tried looking around at how past feature removals were handled, and they all seemed to remove all docs as if the feature never existed, so that's what I went with here. I am not sure whether there's an actual policy, or if everyone's just following what the last person did... If someone would prefer migration docs, I can of course add them. It's somewhat unclear how many frontends (if any) adopted dbg.addr vs. following what Clang does (by not using it).

For the release note, that's a good suggestion, I will add a note about this.

Additionally IMO it could be worth writing up another discourse post with a title that conveys the intention to remove dbg.addr to ensure no one feels caught out, linking to the existing discourse discussion. YMMV.

Ah yes, seems reasonable, I created another thread: https://discourse.llvm.org/t/dbg-addr-intrinsic-slated-for-removal/68781

llvm/docs/SourceLevelDebugging.rst

203–204

Right, probably best for a separate patch. There may be over conventions that need updating here (e.g. undef usage) as well.

[jryans]

Added release notes.

I've also fixed up the style of other debug info notes (there was broken link syntax), hopefully that's okay...

[Orlando]

Thank you! LGTM with inline nit.

llvm/docs/ReleaseNotes.rst

177–178

nit: IMO it's worth mentioning the DW_OP_deref is prepended to the DIExpression.

[Orlando]

llvm/docs/ReleaseNotes.rst

177–178

/s/prepended/appended

[jryans]

Updated release notes to mention DW_OP_deref is appended.

llvm/docs/AssignmentTracking.md

* `trackAssignments` doesn't yet work for variables that have their
   clang/test/CodeGen/assignment-tracking/assignment-tracking.cpp for an
   example.
 
 * In order to solve the first bullet-point we need to be able to specify that a
   memory location is available without using a `DIAssignID`. This is because
   the storage address is not computed by an instruction (it's an argument
   value) and therefore we have nowhere to put the metadata attachment. To solve
   this we probably need another marker intrinsic to denote "the variable's
-  stack home is X address" - similar to `llvm.dbg.declare` and `llvm.dbg.addr`
-  except that it needs to compose with `llvm.dbg.assign` intrinsics such that
-  the stack home address is only selected as a location for the variable when
-  the `llvm.dbg.assign` intrinsics agree it should be.
+  stack home is X address" - similar to `llvm.dbg.declare` except that it needs
+  to compose with `llvm.dbg.assign` intrinsics such that the stack home address
+  is only selected as a location for the variable when the `llvm.dbg.assign`
+  intrinsics agree it should be.
 
 * Given the above (a special "the stack home is X" intrinsic), and the fact
   that we can only track assignments with fixed offsets and sizes, I think we
   can probably get rid of the address and address-expression part, since it
   will always be computable with the info we have.

llvm/docs/LangRef.rst

 and implicit location descriptions.  Note that a location description is
 defined over certain ranges of a program, i.e the location of a variable may
 change over the course of the program. Register and memory location
 descriptions describe the *concrete location* of a source variable (in the
 sense that a debugger might modify its value), whereas *implicit locations*
 describe merely the actual *value* of a source variable which might not exist
 in registers or in memory (see ``DW_OP_stack_value``).
 
-A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect
-value (the address) of a source variable. The first operand of the intrinsic
-must be an address of some kind. A DIExpression attached to the intrinsic
-refines this address to produce a concrete location for the source variable.
+A ``llvm.dbg.declare`` intrinsic describes an indirect value (the address) of a
+source variable. The first operand of the intrinsic must be an address of some
+kind. A DIExpression attached to the intrinsic refines this address to produce a
+concrete location for the source variable.
 
 A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable.
 The first operand of the intrinsic may be a direct or indirect value. A
 DIExpression attached to the intrinsic refines the first operand to produce a
 direct value. For example, if the first operand is an indirect value, it may be
 necessary to insert ``DW_OP_deref`` into the DIExpression in order to produce a
 valid debug intrinsic.
 

llvm/docs/ReleaseNotes.rst

 
 
 Changes to the Metadata Info
 ---------------------------------
 
 Changes to the Debug Info
 ---------------------------------
 
-* The DWARFv5 feature of attaching `DW_AT_default_value` to defaulted template
+* The DWARFv5 feature of attaching ``DW_AT_default_value`` to defaulted template
   parameters will now be available in any non-strict DWARF mode and in a wider
-  range of cases than previously. (`D139953 <https://reviews.llvm.org/D139953>`_, `D139988 <https://reviews.llvm.org/D139988>`_)
-
-* The `DW_AT_name` on `DW_AT_typedef`s for alias templates will now omit defaulted
-  template parameters. (`D142268 <https://reviews.llvm.org/D142268>`_)
+  range of cases than previously.
+  (`D139953 <https://reviews.llvm.org/D139953>`_,
+  `D139988 <https://reviews.llvm.org/D139988>`_)
+
+* The ``DW_AT_name`` on ``DW_AT_typedef``\ s for alias templates will now omit
+  defaulted template parameters. (`D142268 <https://reviews.llvm.org/D142268>`_)
+
+* The experimental ``@llvm.dbg.addr`` intrinsic has been removed (`D144801
+  <https://reviews.llvm.org/D144801>`_). IR inputs with this intrinsic are
+  auto-upgraded to ``@llvm.dbg.value`` with ``DW_OP_deref`` appended to the
+  ``DIExpression`` (`D144793 <https://reviews.llvm.org/D144793>`_).
 
 Changes to the LLVM tools
 ---------------------------------
 
 Changes to LLDB
 ---------------------------------
 
 * In the results of commands such as `expr` and `frame var`, type summaries will now

llvm/docs/SourceLevelDebugging.rst

 .. _format_common_intrinsics:
 
 Debugger intrinsic functions
 ----------------------------
 
 LLVM uses several intrinsic functions (name prefixed with "``llvm.dbg``") to
 track source local variables through optimization and code generation.
 
-``llvm.dbg.addr``
+``llvm.dbg.declare``
 ^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: llvm
 
-  void @llvm.dbg.addr(metadata, metadata, metadata)
+  void @llvm.dbg.declare(metadata, metadata, metadata)
 
 This intrinsic provides information about a local element (e.g., variable).
 The first argument is metadata holding the address of variable, typically a
 static alloca in the function entry block.  The second argument is a
 `local variable <LangRef.html#dilocalvariable>`_ containing a description of
 the variable.  The third argument is a `complex expression
-<LangRef.html#diexpression>`_.  An `llvm.dbg.addr` intrinsic describes the
+<LangRef.html#diexpression>`_.  An `llvm.dbg.declare` intrinsic describes the
 *address* of a source variable.
 
 .. code-block:: text
 
     %i.addr = alloca i32, align 4
-    call void @llvm.dbg.addr(metadata i32* %i.addr, metadata !1,
+    call void @llvm.dbg.declare(metadata i32* %i.addr, metadata !1,
                                 metadata !DIExpression()), !dbg !2
     !1 = !DILocalVariable(name: "i", ...) ; int i
     !2 = !DILocation(...)
     ...
     %buffer = alloca [256 x i8], align 8
     ; The address of i is buffer+64.
-    call void @llvm.dbg.addr(metadata [256 x i8]* %buffer, metadata !3,
+    call void @llvm.dbg.declare(metadata [256 x i8]* %buffer, metadata !3,
                                metadata !DIExpression(DW_OP_plus, 64)), !dbg !4
     !3 = !DILocalVariable(name: "i", ...) ; int i
     !4 = !DILocation(...)
 
-A frontend should generate exactly one call to ``llvm.dbg.addr`` at the point
+A frontend should generate exactly one call to ``llvm.dbg.declare`` at the point
 of declaration of a source variable. Optimization passes that fully promote the
-variable from memory to SSA values will replace this call with possibly
-multiple calls to `llvm.dbg.value`. Passes that delete stores are effectively
-partial promotion, and they will insert a mix of calls to ``llvm.dbg.value``
-and ``llvm.dbg.addr`` to track the source variable value when it is available.
-After optimization, there may be multiple calls to ``llvm.dbg.addr`` describing
-the program points where the variables lives in memory. All calls for the same
-concrete source variable must agree on the memory location.
-
-
-``llvm.dbg.declare``
-^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: llvm
-
-  void @llvm.dbg.declare(metadata, metadata, metadata)
-
-This intrinsic is identical to `llvm.dbg.addr`, except that there can only be
-one call to `llvm.dbg.declare` for a given concrete `local variable
-<LangRef.html#dilocalvariable>`_. It is not control-dependent, meaning that if
-a call to `llvm.dbg.declare` exists and has a valid location argument, that
-address is considered to be the true home of the variable across its entire
-lifetime. This makes it hard for optimizations to preserve accurate debug info
-in the presence of ``llvm.dbg.declare``, so we are transitioning away from it,
-and we plan to deprecate it in future LLVM releases.
+variable from memory to SSA values will replace this call with possibly multiple
+calls to `llvm.dbg.value`. Passes that delete stores are effectively partial
+promotion, and they will insert a mix of calls to ``llvm.dbg.value`` to track
+the source variable value when it is available. After optimization, there may be
+multiple calls to ``llvm.dbg.declare`` describing the program points where the
+variables lives in memory. All calls for the same concrete source variable must
+agree on the memory location.
 
 
 ``llvm.dbg.value``
 ^^^^^^^^^^^^^^^^^^
 
 .. code-block:: llvm
 
   void @llvm.dbg.value(metadata, metadata, metadata)
.. code-block:: c
   3.    int Y = 22;
   4.    {
   5.      int Z = 23;
   6.      Z = X;
   7.    }
   8.    X = Y;
   9.  }
 
-.. FIXME: Update the following example to use llvm.dbg.addr once that is the
-   default in clang.
-
 Compiled to LLVM, this function would be represented like this:
 
 .. code-block:: text
 
   ; Function Attrs: nounwind ssp uwtable
   define void @foo() #0 !dbg !4 {
   entry:
     %X = alloca i32, align 4

 otherwise transformed into a non-register, the variable location becomes
 unavailable.
 
 Locations that are unavailable are treated as if they have been optimized out:
 in IR the location would be assigned ``undef`` by a debug intrinsic, and in MIR
 the equivalent location is used.
 
 After MIR locations are assigned to each variable, machine pseudo-instructions
-corresponding to each ``llvm.dbg.value`` and ``llvm.dbg.addr`` intrinsic are
-inserted. There are two forms of this type of instruction.
+corresponding to each ``llvm.dbg.value`` intrinsic are inserted. There are two
+forms of this type of instruction.
 
 The first form, ``DBG_VALUE``, appears thus:
 
 .. code-block:: text
 
   DBG_VALUE %1, $noreg, !123, !DIExpression()
 
 And has the following operands: