[llvm] 5e63f2c - [DebugInfo][NFC] Document debug record salvage (#215907)

[via llvm-commits]

Author: Eric Christopher
Date: 2026-08-13T18:47:25-07:00
New Revision: 5e63f2ce42db2c42f1d0012a3b5fa9c6113f750a

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

LOG: [DebugInfo][NFC] Document debug record salvage (#215907)

Document the order salvageDebugInfoForDbgValues works in: a dbg.assign
address before its variable location, stop once a variable location
can't be salvaged, and kill every supplied record when none of them were
processed.

salvageDebugInfo is documented on both its declaration and its
definition, keep the header copy and update it.

No regressions on check-llvm.

Added: 
    

Modified: 
    llvm/include/llvm/Transforms/Utils/Local.h
    llvm/lib/Transforms/Utils/Local.cpp

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/Transforms/Utils/Local.h b/llvm/include/llvm/Transforms/Utils/Local.h
index 493a256c2ef58..e81cfd3b94ad9 100644
--- a/llvm/include/llvm/Transforms/Utils/Local.h
+++ b/llvm/include/llvm/Transforms/Utils/Local.h
@@ -317,14 +317,21 @@ LLVM_ABI bool replaceDbgDeclare(Value *Address, Value *NewAddress,
 LLVM_ABI void replaceDbgValueForAlloca(AllocaInst *AI, Value *NewAllocaAddress,
                                        DIBuilder &Builder, int Offset = 0);
 
-/// Assuming the instruction \p I is going to be deleted, attempt to salvage
-/// debug users of \p I by writing the effect of \p I in a DIExpression. If it
-/// cannot be salvaged changes its debug uses to undef.
+/// Salvage debug records that use \p I before the instruction is deleted.
+/// Rewrite those uses in terms of its operands where we can, and encode the
+/// instruction's effect in the record's DIExpression. Deleting the instruction
+/// replaces any remaining debug-record uses with poison.
 LLVM_ABI void salvageDebugInfo(Instruction &I);
 
-/// Implementation of salvageDebugInfo, applying only to instructions in
-/// \p Insns, rather than all debug users from findDbgUsers( \p I).
-/// Mark undef if salvaging cannot be completed.
+/// Salvage only the records in \p DPInsns instead of finding every debug
+/// user of \p I. Every record must be a debug user of the instruction.
+///
+/// Process records in order. For a dbg.assign, salvage a matching address
+/// before its variable location since replacing a variable-location operand
+/// can also replace the address. Stop when a checked variable location cannot
+/// be salvaged. A matching address counts as processed even if salvage leaves
+/// it unchanged. If nothing was processed, call setKillLocation() on every
+/// supplied record.
 LLVM_ABI void
 salvageDebugInfoForDbgValues(Instruction &I,
                              ArrayRef<DbgVariableRecord *> DPInsns);

diff  --git a/llvm/lib/Transforms/Utils/Local.cpp b/llvm/lib/Transforms/Utils/Local.cpp
index 7a73cabb4c762..0f96140a4b161 100644
--- a/llvm/lib/Transforms/Utils/Local.cpp
+++ b/llvm/lib/Transforms/Utils/Local.cpp
@@ -2030,8 +2030,6 @@ void llvm::replaceDbgValueForAlloca(AllocaInst *AI, Value *NewAllocaAddress,
                                Builder, Offset);
 }
 
-/// Where possible to salvage debug information for \p I do so.
-/// If not possible mark undef.
 void llvm::salvageDebugInfo(Instruction &I) {
   SmallVector<DbgVariableRecord *, 1> DPUsers;
   findDbgUsers(&I, DPUsers);
@@ -2053,7 +2051,8 @@ template <typename T> static void salvageDbgAssignAddress(T *Assign) {
   SmallVector<uint64_t, 16> Ops;
   Value *NewV = salvageDebugInfoImpl(*I, CurrentLocOps, Ops, AdditionalValues);
 
-  // Check if the salvage failed.
+  // Keep an address we cannot salvage. If I is deleted, its remaining metadata
+  // use is replaced with poison.
   if (!NewV)
     return;
 
@@ -2083,6 +2082,8 @@ void llvm::salvageDebugInfoForDbgValues(Instruction &I,
   bool Salvaged = false;
 
   for (auto *DVR : DPUsers) {
+    // replaceVariableLocationOp also updates a matching dbg.assign address, so
+    // salvage the address before changing the variable location.
     if (DVR->isDbgAssign()) {
       if (DVR->getAddress() == &I) {
         salvageDbgAssignAddress(DVR);
@@ -2120,8 +2121,8 @@ void llvm::salvageDebugInfoForDbgValues(Instruction &I,
           DIExpression::appendOpsToArg(SalvagedExpr, Ops, LocNo, StackValue);
       LocItr = std::find(++LocItr, DVRLocation.end(), &I);
     }
-    // salvageDebugInfoImpl should fail on examining the first element of
-    // DbgUsers, or none of them.
+    // The failure conditions in salvageDebugInfoImpl do not depend on
+    // CurrentLocOps, so failure can only occur on the first occurrence.
     if (!Op0)
       break;