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

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),
+    eOptionRichAnnotations = (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': //< --rich variable annotations
+    enable_rich_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_rich_annotations = false;
   plugin_name.clear();
 
   Target *target =
@@ -528,6 +533,9 @@ void CommandObjectDisassemble::DoExecute(Args &command,
   if (m_options.raw)
     options |= Disassembler::eOptionRawOuput;
 
+  if (m_options.enable_rich_annotations)
+    options |= Disassembler::eOptionRichAnnotations;
+
   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_rich_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_rich : Option<"variable", "v">,
+    Desc<"Enable rich 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,148 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
     }
   }
 
+  // Add rich 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 (keyed by stable LLDB user_id_t. 8
+  // is a good small-buffer guess.
+  llvm::SmallDenseMap<lldb::user_id_t, VarState, 8> 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 +688,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 & eOptionRichAnnotations) && 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 +888,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 +1235,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; }