Stateful variable-location annotations in Disassembler::PrintInstructions() (follow-up to llvm#147460) (llvm#152887)

**Context**  
Follow-up to
[llvm#147460](llvm#147460), which added
the ability to surface register-resident variable locations.
This PR moves the annotation logic out of `Instruction::Dump()` and into
`Disassembler::PrintInstructions()`, and adds lightweight state tracking
so we only print changes at range starts and when variables go out of
scope.

---

## What this does

While iterating the instructions for a function, we maintain a “live
variable map” keyed by `lldb::user_id_t` (the `Variable`’s ID) to
remember each variable’s last emitted location string. For each
instruction:

- **New (or newly visible) variable** → print `name = <location>` once
at the start of its DWARF location range, cache it.
- **Location changed** (e.g., DWARF range switched to a different
register/const) → print the updated mapping.
- **Out of scope** (was tracked previously but not found for the current
PC) → print `name = <undef>` and drop it.

This produces **concise, stateful annotations** that highlight variable
lifetime transitions without spamming every line.

---

## Why in `PrintInstructions()`?

- Keeps `Instruction` stateless and avoids changing the
`Instruction::Dump()` virtual API.
- Makes it straightforward to diff state across instructions (`prev →
current`) inside the single driver loop.

---

## How it works (high-level)

1. For the current PC, get in-scope variables via
`StackFrame::GetInScopeVariableList(/*get_parent=*/true)`.
2. For each `Variable`, query
`DWARFExpressionList::GetExpressionEntryAtAddress(func_load_addr,
current_pc)` (added in llvm#144238).
3. If the entry exists, call `DumpLocation(..., eDescriptionLevelBrief,
abi)` to get a short, ABI-aware location string (e.g., `DW_OP_reg3 RBX →
RBX`).
4. Compare against the last emitted location in the live map:
   - If not present → emit `name = <location>` and record it.
   - If different → emit updated mapping and record it.
5. After processing current in-scope variables, compute the set
difference vs. the previous map and emit `name = <undef>` for any that
disappeared.

Internally:
- We respect file↔load address translation already provided by
`DWARFExpressionList`.
- We reuse the ABI to map LLVM register numbers to arch register names.

---

## Example output (x86_64, simplified)

```
->  0x55c6f5f6a140 <+0>:  cmpl   $0x2, %edi                                                         ; argc = RDI, argv = RSI
    0x55c6f5f6a143 <+3>:  jl     0x55c6f5f6a176            ; <+54> at d_original_example.c:6:3
    0x55c6f5f6a145 <+5>:  pushq  %r15
    0x55c6f5f6a147 <+7>:  pushq  %r14
    0x55c6f5f6a149 <+9>:  pushq  %rbx
    0x55c6f5f6a14a <+10>: movq   %rsi, %rbx
    0x55c6f5f6a14d <+13>: movl   %edi, %r14d
    0x55c6f5f6a150 <+16>: movl   $0x1, %r15d                                                        ; argc = R14
    0x55c6f5f6a156 <+22>: nopw   %cs:(%rax,%rax)                                                    ; i = R15, argv = RBX
    0x55c6f5f6a160 <+32>: movq   (%rbx,%r15,8), %rdi
    0x55c6f5f6a164 <+36>: callq  0x55c6f5f6a030            ; symbol stub for: puts
    0x55c6f5f6a169 <+41>: incq   %r15
    0x55c6f5f6a16c <+44>: cmpq   %r15, %r14
    0x55c6f5f6a16f <+47>: jne    0x55c6f5f6a160            ; <+32> at d_original_example.c:5:10
    0x55c6f5f6a171 <+49>: popq   %rbx                                                               ; i = <undef>
    0x55c6f5f6a172 <+50>: popq   %r14                                                               ; argv = RSI
    0x55c6f5f6a174 <+52>: popq   %r15                                                               ; argc = RDI
    0x55c6f5f6a176 <+54>: xorl   %eax, %eax
    0x55c6f5f6a178 <+56>: retq  
```

Only transitions are shown: the start of a location, changes, and
end-of-lifetime.

---

## Scope & limitations (by design)

- Handles **simple locations** first (registers, const-in-register cases
surfaced by `DumpLocation`).
- **Memory/composite locations** are out of scope for this PR.
- Annotations appear **only at range boundaries** (start/change/end) to
minimize noise.
- Output is **target-independent**; register names come from the target
ABI.

## Implementation notes

- All annotation printing now happens in
`Disassembler::PrintInstructions()`.
- Uses `std::unordered_map<lldb::user_id_t, std::string>` as the live
map.
- No persistent state across calls; the map is rebuilt while walking
instruction by instruction.
- **No changes** to the `Instruction` interface.

---

## Requested feedback

- Placement and wording of the `<undef>` marker.
- Whether we should optionally gate this behind a setting (currently
always on when disassembling with an `ExecutionContext`).
- Preference for immediate inclusion of tests vs. follow-up patch.

---

Thanks for reviewing! Happy to adjust behavior/format based on feedback.

---------

Co-authored-by: Jonas Devlieghere <[email protected]>
Co-authored-by: Adrian Prantl <[email protected]>

Author: 3 people

lldb/include/lldb/Core/Disassembler.h

@@ -169,7 +169,7 @@ class Instruction {
 
   virtual bool IsAuthenticated() = 0;
 
-  bool CanSetBreakpoint ();
+  bool CanSetBreakpoint();
 
   virtual size_t Decode(const Disassembler &disassembler,
                         const DataExtractor &data,
@@ -282,7 +282,7 @@ std::function<bool(const Instruction::Operand &)> FetchImmOp(int64_t &imm);
 
 std::function<bool(const Instruction::Operand &)>
 MatchOpType(Instruction::Operand::Type type);
-}
+} // namespace OperandMatchers
 
 class InstructionList {
 public:
@@ -316,20 +316,19 @@ class InstructionList {
   /// @param[in] ignore_calls
   ///     It true, then fine the first branch instruction that isn't
   ///     a function call (a branch that calls and returns to the next
-  ///     instruction). If false, find the instruction index of any 
+  ///     instruction). If false, find the instruction index of any
   ///     branch in the list.
-  ///     
+  ///
   /// @param[out] found_calls
-  ///     If non-null, this will be set to true if any calls were found in 
+  ///     If non-null, this will be set to true if any calls were found in
   ///     extending the range.
-  ///    
+  ///
   /// @return
   ///     The instruction index of the first branch that is at or past
-  ///     \a start. Returns UINT32_MAX if no matching branches are 
+  ///     \a start. Returns UINT32_MAX if no matching branches are
   ///     found.
   //------------------------------------------------------------------
-  uint32_t GetIndexOfNextBranchInstruction(uint32_t start,
-                                           bool ignore_calls,
+  uint32_t GetIndexOfNextBranchInstruction(uint32_t start, bool ignore_calls,
                                            bool *found_calls) const;
 
   uint32_t GetIndexOfInstructionAtLoadAddress(lldb::addr_t load_addr,
@@ -399,6 +398,7 @@ class Disassembler : public std::enable_shared_from_this<Disassembler>,
     eOptionMarkPCAddress =
         (1u << 3), // Mark the disassembly line the contains the PC
     eOptionShowControlFlowKind = (1u << 4),
+    eOptionVariableAnnotations = (1u << 5),
   };
 
   enum HexImmediateStyle {

lldb/include/lldb/Expression/DWARFExpression.h

@@ -159,7 +159,8 @@ class DWARFExpression {
     return data.GetByteSize() > 0;
   }
 
-  void DumpLocation(Stream *s, lldb::DescriptionLevel level, ABI *abi) const;
+  void DumpLocation(Stream *s, lldb::DescriptionLevel level, ABI *abi,
+                    llvm::DIDumpOptions options = {}) const;
 
   bool MatchesOperand(StackFrame &frame, const Instruction::Operand &op) const;
 

lldb/source/Commands/CommandObjectDisassemble.cpp

@@ -154,6 +154,10 @@ Status CommandObjectDisassemble::CommandOptions::SetOptionValue(
     }
   } break;
 
+  case 'v':
+    enable_variable_annotations = true;
+    break;
+
   case '\x01':
     force = true;
     break;
@@ -180,6 +184,7 @@ void CommandObjectDisassemble::CommandOptions::OptionParsingStarting(
   end_addr = LLDB_INVALID_ADDRESS;
   symbol_containing_addr = LLDB_INVALID_ADDRESS;
   raw = false;
+  enable_variable_annotations = false;
   plugin_name.clear();
 
   Target *target =
@@ -529,6 +534,9 @@ void CommandObjectDisassemble::DoExecute(Args &command,
   if (m_options.raw)
     options |= Disassembler::eOptionRawOuput;
 
+  if (m_options.enable_variable_annotations)
+    options |= Disassembler::eOptionVariableAnnotations;
+
   llvm::Expected<std::vector<AddressRange>> ranges =
       GetRangesForSelectedMode(result);
   if (!ranges) {

lldb/source/Commands/CommandObjectDisassemble.h

@@ -78,6 +78,7 @@ class CommandObjectDisassemble : public CommandObjectParsed {
     // in SetOptionValue if anything the selects a location is set.
     lldb::addr_t symbol_containing_addr = 0;
     bool force = false;
+    bool enable_variable_annotations = false;
   };
 
   CommandObjectDisassemble(CommandInterpreter &interpreter);

lldb/source/Commands/Options.td

@@ -366,6 +366,8 @@ let Command = "disassemble" in {
     Desc<"Disassemble function containing this address.">;
   def disassemble_options_force : Option<"force", "\\x01">, Groups<[2,3,4,5,7]>,
     Desc<"Force disassembly of large functions.">;
+  def disassemble_options_variable : Option<"variable", "v">,
+    Desc<"Enable variable disassembly annotations for this invocation.">;
 }
 
 let Command = "diagnostics dump" in {

lldb/source/Core/Disassembler.cpp

@@ -26,7 +26,11 @@
 #include "lldb/Symbol/Function.h"
 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Symbol/SymbolContext.h"
+#include "lldb/Symbol/Variable.h"
+#include "lldb/Symbol/VariableList.h"
+#include "lldb/Target/ABI.h"
 #include "lldb/Target/ExecutionContext.h"
+#include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/StackFrame.h"
 #include "lldb/Target/Target.h"
@@ -41,6 +45,8 @@
 #include "lldb/lldb-private-enumerations.h"
 #include "lldb/lldb-private-interfaces.h"
 #include "lldb/lldb-private-types.h"
+#include "llvm/ADT/DenseMap.h"
+#include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Compiler.h"
 #include "llvm/TargetParser/Triple.h"
 
@@ -376,6 +382,147 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
     }
   }
 
+  // Add variable location annotations to the disassembly output.
+  //
+  // For each instruction, this block attempts to resolve in-scope variables
+  // and determine if the current PC falls within their
+  // DWARF location entry. If so, it prints a simplified annotation using the
+  // variable name and its resolved location (e.g., "var = reg; " ).
+  //
+  // Annotations are only included if the variable has a valid DWARF location
+  // entry, and the location string is non-empty after filtering. Decoding
+  // errors and DWARF opcodes are intentionally omitted to keep the output
+  // concise and user-friendly.
+  //
+  // The goal is to give users helpful live variable hints alongside the
+  // disassembled instruction stream, similar to how debug information
+  // enhances source-level debugging.
+
+  struct VarState {
+    std::string name;     ///< Display name.
+    std::string last_loc; ///< Last printed location (empty means <undef>).
+    bool seen_this_inst = false;
+  };
+
+  // Track live variables across instructions.
+  llvm::DenseMap<lldb::user_id_t, VarState> live_vars;
+
+  // Stateful annotator: updates live_vars and returns only what should be
+  // printed for THIS instruction.
+  auto annotate_static = [&](Instruction &inst, Target &target,
+                             ModuleSP module_sp) -> std::vector<std::string> {
+    std::vector<std::string> events;
+
+    // Reset per-instruction seen flags.
+    for (auto &kv : live_vars)
+      kv.second.seen_this_inst = false;
+
+    const Address &iaddr = inst.GetAddress();
+    if (!module_sp) {
+      // Everything previously live becomes <undef>.
+      for (auto I = live_vars.begin(), E = live_vars.end(); I != E;) {
+        auto Cur = I++;
+        events.push_back(
+            llvm::formatv("{0} = <undef>", Cur->second.name).str());
+        live_vars.erase(Cur);
+      }
+      return events;
+    }
+
+    // Resolve innermost block at this *file* address.
+    SymbolContext sc;
+    const lldb::SymbolContextItem mask =
+        eSymbolContextFunction | eSymbolContextBlock;
+    if (!module_sp->ResolveSymbolContextForAddress(iaddr, mask, sc) ||
+        !sc.function) {
+      // No function context: everything dies here.
+      for (auto I = live_vars.begin(), E = live_vars.end(); I != E;) {
+        auto Cur = I++;
+        events.push_back(
+            llvm::formatv("{0} = <undef>", Cur->second.name).str());
+        live_vars.erase(Cur);
+      }
+      return events;
+    }
+
+    Block *B = sc.block; ///< Innermost block containing iaddr.
+    VariableList var_list;
+    if (B) {
+      auto filter = [](Variable *v) -> bool { return v && !v->IsArtificial(); };
+
+      B->AppendVariables(/*can_create*/ true,
+                         /*get_parent_variables*/ true,
+                         /*stop_if_block_is_inlined_function*/ false,
+                         /*filter*/ filter,
+                         /*variable_list*/ &var_list);
+    }
+
+    const lldb::addr_t pc_file = iaddr.GetFileAddress();
+    const lldb::addr_t func_file = sc.function->GetAddress().GetFileAddress();
+
+    // ABI from Target (pretty reg names if plugin exists). Safe to be null.
+    lldb::ProcessSP no_process;
+    lldb::ABISP abi_sp = ABI::FindPlugin(no_process, target.GetArchitecture());
+    ABI *abi = abi_sp.get();
+
+    llvm::DIDumpOptions opts;
+    opts.ShowAddresses = false;
+    if (abi)
+      opts.PrintRegisterOnly = true;
+
+    for (size_t i = 0, e = var_list.GetSize(); i != e; ++i) {
+      lldb::VariableSP v = var_list.GetVariableAtIndex(i);
+      if (!v || v->IsArtificial())
+        continue;
+
+      const char *nm = v->GetName().AsCString();
+      llvm::StringRef name = nm ? nm : "<anon>";
+
+      lldb_private::DWARFExpressionList &exprs = v->LocationExpressionList();
+      if (!exprs.IsValid())
+        continue;
+
+      auto entry_or_err = exprs.GetExpressionEntryAtAddress(func_file, pc_file);
+      if (!entry_or_err)
+        continue;
+
+      auto entry = *entry_or_err;
+
+      StreamString loc_ss;
+      entry.expr->DumpLocation(&loc_ss, eDescriptionLevelBrief, abi, opts);
+      llvm::StringRef loc = llvm::StringRef(loc_ss.GetString()).trim();
+      if (loc.empty())
+        continue;
+
+      auto ins = live_vars.insert(
+          {v->GetID(), VarState{name.str(), loc.str(), /*seen*/ true}});
+      if (ins.second) {
+        // Newly live.
+        events.push_back(llvm::formatv("{0} = {1}", name, loc).str());
+      } else {
+        VarState &vs = ins.first->second;
+        vs.seen_this_inst = true;
+        if (vs.last_loc != loc) {
+          vs.last_loc = loc.str();
+          events.push_back(llvm::formatv("{0} = {1}", vs.name, loc).str());
+        }
+      }
+    }
+
+    // Anything previously live that we didn't see a location for at this inst
+    // is now <undef>.
+    for (auto I = live_vars.begin(), E = live_vars.end(); I != E;) {
+      auto Cur = I++;
+      if (!Cur->second.seen_this_inst) {
+        events.push_back(
+            llvm::formatv("{0} = <undef>", Cur->second.name).str());
+        live_vars.erase(Cur);
+      }
+    }
+
+    return events;
+  };
+
   previous_symbol = nullptr;
   SourceLine previous_line;
   for (size_t i = 0; i < num_instructions_found; ++i) {
@@ -540,10 +687,26 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
       const bool show_bytes = (options & eOptionShowBytes) != 0;
       const bool show_control_flow_kind =
           (options & eOptionShowControlFlowKind) != 0;
-      inst->Dump(&strm, max_opcode_byte_size, true, show_bytes,
+
+      StreamString inst_line;
+
+      inst->Dump(&inst_line, max_opcode_byte_size, true, show_bytes,
                  show_control_flow_kind, &exe_ctx, &sc, &prev_sc, nullptr,
                  address_text_size);
+
+      if ((options & eOptionVariableAnnotations) && target_sp) {
+        auto annotations = annotate_static(*inst, *target_sp, module_sp);
+        if (!annotations.empty()) {
+          const size_t annotation_column = 100;
+          inst_line.FillLastLineToColumn(annotation_column, ' ');
+          inst_line.PutCString("; ");
+          inst_line.PutCString(llvm::join(annotations, ", "));
+        }
+      }
+
+      strm.PutCString(inst_line.GetString());
       strm.EOL();
+
     } else {
       break;
     }
@@ -724,9 +887,7 @@ bool Instruction::DumpEmulation(const ArchSpec &arch) {
   return false;
 }
 
-bool Instruction::CanSetBreakpoint () {
-  return !HasDelaySlot();
-}
+bool Instruction::CanSetBreakpoint() { return !HasDelaySlot(); }
 
 bool Instruction::HasDelaySlot() {
   // Default is false.
@@ -1073,10 +1234,8 @@ void InstructionList::Append(lldb::InstructionSP &inst_sp) {
     m_instructions.push_back(inst_sp);
 }
 
-uint32_t
-InstructionList::GetIndexOfNextBranchInstruction(uint32_t start,
-                                                 bool ignore_calls,
-                                                 bool *found_calls) const {
+uint32_t InstructionList::GetIndexOfNextBranchInstruction(
+    uint32_t start, bool ignore_calls, bool *found_calls) const {
   size_t num_instructions = m_instructions.size();
 
   uint32_t next_branch = UINT32_MAX;

lldb/source/Expression/DWARFExpression.cpp

@@ -67,7 +67,8 @@ void DWARFExpression::UpdateValue(uint64_t const_value,
 }
 
 void DWARFExpression::DumpLocation(Stream *s, lldb::DescriptionLevel level,
-                                   ABI *abi) const {
+                                   ABI *abi,
+                                   llvm::DIDumpOptions options) const {
   auto *MCRegInfo = abi ? &abi->GetMCRegisterInfo() : nullptr;
   auto GetRegName = [&MCRegInfo](uint64_t DwarfRegNum,
                                  bool IsEH) -> llvm::StringRef {
@@ -79,10 +80,9 @@ void DWARFExpression::DumpLocation(Stream *s, lldb::DescriptionLevel level,
         return llvm::StringRef(RegName);
     return {};
   };
-  llvm::DIDumpOptions DumpOpts;
-  DumpOpts.GetNameForDWARFReg = GetRegName;
+  options.GetNameForDWARFReg = GetRegName;
   llvm::DWARFExpression E(m_data.GetAsLLVM(), m_data.GetAddressByteSize());
-  llvm::printDwarfExpression(&E, s->AsRawOstream(), DumpOpts, nullptr);
+  llvm::printDwarfExpression(&E, s->AsRawOstream(), options, nullptr);
 }
 
 RegisterKind DWARFExpression::GetRegisterKind() const { return m_reg_kind; }