A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Data structures to provide transformation of the source
use crate::bytes::{read_sleb, read_uleb};
use core::fmt;
use object::{Bytes, LittleEndian, U32};
use serde_derive::{Deserialize, Serialize};
/// Single source location to generated address mapping.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub struct InstructionAddressMap {
/// Where in the source wasm binary this instruction comes from, specified
/// in an offset of bytes from the front of the file.
pub srcloc: FilePos,
/// Offset from the start of the function's compiled code to where this
/// instruction is located, or the region where it starts.
pub code_offset: u32,
}
/// A position within an original source file,
///
/// This structure is used as a newtype wrapper around a 32-bit integer which
/// represents an offset within a file where a wasm instruction or function is
/// to be originally found.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilePos(u32);
impl FilePos {
/// Create a new file position with the given offset.
pub fn new(pos: u32) -> FilePos {
assert!(pos != u32::MAX);
FilePos(pos)
}
/// Get the null file position.
pub fn none() -> FilePos {
FilePos(u32::MAX)
}
/// Is this the null file position?
#[inline]
pub fn is_none(&self) -> bool {
*self == FilePos::none()
}
/// Returns the offset that this offset was created with.
///
/// Note that positions created with `FilePos::none` and the `Default`
/// implementation will return `None` here, whereas positions created with
/// `FilePos::new` will return `Some`.
pub fn file_offset(self) -> Option<u32> {
if self.0 == u32::MAX {
None
} else {
Some(self.0)
}
}
}
impl Default for FilePos {
fn default() -> FilePos {
FilePos::none()
}
}
/// A Wasm bytecode offset relative to the start of a component (or
/// top-level module) binary.
///
/// When compiling a component, the Wasm parser returns source
/// positions relative to the entire component binary. This type
/// captures that convention. Use
/// [`ComponentPC::to_module_pc`] to convert to a
/// [`ModulePC`] given the byte offset of the module within the
/// component.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ComponentPC(u32);
impl ComponentPC {
/// Create a new component-relative PC from a raw offset.
pub fn new(offset: u32) -> Self {
Self(offset)
}
/// Get the raw u32 offset.
pub fn raw(self) -> u32 {
self.0
}
/// Convert to a module-relative PC by subtracting the byte offset
/// of the module within the component binary.
pub fn to_module_pc(self, wasm_module_offset: u64) -> ModulePC {
let offset = u32::try_from(wasm_module_offset).unwrap();
ModulePC(self.0 - offset)
}
}
impl fmt::Debug for ComponentPC {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "ComponentPC({:#x})", self.0)
}
}
impl fmt::Display for ComponentPC {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{:#x}", self.0)
}
}
/// A Wasm bytecode offset relative to the start of a core Wasm
/// module binary.
///
/// In the guest-debug system, PCs are always module-relative because
/// the debugger presents a core-Wasm view of the world where
/// components are deconstructed into individual core Wasm modules.
///
/// For standalone (non-component) modules, `ModulePC` and
/// [`ComponentPC`] values are numerically identical.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ModulePC(u32);
impl ModulePC {
/// Create a new module-relative PC from a raw offset.
pub fn new(offset: u32) -> Self {
Self(offset)
}
/// Get the raw u32 offset.
pub fn raw(self) -> u32 {
self.0
}
}
impl fmt::Debug for ModulePC {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "ModulePC({:#x})", self.0)
}
}
impl fmt::Display for ModulePC {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{:#x}", self.0)
}
}
/// Number of address-mapping entries packed into one block of the address map
/// section.
///
/// See `AddressMapSection` in `crate::compile` for the full section format.
/// Chosen as a balance between the fixed-width index overhead per block (8
/// bytes, amortized across entries) and the amount of linear decoding required
/// to look up a single pc within a block.
pub(crate) const ADDRMAP_BLOCK_SIZE: usize = 128;
/// A parsed view of the address map section.
///
/// The fields here correspond to the pieces of the section layout described
/// on `AddressMapSection` in `crate::compile`.
#[derive(Clone, Copy)]
struct AddressMap<'a> {
/// Total number of address-mapping entries in this section.
entries: usize,
/// One `(first_offset, block_pos)` pair per block.
block_index: &'a [[U32<LittleEndian>; 2]],
/// Variable-length block bodies, indexed by `block_pos` in the
/// `block_index` table above.
block_bodies: &'a [u8],
}
impl<'a> AddressMap<'a> {
/// Returns an iterator of `(text_offset, FilePos)` for all entries in
/// `block`, or `None` if the section is malformed.
fn block_entries(&self, block_index: usize) -> Option<BlockEntries<'a>> {
let [first_offset, block_pos] = self.block_index.get(block_index)?;
let first_offset = first_offset.get(LittleEndian);
let block_pos = block_pos.get(LittleEndian);
let block = self.block_bodies.get(usize::try_from(block_pos).ok()?..)?;
let remaining = core::cmp::min(
ADDRMAP_BLOCK_SIZE,
self.entries.checked_sub(block_index * ADDRMAP_BLOCK_SIZE)?,
);
Some(BlockEntries {
block,
prev_offset: first_offset,
prev_pos: None,
remaining,
})
}
}
/// Iterator over the entries of a single block, decoding the delta-and-flag
/// varints described in the "block body" portion of the section format on
/// `AddressMapSection` in `crate::compile`.
struct BlockEntries<'a> {
block: &'a [u8],
prev_offset: u32,
prev_pos: Option<u32>,
remaining: usize,
}
impl Iterator for BlockEntries<'_> {
type Item = (u32, FilePos);
fn next(&mut self) -> Option<(u32, FilePos)> {
self.remaining = self.remaining.checked_sub(1)?;
let token = read_uleb(&mut self.block)?;
let delta = u32::try_from(token >> 1).ok()?;
let cur_offset = self.prev_offset.checked_add(delta)?;
self.prev_offset = cur_offset;
if token & 1 != 0 {
return Some((cur_offset, FilePos::none()));
}
let pos = match self.prev_pos {
// The first non-none position of a block is encoded absolutely...
None => u32::try_from(read_uleb(&mut self.block)?).ok()?,
// ... and subsequent positions are sleb deltas from the previous
// non-none position.
Some(prev) => {
let delta = read_sleb(&mut self.block)?;
prev.checked_add_signed(i32::try_from(delta).ok()?)?
}
};
self.prev_pos = Some(pos);
Some((cur_offset, FilePos(pos)))
}
}
/// Parse an `ELF_WASMTIME_ADDRMAP` section into its header, block index, and
/// block bodies.
fn parse(section: &[u8]) -> Option<AddressMap<'_>> {
let mut section = Bytes(section);
// NB: this matches the encoding written by `AddressMapSection` in the
// `compile::address_map` module.
let entries = section.read::<U32<LittleEndian>>().ok()?;
let entries = usize::try_from(entries.get(LittleEndian)).ok()?;
let num_blocks = section.read::<U32<LittleEndian>>().ok()?;
let num_blocks = usize::try_from(num_blocks.get(LittleEndian)).ok()?;
let (block_index, block_bodies) =
object::slice_from_bytes::<[U32<LittleEndian>; 2]>(section.0, num_blocks).ok()?;
Some(AddressMap {
entries,
block_index,
block_bodies,
})
}
/// Lookup an `offset` within an encoded address map section, returning the
/// original `FilePos` that corresponds to the offset, if found.
///
/// This function takes a `section` as its first argument which must have been
/// created with `AddressMapSection` in `crate::compile`, whose documentation
/// describes the format decoded here. This is intended to be the raw
/// `ELF_WASMTIME_ADDRMAP` section from the compilation artifact.
///
/// The `offset` provided is a relative offset from the start of the text
/// section of the pc that is being looked up. If `offset` is out of range or
/// doesn't correspond to anything in this file then `None` is returned.
pub fn lookup_file_pos(section: &[u8], offset: usize) -> Option<FilePos> {
let section = parse(section)?;
let offset = u32::try_from(offset).ok()?;
// Find the last block whose first pc is `<= offset`. Note that, unlike the
// trap section, this is a bucket-style search: each entry covers addresses
// from its own `text_offset` until the next entry's, so `offset` need not
// match an entry exactly. The covering entry is wholly contained in this
// block since the next block only takes over at its own `first_offset`.
let block = section
.block_index
.partition_point(|[first_offset, _]| first_offset.get(LittleEndian) <= offset)
.checked_sub(1)?;
// Find the last entry within this block whose offset is `<= offset`; that
// entry's bucket covers `offset`. At least the block's first entry always
// qualifies due to the index search above.
let mut pos = None;
for (entry_offset, entry_pos) in section.block_entries(block)? {
if entry_offset > offset {
break;
}
pos = Some(entry_pos);
}
pos
}
/// Iterate over the address map contained in the given address map section.
///
/// This function takes a `section` as its first argument which must have been
/// created with `AddressMapSection` in `crate::compile`. This is intended to
/// be the raw `ELF_WASMTIME_ADDRMAP` section from the compilation artifact.
///
/// The yielded offsets are relative to the start of the text section for this
/// map's code object.
pub fn iterate_address_map<'a>(
section: &'a [u8],
) -> Option<impl Iterator<Item = (u32, FilePos)> + 'a> {
let section = parse(section)?;
Some(
(0..section.block_index.len())
.flat_map(move |block| section.block_entries(block).into_iter().flatten()),
)
}