Added --rich option for disassembler annotations and updated SBFrame path**

UltimateForce21 · UltimateForce21 · commit 3d19b0294eaf · 2025-08-08T11:14:56.000-04:00
* Added a new `--rich` (`-R`) command-line option to `CommandObjectDisassemble` to enable rich disassembly annotations for the current invocation.

* Plumbed a new `enable_rich_annotations` flag through:
  * `Disassembler::Disassemble` overloads
  * `Disassembler::PrintInstructions`
  * `Instruction::Dump`
  * `StackFrame::Disassemble`

* Updated `StackFrame::Disassemble` to take an optional `bool enable_rich_annotations` (default `false`) so the SB API can request annotated output without CLI involvement.

* Ensured annotations are only added when `enable_rich_annotations` is `true`; preserved caching for the non-rich path.

* Modified `Options.td` to define the new `--rich` option.

* Added/updated API test `TestRichDisassembler.py` to run `disassemble --rich -f` and check annotated output.

* Kept default behavior unchanged so existing scripts and IDE integrations are unaffected.
diff --git a/lldb/include/lldb/Core/Disassembler.h b/lldb/include/lldb/Core/Disassembler.h
@@ -159,7 +159,8 @@ class Instruction {
                     const SymbolContext *sym_ctx,
                     const SymbolContext *prev_sym_ctx,
                     const FormatEntity::Entry *disassembly_addr_format,
-                    size_t max_address_text_size);
+                    size_t max_address_text_size,
+                    bool enable_rich_annotations = false);
 
   virtual bool DoesBranch() = 0;
 
@@ -443,10 +444,10 @@ class Disassembler : public std::enable_shared_from_this<Disassembler>,
                           const ExecutionContext &exe_ctx, const Address &start,
                           Limit limit, bool mixed_source_and_assembly,
                           uint32_t num_mixed_context_lines, uint32_t options,
-                          Stream &strm);
+                          Stream &strm, bool enable_rich_annotations = false);
 
   static bool Disassemble(Debugger &debugger, const ArchSpec &arch,
-                          StackFrame &frame, Stream &strm);
+                          StackFrame &frame, Stream &strm, bool enable_rich_annotations = false);
 
   // Constructors and Destructors
   Disassembler(const ArchSpec &arch, const char *flavor);
@@ -456,7 +457,7 @@ class Disassembler : public std::enable_shared_from_this<Disassembler>,
                          const ExecutionContext &exe_ctx,
                          bool mixed_source_and_assembly,
                          uint32_t num_mixed_context_lines, uint32_t options,
-                         Stream &strm);
+                         Stream &strm, bool enable_rich_annotations = false);
 
   size_t ParseInstructions(Target &target, Address address, Limit limit,
                            Stream *error_strm_ptr,
diff --git a/lldb/include/lldb/Target/StackFrame.h b/lldb/include/lldb/Target/StackFrame.h
@@ -321,7 +321,8 @@ class StackFrame : public ExecutionContextScope,
   ///
   /// \return
   ///    C string with the assembly instructions for this function.
-  const char *Disassemble();
+  const char *Disassemble(bool enable_rich_annotations = false);
+
 
   /// Print a description of this frame using the provided frame format.
   ///
diff --git a/lldb/source/Commands/CommandObjectDisassemble.cpp b/lldb/source/Commands/CommandObjectDisassemble.cpp
@@ -154,6 +154,10 @@ Status CommandObjectDisassemble::CommandOptions::SetOptionValue(
     }
   } break;
 
+  case 'R': // --rich
+    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 =
@@ -550,7 +555,7 @@ void CommandObjectDisassemble::DoExecute(Args &command,
             cpu_string, features_string, m_exe_ctx, cur_range.GetBaseAddress(),
             limit, m_options.show_mixed,
             m_options.show_mixed ? m_options.num_lines_context : 0, options,
-            result.GetOutputStream())) {
+            result.GetOutputStream(), /*enable_rich_annotations=*/m_options.enable_rich_annotations)) {
       result.SetStatus(eReturnStatusSuccessFinishResult);
     } else {
       if (m_options.symbol_containing_addr != LLDB_INVALID_ADDRESS) {
diff --git a/lldb/source/Commands/CommandObjectDisassemble.h b/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);
diff --git a/lldb/source/Commands/Options.td b/lldb/source/Commands/Options.td
@@ -361,6 +361,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<"rich", "R">,
+    Desc<"Enable rich disassembly annotations for this invocation.">;
 }
 
 let Command = "diagnostics dump" in {
diff --git a/lldb/source/Core/Disassembler.cpp b/lldb/source/Core/Disassembler.cpp
@@ -175,7 +175,8 @@ bool Disassembler::Disassemble(Debugger &debugger, const ArchSpec &arch,
                                const Address &address, Limit limit,
                                bool mixed_source_and_assembly,
                                uint32_t num_mixed_context_lines,
-                               uint32_t options, Stream &strm) {
+                               uint32_t options, Stream &strm,
+                               bool enable_rich_annotations) {
   if (!exe_ctx.GetTargetPtr())
     return false;
 
@@ -191,8 +192,9 @@ bool Disassembler::Disassemble(Debugger &debugger, const ArchSpec &arch,
     return false;
 
   disasm_sp->PrintInstructions(debugger, arch, exe_ctx,
-                               mixed_source_and_assembly,
-                               num_mixed_context_lines, options, strm);
+                             mixed_source_and_assembly,
+                             num_mixed_context_lines, options, strm,
+                             /*enable_rich_annotations=*/enable_rich_annotations);
   return true;
 }
 
@@ -287,7 +289,8 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
                                      const ExecutionContext &exe_ctx,
                                      bool mixed_source_and_assembly,
                                      uint32_t num_mixed_context_lines,
-                                     uint32_t options, Stream &strm) {
+                                     uint32_t options, Stream &strm,
+                                     bool enable_rich_annotations) {
   // We got some things disassembled...
   size_t num_instructions_found = GetInstructionList().GetSize();
 
@@ -545,7 +548,8 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
           (options & eOptionShowControlFlowKind) != 0;
       inst->Dump(&strm, max_opcode_byte_size, true, show_bytes,
                  show_control_flow_kind, &exe_ctx, &sc, &prev_sc, nullptr,
-                 address_text_size);
+                 address_text_size,
+                 enable_rich_annotations);
       strm.EOL();
     } else {
       break;
@@ -554,7 +558,8 @@ void Disassembler::PrintInstructions(Debugger &debugger, const ArchSpec &arch,
 }
 
 bool Disassembler::Disassemble(Debugger &debugger, const ArchSpec &arch,
-                               StackFrame &frame, Stream &strm) {
+                               StackFrame &frame, Stream &strm,
+                               bool enable_rich_annotations) {
   constexpr const char *plugin_name = nullptr;
   constexpr const char *flavor = nullptr;
   constexpr const char *cpu = nullptr;
@@ -641,7 +646,8 @@ void Instruction::Dump(lldb_private::Stream *s, uint32_t max_opcode_byte_size,
                        const SymbolContext *sym_ctx,
                        const SymbolContext *prev_sym_ctx,
                        const FormatEntity::Entry *disassembly_addr_format,
-                       size_t max_address_text_size) {
+                       size_t max_address_text_size,
+                       bool enable_rich_annotations) {
   size_t opcode_column_width = 7;
   const size_t operand_column_width = 25;
 
@@ -801,7 +807,7 @@ void Instruction::Dump(lldb_private::Stream *s, uint32_t max_opcode_byte_size,
     frame->ChangePC(original_pc);
   };
 
-  if (exe_ctx && exe_ctx->GetFramePtr()) {
+  if (enable_rich_annotations && exe_ctx && exe_ctx->GetFramePtr()) {
     annotate_variables();
   }
 
diff --git a/lldb/source/Target/StackFrame.cpp b/lldb/source/Target/StackFrame.cpp
@@ -262,15 +262,22 @@ bool StackFrame::ChangePC(addr_t pc) {
   return true;
 }
 
-const char *StackFrame::Disassemble() {
+const char *StackFrame::Disassemble(bool enable_rich_annotations) {
   std::lock_guard<std::recursive_mutex> guard(m_mutex);
-  if (!m_disassembly.Empty())
-    return m_disassembly.GetData();
+
+  // Keep the existing cache only for the plain (non-rich) path.
+  if (!enable_rich_annotations) {
+    if (!m_disassembly.Empty())
+      return m_disassembly.GetData();
+  }
 
   ExecutionContext exe_ctx(shared_from_this());
   if (Target *target = exe_ctx.GetTargetPtr()) {
-    Disassembler::Disassemble(target->GetDebugger(), target->GetArchitecture(),
-                              *this, m_disassembly);
+    Disassembler::Disassemble(target->GetDebugger(),
+                              target->GetArchitecture(),
+                              *this,
+                              m_disassembly,
+                              /*enable_rich_annotations=*/enable_rich_annotations);
   }
 
   return m_disassembly.Empty() ? nullptr : m_disassembly.GetData();
diff --git a/lldb/test/API/functionalities/rich-disassembler/TestRichDisassembler.py b/lldb/test/API/functionalities/rich-disassembler/TestRichDisassembler.py
@@ -1,11 +1,12 @@
 from lldbsuite.test.lldbtest import *
 from lldbsuite.test.decorators import *
-
+import lldb
 
 class TestRichDisassembler(TestBase):
     def test_d_original_example_O1(self):
         """
-        Tests disassembler output for d_original_example.c built with -O1.
+        Tests disassembler output for d_original_example.c built with -O1,
+        using the CLI with --rich to enable annotations.
         """
         self.build(
             dictionary={"C_SOURCES": "d_original_example.c", "CFLAGS_EXTRAS": "-g -O1"}
@@ -14,20 +15,19 @@ def test_d_original_example_O1(self):
         target = self.dbg.CreateTarget(exe)
         self.assertTrue(target)
 
-        breakpoint = target.BreakpointCreateByName("main")
-        self.assertGreater(breakpoint.GetNumLocations(), 0)
+        bp = target.BreakpointCreateByName("main")
+        self.assertGreater(bp.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)
+        # Run the CLI command and read output from self.res
+        self.runCmd("disassemble --rich -f", check=True)
+        out = self.res.GetOutput()
+        print(out)
 
-        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)
+        self.assertIn("argc = ", out)
+        self.assertIn("argv = ", out)
+        self.assertIn("i = ", out)
+        self.assertNotIn("<decoding error>", out)

Original file line number	Diff line number	Diff line change
`@@ -361,6 +361,8 @@ let Command = "disassemble" in {`
`361`	`361`	`Desc<"Disassemble function containing this address.">;`
`362`	`362`	`def disassemble_options_force : Option<"force", "\\x01">, Groups<[2,3,4,5,7]>,`
`363`	`363`	`Desc<"Force disassembly of large functions.">;`
	`364`	`+ def disassemble_options_rich : Option<"rich", "R">,`
	`365`	`+ Desc<"Enable rich disassembly annotations for this invocation.">;`
`364`	`366`	`}`
`365`	`367`
`366`	`368`	`let Command = "diagnostics dump" in {`