[lldb] Implement RegisterContextWasm (#151056)

This PR implements a register context for Wasm, which uses virtual
registers to resolve Wasm local, globals and stack values. The registers
are used to implement support for `DW_OP_WASM_location` in the DWARF
expression evaluator (#151010). This also adds a more comprehensive
test, showing that we can use this to show local variables.

Author: JDevlieghere

lldb/docs/resources/lldbgdbremote.md

@@ -1998,22 +1998,6 @@ threads (live system debug) / cores (JTAG) in your program have
 stopped and allows LLDB to display and control your program
 correctly.
 
-## qWasmCallStack
-
-Get the Wasm call stack for the given thread id. This returns a hex-encoded
-list of PC values, one for each frame of the call stack. To match the Wasm
-specification, the addresses are encoded in little endian byte order, even if
-the endian of the Wasm runtime's host is not little endian.
-
-```
-send packet: $qWasmCallStack:202dbe040#08
-read packet: $9c01000000000040e501000000000040fe01000000000040#
-```
-
-**Priority to Implement:** Only required for Wasm support. This packed is
-supported by the [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime)
-and [V8](https://v8.dev) Wasm runtimes.
-
 ## qWatchpointSupportInfo
 
 Get the number of hardware watchpoints available on the remote target.
@@ -2479,3 +2463,70 @@ omitting them will work fine; these numbers are always base 16.
 
 The length of the payload is not provided.  A reliable, 8-bit clean,
 transport layer is assumed.
+
+## Wasm Packets
+
+The packet below are supported by the
+[WAMR](https://github.com/bytecodealliance/wasm-micro-runtime) and
+[V8](https://v8.dev) Wasm runtimes.
+
+
+### qWasmCallStack
+
+Get the Wasm call stack for the given thread id. This returns a hex-encoded
+list of PC values, one for each frame of the call stack. To match the Wasm
+specification, the addresses are encoded in little endian byte order, even if
+the endian of the Wasm runtime's host is not little endian.
+
+```
+send packet: $qWasmCallStack:202dbe040#08
+read packet: $9c01000000000040e501000000000040fe01000000000040#
+```
+
+**Priority to Implement:** Only required for Wasm support. Necessary to show
+stack traces.
+
+### qWasmGlobal
+
+Get the value of a Wasm global variable for the given frame index at the given
+variable index. The indexes are encoded as base 10. The result is a hex-encoded
+address from where to read the value.
+
+```
+send packet: $qWasmGlobal:0;2#cb
+read packet: $e0030100#b9
+```
+
+**Priority to Implement:** Only required for Wasm support. Necessary to show
+variables.
+
+
+### qWasmLocal
+
+Get the value of a Wasm function argument or local variable for the given frame
+index at the given variable index. The indexes are encoded as base 10. The
+result is a hex-encoded address from where to read the value.
+
+
+```
+send packet: $qWasmLocal:0;2#cb
+read packet: $e0030100#b9
+```
+
+**Priority to Implement:** Only required for Wasm support. Necessary to show
+variables.
+
+
+### qWasmStackValue
+
+Get the value of a Wasm local variable from the Wasm operand stack, for the
+given frame index at the given variable index. The indexes are encoded as base
+10. The result is a hex-encoded address from where to read value.
+
+```
+send packet: $qWasmStackValue:0;2#cb
+read packet: $e0030100#b9
+```
+
+**Priority to Implement:** Only required for Wasm support. Necessary to show
+variables.

lldb/source/Plugins/Process/wasm/CMakeLists.txt

@@ -1,5 +1,6 @@
 add_lldb_library(lldbPluginProcessWasm PLUGIN
   ProcessWasm.cpp
+  RegisterContextWasm.cpp
   ThreadWasm.cpp
   UnwindWasm.cpp
 

lldb/source/Plugins/Process/wasm/ProcessWasm.cpp

@@ -131,3 +131,36 @@ ProcessWasm::GetWasmCallStack(lldb::tid_t tid) {
 
   return call_stack_pcs;
 }
+
+llvm::Expected<lldb::DataBufferSP>
+ProcessWasm::GetWasmVariable(WasmVirtualRegisterKinds kind, int frame_index,
+                             int index) {
+  StreamString packet;
+  switch (kind) {
+  case eWasmTagLocal:
+    packet.Printf("qWasmLocal:");
+    break;
+  case eWasmTagGlobal:
+    packet.Printf("qWasmGlobal:");
+    break;
+  case eWasmTagOperandStack:
+    packet.PutCString("qWasmStackValue:");
+    break;
+  case eWasmTagNotAWasmLocation:
+    return llvm::createStringError("not a Wasm ___location");
+  }
+  packet.Printf("%d;%d", frame_index, index);
+
+  StringExtractorGDBRemote response;
+  if (m_gdb_comm.SendPacketAndWaitForResponse(packet.GetString(), response) !=
+      GDBRemoteCommunication::PacketResult::Success)
+    return llvm::createStringError("failed to send Wasm variable");
+
+  if (!response.IsNormalResponse())
+    return llvm::createStringError("failed to get response for Wasm variable");
+
+  WritableDataBufferSP buffer_sp(
+      new DataBufferHeap(response.GetStringRef().size() / 2, 0));
+  response.GetHexBytes(buffer_sp->GetData(), '\xcc');
+  return buffer_sp;
+}

lldb/source/Plugins/Process/wasm/ProcessWasm.h

@@ -10,6 +10,7 @@
 #define LLDB_SOURCE_PLUGINS_PROCESS_WASM_PROCESSWASM_H
 
 #include "Plugins/Process/gdb-remote/ProcessGDBRemote.h"
+#include "Utility/WasmVirtualRegisters.h"
 
 namespace lldb_private {
 namespace wasm {
@@ -71,12 +72,19 @@ class ProcessWasm : public process_gdb_remote::ProcessGDBRemote {
   /// Retrieve the current call stack from the WebAssembly remote process.
   llvm::Expected<std::vector<lldb::addr_t>> GetWasmCallStack(lldb::tid_t tid);
 
+  /// Query the value of a WebAssembly variable from the WebAssembly
+  /// remote process.
+  llvm::Expected<lldb::DataBufferSP>
+  GetWasmVariable(WasmVirtualRegisterKinds kind, int frame_index, int index);
+
 protected:
   std::shared_ptr<process_gdb_remote::ThreadGDBRemote>
   CreateThread(lldb::tid_t tid) override;
 
 private:
   friend class UnwindWasm;
+  friend class ThreadWasm;
+
   process_gdb_remote::GDBRemoteDynamicRegisterInfoSP &GetRegisterInfo() {
     return m_register_info_sp;
   }

lldb/source/Plugins/Process/wasm/RegisterContextWasm.cpp

@@ -0,0 +1,109 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "RegisterContextWasm.h"
+#include "Plugins/Process/gdb-remote/GDBRemoteRegisterContext.h"
+#include "ProcessWasm.h"
+#include "ThreadWasm.h"
+#include "lldb/Utility/LLDBLog.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/Utility/RegisterValue.h"
+#include "llvm/Support/Error.h"
+#include <memory>
+
+using namespace lldb;
+using namespace lldb_private;
+using namespace lldb_private::process_gdb_remote;
+using namespace lldb_private::wasm;
+
+RegisterContextWasm::RegisterContextWasm(
+    wasm::ThreadWasm &thread, uint32_t concrete_frame_idx,
+    GDBRemoteDynamicRegisterInfoSP reg_info_sp)
+    : GDBRemoteRegisterContext(thread, concrete_frame_idx, reg_info_sp, false,
+                               false) {}
+
+RegisterContextWasm::~RegisterContextWasm() = default;
+
+uint32_t RegisterContextWasm::ConvertRegisterKindToRegisterNumber(
+    lldb::RegisterKind kind, uint32_t num) {
+  return num;
+}
+
+size_t RegisterContextWasm::GetRegisterCount() {
+  // Wasm has no registers.
+  return 0;
+}
+
+const RegisterInfo *RegisterContextWasm::GetRegisterInfoAtIndex(size_t reg) {
+  uint32_t tag = GetWasmVirtualRegisterTag(reg);
+  if (tag == eWasmTagNotAWasmLocation)
+    return m_reg_info_sp->GetRegisterInfoAtIndex(
+        GetWasmVirtualRegisterIndex(reg));
+
+  auto it = m_register_map.find(reg);
+  if (it == m_register_map.end()) {
+    WasmVirtualRegisterKinds kind = static_cast<WasmVirtualRegisterKinds>(tag);
+    std::tie(it, std::ignore) = m_register_map.insert(
+        {reg, std::make_unique<WasmVirtualRegisterInfo>(
+                  kind, GetWasmVirtualRegisterIndex(reg))});
+  }
+  return it->second.get();
+}
+
+size_t RegisterContextWasm::GetRegisterSetCount() { return 0; }
+
+const RegisterSet *RegisterContextWasm::GetRegisterSet(size_t reg_set) {
+  // Wasm has no registers.
+  return nullptr;
+}
+
+bool RegisterContextWasm::ReadRegister(const RegisterInfo *reg_info,
+                                       RegisterValue &value) {
+  // The only real registers is the PC.
+  if (reg_info->name)
+    return GDBRemoteRegisterContext::ReadRegister(reg_info, value);
+
+  // Read the virtual registers.
+  ThreadWasm *thread = static_cast<ThreadWasm *>(&GetThread());
+  ProcessWasm *process = static_cast<ProcessWasm *>(thread->GetProcess().get());
+  if (!thread)
+    return false;
+
+  uint32_t frame_index = m_concrete_frame_idx;
+  WasmVirtualRegisterInfo *wasm_reg_info =
+      static_cast<WasmVirtualRegisterInfo *>(
+          const_cast<RegisterInfo *>(reg_info));
+
+  llvm::Expected<DataBufferSP> maybe_buffer = process->GetWasmVariable(
+      wasm_reg_info->kind, frame_index, wasm_reg_info->index);
+  if (!maybe_buffer) {
+    LLDB_LOG_ERROR(GetLog(LLDBLog::Process), maybe_buffer.takeError(),
+                   "Failed to read Wasm local: {0}");
+    return false;
+  }
+
+  DataBufferSP buffer_sp = *maybe_buffer;
+  DataExtractor reg_data(buffer_sp, process->GetByteOrder(),
+                         process->GetAddressByteSize());
+  wasm_reg_info->byte_size = buffer_sp->GetByteSize();
+  wasm_reg_info->encoding = lldb::eEncodingUint;
+
+  Status error = value.SetValueFromData(
+      *reg_info, reg_data, reg_info->byte_offset, /*partial_data_ok=*/false);
+  return error.Success();
+}
+
+void RegisterContextWasm::InvalidateAllRegisters() {}
+
+bool RegisterContextWasm::WriteRegister(const RegisterInfo *reg_info,
+                                        const RegisterValue &value) {
+  // The only real registers is the PC.
+  if (reg_info->name)
+    return GDBRemoteRegisterContext::WriteRegister(reg_info, value);
+  return false;
+}

lldb/source/Plugins/Process/wasm/RegisterContextWasm.h

@@ -0,0 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// 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_SOURCE_PLUGINS_PROCESS_WASM_REGISTERCONTEXTWASM_H
+#define LLDB_SOURCE_PLUGINS_PROCESS_WASM_REGISTERCONTEXTWASM_H
+
+#include "Plugins/Process/gdb-remote/GDBRemoteRegisterContext.h"
+#include "ThreadWasm.h"
+#include "Utility/WasmVirtualRegisters.h"
+#include "lldb/lldb-private-types.h"
+#include <unordered_map>
+
+namespace lldb_private {
+namespace wasm {
+
+class RegisterContextWasm;
+
+typedef std::shared_ptr<RegisterContextWasm> RegisterContextWasmSP;
+
+struct WasmVirtualRegisterInfo : public RegisterInfo {
+  WasmVirtualRegisterKinds kind;
+  uint32_t index;
+
+  WasmVirtualRegisterInfo(WasmVirtualRegisterKinds kind, uint32_t index)
+      : RegisterInfo(), kind(kind), index(index) {}
+};
+
+class RegisterContextWasm
+    : public process_gdb_remote::GDBRemoteRegisterContext {
+public:
+  RegisterContextWasm(
+      wasm::ThreadWasm &thread, uint32_t concrete_frame_idx,
+      process_gdb_remote::GDBRemoteDynamicRegisterInfoSP reg_info_sp);
+
+  ~RegisterContextWasm() override;
+
+  uint32_t ConvertRegisterKindToRegisterNumber(lldb::RegisterKind kind,
+                                               uint32_t num) override;
+
+  void InvalidateAllRegisters() override;
+
+  size_t GetRegisterCount() override;
+
+  const RegisterInfo *GetRegisterInfoAtIndex(size_t reg) override;
+
+  size_t GetRegisterSetCount() override;
+
+  const RegisterSet *GetRegisterSet(size_t reg_set) override;
+
+  bool ReadRegister(const RegisterInfo *reg_info,
+                    RegisterValue &value) override;
+
+  bool WriteRegister(const RegisterInfo *reg_info,
+                     const RegisterValue &value) override;
+
+private:
+  std::unordered_map<size_t, std::unique_ptr<WasmVirtualRegisterInfo>>
+      m_register_map;
+};
+
+} // namespace wasm
+} // namespace lldb_private
+
+#endif

lldb/source/Plugins/Process/wasm/ThreadWasm.cpp

@@ -9,6 +9,7 @@
 #include "ThreadWasm.h"
 
 #include "ProcessWasm.h"
+#include "RegisterContextWasm.h"
 #include "UnwindWasm.h"
 #include "lldb/Target/Target.h"
 
@@ -32,3 +33,19 @@ llvm::Expected<std::vector<lldb::addr_t>> ThreadWasm::GetWasmCallStack() {
   }
   return llvm::createStringError("no process");
 }
+
+lldb::RegisterContextSP
+ThreadWasm::CreateRegisterContextForFrame(StackFrame *frame) {
+  uint32_t concrete_frame_idx = 0;
+  ProcessSP process_sp(GetProcess());
+  ProcessWasm *wasm_process = static_cast<ProcessWasm *>(process_sp.get());
+
+  if (frame)
+    concrete_frame_idx = frame->GetConcreteFrameIndex();
+
+  if (concrete_frame_idx == 0)
+    return std::make_shared<RegisterContextWasm>(
+        *this, concrete_frame_idx, wasm_process->GetRegisterInfo());
+
+  return GetUnwinder().CreateRegisterContextForFrame(frame);
+}

lldb/source/Plugins/Process/wasm/ThreadWasm.h

@@ -25,6 +25,9 @@ class ThreadWasm : public process_gdb_remote::ThreadGDBRemote {
   /// Retrieve the current call stack from the WebAssembly remote process.
   llvm::Expected<std::vector<lldb::addr_t>> GetWasmCallStack();
 
+  lldb::RegisterContextSP
+  CreateRegisterContextForFrame(StackFrame *frame) override;
+
 protected:
   Unwind &GetUnwinder() override;