Add a wasmtime objdump subcommand

This commit adds an `objdump` subcommand to the `wasmtime` CLI. Like all
other subcommands this can be disabled for a more minimal build of the
CLI as well. The purpose of this subcommand is to provide a
Wasmtime-specific spin on the venerable native `objdump` itself. Notably
this brings Wasmtime-specific knowledge for filtering functions, showing
Wasmtime metadata, etc.

This command is intended to look like `objdump` roughly but also has
configurable output with various flags and things that can be printed.
For now the main Wasmtime additions are showing the address map
section, stack map section, and trap section of a `*.cwasm` file.

This new subcommand replaces the infrastructure of the `disas` test
suite, and now that test suite uses `wasmtime objdump` to generate test
expectations. Additionally the subcommand replaces the Pulley `objdump`
example as a more full-featured objdump that also works natively with
Pulley.

The hope is that if we add more binary metadata in the future (such as
unwinding tables) that can be relatively easily added here for
exploration as well. Otherwise this is mostly just a developer
convenience for Wasmtime developers as well and hopefully doesn't cost
too much in maintenance burden.

Closes bytecodealliance#10336

Author: alexcrichton

.github/workflows/main.yml

@@ -393,6 +393,7 @@ jobs:
               -p wasmtime-cli --no-default-features --features compile
               -p wasmtime-cli --no-default-features --features compile,cranelift
               -p wasmtime-cli --no-default-features --features compile,cranelift,component-model
+              -p wasmtime-cli --no-default-features --features objdump
               -p wasmtime-cli --all-features
               -p wasmtime-cli --features component-model
 
@@ -405,7 +406,7 @@ jobs:
             checks: |
               -p cranelift-entity --no-default-features
               -p cranelift-entity --no-default-features --features enable-serde
-              
+
           - name: wasmtime-bench-api
             checks: |
               -p wasmtime-bench-api

Cargo.lock

@@ -71,6 +71,12 @@ wasmparser = { workspace = true }
 tracing = { workspace = true }
 log = { workspace = true }
 tempfile = { workspace = true, optional = true }
+object = { workspace = true, optional = true }
+cranelift-codegen = { workspace = true, optional = true, features = ['disas'] }
+capstone = { workspace = true, optional = true }
+termcolor = { workspace = true, optional = true }
+gimli = { workspace = true, optional = true }
+pulley-interpreter = { workspace = true, optional = true }
 
 async-trait = { workspace = true }
 trait-variant = { workspace = true }
@@ -381,6 +387,7 @@ libm = "0.2.7"
 tokio-rustls = "0.25.0"
 rustls = "0.22.0"
 webpki-roots = "0.26.0"
+termcolor = "1.4.1"
 
 # =============================================================================
 #
@@ -406,6 +413,7 @@ default = [
   "wast",
   "config",
   "completion",
+  "objdump",
 
   # On-by-default WASI features
   "wasi-nn",
@@ -513,6 +521,14 @@ run = [
   "wasmtime-cli-flags/async",
 ]
 completion = ["dep:clap_complete"]
+objdump = [
+  'dep:object',
+  'dep:cranelift-codegen',
+  'dep:capstone',
+  'dep:termcolor',
+  'dep:gimli',
+  'pulley-interpreter/disas',
+]
 
 [[test]]
 name = "disas"

Cargo.toml

@@ -285,34 +285,41 @@ pub trait Compiler: Send + Sync {
         use target_lexicon::Architecture::*;
 
         let triple = self.triple();
+        let (arch, flags) = match triple.architecture {
+            X86_32(_) => (Architecture::I386, 0),
+            X86_64 => (Architecture::X86_64, 0),
+            Arm(_) => (Architecture::Arm, 0),
+            Aarch64(_) => (Architecture::Aarch64, 0),
+            S390x => (Architecture::S390x, 0),
+            Riscv64(_) => (Architecture::Riscv64, 0),
+            // XXX: the `object` crate won't successfully build an object
+            // with relocations and such if it doesn't know the
+            // architecture, so just pretend we are riscv64. Yolo!
+            //
+            // Also note that we add some flags to `e_flags` in the object file
+            // to indicate that it's pulley, not actually riscv64. This is used
+            // by `wasmtime objdump` for example.
+            Pulley32 | Pulley32be => (Architecture::Riscv64, obj::EF_WASMTIME_PULLEY32),
+            Pulley64 | Pulley64be => (Architecture::Riscv64, obj::EF_WASMTIME_PULLEY64),
+            architecture => {
+                anyhow::bail!("target architecture {:?} is unsupported", architecture,);
+            }
+        };
         let mut obj = Object::new(
             BinaryFormat::Elf,
-            match triple.architecture {
-                X86_32(_) => Architecture::I386,
-                X86_64 => Architecture::X86_64,
-                Arm(_) => Architecture::Arm,
-                Aarch64(_) => Architecture::Aarch64,
-                S390x => Architecture::S390x,
-                Riscv64(_) => Architecture::Riscv64,
-                // XXX: the `object` crate won't successfully build an object
-                // with relocations and such if it doesn't know the
-                // architecture, so just pretend we are riscv64. Yolo!
-                Pulley32 | Pulley64 | Pulley32be | Pulley64be => Architecture::Riscv64,
-                architecture => {
-                    anyhow::bail!("target architecture {:?} is unsupported", architecture,);
-                }
-            },
+            arch,
             match triple.endianness().unwrap() {
                 target_lexicon::Endianness::Little => object::Endianness::Little,
                 target_lexicon::Endianness::Big => object::Endianness::Big,
             },
         );
         obj.flags = FileFlags::Elf {
             os_abi: obj::ELFOSABI_WASMTIME,
-            e_flags: match kind {
-                ObjectKind::Module => obj::EF_WASMTIME_MODULE,
-                ObjectKind::Component => obj::EF_WASMTIME_COMPONENT,
-            },
+            e_flags: flags
+                | match kind {
+                    ObjectKind::Module => obj::EF_WASMTIME_MODULE,
+                    ObjectKind::Component => obj::EF_WASMTIME_COMPONENT,
+                },
             abi_version: 0,
         };
         Ok(obj)

crates/environ/src/compile/mod.rs

@@ -17,6 +17,14 @@ pub const EF_WASMTIME_MODULE: u32 = 1 << 0;
 /// component.
 pub const EF_WASMTIME_COMPONENT: u32 = 1 << 1;
 
+/// Flag for the `e_flags` field in the ELF header indicating compiled code for
+/// pulley32
+pub const EF_WASMTIME_PULLEY32: u32 = 1 << 2;
+
+/// Flag for the `e_flags` field in the ELF header indicating compiled code for
+/// pulley64
+pub const EF_WASMTIME_PULLEY64: u32 = 1 << 3;
+
 /// Flag for the `sh_flags` field in the ELF text section that indicates that
 /// the text section does not itself need to be executable. This is used for the
 /// Pulley target, for example, to indicate that it does not need to be made

crates/environ/src/obj.rs

@@ -174,13 +174,7 @@ impl core::error::Error for Trap {}
 /// `TrapEncodingBuilder` above. Additionally the `offset` should be a relative
 /// offset within the text section of the compilation image.
 pub fn lookup_trap_code(section: &[u8], offset: usize) -> Option<Trap> {
-    let mut section = Bytes(section);
-    // NB: this matches the encoding written by `append_to` above.
-    let count = section.read::<U32Bytes<LittleEndian>>().ok()?;
-    let count = usize::try_from(count.get(LittleEndian)).ok()?;
-    let (offsets, traps) =
-        object::slice_from_bytes::<U32Bytes<LittleEndian>>(section.0, count).ok()?;
-    debug_assert_eq!(traps.len(), count);
+    let (offsets, traps) = parse(section)?;
 
     // The `offsets` table is sorted in the trap section so perform a binary
     // search of the contents of this section to find whether `offset` is an
@@ -202,3 +196,26 @@ pub fn lookup_trap_code(section: &[u8], offset: usize) -> Option<Trap> {
     debug_assert!(trap.is_some(), "missing mapping for {byte}");
     trap
 }
+
+fn parse(section: &[u8]) -> Option<(&[U32Bytes<LittleEndian>], &[u8])> {
+    let mut section = Bytes(section);
+    // NB: this matches the encoding written by `append_to` above.
+    let count = section.read::<U32Bytes<LittleEndian>>().ok()?;
+    let count = usize::try_from(count.get(LittleEndian)).ok()?;
+    let (offsets, traps) =
+        object::slice_from_bytes::<U32Bytes<LittleEndian>>(section.0, count).ok()?;
+    debug_assert_eq!(traps.len(), count);
+    Some((offsets, traps))
+}
+
+/// Returns an iterator over all of the traps encoded in `section`, which should
+/// have been produced by `TrapEncodingBuilder`.
+pub fn iterate_traps(section: &[u8]) -> Option<impl Iterator<Item = (u32, Trap)> + '_> {
+    let (offsets, traps) = parse(section)?;
+    Some(
+        offsets
+            .iter()
+            .zip(traps)
+            .map(|(offset, trap)| (offset.get(LittleEndian), Trap::from_u8(*trap).unwrap())),
+    )
+}

crates/environ/src/trap_encoding.rs

@@ -226,13 +226,13 @@ impl Engine {
     /// [`Engine::precompile_module`], or [`Engine::precompile_component`], then
     /// this will return `Some(...)` indicating so. Otherwise `None` is
     /// returned.
-    pub fn detect_precompiled(&self, bytes: &[u8]) -> Option<Precompiled> {
+    pub fn detect_precompiled(bytes: &[u8]) -> Option<Precompiled> {
         serialization::detect_precompiled_bytes(bytes)
     }
 
     /// Like [`Engine::detect_precompiled`], but performs the detection on a file.
     #[cfg(feature = "std")]
-    pub fn detect_precompiled_file(&self, path: impl AsRef<Path>) -> Result<Option<Precompiled>> {
+    pub fn detect_precompiled_file(path: impl AsRef<Path>) -> Result<Option<Precompiled>> {
         serialization::detect_precompiled_file(path)
     }
 

crates/wasmtime/src/engine.rs

@@ -68,7 +68,7 @@ pub fn check_compatible(engine: &Engine, mmap: &[u8], expected: ObjectKind) -> R
             os_abi: obj::ELFOSABI_WASMTIME,
             abi_version: 0,
             e_flags,
-        } if e_flags == expected_e_flags => {}
+        } if e_flags & expected_e_flags == expected_e_flags => {}
         _ => bail!("incompatible object file format"),
     }
 
@@ -149,13 +149,13 @@ fn detect_precompiled<'data, R: object::ReadRef<'data>>(
         FileFlags::Elf {
             os_abi: obj::ELFOSABI_WASMTIME,
             abi_version: 0,
-            e_flags: obj::EF_WASMTIME_MODULE,
-        } => Some(Precompiled::Module),
+            e_flags,
+        } if e_flags & obj::EF_WASMTIME_MODULE != 0 => Some(Precompiled::Module),
         FileFlags::Elf {
             os_abi: obj::ELFOSABI_WASMTIME,
             abi_version: 0,
-            e_flags: obj::EF_WASMTIME_COMPONENT,
-        } => Some(Precompiled::Component),
+            e_flags,
+        } if e_flags & obj::EF_WASMTIME_COMPONENT != 0 => Some(Precompiled::Component),
         _ => None,
     }
 }

crates/wasmtime/src/engine/serialization.rs

@@ -19,13 +19,13 @@ Windows users will want to visit our [releases page][releases] and can download
 the MSI installer (`wasmtime-dev-x86_64-windows.msi` for example) and use that
 to install.
 
-[releases]: https://github.com/bytecodealliance/wasmtime/releases
+[releases]: https://github.com/bytecodealliance/wasmtime/releases/latest
 
 You can confirm your installation works by executing:
 
 ```sh
 $ wasmtime -V
-wasmtime 0.12.0
+wasmtime 30.0.0 (ede663c2a 2025-02-19)
 ```
 
 And now you're off to the races! Be sure to check out the [various CLI
@@ -56,9 +56,9 @@ the `dev` release)
 Each of these archives has a `wasmtime` binary placed inside which can be
 executed normally as the CLI would.
 
-[wasmtime-dev-x86_64-linux.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-linux.tar.xz
-[wasmtime-dev-x86_64-macos.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-macos.tar.xz
-[wasmtime-dev-x86_64-windows.zip`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-windows.zip
+[`wasmtime-dev-x86_64-linux.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-linux.tar.xz
+[`wasmtime-dev-x86_64-macos.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-macos.tar.xz
+[`wasmtime-dev-x86_64-windows.zip`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-windows.zip
 
 ## Compiling from Source
 

docs/cli-install.md

@@ -127,6 +127,57 @@ display what Cranelift settings are inferred for the host:
 $ wasmtime settings
 ```
 
+## `explore`
+
+This subcommand can be used to explore a `*.cwasm` file and see how it connects
+to the original wasm file in a web browser. This will compile an input wasm
+file and emit an HTML file that can be opened in a web browser:
+
+```
+$ wasmtime explore foo.wasm
+Exploration written to foo.explore.html
+```
+
+The output HTML file can be used to compare what WebAssembly instruction
+compiles to what native instruction. Compilation options can be passed to
+`wasmtime explore` to see the effect of compilation options on generated code.
+
+## `objdump`
+
+Primarily intended as a debugging utility the `objdump` subcommand can be used
+to explore a `*.cwasm` file locally on your terminal. This is roughly modeled
+after native `objdump` binaries themselves:
+
+```
+$ wasmtime objdump foo.cwasm
+wasm[0]::function[0]:
+            stp     x29, x30, [sp, #-0x10]!
+            mov     x29, sp
+            ldr     x5, [x2, #0x50]
+            lsl     w6, w4, #2
+            ldr     w2, [x5, w6, uxtw]
+            ldp     x29, x30, [sp], #0x10
+            ret
+```
+
+You can also pass various options to configure and annotate the output:
+
+```
+$ wasmtime objdump foo.cwasm --addresses --bytes --addrma
+00000000 wasm[0]::function[0]:
+         0: fd 7b bf a9                  stp     x29, x30, [sp, #-0x10]!
+         4: fd 03 00 91                  mov     x29, sp
+         8: 45 28 40 f9                  ldr     x5, [x2, #0x50]
+                                          ╰─╼ addrmap: 0x23
+         c: 86 74 1e 53                  lsl     w6, w4, #2
+                                          ╰─╼ addrmap: 0x22
+        10: a2 48 66 b8                  ldr     w2, [x5, w6, uxtw]
+                                          ╰─╼ addrmap: 0x23
+        14: fd 7b c1 a8                  ldp     x29, x30, [sp], #0x10
+                                          ╰─╼ addrmap: 0x26
+        18: c0 03 5f d6                  ret
+```
+
 # Additional options
 Many of the above subcommands also take additional options. For example,
 - run