[docs] Sketch outline for HowToUpdateDebugInfo.rst

[vsk]

Summary

Sketch the outline for a new document that explains how to update debug
info in various kinds of code transformations.

Some of the guidelines that belong in HowToUpdateDebugInfo.rst were in
SourceLevelDebugging.rst already under the debugify section. It seems
like the distinction between the two docs ought to be that the former is
more prescriptive, while the latter is more descriptive.

To that end I've consolidated the "how to update debug info" guidelines
which were in SourceLevelDebugging.rst into the new doc, along with the
information about using "debugify" to test transformations. Since we've
added a mir-debugify pass, I've described that as well.

[vsk]

Clean up grammar.

[TWeaver]

llvm/docs/HowToUpdateDebugInfo.rst

28

Hi and thanks for this!

I'm not sure this line is actually correct.

It's my assumption that when a value pointed at by an intrinsic is deleted, the intrinsic is left with a valueless ValueAsMetaData() operand.

This empty ValueAsMetaData points at an empty metadata node, thus leaving us with an 'empty' intrinsic.

These empty intrinsics are usually removed from the program by later passes that clean up or remove 'junk' from the instruction stream.

My reading of this line gives me the impression that if I delete a value pointed to by an intrinsic, the intrinsic is auto-magically fixed up to be undef.

This may not have been your intent but it's how it reads to me.

I've fixed a bug in the Reassociate pass related to this issue in:

https://reviews.llvm.org/rG41c3f76dcd0daeec60eddfcb56008a31ad6e8738

[aprantl]

This is what we've been missing!

llvm/docs/HowToUpdateDebugInfo.rst

3

How to update Debug Info after a code transformation
?

30

reconstitute

30

unavailable, starting with the llvm.dbg.value(undef, ...).

103

TODO

Merging two instructions
-----------------------------

233

Do we want to add a section on SelectionDAG & GlobalISel, DAGCombine, etc?

[vsk]

llvm/docs/HowToUpdateDebugInfo.rst

28

Thanks for pointing this out. This seems bad.

A valueless dbg.value is treated as trivially dead (see wouldInstructionBeTriviallyDead). So unless specific care is taken to call salvageDebugInfoOrMarkUndef, deleting an Instruction -- and then running any instruction simplification helper -- results in inaccurate debug info.

@aprantl @dexonsmith can we change Instruction deletion s.t. any ValueAsMetadata nodes pointing to the dying value change to undef?

233

The info about MIR should generally carry over to GIsel. This probably does need a separate section for SelectionDAG, but I'm not sure how to structure that, so I'll leave it as TODO as well.

[djtodoro]

llvm/docs/HowToUpdateDebugInfo.rst

22

A TODO on changing DIMeatadata (such as introducing a DIFlag etc) by describing bitcode backward compatibility etc. ?

233

I guess we can add TODOs for the sections on VirtRegRewriter/LiveDebugVariables; LiveDebugValues; AsmPrinter(DwarfDebug;DwarfExpression); as well.

[jmorse]

This is going to be highly useful, thanks for kicking it off. Other topics we might want to cover:

• What to do when mutating instructions -- we saw that happen in PR45889.
• Control flow changes -- we probably want to prescribe that if one jump threads, duplicates or erases blocks, then the same sequence of debug intrinsics is seen on each program path as before. (Or otherwise, what to do in those scenarios).

Plus: how to update DebugLocs / line-numbers. These could be in their own top level section, or documented alongside the IR transforms. (I've no opinion on which).

llvm/docs/HowToUpdateDebugInfo.rst

233

My feeling is that the debug specific passes are best documented in SourceLevelDebugging.rst instead -- with this document focused on how optimisation writers should use LLVM APIs to preserve debug info in their passes.

The isel passes kind of fall into both those categories -- there's debug updating occurring, but lots of unrelated implementation details too.

[dsanders]

Thanks for working on this. I had a couple inline comments.

We should probably mention the LostDebugLocObserver that can be integrated into passes to detect location loss while a pass runs.

llvm/docs/HowToUpdateDebugInfo.rst

265–267

This is slightly misleading because the MIR one is called mir-debugify and we don't have a check pass, we just strip it

278–283

This will only run mir-debugify and not the normal pipeline. If you want to run it with a specific pass you need -run-pass=mir-debugify,other-pass.

To run it as part of the normal pipeline there's -debugify-and-strip-all-safe which can be combined with -start-before/-start-after. There's currently no way to run it once and then resume the normal pipeline without running it between every pass.

[aprantl]

To avoid the perfect being the enemy of the good, I would recommend not filling in any of the TODOs in this review, and instead create separate patches for adding additional documentation. With that said, this LGTM with all outstanding feedback addressed.

[aprantl]

llvm/docs/HowToUpdateDebugInfo.rst

28

Short answer: I don't know yet, we'll have to figure this out.

[dexonsmith]

llvm/docs/HowToUpdateDebugInfo.rst

28

@aprantl @dexonsmith can we change Instruction deletion s.t. any ValueAsMetadata nodes pointing to the dying value change to undef?

Sounds like a great idea to me (although I haven't looked at the IR implications of that recently).

[vsk]

Sorry for the delay. I'll share an update soon. I'll plan to land this by EOD next Monday (PST) if there aren't any objections, so we can parallelize work on this.

llvm/docs/HowToUpdateDebugInfo.rst

3

I humbly submit "s/after a code transformation/: A Guide for LLVM Pass Authors/" to make the target audience super-explicit.

22

I think we should spin up a separate document to describe how to hack on llvm's debug info facilities/representation. That way, we can keep this doc focused on what llvm pass authors need to know.

28

Great, this is done as of D80264.

233

+1 to @jmorse's comment here.

265–267

I've edited this to make it less misleading (and call out that there's no equivalent check-debugify pass).

278–283

Thanks, I've tried to fold this info in.

[vsk]

Incorporate suggestions from reviewers.

[vsk]

Update wording to reflect a change from D80264.

[aprantl]

llvm/docs/HowToUpdateDebugInfo.rst

3

I like it!

[djtodoro]

llvm/docs/HowToUpdateDebugInfo.rst

22

Having the A Guide for LLVM Pass Authors makes sense to me! Thanks!

233

Makes sense to me, thanks!

llvm/docs/HowToUpdateDebugInfo.rst

+=======================================================
+How to Update Debug Info: A Guide for LLVM Pass Authors
+=======================================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+Certain kinds of code transformations can inadvertently result in a loss of
+debug info, or worse, make debug info misrepresent the state of a program.
+
+This document specifies how to correctly update debug info in various kinds of
+code transformations, and offers suggestions for how to create targeted debug
+info tests for arbitrary transformations.
+
+For more on the philosophy behind LLVM debugging information, see
+:doc:`SourceLevelDebugging`.
+
+IR-level transformations
+========================
+
+Deleting an Instruction
+-----------------------
+
+When an ``Instruction`` is deleted, its debug uses change to ``undef``. This is
+a loss of debug info: the value of a one or more source variables becomes
+unavailable, starting with the ``llvm.dbg.value(undef, ...)``. When there is no
+way to reconstitute the value of the lost instruction, this is the best
+possible outcome. However, it's often possible to do better:
+
+* If the dying instruction can be RAUW'd, do so. The
+  ``Value::replaceAllUsesWith`` API transparently updates debug uses of the
+  dying instruction to point to the replacement value.
+
+* If the dying instruction cannot be RAUW'd, call
+  ``llvm::salvageDebugInfoOrMarkUndef`` on it. This makes a best-effort attempt
+  to rewrite debug uses of the dying instruction by describing its effect as a
+  ``DIExpression``.
+
+* If one of the **operands** of a dying instruction would become trivially
+  dead, use ``llvm::replaceAllDbgUsesWith`` to rewrite the debug uses of that
+  operand. Consider the following example function:
+
+.. code-block:: llvm
+
+  define i16 @foo(i16 %a) {
+    %b = sext i16 %a to i32
+    %c = and i32 %b, 15
+    call void @llvm.dbg.value(metadata i32 %c, ...)
+    %d = trunc i32 %c to i16
+    ret i16 %d
+  }
+
+Now, here's what happens after the unnecessary truncation instruction ``%d`` is
+replaced with a simplified instruction:
+
+.. code-block:: llvm
+
+  define i16 @foo(i16 %a) {
+    call void @llvm.dbg.value(metadata i32 undef, ...)
+    %simplified = and i16 %a, 15
+    ret i16 %simplified
+  }
+
+Note that after deleting ``%d``, all uses of its operand ``%c`` become
+trivially dead. The debug use which used to point to ``%c`` is now ``undef``,
+and debug info is needlessly lost.
+
+To solve this problem, do:
+
+.. code-block:: cpp
+
+  llvm::replaceAllDbgUsesWith(%c, theSimplifiedAndInstruction, ...)
+
+This results in better debug info because the debug use of ``%c`` is preserved:
+
+.. code-block:: llvm
+
+  define i16 @foo(i16 %a) {
+    %simplified = and i16 %a, 15
+    call void @llvm.dbg.value(metadata i16 %simplified, ...)
+    ret i16 %simplified
+  }
+
+You may have noticed that ``%simplified`` is narrower than ``%c``: this is not
+a problem, because ``llvm::replaceAllDbgUsesWith`` takes care of inserting the
+necessary conversion operations into the DIExpressions of updated debug uses.
+
+Hoisting an Instruction
+-----------------------
+
+TODO
+
+Sinking an Instruction
+----------------------
+
+TODO
+
+Cloning an Instruction
+----------------------
+
+TODO
+
+Merging two Instructions
+------------------------
+
+TODO
+
+Creating an artificial Instruction
+----------------------------------
+
+TODO
+
+Mutation testing for IR-level transformations
+---------------------------------------------
+
+An IR test case for a transformation can, in many cases, be automatically
+mutated to test debug info handling within that transformation. This is a
+simple way to test for proper debug info handling.
+
+The ``debugify`` utility
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``debugify`` testing utility is just a pair of passes: ``debugify`` and
+``check-debugify``.
+
+The first applies synthetic debug information to every instruction of the
+module, and the second checks that this DI is still available after an
+optimization has occurred, reporting any errors/warnings while doing so.
+
+The instructions are assigned sequentially increasing line locations, and are
+immediately used by debug value intrinsics everywhere possible.
+
+For example, here is a module before:
+
+.. code-block:: llvm
+
+   define void @f(i32* %x) {
+   entry:
+     %x.addr = alloca i32*, align 8
+     store i32* %x, i32** %x.addr, align 8
+     %0 = load i32*, i32** %x.addr, align 8
+     store i32 10, i32* %0, align 4
+     ret void
+   }
+
+and after running ``opt -debugify``:
+
+.. code-block:: llvm
+
+   define void @f(i32* %x) !dbg !6 {
+   entry:
+     %x.addr = alloca i32*, align 8, !dbg !12
+     call void @llvm.dbg.value(metadata i32** %x.addr, metadata !9, metadata !DIExpression()), !dbg !12
+     store i32* %x, i32** %x.addr, align 8, !dbg !13
+     %0 = load i32*, i32** %x.addr, align 8, !dbg !14
+     call void @llvm.dbg.value(metadata i32* %0, metadata !11, metadata !DIExpression()), !dbg !14
+     store i32 10, i32* %0, align 4, !dbg !15
+     ret void, !dbg !16
+   }
+
+   !llvm.dbg.cu = !{!0}
+   !llvm.debugify = !{!3, !4}
+   !llvm.module.flags = !{!5}
+
+   !0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
+   !1 = !DIFile(filename: "debugify-sample.ll", directory: "/")
+   !2 = !{}
+   !3 = !{i32 5}
+   !4 = !{i32 2}
+   !5 = !{i32 2, !"Debug Info Version", i32 3}
+   !6 = distinct !DISubprogram(name: "f", linkageName: "f", scope: null, file: !1, line: 1, type: !7, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: true, unit: !0, retainedNodes: !8)
+   !7 = !DISubroutineType(types: !2)
+   !8 = !{!9, !11}
+   !9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
+   !10 = !DIBasicType(name: "ty64", size: 64, encoding: DW_ATE_unsigned)
+   !11 = !DILocalVariable(name: "2", scope: !6, file: !1, line: 3, type: !10)
+   !12 = !DILocation(line: 1, column: 1, scope: !6)
+   !13 = !DILocation(line: 2, column: 1, scope: !6)
+   !14 = !DILocation(line: 3, column: 1, scope: !6)
+   !15 = !DILocation(line: 4, column: 1, scope: !6)
+   !16 = !DILocation(line: 5, column: 1, scope: !6)
+
+Using ``debugify``
+^^^^^^^^^^^^^^^^^^
+
+A simple way to use ``debugify`` is as follows:
+
+.. code-block:: bash
+
+  $ opt -debugify -pass-to-test -check-debugify sample.ll
+
+This will inject synthetic DI to ``sample.ll`` run the ``pass-to-test`` and
+then check for missing DI. The ``-check-debugify`` step can of course be
+omitted in favor of more customizable FileCheck directives.
+
+Some other ways to run debugify are available:
+
+.. code-block:: bash
+
+   # Same as the above example.
+   $ opt -enable-debugify -pass-to-test sample.ll
+
+   # Suppresses verbose debugify output.
+   $ opt -enable-debugify -debugify-quiet -pass-to-test sample.ll
+
+   # Prepend -debugify before and append -check-debugify -strip after
+   # each pass on the pipeline (similar to -verify-each).
+   $ opt -debugify-each -O2 sample.ll
+
+In order for ``check-debugify`` to work, the DI must be coming from
+``debugify``. Thus, modules with existing DI will be skipped.
+
+``debugify`` can be used to test a backend, e.g:
+
+.. code-block:: bash
+
+   $ opt -debugify < sample.ll | llc -o -
+
+There is also a MIR-level debugify pass that can be run before each backend
+pass, see:
+:ref:`Mutation testing for MIR-level transformations`.
+
+``debugify`` in regression tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The output of the ``debugify`` pass must be stable enough to use in regression
+tests. Changes to this pass are not allowed to break existing tests.
+
+.. note::
+
+   Regression tests must be robust. Avoid hardcoding line/variable numbers in
+   check lines. In cases where this can't be avoided (say, if a test wouldn't
+   be precise enough), moving the test to its own file is preferred.
+
+MIR-level transformations
+=========================
+
+Deleting a MachineInstr
+-----------------------
+
+TODO
+
+Hoisting a MachineInstr
+-----------------------
+
+TODO
+
+Sinking a MachineInstr
+----------------------
+
+TODO
+
+Cloning a MachineInstr
+----------------------
+
+TODO
+
+Creating an artificial MachineInstr
+-----------------------------------
+
+TODO
+
+Mutation testing for MIR-level transformations
+----------------------------------------------
+
+A varaint of the ``debugify`` utility described in :ref:`Mutation testing for
+IR-level transformations` can be used for MIR-level transformations as well:
+much like the IR-level pass, ``mir-debugify`` inserts sequentially increasing
+line locations to each ``MachineInstr`` in a ``Module`` (although there is no
+equivalent MIR-level ``check-debugify`` pass).
+
+For example, here is a snippet before:
+
+.. code-block:: llvm
+
+  name:            test
+  body:             |
+    bb.1 (%ir-block.0):
+      %0:_(s32) = IMPLICIT_DEF
+      %1:_(s32) = IMPLICIT_DEF
+      %2:_(s32) = G_CONSTANT i32 2
+      %3:_(s32) = G_ADD %0, %2
+      %4:_(s32) = G_SUB %3, %1
+
+and after running ``llc -run-pass=mir-debugify``:
+
+.. code-block:: llvm
+
+  name:            test
+  body:             |
+    bb.0 (%ir-block.0):
+      %0:_(s32) = IMPLICIT_DEF debug-location !12
+      DBG_VALUE %0(s32), $noreg, !9, !DIExpression(), debug-location !12
+      %1:_(s32) = IMPLICIT_DEF debug-location !13
+      DBG_VALUE %1(s32), $noreg, !11, !DIExpression(), debug-location !13
+      %2:_(s32) = G_CONSTANT i32 2, debug-location !14
+      DBG_VALUE %2(s32), $noreg, !9, !DIExpression(), debug-location !14
+      %3:_(s32) = G_ADD %0, %2, debug-location !DILocation(line: 4, column: 1, scope: !6)
+      DBG_VALUE %3(s32), $noreg, !9, !DIExpression(), debug-location !DILocation(line: 4, column: 1, scope: !6)
+      %4:_(s32) = G_SUB %3, %1, debug-location !DILocation(line: 5, column: 1, scope: !6)
+      DBG_VALUE %4(s32), $noreg, !9, !DIExpression(), debug-location !DILocation(line: 5, column: 1, scope: !6)
+
+By default, ``mir-debugify`` inserts ``DBG_VALUE`` instructions **everywhere**
+it is legal to do so.  In particular, every (non-PHI) machine instruction that
+defines a register should be followed by a ``DBG_VALUE`` use of that def.  If
+an instruction does not define a register, but can be followed by a debug inst,
+MIRDebugify inserts a ``DBG_VALUE`` that references a constant.  Insertion of
+``DBG_VALUE``'s can be disabled by setting ``-debugify-level=locations``.
+
+To run MIRDebugify once, simply insert ``mir-debugify`` into your ``llc``
+invocation, like:
+
+.. code-block:: bash
+
+  # Before some other pass.
+  $ llc -run-pass=mir-debugify,other-pass ...
+
+  # After some other pass.
+  $ llc -run-pass=other-pass,mir-debugify ...
+
+To run MIRDebugify before each pass in a pipeline, use
+``-debugify-and-strip-all-safe``. This can be combined with ``-start-before``
+and ``-start-after``. For example:
+
+.. code-block:: bash
+
+  $ llc -debugify-and-strip-all-safe -run-pass=... <other llc args>
+  $ llc -debugify-and-strip-all-safe -O1 <other llc args>
+
+To strip out all debug info from a test, use ``mir-strip-debug``, like:
+
+.. code-block:: bash
+
+  $ llc -run-pass=mir-debugify,other-pass,mir-strip-debug
+
+It can be useful to combine ``mir-debugify`` and ``mir-strip-debug`` to
+identify backend transformations which break in the presence of debug info.
+For example, to run the AArch64 backend tests with all normal passes
+"sandwiched" in between MIRDebugify and MIRStripDebugify mutation passes, run:
+
+.. code-block:: bash
+
+  $ llvm-lit test/CodeGen/AArch64 -Dllc="llc -debugify-and-strip-all-safe"
+
+Using the LostDebugLocObserver
+------------------------------
+
+TODO

llvm/docs/SourceLevelDebugging.rst

 -----------------------------------
 
 An extremely high priority of LLVM debugging information is to make it interact
 well with optimizations and analysis.  In particular, the LLVM debug
 information provides the following guarantees:
 
 * LLVM debug information **always provides information to accurately read
   the source-level state of the program**, regardless of which LLVM
-  optimizations have been run, and without any modification to the
-  optimizations themselves.  However, some optimizations may impact the
-  ability to modify the current state of the program with a debugger, such
-  as setting program variables, or calling functions that have been
-  deleted.
+  optimizations have been run. :doc:`HowToUpdateDebugInfo` specifies how debug
+  info should be updated in various kinds of code transformations to avoid
+  breaking this guarantee, and how to preserve as much useful debug info as
+  possible.  Note that some optimizations may impact the ability to modify the
+  current state of the program with a debugger, such as setting program
+  variables, or calling functions that have been deleted.
 
 * As desired, LLVM optimizations can be upgraded to be aware of debugging
   information, allowing them to update the debugging information as they
   perform aggressive optimizations.  This means that, with effort, the LLVM
   optimizers could optimize debug code just as well as non-debug code.
 
 * LLVM debug information does not prevent optimizations from
   happening (for example inlining, basic block reordering/merging/cleanup,
* Generate and dump CodeView from LLVM IR metadata::
     $ llvm-readobj --codeview foo.obj > foo.txt
 
   Use this pattern in lit test cases and FileCheck the output of llvm-readobj
 
 Improving LLVM's CodeView support is a process of finding interesting type
 records, constructing a C++ test case that makes MSVC emit those records,
 dumping the records, understanding them, and then generating equivalent records
 in LLVM's backend.
-
-Testing Debug Info Preservation in Optimizations
-================================================
-
-The following paragraphs are an introduction to the debugify utility
-and examples of how to use it in regression tests to check debug info
-preservation after optimizations.
-
-The ``debugify`` utility
-------------------------
-
-The ``debugify`` synthetic debug info testing utility consists of two
-main parts. The ``debugify`` pass and the ``check-debugify`` one. They are
-meant to be used with ``opt`` for development purposes.
-
-The first applies synthetic debug information to every instruction of the module,
-while the latter checks that this DI is still available after an optimization
-has occurred, reporting any errors/warnings while doing so.
-
-The instructions are assigned sequentially increasing line locations,
-and are immediately used by debug value intrinsics when possible.
-
-For example, here is a module before:
-
-.. code-block:: llvm
-
-   define void @f(i32* %x) {
-   entry:
-     %x.addr = alloca i32*, align 8
-     store i32* %x, i32** %x.addr, align 8
-     %0 = load i32*, i32** %x.addr, align 8
-     store i32 10, i32* %0, align 4
-     ret void
-   }
-
-and after running ``opt -debugify``  on it we get:
-
-.. code-block:: text
-
-   define void @f(i32* %x) !dbg !6 {
-   entry:
-     %x.addr = alloca i32*, align 8, !dbg !12
-     call void @llvm.dbg.value(metadata i32** %x.addr, metadata !9, metadata !DIExpression()), !dbg !12
-     store i32* %x, i32** %x.addr, align 8, !dbg !13
-     %0 = load i32*, i32** %x.addr, align 8, !dbg !14
-     call void @llvm.dbg.value(metadata i32* %0, metadata !11, metadata !DIExpression()), !dbg !14
-     store i32 10, i32* %0, align 4, !dbg !15
-     ret void, !dbg !16
-   }
-
-   !llvm.dbg.cu = !{!0}
-   !llvm.debugify = !{!3, !4}
-   !llvm.module.flags = !{!5}
-
-   !0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
-   !1 = !DIFile(filename: "debugify-sample.ll", directory: "/")
-   !2 = !{}
-   !3 = !{i32 5}
-   !4 = !{i32 2}
-   !5 = !{i32 2, !"Debug Info Version", i32 3}
-   !6 = distinct !DISubprogram(name: "f", linkageName: "f", scope: null, file: !1, line: 1, type: !7, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: true, unit: !0, retainedNodes: !8)
-   !7 = !DISubroutineType(types: !2)
-   !8 = !{!9, !11}
-   !9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
-   !10 = !DIBasicType(name: "ty64", size: 64, encoding: DW_ATE_unsigned)
-   !11 = !DILocalVariable(name: "2", scope: !6, file: !1, line: 3, type: !10)
-   !12 = !DILocation(line: 1, column: 1, scope: !6)
-   !13 = !DILocation(line: 2, column: 1, scope: !6)
-   !14 = !DILocation(line: 3, column: 1, scope: !6)
-   !15 = !DILocation(line: 4, column: 1, scope: !6)
-   !16 = !DILocation(line: 5, column: 1, scope: !6)
-
-The following is an example of the -check-debugify output:
-
-.. code-block:: none
-
-   $ opt -enable-debugify -loop-vectorize llvm/test/Transforms/LoopVectorize/i8-induction.ll -disable-output
-   ERROR: Instruction with empty DebugLoc in function f --  %index = phi i32 [ 0, %vector.ph ], [ %index.next, %vector.body ]
-
-Errors/warnings can range from instructions with empty debug location to an
-instruction having a type that's incompatible with the source variable it describes,
-all the way to missing lines and missing debug value intrinsics.
-
-Fixing errors
-^^^^^^^^^^^^^
-
-Each of the errors above has a relevant API available to fix it.
-
-* In the case of missing debug location, ``Instruction::setDebugLoc`` or possibly
-  ``IRBuilder::setCurrentDebugLocation`` when using a Builder and the new location
-  should be reused.
-
-* When a debug value has incompatible type ``llvm::replaceAllDbgUsesWith`` can be used.
-  After a RAUW call an incompatible type error can occur because RAUW does not handle
-  widening and narrowing of variables while ``llvm::replaceAllDbgUsesWith`` does. It is
-  also capable of changing the DWARF expression used by the debugger to describe the variable.
-  It also prevents use-before-def by salvaging or deleting invalid debug values.
-
-* When a debug value is missing ``llvm::salvageDebugInfo`` can be used when no replacement
-  exists, or ``llvm::replaceAllDbgUsesWith`` when a replacement exists.
-
-Using ``debugify``
-------------------
-
-In order for ``check-debugify`` to work, the DI must be coming from
-``debugify``. Thus, modules with existing DI will be skipped.
-
-The most straightforward way to use ``debugify`` is as follows::
-
-  $ opt -debugify -pass-to-test -check-debugify sample.ll
-
-This will inject synthetic DI to ``sample.ll`` run the ``pass-to-test``
-and then check for missing DI.
-
-Some other ways to run debugify are available:
-
-.. code-block:: bash
-
-   # Same as the above example.
-   $ opt -enable-debugify -pass-to-test sample.ll
-
-   # Suppresses verbose debugify output.
-   $ opt -enable-debugify -debugify-quiet -pass-to-test sample.ll
-
-   # Prepend -debugify before and append -check-debugify -strip after
-   # each pass on the pipeline (similar to -verify-each).
-   $ opt -debugify-each -O2 sample.ll
-
-``debugify`` can also be used to test a backend, e.g:
-
-.. code-block:: bash
-
-   $ opt -debugify < sample.ll | llc -o -
-
-``debugify`` in regression tests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``-debugify`` pass is especially helpful when it comes to testing that
-a given pass preserves DI while transforming the module. For this to work,
-the ``-debugify`` output must be stable enough to use in regression tests.
-Changes to this pass are not allowed to break existing tests.
-
-It allows us to test for DI loss in the same tests we check that the
-transformation is actually doing what it should.
-
-Here is an example from ``test/Transforms/InstCombine/cast-mul-select.ll``:
-
-.. code-block:: llvm
-
-   ; RUN: opt < %s -debugify -instcombine -S | FileCheck %s --check-prefix=DEBUGINFO
-
-   define i32 @mul(i32 %x, i32 %y) {
-   ; DBGINFO-LABEL: @mul(
-   ; DBGINFO-NEXT:    [[C:%.*]] = mul i32 {{.*}}
-   ; DBGINFO-NEXT:    call void @llvm.dbg.value(metadata i32 [[C]]
-   ; DBGINFO-NEXT:    [[D:%.*]] = and i32 {{.*}}
-   ; DBGINFO-NEXT:    call void @llvm.dbg.value(metadata i32 [[D]]
-
-     %A = trunc i32 %x to i8
-     %B = trunc i32 %y to i8
-     %C = mul i8 %A, %B
-     %D = zext i8 %C to i32
-     ret i32 %D
-   }
-
-Here we test that the two ``dbg.value`` instrinsics are preserved and
-are correctly pointing to the ``[[C]]`` and ``[[D]]`` variables.
-
-.. note::
-
-   Note, that when writing this kind of regression tests, it is important
-   to make them as robust as possible. That's why we should try to avoid
-   hardcoding line/variable numbers in check lines. If for example you test
-   for a ``DILocation`` to have a specific line number, and someone later adds
-   an instruction before the one we check the test will fail. In the cases this
-   can't be avoided (say, if a test wouldn't be precise enough), moving the
-   test to its own file is preferred.

llvm/docs/UserGuides.rst

.. toctree::
    DebuggingJITedCode
    Docker
    ExtendingLLVM
    GoldPlugin
    HowToBuildOnARM
    HowToBuildWithPGO
    HowToCrossCompileBuiltinsOnArm
    HowToCrossCompileLLVM
+   HowToUpdateDebugInfo
    LinkTimeOptimization
    LoopTerminology
    MarkdownQuickstartTemplate
    MemorySSA
    MergeFunctions
    MCJITDesignAndImplementation
    NVPTXUsage
    Phabricator

 :doc:`NVPTXUsage`
    This document describes using the NVPTX backend to compile GPU kernels.
 
 :doc:`AMDGPUUsage`
    This document describes using the AMDGPU backend to compile GPU kernels.
 
 :doc:`AMDGPUDwarfProposalForHeterogeneousDebugging`
    This document describes a DWARF proposal to support heterogeneous debugging
-   for targets such as the AMDGPU backend.
+   for targets such as the AMDGPU backend.