wasmtime_cli/commands/

objdump.rs

//! Implementation of the `wasmtime objdump` CLI command.

use crate::disas::{self, Inst};
use clap::Parser;
use object::read::elf::ElfFile64;
use object::{Endianness, Object, ObjectSection, ObjectSymbol};
use smallvec::SmallVec;
use std::io::{IsTerminal, Read};
use std::iter::{self, Peekable};
use std::path::{Path, PathBuf};
use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, WriteColor};
use wasmtime::{Engine, Result, bail, error::Context as _};
use wasmtime_environ::{
    CompiledTrap, FilePos, FrameInstPos, FrameStackShape, FrameStateSlot, FrameTable,
    FrameTableDescriptorIndex, ModulePC, StackMap, obj,
};
use wasmtime_unwinder::{ExceptionHandler, ExceptionTable};

/// A helper utility in wasmtime to explore the compiled object file format of
/// a `*.cwasm` file.
#[derive(Parser)]
pub struct ObjdumpCommand {
    /// The path to a compiled `*.cwasm` file.
    ///
    /// If this is `-` or not provided then stdin is used as input.
    cwasm: Option<PathBuf>,

    /// Whether or not to display function/instruction addresses.
    #[arg(long)]
    addresses: bool,

    /// Whether or not to try to only display addresses of instruction jump
    /// targets.
    #[arg(long)]
    address_jumps: bool,

    /// What functions should be printed
    #[arg(long, default_value = "wasm", value_name = "KIND")]
    funcs: Vec<Func>,

    /// String filter to apply to function names to only print some functions.
    #[arg(long, value_name = "STR")]
    filter: Option<String>,

    /// Whether or not instruction bytes are disassembled.
    #[arg(long)]
    bytes: bool,

    /// Whether or not to use color.
    #[arg(long, default_value = "auto")]
    color: ColorChoice,

    /// Whether or not to interleave instructions with address maps.
    #[arg(long, require_equals = true, value_name = "true|false")]
    addrmap: Option<Option<bool>>,

    /// Column width of how large an address is rendered as.
    #[arg(long, default_value = "10", value_name = "N")]
    address_width: usize,

    /// Whether or not to show information about what instructions can trap.
    #[arg(long, require_equals = true, value_name = "true|false")]
    traps: Option<Option<bool>>,

    /// Whether or not to show information about stack maps.
    #[arg(long, require_equals = true, value_name = "true|false")]
    stack_maps: Option<Option<bool>>,

    /// Whether or not to show information about exception tables.
    #[arg(long, require_equals = true, value_name = "true|false")]
    exception_tables: Option<Option<bool>>,

    /// Whether or not to show information about frame tables.
    #[arg(long, require_equals = true, value_name = "true|false")]
    frame_tables: Option<Option<bool>>,
}

fn optional_flag_with_default(flag: Option<Option<bool>>, default: bool) -> bool {
    match flag {
        None => default,
        Some(None) => true,
        Some(Some(val)) => val,
    }
}

impl ObjdumpCommand {
    fn addrmap(&self) -> bool {
        optional_flag_with_default(self.addrmap, false)
    }

    fn traps(&self) -> bool {
        optional_flag_with_default(self.traps, true)
    }

    fn stack_maps(&self) -> bool {
        optional_flag_with_default(self.stack_maps, true)
    }

    fn exception_tables(&self) -> bool {
        optional_flag_with_default(self.exception_tables, true)
    }

    fn frame_tables(&self) -> bool {
        optional_flag_with_default(self.frame_tables, true)
    }

    /// Executes the command.
    pub fn execute(self) -> Result<()> {
        // Setup stdout handling color options.
        let mut choice = self.color;
        if choice == ColorChoice::Auto && !std::io::stdout().is_terminal() {
            choice = ColorChoice::Never;
        }
        let mut stdout = StandardStream::stdout(choice);

        let bytes = self.read_cwasm()?;
        self.disassemble(&bytes, &mut stdout)
    }

    /// Disassembles the `*.cwasm` image in `bytes`, rendering a human-readable
    /// listing to `stdout`.
    //
    // XXX: This is only `pub` so it can be shared with the `disas` test runner,
    // so that that doesn't need to spawn a subprocess per `disas` test, which
    // is extremely slow on machines with corporate management software that
    // intercept every process spawn.
    #[doc(hidden)]
    pub fn disassemble(&self, bytes: &[u8], stdout: &mut dyn WriteColor) -> Result<()> {
        // Build some variables used below to configure colors of certain items.
        let mut color_address = ColorSpec::new();
        color_address.set_bold(true).set_fg(Some(Color::Yellow));
        let mut color_bytes = ColorSpec::new();
        color_bytes.set_fg(Some(Color::Magenta));

        // Double-check this is a `*.cwasm`
        if Engine::detect_precompiled(bytes).is_none() {
            bail!("not a `*.cwasm` file from wasmtime: {:?}", self.cwasm);
        }

        // Parse the input as an ELF file, extract the `.text` section.
        let elf = ElfFile64::<Endianness>::parse(bytes)?;
        let text = elf
            .section_by_name(".text")
            .context("missing .text section")?;
        let text = text.data()?;

        let frame_table_descriptors = elf
            .section_by_name(obj::ELF_WASMTIME_FRAMES)
            .and_then(|section| section.data().ok())
            .and_then(|bytes| FrameTable::parse(bytes, text).ok());

        let mut breakpoints = frame_table_descriptors
            .iter()
            .flat_map(|ftd| ftd.breakpoint_patches())
            .map(|(wasm_pc, patch)| (wasm_pc, patch.offset, SmallVec::from(patch.enable)))
            .collect::<Vec<_>>();
        breakpoints.sort_by_key(|(_wasm_pc, native_offset, _patch)| *native_offset);
        let breakpoints: Box<dyn Iterator<Item = _>> = Box::new(breakpoints.into_iter());
        let breakpoints = breakpoints.peekable();

        // Build the helper that'll get used to attach decorations/annotations
        // to various instructions.
        let mut decorator = Decorator {
            addrmap: elf
                .section_by_name(obj::ELF_WASMTIME_ADDRMAP)
                .and_then(|section| section.data().ok())
                .and_then(|bytes| wasmtime_environ::iterate_address_map(bytes))
                .map(|i| (Box::new(i) as Box<dyn Iterator<Item = _>>).peekable()),
            traps: elf
                .section_by_name(obj::ELF_WASMTIME_TRAPS)
                .and_then(|section| section.data().ok())
                .and_then(|bytes| wasmtime_environ::iterate_traps(bytes))
                .map(|i| (Box::new(i) as Box<dyn Iterator<Item = _>>).peekable()),
            stack_maps: elf
                .section_by_name(obj::ELF_WASMTIME_STACK_MAP)
                .and_then(|section| section.data().ok())
                .and_then(|bytes| StackMap::iter(bytes))
                .map(|i| (Box::new(i) as Box<dyn Iterator<Item = _>>).peekable()),
            exception_tables: elf
                .section_by_name(obj::ELF_WASMTIME_EXCEPTIONS)
                .and_then(|section| section.data().ok())
                .and_then(|bytes| ExceptionTable::parse(bytes).ok())
                .map(|table| table.into_iter())
                .map(|i| (Box::new(i) as Box<dyn Iterator<Item = _>>).peekable()),
            frame_tables: elf
                .section_by_name(obj::ELF_WASMTIME_FRAMES)
                .and_then(|section| section.data().ok())
                .and_then(|bytes| FrameTable::parse(bytes, text).ok())
                .map(|table| table.into_program_points())
                .map(|i| (Box::new(i) as Box<dyn Iterator<Item = _>>).peekable()),

            breakpoints,

            frame_table_descriptors,

            objdump: &self,
        };

        // Iterate over all symbols which will be functions for a cwasm and
        // we'll disassemble them all.
        let mut first = true;
        for sym in elf.symbols() {
            let name = match sym.name() {
                Ok(name) => name,
                Err(_) => continue,
            };
            let bytes = &text[sym.address() as usize..][..sym.size() as usize];

            let kind = if name.starts_with("wasmtime_builtin")
                || name.starts_with("wasmtime_patchable_builtin")
            {
                Func::Builtin
            } else if name.contains("]::function[") {
                Func::Wasm
            } else if name.contains("trampoline")
                || name.ends_with("_array_call")
                || name.ends_with("_wasm_call")
                || name.contains("unsafe-intrinsics-")
                || name.contains("module_start")
            {
                Func::Trampoline
            } else if name.contains("libcall") || name.starts_with("component") {
                Func::Libcall
            } else {
                panic!("unknown symbol: {name}")
            };

            // Apply any filters, if provided, to this function to look at just
            // one function in the disassembly.
            if self.funcs.is_empty() {
                if kind != Func::Wasm {
                    continue;
                }
            } else {
                if !(self.funcs.contains(&Func::All) || self.funcs.contains(&kind)) {
                    continue;
                }
            }
            if let Some(filter) = &self.filter {
                if !name.contains(filter) {
                    continue;
                }
            }

            // Place a blank line between functions.
            if first {
                first = false;
            } else {
                writeln!(stdout)?;
            }

            // Print the function's address, if so desired. Then print the
            // function name.
            if self.addresses {
                stdout.set_color(color_address.clone().set_bold(true))?;
                write!(stdout, "{:08x} ", sym.address())?;
                stdout.reset()?;
            }
            stdout.set_color(ColorSpec::new().set_bold(true).set_fg(Some(Color::Green)))?;
            write!(stdout, "{name}")?;
            stdout.reset()?;
            writeln!(stdout, ":")?;

            // Tracking variables for rough heuristics of printing targets of
            // jump instructions for `--address-jumps` mode.
            let mut prev_jump = false;
            let mut write_offsets = false;

            for inst in disas::disas(&elf, bytes, sym.address())? {
                let Inst {
                    address,
                    is_jump,
                    is_return,
                    disassembly: disas,
                    bytes,
                } = inst;

                // Generate an infinite list of bytes to make printing below
                // easier, but only limit `inline_bytes` to get printed before
                // an instruction.
                let mut bytes = bytes.iter().map(Some).chain(iter::repeat(None));
                let inline_bytes = 9;
                let width = self.address_width;

                // Collect any "decorations" or annotations for this
                // instruction. This includes the address map, stack
                // maps, exception handlers, etc.
                //
                // Once they're collected then we print them before or
                // after the instruction attempting to use some
                // unicode characters to make it easier to read/scan.
                //
                // Note that some decorations occur "before" an
                // instruction: for example, exception handler entries
                // logically occur at the return point after a call,
                // so "before" the instruction following the call.
                let mut pre_decorations = Vec::new();
                let mut post_decorations = Vec::new();
                decorator.decorate(address, &mut pre_decorations, &mut post_decorations);

                let print_whitespace_to_decoration = |stdout: &mut dyn WriteColor| -> Result<()> {
                    write!(stdout, "{:width$}  ", "")?;
                    if self.bytes {
                        for _ in 0..inline_bytes + 1 {
                            write!(stdout, "   ")?;
                        }
                    }
                    Ok(())
                };

                let print_decorations =
                    |stdout: &mut dyn WriteColor, decorations: Vec<String>| -> Result<()> {
                        for (i, decoration) in decorations.iter().enumerate() {
                            print_whitespace_to_decoration(stdout)?;
                            let mut color = ColorSpec::new();
                            color.set_fg(Some(Color::Cyan));
                            stdout.set_color(&color)?;
                            let final_decoration = i == decorations.len() - 1;
                            if !final_decoration {
                                write!(stdout, "├")?;
                            } else {
                                write!(stdout, "╰")?;
                            }
                            for (i, line) in decoration.lines().enumerate() {
                                if i == 0 {
                                    write!(stdout, "─╼ ")?;
                                } else {
                                    print_whitespace_to_decoration(stdout)?;
                                    if final_decoration {
                                        write!(stdout, "    ")?;
                                    } else {
                                        write!(stdout, "│   ")?;
                                    }
                                }
                                writeln!(stdout, "{line}")?;
                            }
                            stdout.reset()?;
                        }
                        Ok(())
                    };

                print_decorations(&mut *stdout, pre_decorations)?;

                // Some instructions may disassemble to multiple lines, such as
                // `br_table` with Pulley. Handle separate lines per-instruction
                // here.
                for (i, line) in disas.lines().enumerate() {
                    let print_address = self.addresses
                        || (self.address_jumps && (write_offsets || (prev_jump && !is_jump)));
                    if i == 0 && print_address {
                        stdout.set_color(&color_address)?;
                        write!(stdout, "{address:>width$x}: ")?;
                        stdout.reset()?;
                    } else {
                        write!(stdout, "{:width$}  ", "")?;
                    }

                    // If we're printing inline bytes then print up to
                    // `inline_bytes` of instruction data, and any remaining
                    // data will go on the next line, if any, or after the
                    // instruction below.
                    if self.bytes {
                        stdout.set_color(&color_bytes)?;
                        for byte in bytes.by_ref().take(inline_bytes) {
                            match byte {
                                Some(byte) => write!(stdout, "{byte:02x} ")?,
                                None => write!(stdout, "   ")?,
                            }
                        }
                        write!(stdout, "  ")?;
                        stdout.reset()?;
                    }

                    writeln!(stdout, "{line}")?;
                }

                // Flip write_offsets to true once we've seen a `ret`, as
                // instructions that follow the return are often related to trap
                // tables.
                write_offsets |= is_return;
                prev_jump = is_jump;

                // After the instruction is printed then finish printing the
                // instruction bytes if any are present. Still limit to
                // `inline_bytes` per line.
                if self.bytes {
                    let mut inline = 0;
                    stdout.set_color(&color_bytes)?;
                    for byte in bytes {
                        let Some(byte) = byte else { break };
                        if inline == 0 {
                            write!(stdout, "{:width$}  ", "")?;
                        } else {
                            write!(stdout, " ")?;
                        }
                        write!(stdout, "{byte:02x}")?;
                        inline += 1;
                        if inline == inline_bytes {
                            writeln!(stdout)?;
                            inline = 0;
                        }
                    }
                    stdout.reset()?;
                    if inline > 0 {
                        writeln!(stdout)?;
                    }
                }

                print_decorations(&mut *stdout, post_decorations)?;
            }
        }
        Ok(())
    }

    /// Helper to read the input bytes of the `*.cwasm` handling stdin
    /// automatically.
    fn read_cwasm(&self) -> Result<Vec<u8>> {
        if let Some(path) = &self.cwasm {
            if path != Path::new("-") {
                return std::fs::read(path).with_context(|| format!("failed to read {path:?}"));
            }
        }

        let mut stdin = Vec::new();
        std::io::stdin()
            .read_to_end(&mut stdin)
            .context("failed to read stdin")?;
        Ok(stdin)
    }
}

#[derive(clap::ValueEnum, Clone, Copy, PartialEq, Eq)]
enum Func {
    All,
    Wasm,
    Trampoline,
    Builtin,
    Libcall,
}

struct Decorator<'a> {
    objdump: &'a ObjdumpCommand,
    addrmap: Option<Peekable<Box<dyn Iterator<Item = (u32, FilePos)> + 'a>>>,
    traps: Option<Peekable<Box<dyn Iterator<Item = (u32, CompiledTrap)> + 'a>>>,
    stack_maps: Option<Peekable<Box<dyn Iterator<Item = (u32, StackMap<'a>)> + 'a>>>,
    exception_tables:
        Option<Peekable<Box<dyn Iterator<Item = (u32, Option<u32>, Vec<ExceptionHandler>)> + 'a>>>,
    frame_tables: Option<
        Peekable<
            Box<
                dyn Iterator<
                        Item = (
                            u32,
                            FrameInstPos,
                            Vec<(ModulePC, FrameTableDescriptorIndex, FrameStackShape)>,
                        ),
                    > + 'a,
            >,
        >,
    >,

    // Breakpoint table, sorted by native offset instead so we can
    // display inline with disassembly (the table in the image is
    // sorted by Wasm PC).
    breakpoints: Peekable<Box<dyn Iterator<Item = (ModulePC, usize, SmallVec<[u8; 8]>)>>>,

    frame_table_descriptors: Option<FrameTable<'a>>,
}

impl Decorator<'_> {
    fn decorate(&mut self, address: u64, pre_list: &mut Vec<String>, post_list: &mut Vec<String>) {
        self.addrmap(address, post_list);
        self.traps(address, post_list);
        self.stack_maps(address, post_list);
        self.exception_table(address, pre_list);
        self.frame_table(address, pre_list, post_list);
        self.breakpoints(address, pre_list);
    }

    fn addrmap(&mut self, address: u64, list: &mut Vec<String>) {
        if !self.objdump.addrmap() {
            return;
        }
        let Some(addrmap) = &mut self.addrmap else {
            return;
        };
        while let Some((addr, pos)) = addrmap.next_if(|(addr, _pos)| u64::from(*addr) <= address) {
            if u64::from(addr) != address {
                continue;
            }
            if let Some(offset) = pos.file_offset() {
                list.push(format!("addrmap: {offset:#x}"));
            }
        }
    }

    fn traps(&mut self, address: u64, list: &mut Vec<String>) {
        if !self.objdump.traps() {
            return;
        }
        let Some(traps) = &mut self.traps else {
            return;
        };
        while let Some((addr, trap)) = traps.next_if(|(addr, _pos)| u64::from(*addr) <= address) {
            if u64::from(addr) != address {
                continue;
            }
            list.push(format!("trap: {trap:?}"));
        }
    }

    fn stack_maps(&mut self, address: u64, list: &mut Vec<String>) {
        if !self.objdump.stack_maps() {
            return;
        }
        let Some(stack_maps) = &mut self.stack_maps else {
            return;
        };
        while let Some((addr, stack_map)) =
            stack_maps.next_if(|(addr, _pos)| u64::from(*addr) <= address)
        {
            if u64::from(addr) != address {
                continue;
            }
            list.push(format!(
                "stack_map: frame_size={}, frame_offsets={:?}",
                stack_map.frame_size(),
                stack_map.offsets().collect::<Vec<_>>()
            ));
        }
    }

    fn exception_table(&mut self, address: u64, list: &mut Vec<String>) {
        if !self.objdump.exception_tables() {
            return;
        }
        let Some(exception_tables) = &mut self.exception_tables else {
            return;
        };
        while let Some((addr, frame_offset, handlers)) =
            exception_tables.next_if(|(addr, _, _)| u64::from(*addr) <= address)
        {
            if u64::from(addr) != address {
                continue;
            }
            if let Some(frame_offset) = frame_offset {
                list.push(format!(
                    "exception frame offset: SP = FP - 0x{frame_offset:x}",
                ));
            }
            for handler in &handlers {
                let tag = match handler.tag {
                    Some(tag) => format!("tag={tag}"),
                    None => "default handler".to_string(),
                };
                let context = match handler.context_sp_offset {
                    Some(offset) => format!("context at [SP+0x{offset:x}]"),
                    None => "no dynamic context".to_string(),
                };
                list.push(format!(
                    "exception handler: {tag}, {context}, handler=0x{:x}",
                    handler.handler_offset
                ));
            }
        }
    }

    fn frame_table(
        &mut self,
        address: u64,
        pre_list: &mut Vec<String>,
        post_list: &mut Vec<String>,
    ) {
        if !self.objdump.frame_tables() {
            return;
        }
        let (Some(frame_table_iter), Some(frame_tables)) =
            (&mut self.frame_tables, &self.frame_table_descriptors)
        else {
            return;
        };

        while let Some((addr, pos, frames)) =
            frame_table_iter.next_if(|(addr, _, _)| u64::from(*addr) <= address)
        {
            if u64::from(addr) != address {
                continue;
            }
            let list = match pos {
                // N.B.: the "post" position means that we are
                // attached to the end of the previous instruction
                // (its "post"); which means that from this
                // instruction's PoV, we print before the instruction
                // (the "pre list"). And vice versa for the "pre"
                // position. Hence the reversal here.
                FrameInstPos::Post => &mut *pre_list,
                FrameInstPos::Pre => &mut *post_list,
            };
            let pos = match pos {
                FrameInstPos::Post => "after previous inst",
                FrameInstPos::Pre => "before next inst",
            };
            for (wasm_pc, frame_descriptor, stack_shape) in frames {
                let (frame_descriptor_data, offset) =
                    frame_tables.frame_descriptor(frame_descriptor).unwrap();
                let frame_descriptor = FrameStateSlot::parse(frame_descriptor_data).unwrap();

                let local_shape = Self::describe_local_shape(&frame_descriptor);
                let stack_shape = Self::describe_stack_shape(&frame_descriptor, stack_shape);
                let func_key = frame_descriptor.func_key();
                list.push(format!("debug frame state ({pos}): func key {func_key:?}, wasm PC {wasm_pc}, slot at FP-0x{offset:x}, locals {local_shape}, stack {stack_shape}"));
            }
        }
    }

    fn breakpoints(&mut self, address: u64, list: &mut Vec<String>) {
        while let Some((wasm_pc, addr, patch)) = self.breakpoints.next_if(|(_, addr, patch)| {
            u64::try_from(*addr).unwrap() + u64::try_from(patch.len()).unwrap() <= address
        }) {
            if u64::try_from(addr).unwrap() + u64::try_from(patch.len()).unwrap() != address {
                continue;
            }
            list.push(format!(
                "breakpoint patch: wasm PC {wasm_pc}, patch bytes {patch:?}"
            ));
        }
    }

    fn describe_local_shape(desc: &FrameStateSlot<'_>) -> String {
        let mut parts = vec![];
        for (offset, ty) in desc.locals() {
            parts.push(format!("{ty:?} @ slot+0x{:x}", offset.offset()));
        }
        parts.join(", ")
    }

    fn describe_stack_shape(desc: &FrameStateSlot<'_>, shape: FrameStackShape) -> String {
        let mut parts = vec![];
        for (offset, ty) in desc.stack(shape) {
            parts.push(format!("{ty:?} @ slot+0x{:x}", offset.offset()));
        }
        parts.reverse();
        parts.join(", ")
    }
}