Annotate disassembly with register‐resident variable locations

lldb/include/lldb/Expression/DWARFExpression.h

@@ -157,7 +157,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/include/lldb/Expression/DWARFExpressionList.h

@@ -9,6 +9,7 @@
 #ifndef LLDB_EXPRESSION_DWARFEXPRESSIONLIST_H
 #define LLDB_EXPRESSION_DWARFEXPRESSIONLIST_H
 
+#include "lldb/Core/AddressRange.h"
 #include "lldb/Core/Value.h"
 #include "lldb/Expression/DWARFExpression.h"
 #include "lldb/Utility/RangeMap.h"
@@ -58,6 +59,20 @@ class DWARFExpressionList {
   }
 
   lldb::addr_t GetFuncFileAddress() { return m_func_file_addr; }
+
+  /// Represents an entry in the DWARFExpressionList with all needed metadata.
+  struct DWARFExpressionEntry {
+    /// Represents a DWARF location range in the DWARF unit’s file‐address space
+    std::optional<AddressRange> file_range; ///< None = always-valid single expr
+    const DWARFExpression *expr;
+  };
+
+  /// Returns a DWARFExpressionEntry whose file_range contains the given
+  /// load‐address.  `func_load_addr` is the load‐address of the function
+  /// start; `load_addr` is the full runtime PC.  On success, `expr` is non-null.
+  std::optional<DWARFExpressionEntry>
+  GetExpressionEntryAtAddress(lldb::addr_t func_load_addr,
+                              lldb::addr_t load_addr) const;
 
   const DWARFExpression *GetExpressionAtAddress(lldb::addr_t func_load_addr,
                                                 lldb::addr_t load_addr) const;

lldb/source/Core/Disassembler.cpp

@@ -26,7 +26,10 @@
 #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/ExecutionContext.h"
+#include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/StackFrame.h"
 #include "lldb/Target/Target.h"
@@ -702,6 +705,98 @@ void Instruction::Dump(lldb_private::Stream *s, uint32_t max_opcode_byte_size,
   ss.FillLastLineToColumn(opcode_pos + opcode_column_width, ' ');
   ss.PutCString(mnemonics);
 
+  // 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.
+
+  const size_t annotation_column = 150;
+
+  auto annotate_variables = [&]() {
+    StackFrame *frame = exe_ctx->GetFramePtr();
+    TargetSP target_sp = exe_ctx->GetTargetSP();
+    if (!frame || !target_sp)
+      return;
+
+    addr_t current_pc = m_address.GetLoadAddress(target_sp.get());
+    addr_t original_pc = frame->GetFrameCodeAddress().GetLoadAddress(target_sp.get());
+
+    if (!frame->ChangePC(current_pc))
+      return;
+
+    VariableListSP var_list_sp = frame->GetInScopeVariableList(true);
+    if (!var_list_sp)
+      return;
+
+    SymbolContext sc = frame->GetSymbolContext(eSymbolContextFunction);
+    addr_t func_load_addr = LLDB_INVALID_ADDRESS;
+    if (sc.function)
+      func_load_addr = sc.function->GetAddress().GetLoadAddress(target_sp.get());
+
+    // Only annotate if the current disassembly line is short enough
+    // to keep annotations aligned past the desired annotation_column.
+    if (ss.GetSizeOfLastLine() >= annotation_column)
+      return;
+
+    std::vector<std::string> annotations;
+
+    for (const VariableSP &var_sp : *var_list_sp) {
+      if (!var_sp)
+        continue;
+
+      const char *name = var_sp->GetName().AsCString();
+      auto &expr_list = var_sp->LocationExpressionList();
+      if (!expr_list.IsValid())
+        continue;
+
+      // Handle std::optional<DWARFExpressionEntry>.
+      if (auto entryOrErr = expr_list.GetExpressionEntryAtAddress(func_load_addr, current_pc)) {
+        auto entry = *entryOrErr;
+        // Check if entry has a file_range, and filter on address if so.
+        if (!entry.file_range || entry.file_range->ContainsFileAddress(
+                (current_pc - func_load_addr) + expr_list.GetFuncFileAddress())) {
+
+          StreamString loc_str;
+          ABI *abi = exe_ctx->GetProcessPtr()->GetABI().get();
+          llvm::DIDumpOptions opts;
+          opts.ShowAddresses = false;
+          opts.PrintRegisterOnly = true; // <-- important: suppress DW_OP_... annotations, etc.
+
+          entry.expr->DumpLocation(&loc_str, eDescriptionLevelBrief, abi, opts);
+
+          // Only include if not empty.
+          llvm::StringRef loc_clean = llvm::StringRef(loc_str.GetString()).trim();
+          if (!loc_clean.empty()) {
+            annotations.push_back(llvm::formatv("{0} = {1}", name, loc_clean));
+          }
+        }
+      }
+    }
+
+    if (!annotations.empty()) {
+      ss.FillLastLineToColumn(annotation_column, ' ');
+      ss.PutCString(" ; ");
+      ss.PutCString(llvm::join(annotations, ", "));
+    }
+
+    frame->ChangePC(original_pc);
+  };
+
+  if (exe_ctx && exe_ctx->GetFramePtr()) {
+    annotate_variables();
+  }
+
   if (!m_comment.empty()) {
     ss.FillLastLineToColumn(
         opcode_pos + opcode_column_width + operand_column_width, ' ');
@@ -711,6 +806,7 @@ void Instruction::Dump(lldb_private::Stream *s, uint32_t max_opcode_byte_size,
   s->PutCString(ss.GetString());
 }
 
+
 bool Instruction::DumpEmulation(const ArchSpec &arch) {
   std::unique_ptr<EmulateInstruction> insn_emulator_up(
       EmulateInstruction::FindPlugin(arch, eInstructionTypeAny, nullptr));

lldb/source/Expression/DWARFExpression.cpp

@@ -66,7 +66,7 @@ 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 {
@@ -78,10 +78,9 @@ void DWARFExpression::DumpLocation(Stream *s, lldb::DescriptionLevel level,
         return llvm::StringRef(RegName);
     return {};
   };
-  llvm::DIDumpOptions DumpOpts;
-  DumpOpts.GetNameForDWARFReg = GetRegName;
-  llvm::DWARFExpression(m_data.GetAsLLVM(), m_data.GetAddressByteSize())
-      .print(s->AsRawOstream(), DumpOpts, nullptr);
+  options.GetNameForDWARFReg = GetRegName;
+  llvm::DWARFExpression expression (m_data.GetAsLLVM(), m_data.GetAddressByteSize());
+  expression.print(s->AsRawOstream(), options, nullptr);
 }
 
 RegisterKind DWARFExpression::GetRegisterKind() const { return m_reg_kind; }

lldb/source/Expression/DWARFExpressionList.cpp

@@ -6,6 +6,7 @@
 //
 //===----------------------------------------------------------------------===//
 
+#include "lldb/Core/AddressRange.h"
 #include "lldb/Expression/DWARFExpressionList.h"
 #include "lldb/Symbol/Function.h"
 #include "lldb/Target/RegisterContext.h"
@@ -53,6 +54,37 @@ bool DWARFExpressionList::ContainsAddress(lldb::addr_t func_load_addr,
   return GetExpressionAtAddress(func_load_addr, addr) != nullptr;
 }
 
+std::optional<DWARFExpressionList::DWARFExpressionEntry>
+DWARFExpressionList::GetExpressionEntryAtAddress(lldb::addr_t func_load_addr,
+                                                lldb::addr_t load_addr) const {
+  if (const DWARFExpression *always = GetAlwaysValidExpr()) {
+    return DWARFExpressionEntry{std::nullopt, always};
+  }
+
+  if (func_load_addr == LLDB_INVALID_ADDRESS)
+    func_load_addr = m_func_file_addr;
+
+  // Guard against underflow when translating a load address back into file space.
+  if (load_addr < func_load_addr)
+      return std::nullopt;
+
+  // Guard against overflow.
+  lldb::addr_t delta = load_addr - func_load_addr;
+  if (delta > std::numeric_limits<lldb::addr_t>::max() - m_func_file_addr)
+    return std::nullopt;
+
+  lldb::addr_t file_pc = (load_addr - func_load_addr) + m_func_file_addr;
+
+  if (const auto *entry = m_exprs.FindEntryThatContains(file_pc)) {
+    AddressRange range_in_file(entry->GetRangeBase(),
+                              entry->GetRangeEnd() - entry->GetRangeBase());
+    return DWARFExpressionEntry{range_in_file, &entry->data};
+  }
+
+  // No entry covers this PC:
+  return std::nullopt;
+}
+
 const DWARFExpression *
 DWARFExpressionList::GetExpressionAtAddress(lldb::addr_t func_load_addr,
                                             lldb::addr_t load_addr) const {

lldb/test/API/functionalities/rich-disassembler/Makefile

@@ -0,0 +1,6 @@
+
+# CXX_SOURCES := a_loop_with_local_variable.c  b_multiple_stack_variables.c  c_variable_passed_to_another_function.c  d_original_example.c  e_control_flow_edge.c
+C_SOURCES := a_loop_with_local_variable.c b_multiple_stack_variables.c c_variable_passed_to_another_function.c d_original_example.c e_control_flow_edge.c
+
+
+include Makefile.rules

lldb/test/API/functionalities/rich-disassembler/TestRichDisassembler.py

@@ -0,0 +1,43 @@
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test.decorators import *
+
+class TestRichDisassembler(TestBase):
+    def test_d_original_example_O1(self):
+        """
+        Tests disassembler output for d_original_example.c built with -O1.
+        """
+        self.build(dictionary={
+            'C_SOURCES': 'd_original_example.c',
+            'CFLAGS_EXTRAS': '-g -O1'
+        })
+        exe = self.getBuildArtifact("a.out")
+        target = self.dbg.CreateTarget(exe)
+        self.assertTrue(target)
+
+        breakpoint = target.BreakpointCreateByName("main")
+        self.assertGreater(breakpoint.GetNumLocations(), 0)
+
+        process = target.LaunchSimple(None, None, self.get_process_working_directory())
+        self.assertTrue(process, "Failed to launch process")
+        self.assertEqual(process.GetState(), lldb.eStateStopped)
+
+        frame = process.GetSelectedThread().GetSelectedFrame()
+        disasm = frame.Disassemble()
+        print(disasm)
+
+        self.assertIn("argc = ", disasm)
+        self.assertIn("argv = ", disasm)
+        self.assertIn("i = ", disasm)
+        # self.assertIn("DW_OP_reg", disasm)
+        # self.assertIn("DW_OP_stack_value", disasm)
+        self.assertNotIn("<decoding error>", disasm)
+
+
+
+
+
+
+
+
+
+

lldb/test/API/functionalities/rich-disassembler/d_original_example.c

@@ -0,0 +1,7 @@
+#include <stdio.h>
+
+int main(int argc, char **argv) {
+    for (int i = 1; i < argc; ++i)
+        puts(argv[i]);
+    return 0;
+}

llvm/include/llvm/DebugInfo/DIContext.h

@@ -209,6 +209,7 @@ struct DIDumpOptions {
   bool IsEH = false;
   bool DumpNonSkeleton = false;
   bool ShowAggregateErrors = false;
+  bool PrintRegisterOnly = false;
   std::string JsonErrSummaryFile;
   std::function<llvm::StringRef(uint64_t DwarfRegNum, bool IsEH)>
       GetNameForDWARFReg;