A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Debug utils for WebAssembly using Cranelift.
// FIXME: this whole crate opts-in to these two noisier-than-default lints, but
// this module has lots of hits on this warning which aren't the easiest to
// resolve. Ideally all warnings would be resolved here though.
#![expect(
clippy::cast_possible_truncation,
clippy::cast_sign_loss,
reason = "haven't had a chance to fix these yet"
)]
use crate::CompiledFunctionMetadata;
use core::fmt;
use cranelift_codegen::isa::TargetIsa;
use object::write::SymbolId;
use std::collections::HashMap;
use wasmtime_environ::{
DefinedFuncIndex, DefinedMemoryIndex, EntityRef, MemoryIndex, ModuleTranslation,
OwnedMemoryIndex, PrimaryMap, PtrSize, StaticModuleIndex, Tunables, VMOffsets,
};
/// Memory definition offset in the VMContext structure.
#[derive(Debug, Clone)]
pub enum ModuleMemoryOffset {
/// Not available.
None,
/// Offset to the defined memory.
Defined(u32),
/// This memory is imported.
Imported {
/// Offset, in bytes, to the `*mut VMMemoryDefinition` structure within
/// `VMContext`.
offset_to_vm_memory_definition: u32,
/// Offset, in bytes within `VMMemoryDefinition` where the `base` field
/// lies.
offset_to_memory_base: u32,
},
}
type Reader<'input> = gimli::EndianSlice<'input, gimli::LittleEndian>;
/// "Package structure" to collect together various artifacts/results of a
/// compilation.
///
/// This structure is threaded through a number of top-level functions of DWARF
/// processing within in this submodule to pass along all the bits-and-pieces of
/// the compilation context.
pub struct Compilation<'a> {
/// All module translations which were present in this compilation.
///
/// This map has one entry for core wasm modules and may have multiple (or
/// zero) for components.
translations: &'a PrimaryMap<StaticModuleIndex, ModuleTranslation<'a>>,
/// Accessor of a particular compiled function for a module.
///
/// This returns the `object`-based-symbol for the function as well as the
/// `&CompiledFunction`.
get_func: &'a dyn Fn(
StaticModuleIndex,
DefinedFuncIndex,
) -> (Option<SymbolId>, &'a CompiledFunctionMetadata),
/// Optionally-specified `*.dwp` file, currently only supported for core
/// wasm modules.
dwarf_package_bytes: Option<&'a [u8]>,
/// Compilation settings used when producing functions.
tunables: &'a Tunables,
/// Translation between `SymbolId` and a `usize`-based symbol which gimli
/// uses.
symbol_index_to_id: Vec<Option<SymbolId>>,
symbol_id_to_index: HashMap<SymbolId, (usize, StaticModuleIndex, DefinedFuncIndex)>,
/// The `ModuleMemoryOffset` for each module within `translations`.
///
/// Note that this doesn't support multi-memory at this time.
module_memory_offsets: PrimaryMap<StaticModuleIndex, ModuleMemoryOffset>,
}
impl<'a> Compilation<'a> {
pub fn new(
isa: &dyn TargetIsa,
translations: &'a PrimaryMap<StaticModuleIndex, ModuleTranslation<'a>>,
get_func: &'a dyn Fn(
StaticModuleIndex,
DefinedFuncIndex,
) -> (Option<SymbolId>, &'a CompiledFunctionMetadata),
dwarf_package_bytes: Option<&'a [u8]>,
tunables: &'a Tunables,
) -> Compilation<'a> {
// Build the `module_memory_offsets` map based on the modules in
// `translations`.
let mut module_memory_offsets = PrimaryMap::new();
for (i, translation) in translations {
let ofs = VMOffsets::new(
isa.triple().architecture.pointer_width().unwrap().bytes(),
&translation.module,
);
let memory_offset = if ofs.num_imported_memories > 0 {
let index = MemoryIndex::new(0);
ModuleMemoryOffset::Imported {
offset_to_vm_memory_definition: ofs.imported_memories().at(index)
+ u32::from(ofs.ptr.vm_memory_import().from()),
offset_to_memory_base: ofs.ptr.vm_memory_definition().base().into(),
}
} else if ofs.num_owned_memories > 0 {
let index = OwnedMemoryIndex::new(0);
ModuleMemoryOffset::Defined(
ofs.owned_memories().at(index)
+ u32::from(ofs.ptr.vm_memory_definition().base()),
)
} else if ofs.num_defined_memories > 0 {
let index = DefinedMemoryIndex::new(0);
ModuleMemoryOffset::Imported {
offset_to_vm_memory_definition: ofs.memories().at(index),
offset_to_memory_base: ofs.ptr.vm_memory_definition().base().into(),
}
} else {
ModuleMemoryOffset::None
};
let j = module_memory_offsets.push(memory_offset);
assert_eq!(i, j);
}
// Build the `symbol <=> usize` mappings
let mut symbol_index_to_id = Vec::new();
let mut symbol_id_to_index = HashMap::new();
for (module, translation) in translations {
for func in translation.module.defined_func_indices() {
let (sym, _func) = get_func(module, func);
if let Some(sym) = sym {
symbol_id_to_index.insert(sym, (symbol_index_to_id.len(), module, func));
}
symbol_index_to_id.push(sym);
}
}
Compilation {
translations,
get_func,
dwarf_package_bytes,
tunables,
symbol_index_to_id,
symbol_id_to_index,
module_memory_offsets,
}
}
/// Returns an iterator over all function indexes present in this
/// compilation.
///
/// Each function is additionally accompanied with its module index.
fn indexes(&self) -> impl Iterator<Item = (StaticModuleIndex, DefinedFuncIndex)> + use<'_> {
self.translations
.iter()
.flat_map(|(i, t)| t.module.defined_func_indices().map(move |j| (i, j)))
}
/// Returns an iterator of all functions with their module, symbol, and
/// function metadata that were produced during compilation.
fn functions(
&self,
) -> impl Iterator<
Item = (
StaticModuleIndex,
Option<usize>,
&'a CompiledFunctionMetadata,
),
> + '_ {
self.indexes().map(move |(module, func)| {
let (sym, func) = self.function(module, func);
(module, sym, func)
})
}
/// Returns the symbol and metadata associated with a specific function.
fn function(
&self,
module: StaticModuleIndex,
func: DefinedFuncIndex,
) -> (Option<usize>, &'a CompiledFunctionMetadata) {
let (sym, func) = (self.get_func)(module, func);
(sym.map(|sym| self.symbol_id_to_index[&sym].0), func)
}
/// Maps a `usize`-based symbol used by gimli to the object-based
/// `SymbolId`.
pub fn symbol_id(&self, sym: usize) -> Option<SymbolId> {
self.symbol_index_to_id[sym]
}
}
impl<'a> fmt::Debug for Compilation<'a> {
// Sample output: '[#0: OneModule, #1: TwoModule, #3]'.
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "[")?;
let mut is_first_module = true;
for (i, translation) in self.translations {
if !is_first_module {
write!(f, ", ")?;
} else {
is_first_module = false;
}
write!(f, "#{}", i.as_u32())?;
if let Some(name) = translation.debuginfo.name_section.module_name {
write!(f, ": {name}")?;
}
}
write!(f, "]")
}
}
pub use write_debuginfo::{DwarfSectionRelocTarget, emit_dwarf};
mod gc;
mod transform;
mod write_debuginfo;