gdbstub_arch: add a WebAssembly architecture.

Builds on #188, #189, #190: add definitions for the WebAssembly
architecture to `gdbstub_arch`. This includes all definitions needed
for the `Arch` trait, as well as utility code for encoding/decoding
the synthetic address space used by the gdbstub definitions for this
architecture.

Tested with Wasmtime using a (soon to be upstreamed) guest-debugging
facility.

Author: cfallin

gdbstub_arch/src/lib.rs

@@ -59,6 +59,7 @@ pub mod mips;
 pub mod msp430;
 pub mod ppc;
 pub mod riscv;
+pub mod wasm;
 pub mod x86;
 
 // used as part of intra-doc link

gdbstub_arch/src/wasm/addr.rs

@@ -0,0 +1,166 @@
+//! Synthetic 64-bit Wasm address space expected by the LLDB Wasm
+//! extensions.
+//!
+//! WebAssembly is natively *multi-memory* and *multi-address-space*:
+//!
+//! - It supports zero or more "linear memories", and they have no canonical
+//!   mapping into a single global address space for pointers; rather, each load
+//!   and store instruction names which memory it accesses statically.
+//! - It supports one or more "modules" containing first-class functions, and
+//!   they have no canonical mapping into a single global code space; rather,
+//!   control flow is structured, and calls between functions in different
+//!   modules only occur via explicit strongly-typed function imports and
+//!   exports.
+//!
+//! Wasm implementations typically represent these concepts directly
+//! rather than attempt to map to a more conventional ISA model of a
+//! single flat address space with machine code and data. However, the
+//! gdbstub protocol assumes the latter: all of its commands, such as
+//! memory reads/writes, breakpoint updates, and the like, use
+//! integers as pointers in a single address space.
+//!
+//! The LLDB Wasm extensions thus define a canonical mapping between
+//! the multi-address-space world and a flat 64-bit address space for
+//! the purposes of the protocol only. Note that this is 64-bit even
+//! when Wasm natively has 32-bit memory offsets (the "wasm32"
+//! architecture), because the definition adds additional information
+//! above the 32-bit offset.
+//!
+//! The [ProcessWasm.h] header file in the LLDB source contains
+//! definitions that are as close to documentation as we can find: see
+//! the `WasmAddressType` and `wasm_addr_t` definitions.
+//!
+//! An address consists of three parts:
+//!
+//! - The type: code or data. Wasm has separate "address spaces" for these, so
+//!   they are mapped to different regions of the 64-bit synthetic space.
+//!
+//!   Note that this implies that the original bytecode (the full
+//!   image of the Wasm module, starting with its magic number) is
+//!   present in this synthetic address space. An engine that
+//!   implements debugging for Wasm should keep around the original
+//!   bytecode, even if it does ahead-of-time compilation or other
+//!   processing, so that the debugger can use it: LLDB will read the
+//!   module bytecode from the synthetic address space, including its
+//!   debug sections, rather than find the image elsewhere.
+//!
+//! - The module/memory index. The engine decides an arbitrary index ordering
+//!   for all of the Wasm modules and Wasm linear memories present in a given
+//!   execution.
+//!
+//! - The offset within that Wasm module bytecode or linear memory.
+//!
+//! [ProcessWasm.h]: https://github.com/llvm/llvm-project/blob/main/lldb/source/Plugins/Process/wasm/ProcessWasm.h
+
+/// The type of an address in the synthetic address space used by the
+/// Wasm target.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+pub enum WasmAddrType {
+    /// Address in a 32-bit linear memory.
+    Memory,
+    /// Address in a `.wasm` module image.
+    ///
+    /// Used both for memory-read commands to fetch the Wasm binary
+    /// from the gdbstub host, and software-breakpoint commands.
+    Object,
+}
+
+/// An address in the synthetic address space used by the Wasm target.
+#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct WasmAddr(u64);
+
+impl WasmAddr {
+    const TYPE_BITS: u32 = 2;
+    const MODULE_BITS: u32 = 30;
+    const OFFSET_BITS: u32 = 32;
+
+    const MODULE_SHIFT: u32 = Self::OFFSET_BITS;
+    const TYPE_SHIFT: u32 = Self::OFFSET_BITS + Self::MODULE_BITS;
+
+    const TYPE_MASK: u64 = (1u64 << Self::TYPE_BITS) - 1;
+    const MODULE_MASK: u64 = (1u64 << Self::MODULE_BITS) - 1;
+    const OFFSET_MASK: u64 = (1u64 << Self::OFFSET_BITS) - 1;
+
+    /// Construct a `WasmAddr` from a raw 64-bit encoded address.
+    ///
+    /// Returns `None` if the encoding is invalid.
+    pub fn from_raw(raw: u64) -> Option<Self> {
+        let type_bits = (raw >> Self::TYPE_SHIFT) & Self::TYPE_MASK;
+        if type_bits > 1 {
+            return None;
+        }
+        Some(WasmAddr(raw))
+    }
+
+    /// Provide the raw 64-bit encoding of this `WasmAddr`.
+    pub fn as_raw(self) -> u64 {
+        self.0
+    }
+
+    /// Construct a `WasmAddr` from its constituent parts.
+    pub fn new(addr_type: WasmAddrType, module_index: u32, offset: u32) -> Self {
+        // There are fewer than 32 bits in the encoding for the module
+        // index.
+        assert_eq!(
+            module_index >> Self::MODULE_BITS,
+            0,
+            "Out-of-bounds module index"
+        );
+        let type_bits: u64 = match addr_type {
+            WasmAddrType::Memory => 0,
+            WasmAddrType::Object => 1,
+        };
+        WasmAddr(
+            (type_bits << Self::TYPE_SHIFT)
+                | ((u64::from(module_index)) << Self::MODULE_SHIFT)
+                | (u64::from(offset)),
+        )
+    }
+
+    /// Get the type of this address.
+    pub fn addr_type(self) -> WasmAddrType {
+        match (self.0 >> Self::TYPE_SHIFT) & Self::TYPE_MASK {
+            0 => WasmAddrType::Memory,
+            1 => WasmAddrType::Object,
+            // We never set other type-bits and the raw bits are fully
+            // encapsulated and checked in `from_raw`, so this is
+            // unreachable. `gdbstub_arch` forbids panics, so we
+            // return a bogus type here.
+            _ => WasmAddrType::Memory,
+        }
+    }
+
+    /// Get the index of the module or memory referenced by this
+    /// address.
+    pub fn module_index(self) -> u32 {
+        ((self.0 >> Self::MODULE_SHIFT) & Self::MODULE_MASK) as u32
+    }
+
+    /// Get the offset within the module or memory referenced by this
+    /// address.
+    pub fn offset(self) -> u32 {
+        (self.0 & Self::OFFSET_MASK) as u32
+    }
+}
+
+impl core::fmt::Display for WasmAddr {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        let type_str = match self.addr_type() {
+            WasmAddrType::Memory => "Memory",
+            WasmAddrType::Object => "Object",
+        };
+        write!(
+            f,
+            "{}(module={}, offset={:#x})",
+            type_str,
+            self.module_index(),
+            self.offset()
+        )
+    }
+}
+
+impl core::fmt::Debug for WasmAddr {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "WasmAddr({self})")
+    }
+}

gdbstub_arch/src/wasm/mod.rs

@@ -0,0 +1,46 @@
+//! Implementation for the WebAssembly architecture.
+//!
+//! This implementation follows the [LLDB-specific Wasm extensions] to
+//! the gdbstub protocol, which define a mapping from Wasm concepts to
+//! more classicasl ISA concepts.
+//!
+//! WebAssembly is somewhat *unlike* most ISAs in many of its details:
+//! for example, it uses an operand stack rather than classical
+//! registers, and has explicit concepts of function locals, of
+//! globals, and of first-class functions and a callstack, rather than
+//! a flat address space of bytes that are used to build up machine
+//! code, a stack, and storage as in most other ISAs.
+//!
+//! You'll likely want to implement the `Wasm` extension trait in your
+//! `Target` implementation in order to provide LLDB access to these
+//! Wasm-native concepts.
+//!
+//! As a particularly important detail, note that the natively
+//! multi-address-space Wasm world, where multiple code modules exist
+//! without a native concept of a global PC space, and multiple linear
+//! memories exist with every load/store qualified by the memory it
+//! accesses, is mapped into a single synthesized 64-bit address space
+//! by definition of the protocol extensions. See the [`self::addr`]
+//! submodule for utilities to encode and decode these synthesized
+//! addresses.
+//!
+//! [LLDB-specific Wasm extensions]: https://lldb.llvm.org/resources/lldbgdbremote.html#wasm-packets
+
+use gdbstub::arch::Arch;
+
+pub mod addr;
+pub mod reg;
+
+/// Implements `Arch` for the WebAssembly architecture.
+pub enum Wasm {}
+
+impl Arch for Wasm {
+    /// Even though Wasm is nominally a 32-bit platform, the gdbstub
+    /// protocol for Wasm uses a 64-bit address word to multiplex module
+    /// bytecode regions and linear memory regions into a single address
+    /// space.
+    type Usize = u64;
+    type Registers = reg::WasmRegisters;
+    type RegId = reg::id::WasmRegId;
+    type BreakpointKind = usize;
+}

gdbstub_arch/src/wasm/reg/id.rs

@@ -0,0 +1,25 @@
+use core::num::NonZeroUsize;
+use gdbstub::arch::RegId;
+
+/// The only register exposed to GDB: `pc` (register index 0).
+#[derive(Debug, Clone, Copy)]
+#[non_exhaustive]
+pub enum WasmRegId {
+    /// Program Counter.
+    Pc,
+}
+
+impl RegId for WasmRegId {
+    fn from_raw_id(id: usize) -> Option<(Self, Option<NonZeroUsize>)> {
+        match id {
+            0 => Some((WasmRegId::Pc, NonZeroUsize::new(8))),
+            _ => None,
+        }
+    }
+
+    fn to_raw_id(&self) -> Option<usize> {
+        match self {
+            WasmRegId::Pc => Some(0),
+        }
+    }
+}

gdbstub_arch/src/wasm/reg/mod.rs

@@ -0,0 +1,12 @@
+//! `Register` structs for the WebAssembly architecture.
+//!
+//! Because Wasm is mostly stack-based, it only has one "register":
+//! the program counter (PC) according to the gdbstub mappings for
+//! this architecture.
+
+/// `RegId` definitions for WebAssembly.
+pub mod id;
+
+mod wasm_regs;
+
+pub use wasm_regs::WasmRegisters;

gdbstub_arch/src/wasm/reg/wasm_regs.rs

@@ -0,0 +1,32 @@
+use core::convert::TryInto;
+use gdbstub::arch::Registers;
+
+/// The register state for WebAssembly.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct WasmRegisters {
+    /// Program Counter. See [`crate::wasm::addr`] for the 64-bit
+    /// synthetic address space in which this PC exists.
+    pub pc: u64,
+}
+
+impl Registers for WasmRegisters {
+    type ProgramCounter = u64;
+
+    fn pc(&self) -> u64 {
+        self.pc
+    }
+
+    fn gdb_serialize(&self, mut write_byte: impl FnMut(Option<u8>)) {
+        for byte in self.pc.to_le_bytes() {
+            write_byte(Some(byte));
+        }
+    }
+
+    fn gdb_deserialize(&mut self, bytes: &[u8]) -> Result<(), ()> {
+        if bytes.len() < 8 {
+            return Err(());
+        }
+        self.pc = u64::from_le_bytes(bytes[..8].try_into().unwrap());
+        Ok(())
+    }
+}

src/target/ext/wasm.rs

@@ -19,6 +19,9 @@
 //!
 //! [LLDB source code]:
 //!     https://github.com/llvm/llvm-project/blob/main/lldb/source/Plugins/Process/wasm/ProcessWasm.h
+//!
+//! An implementation of this address encoding/decoding can be found
+//! in the `gdbstub_arch` crate in `gdbstub_arch::wasm::addr`.
 use crate::common::Tid;
 use crate::target::Target;