[llvm] ac93554 - Refine the examples in the debug info document (#86272)

[via llvm-commits]

Author: Shan Huang
Date: 2024-09-09T13:49:38+08:00
New Revision: ac9355446291a02239ce9b45d0c2225a4db0515a

URL: https://github.com/llvm/llvm-project/commit/ac9355446291a02239ce9b45d0c2225a4db0515a
DIFF: https://github.com/llvm/llvm-project/commit/ac9355446291a02239ce9b45d0c2225a4db0515a.diff

LOG: Refine the examples in the debug info document (#86272)

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.

Added: 
    

Modified: 
    llvm/docs/HowToUpdateDebugInfo.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index db3465aa54d844..f7db92d58f4356 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -91,8 +91,12 @@ misattributed to a block containing one of the instructions-to-be-merged.
 
 Examples of transformations that should follow this rule include:
 
-* Merging identical loads/stores which occur on both sides of a CFG diamond
-  (see the ``MergedLoadStoreMotion`` pass).
+* Hoisting identical instructions from all successors of a conditional branch
+  or sinking those from all paths to a postdominating block. For example,
+  merging identical loads/stores which occur on both sides of a CFG diamond
+  (see the ``MergedLoadStoreMotion`` pass). For each group of identical
+  instructions being hoisted/sunk, the merge of all their locations should be
+  applied to the merged instruction.
 
 * Merging identical loop-invariant stores (see the LICM utility
   ``llvm::promoteLoopAccessesToScalars``).
@@ -115,9 +119,11 @@ Examples of transformations for which this rule *does not* apply include:
   single-stepping experience. The rule for
   :ref:`dropping locations<WhenToDropLocation>` should apply here.
 
-* Hoisting identical instructions which appear in several successor blocks into
-  a predecessor block (see ``BranchFolder::HoistCommonCodeInSuccs``). In this
-  case there is no single merged instruction. The rule for
+* Hoisting/sinking that would make a location reachable when it previously
+  wasn't. Consider hoisting two identical instructions with the same location
+  from first two cases of a switch that has three cases. Merging their
+  locations would make the location from the first two cases reachable when the
+  third case is taken. The rule for
   :ref:`dropping locations<WhenToDropLocation>` applies.
 
 .. _WhenToDropLocation: