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

[Shan Huang via llvm-commits]

https://github.com/Apochens updated https://github.com/llvm/llvm-project/pull/86272

>From 7727a9d99398494cd6ab58983b3e67ac859e9256 Mon Sep 17 00:00:00 2001
From: Apochens <52285902006 at stu.ecnu.edu.cn>
Date: Fri, 22 Mar 2024 12:08:52 +0000
Subject: [PATCH 1/5] refine the examples of merging locations

---
 llvm/docs/HowToUpdateDebugInfo.rst | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index c64b5d1d0d98b6..1e36c0c45c8490 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -91,8 +91,11 @@ 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 successors of a conditional branch. For
+  example, merging identical loads/stores which occur on both sides of a CFG
+  diamond (see the ``MergedLoadStoreMotion`` pass). If there are more than one
+  group of identical instructions hoisted, apply merging instruction locations
+  for each single merged instruction.
 
 * Merging identical loop-invariant stores (see the LICM utility
   ``llvm::promoteLoopAccessesToScalars``).
@@ -115,11 +118,6 @@ 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
-  :ref:`dropping locations<WhenToDropLocation>` applies.
-
 .. _WhenToDropLocation:
 
 When to drop an instruction location

>From 6d5ad3f8c83aa2d6e888c6a88ec6bdea1e42f42d Mon Sep 17 00:00:00 2001
From: Apochens <52285902006 at stu.ecnu.edu.cn>
Date: Fri, 22 Mar 2024 15:08:15 +0000
Subject: [PATCH 2/5] refine description

---
 llvm/docs/HowToUpdateDebugInfo.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index 1e36c0c45c8490..e410125ddaee0b 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -91,11 +91,12 @@ misattributed to a block containing one of the instructions-to-be-merged.
 
 Examples of transformations that should follow this rule include:
 
-* Hoisting identical instructions from successors of a conditional branch. For
-  example, merging identical loads/stores which occur on both sides of a CFG
-  diamond (see the ``MergedLoadStoreMotion`` pass). If there are more than one
-  group of identical instructions hoisted, apply merging instruction locations
-  for each single merged instruction.
+* Hoisting identical instructions from successors of a conditional branch or
+  sinking those from different predecessors. 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``).

>From c314066a9c9b829162a93eaff490bb90f8906307 Mon Sep 17 00:00:00 2001
From: Apochens <52285902006 at stu.ecnu.edu.cn>
Date: Fri, 23 Aug 2024 02:47:35 +0000
Subject: [PATCH 3/5] refine the example

---
 llvm/docs/HowToUpdateDebugInfo.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index e410125ddaee0b..096bf9e4c6f601 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -91,9 +91,9 @@ misattributed to a block containing one of the instructions-to-be-merged.
 
 Examples of transformations that should follow this rule include:
 
-* Hoisting identical instructions from successors of a conditional branch or
-  sinking those from different predecessors. For example, merging identical
-  loads/stores which occur on both sides of a CFG diamond (see the
+* Hoisting identical instructions from all successors of a conditional branch
+  or sinking those from all different predecessors. 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.

>From 7488deb9555f891758cdbc8c6376c904b56a9178 Mon Sep 17 00:00:00 2001
From: Apochens <52285902006 at stu.ecnu.edu.cn>
Date: Wed, 28 Aug 2024 06:54:30 +0000
Subject: [PATCH 4/5] add the counter-example

---
 llvm/docs/HowToUpdateDebugInfo.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index 096bf9e4c6f601..987628959664fb 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -119,6 +119,13 @@ 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/sinking a part of the identical instructions with the same location.
+  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:
 
 When to drop an instruction location

>From 51ab177ca99fb08f755f4ed37072f4199ae1776e Mon Sep 17 00:00:00 2001
From: Apochens <52285902006 at stu.ecnu.edu.cn>
Date: Thu, 29 Aug 2024 03:34:48 +0000
Subject: [PATCH 5/5] refine wording

---
 llvm/docs/HowToUpdateDebugInfo.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index 987628959664fb..209f15333f7726 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -92,7 +92,7 @@ misattributed to a block containing one of the instructions-to-be-merged.
 Examples of transformations that should follow this rule include:
 
 * Hoisting identical instructions from all successors of a conditional branch
-  or sinking those from all different predecessors. For example, merging
+  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