[lldb-vscode] Add support for disassembly view

[eloparco]

Summary

Implement DAP (Debug Adapter Protocol) for Disassemble Requests.

[eloparco]

That's how it currently looks like:

[eloparco]

Avoid tracking stack frame boundaries. It is unnecessary and makes the disassembler functionality not work in multi-threaded programs.

[eloparco]

@JDevlieghere let me know if there's anything I can do to make the review easier

[clayborg]

Sorry for delay, I was on recharge for all of December.

[clayborg]

Sorry for delay, I was on recharge for all of December.

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

This will work if the min and max opcode byte size are the same, like for arm64, the min and max are 4. This won't work for x86 or arm32 in thumb mode. So when backing up, we need to do an address lookup on the address we think we want to go to, and then adjust the starting address accordingly. Something like:

SBAddress start_sbaddr = (base_addr - bytes_offset, g_vsc.target);

now we have a section offset address that can tell us more about what it is. We can find the SBFunction or SBSymbol for this address and use those to find the right instructions. This will allow us to correctly disassemble code bytes.

We can also look at the section that the memory comes from and see what the section contains. If the section is data, then emit something like:

0x00001000 .byte 0x23
0x00001001 .byte 0x34
...

To find the section type we can do:

SBSection section = start_sbaddr.GetSection();
if (section.IsValid() && section.GetSectionType() == lldb::eSectionTypeCode) {
 // Disassemble from a valid boundary
} else {
  // Emit a byte or long at a time with ".byte 0xXX" or other ASM directive for binary data
}

We need to ensure we start disassembling on the correct instruction boundary as well as our math for "start_addr" might be in between actual opcode boundaries. If we are in a lldb::eSectionTypeCode, then we know we have instructions, and if we are not, then we can emit ".byte" or other binary data directives. So if we do have lldb::eSectionTypeCode as our section type, then we should have a function or symbol, and we can get instructions from those objects easily:

if (section.IsValid() && section.GetSectionType() == lldb::eSectionTypeCode) {
 lldb::SBInstructionList instructions;
 lldb::SBFunction function = start_sbaddr.GetFunction();
 if (function.IsValid()) {
    instructions = function.GetInstructions(g_vsc.target);
 } else {
    symbol = start_sbaddr.GetSymbol();
    if (symbol.IsValid())
      instructions = symbol.GetInstructions(g_vsc.target);
}
const size_t num_instrs = instructions.GetSize();
if (num_instrs > 0) {
  // we found instructions from a function or symbol and we need to 
  // find the matching instruction that we want to start from by iterating
  // over the instructions and finding the right address
  size_t matching_idx = num_instrs; // Invalid index
  for (size_t i=0; i<num_instrs; ++i) {
    lldb::SBInstruction inst = instructions.GetInstructionAtIndex(i);
    if (inst.GetAddress().GetLoadAddress(g_vsc.target) >= start_addr) {
      matching_idx = i;
      break;
    }
  }
  if (matching_idx < num_instrs) {
    // Now we can print the instructions from [matching_idx, num_instrs)
    // then we need to repeat the search for the next function or symbol. 
    // note there may be bytes between functions or symbols which we can disassemble
    // by calling _get_instructions_from_memory(...) but we must find the next
    // symbol or function boundary and get back on track
  }

2194

Remove any and all printf, or fprintf statements. You can't print anything to stderr or stdout as this is where the DAP packets are get emitted to. We do make it so this won't affect lldb-vscode by doing some magic with the STDOUT/STDERR file handles, but this output will be sent to /dev/null most likely. You can print something to a console (using "g_vsc.SendOutput(...)" is one way).

2244

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

Sorry, I should have provided a proper explanation.

I use the maximum instruction size as the "worst case". Basically, I need to read a portion of memory but I do not know the start address and the size. For the start address, if I want to read N instructions before base_addr I need to read at least starting from base_addr - N * max_instruction_size: if all instructions are of size max_instruction_size I will read exactly N instructions; otherwise I will read more than N instructions and prune the additional ones afterwards. Same for applies for the size.

Since start_addr is based on a "worst case", it may be an address in the middle of an instruction. In that case, that first instruction will be misinterpreted, but I think that is negligible.

The logic is similar to what is implemented in other VS Code extensions, like https://github.com/vadimcn/vscode-lldb/blob/master/adapter/src/debug_session.rs#L1134.

Does it make sense?

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2194

I suppose I have to replace llvm::errs() too, right?

[eloparco]

Remove printf usage

[eloparco]

Add integration tests for disassemble request

[eloparco]

Add integration tests for disassemble request

[clayborg]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

The issue is, you might end up backing up by N bytes, and you might not end up on an opcode boundary. Lets say you have x86 disassembly like:

0x100002e37 <+183>: 48 8b 4d f8              movq   -0x8(%rbp), %rcx
0x100002e3b <+187>: 48 39 c8                 cmpq   %rcx, %rax
0x100002e3e <+190>: 0f 85 09 00 00 00        jne    0x100002e4d               ; <+205> at main.cpp
0x100002e44 <+196>: 8b 45 94                 movl   -0x6c(%rbp), %eax
0x100002e47 <+199>: 48 83 c4 70              addq   $0x70, %rsp
0x100002e4b <+203>: 5d                       popq   %rbp
0x100002e4c <+204>: c3                       retq   
0x100002e4d <+205>: e8 7e 0f 00 00           callq  0x100003dd0               ; symbol stub for: __stack_chk_fail
0x100002e52 <+210>: 0f 0b                    ud2

Let's say you started with the address 0x100002e4c, and backed up by the max opcode size of 15 for x86_64, that would be 0x100002e3d. You would start disassembling on a non opcode boundary as this is the last byte of the 3 byte opcode at 0x100002e3b (0xc8). And this would disassembly incorrectly. So we need to make use of the functions or symbol boundaries to ensure we are disassembling correctly. If we have no function or symbol, we can do our best. But as you can see we would get things completely wrong in this case and we need to fix this as detailed.

2194

yes! the main issue is, will the user expect to see this output in the console and will it make sense to the user. I don't know what the user will think if they see "current line not found in disassembled instructions" in the debug console. That goes for all output to the console. It will have to make sense to the user. I don't know if the user will care and or be able to do anything about this message. It also isn't prefixed with a "warning:" or "error:". I would vote to remove it.

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

Actually, I was mislead by the fact that so far I tried on both:

• my ARM machine, with instructions of fixed size (4)
• with WAMR disassembling to WASM, where, when the start address is in the middle of an instruction, only that first instruction is misinterpreted

Without going into sections and symbols as you were proposing, the solution can be as easy as done in this VS Code Extension: https://github.com/vadimcn/vscode-lldb/commit/28ae4f4bf3bd29a0c84dd586cd5360836210ab51.

I'll update the code and put some additional comments to clarify the logic. Let me know what you think.

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2194

Right, it is just a print to debug, is there anything else I can use for that purpose?
Otherwise I'll just get rid of it as you were saying.

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2194

Probably better to remove it rather than prefixing the message with "debug"

[eloparco]

Fix disassemble on variable-length instructions and disassemble with positive offset

[jingham]

I haven't followed the lldb-vscode codebase closely enough to have useful comments on that part of the code.

But so far as I can tell, you didn't add a test for SBTarget::GetMaximumOpcodeByteSize, so you should add that before this goes in. Maybe it was folded into the lldb-vscode tests and I missed it, but even so this should have a direct test; I don't think we should require people to build lldb-vscode to test general features of lldb.

[eloparco]

Add binding and test for SBTarget::GetMaximumOpcodeByteSize()

[eloparco]

@jingham I added the test that was missing

[jingham]

That looks fine. I'm removing my objection, but that's just to the SB API parts, I'm not commenting on the vscode part.

[clayborg]

Are you planning on updating the reverse disassembly code still on this patch?

lldb/include/lldb/API/SBTarget.h

844

Do we still need this API change with the new approach? We can't really use this unless we include GetMinimumOpcodeByteSize() and only use this value to backup if the min and max are the same.

lldb/tools/lldb-vscode/lldb-vscode.cpp

2183–2194

Use C++ comments instead of C style comments.

[eloparco]

In D140358#4045210, @clayborg wrote:

Are you planning on updating the reverse disassembly code still on this patch?

What do you mean by "reverse disassembly"?

[clayborg]

In D140358#4045442, @eloparco wrote:

In D140358#4045210, @clayborg wrote:

Are you planning on updating the reverse disassembly code still on this patch?

What do you mean by "reverse disassembly"?

I mean when we try and back up by some offset.

[eloparco]

lldb/include/lldb/API/SBTarget.h

844

In principle we could assume a maximum opcode of size 16 in the calculation, but knowing the maximum actually supported by the architecture can save us from reading unnecessary chunks of memory. In this way, we avoid reading instructions that will then be discarded because resulting in more than instructionCount total instructions.

[eloparco]

In D140358#4045450, @clayborg wrote:

In D140358#4045442, @eloparco wrote:

In D140358#4045210, @clayborg wrote:

Are you planning on updating the reverse disassembly code still on this patch?

What do you mean by "reverse disassembly"?

I mean when we try and back up by some offset.

Sorry, still not clear. So probably not intended for this patch :)

[eloparco]

Use single-line comments

[eloparco]

In D140358#4045469, @eloparco wrote:

In D140358#4045450, @clayborg wrote:

In D140358#4045442, @eloparco wrote:

In D140358#4045210, @clayborg wrote:

Are you planning on updating the reverse disassembly code still on this patch?

What do you mean by "reverse disassembly"?

I mean when we try and back up by some offset.

Sorry, still not clear. So probably not intended for this patch :)

If you mean setting breakpoints and stepping through disassembled instructions, that's outside the purpose of this initial patch

[clayborg]

I mean we can not just subtract something, any number, from any address unless we have fixed size opcodes. If we do this for x86, you can get complete garbage with no hope of ever getting back on track and this disassembly just won't make sense at all and will be useless. I thought my x86 example spelled out why it is bad to backup. If we start disassembling in the middle of an opcode, we can attempt to disassemble immediate values that are encoded into the middle of an opcode. Since x86 instructions can be 1 byte to 15 bytes, we might disassembly garbage and never align up to real opcodes.

So I see a few solutions:

• use functions and symbols to get actual boundaries, and use sections to detect when there are instruction (code) and not
• check if min and max opcode sizes are the same and only try to backup if they are the same, but still use sections to disassembly data as .byte or .long directives

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

Actually, I was mislead by the fact that so far I tried on both:

• my ARM machine, with instructions of fixed size (4)
• with WAMR disassembling to WASM, where, when the start address is in the middle of an instruction, only that first instruction is misinterpreted

Without going into sections and symbols as you were proposing, the solution can be as easy as done in this VS Code Extension: https://github.com/vadimcn/vscode-lldb/commit/28ae4f4bf3bd29a0c84dd586cd5360836210ab51.

I'll update the code and put some additional comments to clarify the logic. Let me know what you think.

2177

@clayborg what I wrote in the comment before this one is what I implemented (Diff 6), do you think that is not enough? I'll try it on a x86 linux machine to make sure it works there

[clayborg]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

Just checked out your changes, and you are still just subtracting a value from the start address and attempting to disassemble from memory which is the problem. We need to take that subtracted address, and look it up as suggested in previous code examples I posted. If you find a function to symbol, ask those objects for their instructions. and then try to use those.

But basically for _any_ disassembly this is what I would recommend doing:

• first resolve the "start_address" (no matter how you come up the address) that want to disassemble into a SBAddress
• check its section. If the section is valid and contains instructions, call a function that will disassemble the address range for the section that starts at "start_address" and ends at the end of the section. We can call this "disassemble_code" as a function. More details on this below
• If the section does not contain instructions, just read the bytes and emit a lines like:

0x1000 .byte 0x12
0x1000 .byte 0x34
...

Now for the disassemble_code function. We know the address range for this is in code. We then need to resolve the address passed to "disassemble_code" into a SBAddress and ask that address for a SBFunction or SBSymbol as I mentioned. Then we ask the SBFunction or SBSymbol for all instructions that they contain, and then use any instructions that fall into the range we have. If there is no SBFunction or SBSymbol, then disassemble an instruction at a time and then see if the new address will resolve to a function or symbol.

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

Tried my changes on a linux x86 machine and the loop for (unsigned i = 0; i < max_instruction_size; i++) { (L2190) takes care of the start_address possibly being in the middle of an instruction, so that's not a problem. The problem I faced is that it tries to read too far from base_addr and the ReadMemory() operation returns few instructions (without reaching base_addr). That was not happening on my macOS M1 (arm) machine.

To solve, I changed the loop at L2190 to

for (unsigned i = 0; i < bytes_offset; i++) {
    auto sb_instructions =
        _get_instructions_from_memory(start_addr + i, disassemble_bytes);

and if start_addr is in sb_instructions we're done and can exit the loop. That worked.

Another similar thing that can be done is to start from start_sbaddr as you were saying, increment the address until a valid section is found. Then call _get_instructions_from_memory() passing the section start.
What do you think? Delegating the disassembling to ReadMemory() + GetInstructions() looks simpler to me than to manually iterate over sections and get instructions from symbols and functions.
Is there any shortcoming I'm not seeing?

[clayborg]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

so your

for (unsigned i = 0; i < max_instruction_size; i++) {

disassembles and tries to make sure you make it back to the original base address from the original disassemble packet? That can work but could a a bit time consuming?

The main issue, as you saw on x86, is you don't know what is in memory. You could have unreadable areas of memory when trying to disassemble. Also if you do have good memory that does contain instructions, there can be padding in between functions or even data between functions that the function accesses that can't be correctly disassembled and could throw things off again.

The memory regions are the safest way to traverse memory to see what you have and would help you deal with holes in the memory. You can ask about a memory region with:

lldb::SBError SBProcess::GetMemoryRegionInfo(lldb::addr_t load_addr, lldb::SBMemoryRegionInfo &region_info);

If you ask about an invalid address, like zero on most platforms, it will return a valid "region_info" with the bounds of the unreadable address range filled in no read/write/execute permissions:

(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> region = lldb.SBMemoryRegionInfo()
>>> err = lldb.process.GetMemoryRegionInfo(0, region)
[0x0000000000000000-0x0000000100000000 ---]

So you could use the memory region info to your advantage here. If you have execute permissions, disassemble as instructions, and if you don't emit ".byte 0xXX" for each byte. If there are no permissions, you can emit some other string like "0x00000000: <invalid memory>".

That being said, even when you do find an executable section of memory, there can be different stuff there even if a section _is_ executable. For instance, if we ask about the next memory region on a mac M1:

>>> err = lldb.process.GetMemoryRegionInfo(0x0000000100000000, region)
>>> print(region)
[0x0000000100000000-0x0000000100004000 R-X]

Notice that this is read + execute (you can access these via:

region.IsReadable()
region.IsWritable()
region.IsExecutable()

But at this address, this is the mach-o header which doesn't make sense to try and disassemble:

(lldb) memory read 0x0000000100000000
0x100000000: cf fa ed fe 0c 00 00 01 00 00 00 00 02 00 00 00  ................
0x100000010: 11 00 00 00 18 03 00 00 85 00 20 00 00 00 00 00  .......... .....
(lldb) memory read -fx -s4 -c 4 0x0000000100000000
0x100000000: 0xfeedfacf 0x0100000c 0x00000000 0x00000002

0xfeedfacf is the mach-o magic bytes for little endian 64 bit mach-o files.

(lldb) disassemble --start-address 0x0000000100000000
a.out`_mh_execute_header:
    0x100000000 <+0>:  .long  0xfeedfacf                ; unknown opcode
    0x100000004 <+4>:  .long  0x0100000c                ; unknown opcode
    0x100000008 <+8>:  udf    #0x0
    0x10000000c <+12>: udf    #0x2
    0x100000010 <+16>: udf    #0x11
    0x100000014 <+20>: udf    #0x318
    0x100000018 <+24>: .long  0x00200085                ; unknown opcode
    0x10000001c <+28>: udf    #0x0

So this is the main reason why I would suggest just disassembling using .byte or .long when we aren't in a function or symbol.

[eloparco]

lldb/tools/lldb-vscode/lldb-vscode.cpp

2177

understood, so in that case we also have to do the same for _handle_disassemble_positive_offset, because even there, when we use ReadInstructions(), we could have some unreadable areas in the middle and ReadInstructions() would stop prematurely when running into one of them, resulting in less instructions returned than expected

lldb/bindings/interface/SBTarget.i

#endif
     FindSymbols (const char *name, lldb::SymbolType type = eSymbolTypeAny);
 
     bool
     GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level);
 
     lldb::addr_t
     GetStackRedZoneSize();
 
+    uint32_t
+    GetMaximumOpcodeByteSize() const;
+
     %feature("docstring", "
     Returns true if the module has been loaded in this `SBTarget`.
     A module can be loaded either by the dynamic loader or by being manually
     added to the target (see `SBTarget.AddModule` and the ``target module add`` command).
 
     :rtype: bool
     ") IsLoaded;
     bool

lldb/include/lldb/API/SBTarget.h

public:
 
   lldb::SBValue EvaluateExpression(const char *expr);
 
   lldb::SBValue EvaluateExpression(const char *expr,
                                    const SBExpressionOptions &options);
 
   lldb::addr_t GetStackRedZoneSize();
 
+  uint32_t GetMaximumOpcodeByteSize() const;
+
   bool IsLoaded(const lldb::SBModule &module) const;
 
   lldb::SBLaunchInfo GetLaunchInfo() const;
 
   void SetLaunchInfo(const lldb::SBLaunchInfo &launch_info);
 
   /// Get a \a SBTrace object the can manage the processor trace information of
   /// this target.

lldb/packages/Python/lldbsuite/test/tools/lldb-vscode/vscode.py

def request_testGetTargetBreakpoints(self):
         '''
         command_dict = {
             'command': '_testGetTargetBreakpoints',
             'type': 'request',
             'arguments': {}
         }
         return self.send_recv(command_dict)
 
+    def request_disassemble(self, memoryReference, instructionOffset, instructionCount):
+        args_dict = {
+            'memoryReference': memoryReference,
+            'instructionOffset': instructionOffset,
+            'instructionCount': instructionCount,
+        }
+        command_dict = {
+            'command': 'disassemble',
+            'type': 'request',
+            'arguments': args_dict
+        }
+        return self.send_recv(command_dict)
+
     def terminate(self):
         self.send.close()
         # self.recv.close()
 
 
 class DebugAdaptor(DebugCommunication):
     def __init__(self, executable=None, port=None, init_commands=[], log_file=None, env=None):
         self.process = None

lldb/source/API/SBTarget.cpp

if (addr_ptr) {
           target_sp->GetArchitecture(), nullptr, flavor_string, *addr_ptr,
           data.GetBytes(), bytes_read, count, data_from_file));
     }
   }
 
   return sb_instructions;
 }
 
+uint32_t SBTarget::GetMaximumOpcodeByteSize() const {
+  LLDB_INSTRUMENT_VA(this);
+
+  TargetSP target_sp(GetSP());
+  if (target_sp) 
+    return target_sp->GetArchitecture().GetMaximumOpcodeByteSize();
+    
+  return 0;
+}
+
 lldb::SBInstructionList SBTarget::GetInstructions(lldb::SBAddress base_addr,
                                                   const void *buf,
                                                   size_t size) {
   LLDB_INSTRUMENT_VA(this, base_addr, buf, size);
 
   return GetInstructionsWithFlavor(base_addr, nullptr, buf, size);
 }
 

lldb/test/API/python_api/target/TestTargetAPI.py

def test_is_loaded(self):
 
         process = target.LaunchSimple(None, None,
                                       self.get_process_working_directory())
 
         for i in range(num_modules):
             module = target.GetModuleAtIndex(i)
             self.assertTrue(target.IsLoaded(module), "Running the target should "
                             "have loaded its modules.")
+
+    def test_get_max_opcode_byte_size(self):
+        """Exercise SBTarget.GetMaximumOpcodeByteSize() API."""
+
+        d = {'EXE': 'b.out'}
+        self.build(dictionary=d)
+        self.setTearDownCleanup(dictionary=d)
+        target = self.create_simple_target('b.out')
+
+        maxOpcodeByteSize = target.GetMaximumOpcodeByteSize()
+        self.assertTrue(maxOpcodeByteSize > 0 and maxOpcodeByteSize < 16)

lldb/test/API/tools/lldb-vscode/disassemble/Makefile

+CXX_SOURCES := main.cpp
+
+include Makefile.rules
 No newline at end of file

lldb/test/API/tools/lldb-vscode/disassemble/TestVSCode_disassemble.py

+"""
+Test lldb-vscode disassemble request
+"""
+
+
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+import lldbvscode_testcase
+
+
+class TestVSCode_disassemble(lldbvscode_testcase.VSCodeTestCaseBase):
+    def setUp(self):
+        lldbvscode_testcase.VSCodeTestCaseBase.setUp(self)
+
+        program = self.getBuildArtifact("a.out")
+        self.build_and_launch(program)
+        source = "main.cpp"
+
+        breakpoint_line = line_number(source, "// breakpoint")
+        breakpoint_ids = self.set_source_breakpoints(source, [breakpoint_line])
+        self.continue_to_breakpoints(breakpoint_ids)
+
+    @skipIfWindows
+    @skipIfRemote
+    def test_disassemble_negative_offset(self):
+        # Retrieve program counter
+        stackFrames, _ = self.get_stackFrames_and_totalFramesCount()
+        pc = stackFrames[0]["instructionPointerReference"]
+
+        # Get disassembled instructions
+        num_instructions, offset = 8, -4
+        response = self.vscode.request_disassemble(
+            memoryReference=pc,
+            instructionOffset=offset,
+            instructionCount=num_instructions,
+        )
+        self.assertTrue(response["success"])
+
+        disas_instructions = response["body"]["instructions"]
+        self.assertEquals(len(disas_instructions), num_instructions)
+        self.assertEquals(disas_instructions[num_instructions + offset]["address"], pc)
+        for instr in disas_instructions:
+            self.assertTrue("invalid" not in instr["instruction"])
+
+    @skipIfWindows
+    @skipIfRemote
+    def test_disassemble_zero_offset(self):
+        # Retrieve program counter
+        stackFrames, _ = self.get_stackFrames_and_totalFramesCount()
+        pc = stackFrames[0]["instructionPointerReference"]
+
+        # Get disassembled instructions
+        num_instructions, offset = 4, 0
+        response = self.vscode.request_disassemble(
+            memoryReference=pc,
+            instructionOffset=offset,
+            instructionCount=num_instructions,
+        )
+        self.assertTrue(response["success"])
+
+        disas_instructions = response["body"]["instructions"]
+        self.assertEquals(len(disas_instructions), num_instructions)
+        self.assertEquals(disas_instructions[offset]["address"], pc)
+        for instr in disas_instructions:
+            self.assertTrue("invalid" not in instr["instruction"])
+
+    @skipIfWindows
+    @skipIfRemote
+    def test_disassemble_positive_offset(self):
+        # Retrieve program counter
+        stackFrames, _ = self.get_stackFrames_and_totalFramesCount()
+        pc = stackFrames[0]["instructionPointerReference"]
+
+        # Get disassembled instructions
+        num_instructions, offset = 4, 2
+        response = self.vscode.request_disassemble(
+            memoryReference=pc,
+            instructionOffset=offset,
+            instructionCount=num_instructions,
+        )
+        self.assertTrue(response["success"])
+
+        disas_instructions = response["body"]["instructions"]
+        self.assertEquals(len(disas_instructions), num_instructions)
+        for instr in disas_instructions:
+            self.assertTrue("invalid" not in instr["instruction"])
+
+    @skipIfWindows
+    @skipIfRemote
+    def test_disassemble_invalid_address(self):
+        response = self.vscode.request_disassemble(
+            memoryReference="0x0",
+            instructionOffset=-200,
+            instructionCount=400,
+        )
+        self.assertFalse(response["success"])

lldb/test/API/tools/lldb-vscode/disassemble/main.cpp

+int add(int x, int y) { return x + y; }
+
+int main() {
+  int sum = add(2, 3); // breakpoint
+  sum++;
+
+  return sum;
+}
 No newline at end of file

lldb/tools/lldb-vscode/CMakeLists.txt

 # not re-export those.
 set(LLVM_LINK_COMPONENTS Support)
 set(LLVM_TARGET_DEFINITIONS Options.td)
 tablegen(LLVM Options.inc -gen-opt-parser-defs)
 add_public_tablegen_target(LLDBVSCodeOptionsTableGen)
 add_lldb_tool(lldb-vscode
   lldb-vscode.cpp
   BreakpointBase.cpp
+  DisassembledInstruction.cpp
   ExceptionBreakpoint.cpp
   FifoFiles.cpp
   FunctionBreakpoint.cpp
   IOStream.cpp
   JSONUtils.cpp
   LLDBUtils.cpp
   OutputRedirector.cpp
   ProgressEvent.cpp

lldb/tools/lldb-vscode/DisassembledInstruction.h

+#ifndef LLDB_TOOLS_LLDB_VSCODE_DISASSEMBLED_INSTRUCTION_H
+#define LLDB_TOOLS_LLDB_VSCODE_DISASSEMBLED_INSTRUCTION_H
+
+#include "VSCodeForward.h"
+#include <string>
+
+namespace lldb_vscode {
+
+struct DisassembledInstruction {
+  std::string m_address;
+  std::string m_instruction;
+
+  DisassembledInstruction();
+  DisassembledInstruction(lldb::SBInstruction &inst);
+};
+
+} // namespace lldb_vscode
+
+#endif // LLDB_TOOLS_LLDB_VSCODE_DISASSEMBLED_INSTRUCTION_H
 No newline at end of file

lldb/tools/lldb-vscode/DisassembledInstruction.cpp

+#include "DisassembledInstruction.h"
+
+#include "LLDBUtils.h"
+#include "VSCode.h"
+#include "lldb/API/SBInstruction.h"
+
+namespace lldb_vscode {
+
+DisassembledInstruction::DisassembledInstruction()
+    : m_address("0x0000000000000000"), m_instruction("<invalid>") {}
+
+DisassembledInstruction::DisassembledInstruction(lldb::SBInstruction &inst) {
+  const auto inst_addr = inst.GetAddress().GetLoadAddress(g_vsc.target);
+  const char *m = inst.GetMnemonic(g_vsc.target);
+  const char *o = inst.GetOperands(g_vsc.target);
+  const char *c = inst.GetComment(g_vsc.target);
+
+  std::string line;
+  llvm::raw_string_ostream line_strm(line);
+  const auto comment_sep = (c == nullptr || std::string(c) == "") ? "" : "  ; ";
+  line_strm << llvm::formatv("{0,12} {1}{2}{3}", m, o, comment_sep, c);
+
+  m_address = addr_to_hex_string(inst_addr);
+  m_instruction = line_strm.str();
+}
+
+} // namespace lldb_vscode
 No newline at end of file

lldb/tools/lldb-vscode/JSONUtils.h

 ///
 /// This function will fill in the following keys in the returned
 /// object:
 ///   "id" - the stack frame ID as an integer
 ///   "name" - the function name as a string
 ///   "source" - source file information as a "Source" VSCode object
 ///   "line" - the source file line number as an integer
 ///   "column" - the source file column number as an integer
+///   "instructionPointerReference" - a memory reference for the current
+///                                   instruction pointer in this frame
 ///
 /// \param[in] frame
 ///     The LLDB stack frame to use when populating out the "StackFrame"
 ///     object.
 ///
 /// \return
 ///     A "StackFrame" JSON object with that follows the formal JSON
 ///     definition outlined by Microsoft.

 ///
 /// \return
 ///     A "Variable" JSON object with that follows the formal JSON
 ///     definition outlined by Microsoft.
 llvm::json::Value CreateVariable(lldb::SBValue v, int64_t variablesReference,
                                  int64_t varID, bool format_hex,
                                  bool is_name_duplicated = false);
 
+/// Create a "DisassembledInstruction" object for a LLDB disassembled
+/// instruction object.
+///
+/// This function will fill in the following keys in the returned
+/// object:
+///   "address" - the address of the instruction
+///   "instruction" - the text representing the instruction and its operands
+///
+/// \param[in] instruction
+///     The LLDB disassembled instruction to use when populating out the
+///     "DisassembledInstruction" object.
+///
+/// \return
+///     A "DisassembledInstruction" JSON object with that follows the formal
+///     JSON definition outlined by Microsoft.
+llvm::json::Value
+CreateDisassembledInstruction(DisassembledInstruction instruction);
+
 llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit);
 
 /// Create a runInTerminal reverse request object
 ///
 /// \param[in] launch_request
 ///     The original launch_request object whose fields are used to construct
 ///     the reverse request object.
 ///

lldb/tools/lldb-vscode/JSONUtils.cpp

if (disasm_line > 0) {
     object.try_emplace("line", disasm_line);
   } else {
     auto line = line_entry.GetLine();
     if (line == UINT32_MAX)
       line = 0;
     object.try_emplace("line", line);
   }
   object.try_emplace("column", line_entry.GetColumn());
+
+  auto pc = addr_to_hex_string(frame.GetPC());
+  object.try_emplace("instructionPointerReference", pc);
   return llvm::json::Value(std::move(object));
 }
 
 // "Thread": {
 //   "type": "object",
 //   "description": "A Thread",
 //   "properties": {
 //     "id": {
llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit) {
   llvm::json::Object object;
   char unit_path_arr[PATH_MAX];
   unit.GetFileSpec().GetPath(unit_path_arr, sizeof(unit_path_arr));
   std::string unit_path(unit_path_arr);
   object.try_emplace("compileUnitPath", unit_path);
   return llvm::json::Value(std::move(object));
 }
 
+llvm::json::Value
+CreateDisassembledInstruction(DisassembledInstruction instruction) {
+  llvm::json::Object object;
+  EmplaceSafeString(object, "address", instruction.m_address);
+  EmplaceSafeString(object, "instruction", instruction.m_instruction);
+  return llvm::json::Value(std::move(object));
+}
+
 /// See
 /// https://microsoft.github.io/debug-adapter-protocol/specification#Reverse_Requests_RunInTerminal
 llvm::json::Object
 CreateRunInTerminalReverseRequest(const llvm::json::Object &launch_request,
                                   llvm::StringRef debug_adaptor_path,
                                   llvm::StringRef comm_file) {
   llvm::json::Object reverse_request;
   reverse_request.try_emplace("type", "request");

lldb/tools/lldb-vscode/LLDBUtils.h

 //===-- LLDBUtils.h ---------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_TOOLS_LLDB_VSCODE_LLDBUTILS_H
 #define LLDB_TOOLS_LLDB_VSCODE_LLDBUTILS_H
 
 #include "VSCodeForward.h"
+#include "lldb/lldb-types.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/raw_ostream.h"
 #include <string>
 #include <vector>
 
 namespace lldb_vscode {
 

 ///
 /// \param[in] dap_frame_id
 ///     The VSCode frame ID to convert to a frame ID.
 ///
 /// \return
 ///     The LLDB frame index ID.
 uint32_t GetLLDBFrameID(uint64_t dap_frame_id);
 
+/// Given an address, convert it to its hexadecimal representation.
+///
+/// \param[in] address
+///     The address to convert.
+///
+/// \return
+///     The hexadecimal representation of the address.
+std::string addr_to_hex_string(const lldb::addr_t address);
+
+/// Given an hexadecimal representation of an address, convert it to a number.
+///
+/// Reverse of `addr_to_hex_string()`.
+///
+/// \param[in] hex_address
+///     The hexadecimal address to convert.
+///
+/// \return
+///     The decimal representation of the hex address.
+lldb::addr_t
+hex_string_to_addr(const std::optional<llvm::StringRef> hex_address);
+
 } // namespace lldb_vscode
 
 #endif

lldb/tools/lldb-vscode/LLDBUtils.cpp

uint32_t GetLLDBFrameID(uint64_t dap_frame_id) {
   return dap_frame_id & ((1u << THREAD_INDEX_SHIFT) - 1);
 }
 
 int64_t MakeVSCodeFrameID(lldb::SBFrame &frame) {
   return (int64_t)(frame.GetThread().GetIndexID() << THREAD_INDEX_SHIFT |
                    frame.GetFrameID());
 }
 
+std::string addr_to_hex_string(const lldb::addr_t address) {
+  return "0x" + llvm::utohexstr(address, true);
+}
+
+lldb::addr_t
+hex_string_to_addr(const std::optional<llvm::StringRef> hex_address) {
+  return std::stoull(hex_address->data(), nullptr, 16);
+}
+
 } // namespace lldb_vscode

lldb/tools/lldb-vscode/VSCode.h

 #include "lldb/API/SBLineEntry.h"
 #include "lldb/API/SBListener.h"
 #include "lldb/API/SBProcess.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBTarget.h"
 #include "lldb/API/SBThread.h"
 
+#include "DisassembledInstruction.h"
 #include "ExceptionBreakpoint.h"
 #include "FunctionBreakpoint.h"
 #include "IOStream.h"
 #include "ProgressEvent.h"
 #include "RunInTerminal.h"
 #include "SourceBreakpoint.h"
 #include "SourceReference.h"
 

lldb/tools/lldb-vscode/VSCodeForward.h

 #define LLDB_TOOLS_LLDB_VSCODE_VSCODEFORWARD_H
 
 namespace lldb_vscode {
 struct BreakpointBase;
 struct ExceptionBreakpoint;
 struct FunctionBreakpoint;
 struct SourceBreakpoint;
 struct SourceReference;
+struct DisassembledInstruction;
 } // namespace lldb_vscode
 
 namespace lldb {
 class SBAttachInfo;
 class SBBreakpoint;
 class SBBreakpointLocation;
 class SBCommandInterpreter;
 class SBCommandReturnObject;

lldb/tools/lldb-vscode/lldb-vscode.cpp

void request_initialize(const llvm::json::Object &request) {
   };
 
   auto arguments = request.getObject("arguments");
   // sourceInitFile option is not from formal DAP specification. It is only
   // used by unit tests to prevent sourcing .lldbinit files from environment
   // which may affect the outcome of tests.
   bool source_init_file = GetBoolean(arguments, "sourceInitFile", true);
 
-  g_vsc.debugger =
-      lldb::SBDebugger::Create(source_init_file, log_cb, nullptr);
+  g_vsc.debugger = lldb::SBDebugger::Create(source_init_file, log_cb, nullptr);
   g_vsc.progress_event_thread = std::thread(ProgressEventThreadFunction);
 
   // Start our event thread so we can receive events from the debugger, target,
   // process and more.
   g_vsc.event_thread = std::thread(EventThreadFunction);
 
   llvm::json::Object response;
   FillResponse(request, response);
void request_initialize(const llvm::json::Object &request) {
   body.try_emplace("supportsDelayedStackTraceLoading", true);
   // The debug adapter supports the 'loadedSources' request.
   body.try_emplace("supportsLoadedSourcesRequest", false);
   // The debug adapter supports sending progress reporting events.
   body.try_emplace("supportsProgressReporting", true);
   // The debug adapter supports 'logMessage' in breakpoint.
   body.try_emplace("supportsLogPoints", true);
 
+  body.try_emplace("supportsDisassembleRequest", true);
+
   response.try_emplace("body", std::move(body));
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));
 }
 
 llvm::Error request_runInTerminal(const llvm::json::Object &launch_request) {
   g_vsc.is_attach = true;
   lldb::SBAttachInfo attach_info;
 
void request_setBreakpoints(const llvm::json::Object &request) {
   }
 
   llvm::json::Object body;
   body.try_emplace("breakpoints", std::move(response_breakpoints));
   response.try_emplace("body", std::move(body));
   g_vsc.SendJSON(llvm::json::Value(std::move(response)));
 }
 
+std::vector<lldb::SBInstruction>
+_get_instructions_from_memory(lldb::addr_t start, uint64_t count) {
+  lldb::SBProcess process = g_vsc.target.GetProcess();
+
+  lldb::SBError error;
+  std::vector<uint8_t> buffer(count, 0);
+  const size_t bytes_read __attribute__((unused)) = process.ReadMemory(
+      start, static_cast<void *>(buffer.data()), count, error);
+  assert(bytes_read == count && error.Success() &&
+         "unable to read byte range from memory");
+
+  // If base_addr starts in the middle of an instruction,
+  // that first instruction will not be parsed correctly (negligible)
+  std::vector<lldb::SBInstruction> sb_instructions;
+  const auto base_addr = lldb::SBAddress(start, g_vsc.target);
+  lldb::SBInstructionList instructions =
+      g_vsc.target.GetInstructions(base_addr, buffer.data(), count);
+
+  for (size_t i = 0; i < instructions.GetSize(); i++) {
+    auto instr = instructions.GetInstructionAtIndex(i);
+    sb_instructions.emplace_back(instr);
+  }
+  return sb_instructions;
+}
+
+auto _handle_disassemble_positive_offset(lldb::addr_t base_addr,
+                                         int64_t instruction_offset,
+                                         uint64_t instruction_count) {
+  llvm::json::Array response_instructions;
+
+  // For positive offsets, we use the `ReadInstructions()` API to get
+  // `instruction_offset + instruction_count` instructions after the
+  // `base_addr`.
+  auto start_addr = lldb::SBAddress(base_addr, g_vsc.target);
+  lldb::SBInstructionList instructions = g_vsc.target.ReadInstructions(
+      start_addr, instruction_offset + instruction_count);
+
+  const auto num_instrs_to_skip = static_cast<size_t>(instruction_offset);
+  for (size_t i = num_instrs_to_skip; i < instructions.GetSize(); ++i) {
+    lldb::SBInstruction instr = instructions.GetInstructionAtIndex(i);
+
+    auto disass_instr =
+        CreateDisassembledInstruction(DisassembledInstruction(instr));
+    response_instructions.emplace_back(std::move(disass_instr));
+  }
+
+  return response_instructions;
+}
+
+auto _handle_disassemble_negative_offset(
+    lldb::addr_t base_addr, int64_t instruction_offset,
+    uint64_t instruction_count,
+    std::optional<llvm::StringRef> memory_reference) {
+  llvm::json::Array response_instructions;
+
+  const auto max_instruction_size = g_vsc.target.GetMaximumOpcodeByteSize();
+  const auto bytes_offset = -instruction_offset * max_instruction_size;
+  auto start_addr = base_addr - bytes_offset;
+  const auto disassemble_bytes = instruction_count * max_instruction_size;
+
+  // For negative offsets, we do not know what `start_addr` corresponds to the
+  // instruction located `instruction_offset` instructions before `base_addr`
+  // since on some architectures opcodes have variable length.
+  // To address that, we need to read at least starting from `start_addr =
+  // base_addr + instruction_offset * max_instruction_size` (pruning is done if
+  // more than `instruction_count` instructions are fetched) and ensure we start
+  // disassembling on the correct instruction boundary since `start_addr` might
+  // be in between opcode boundaries. To address the latter concern, we use the
+  // following loop.
+  for (unsigned i = 0; i < max_instruction_size; i++) {
+    auto sb_instructions =
+        _get_instructions_from_memory(start_addr - i, disassemble_bytes);
+
+    // Find position of requested instruction
+    // in retrieved disassembled instructions
+    auto index = sb_instructions.size() + 1;
+    for (size_t i = 0; i < sb_instructions.size(); i++) {
+      if (sb_instructions[i].GetAddress().GetLoadAddress(g_vsc.target) ==
+          base_addr) {
+        index = i;
+        break;
+      }
+    }
+    if (index == sb_instructions.size() + 1)
+      continue;
+
+    // Copy instructions into queue to easily manipulate them
+    std::deque<DisassembledInstruction> disass_instructions;
+    for (auto &instr : sb_instructions)
+      disass_instructions.emplace_back(DisassembledInstruction(instr));
+
+    // Make sure the address in the disassemble request is at the right position
+    const uint64_t expected_index = -instruction_offset;
+    if (index < expected_index) {
+      for (uint64_t i = 0; i < (expected_index - index); i++) {
+        DisassembledInstruction nop_instruction;
+        disass_instructions.emplace_front(nop_instruction);
+      }
+    } else if (index > expected_index) {
+      const auto num_instr_to_remove = index - expected_index;
+      disass_instructions.erase(disass_instructions.begin(),
+                                disass_instructions.begin() +
+                                    num_instr_to_remove);
+    }
+
+    // Truncate if too many instructions
+    if (disass_instructions.size() > instruction_count) {
+      disass_instructions.erase(disass_instructions.begin() + instruction_count,
+                                disass_instructions.end());
+    }
+
+    assert(disass_instructions.size() > expected_index &&
+           disass_instructions[expected_index].m_address ==
+               memory_reference.value());
+
+    for (auto &instr : disass_instructions)
+      response_instructions.emplace_back(CreateDisassembledInstruction(instr));
+    return response_instructions;
+  }
+
+  return response_instructions;
+}
+
+void request_disassemble(const llvm::json::Object &request) {
+  llvm::json::Object response;
+  lldb::SBError error;
+  FillResponse(request, response);
+  auto arguments = request.getObject("arguments");
+  const auto memory_reference = arguments->getString("memoryReference");
+  const auto instruction_offset = GetSigned(arguments, "instructionOffset", 0);
+  const auto instruction_count = GetUnsigned(arguments, "instructionCount", 0);
+  llvm::json::Array response_instructions;
+
+  bool success = true;
+  auto base_addr = hex_string_to_addr(memory_reference);
+  if (base_addr == 0) {
+    success = false;
+  } else {
+    response_instructions =
+        instruction_offset >= 0
+            ? _handle_disassemble_positive_offset(base_addr, instruction_offset,
+                                                  instruction_count)
+            : _handle_disassemble_negative_offset(base_addr, instruction_offset,
+                                                  instruction_count,
+                                                  memory_reference);
+  }
+
+  // Add padding if not enough instructions
+  if (response_instructions.size() < instruction_count) {
+    const auto padding_len = instruction_count - response_instructions.size();
+    for (size_t i = 0; i < padding_len; i++) {
+      const DisassembledInstruction nop_instruction;
+      auto disass_instr = CreateDisassembledInstruction(nop_instruction);
+      response_instructions.emplace_back(std::move(disass_instr));
+    }
+  }
+
+  assert((response_instructions.size() == instruction_count) &&
+         "should return exact number of requested instructions");
+
+  llvm::json::Object body;
+  body.try_emplace("instructions", std::move(response_instructions));
+  response.try_emplace("body", std::move(body));
+  response["success"] = llvm::json::Value(success);
+  g_vsc.SendJSON(llvm::json::Value(std::move(response)));
+}
+
 // "SetExceptionBreakpointsRequest": {
 //   "allOf": [ { "$ref": "#/definitions/Request" }, {
 //     "type": "object",
 //     "description": "SetExceptionBreakpoints request; value of command field
 //     is 'setExceptionBreakpoints'. The request configures the debuggers
 //     response to thrown exceptions. If an exception is configured to break, a
 //     StoppedEvent is fired (event type 'exception').", "properties": {
 //       "command": {
g_vsc.RegisterRequestCallback("setFunctionBreakpoints",
                                 request_setFunctionBreakpoints);
   g_vsc.RegisterRequestCallback("setVariable", request_setVariable);
   g_vsc.RegisterRequestCallback("source", request_source);
   g_vsc.RegisterRequestCallback("stackTrace", request_stackTrace);
   g_vsc.RegisterRequestCallback("stepIn", request_stepIn);
   g_vsc.RegisterRequestCallback("stepOut", request_stepOut);
   g_vsc.RegisterRequestCallback("threads", request_threads);
   g_vsc.RegisterRequestCallback("variables", request_variables);
+  g_vsc.RegisterRequestCallback("disassemble", request_disassemble);
   // Custom requests
   g_vsc.RegisterRequestCallback("compileUnits", request_compileUnits);
   g_vsc.RegisterRequestCallback("modules", request_modules);
   // Testing requests
   g_vsc.RegisterRequestCallback("_testGetTargetBreakpoints",
                                 request__testGetTargetBreakpoints);
 }