Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Add CLI options for unsafe intrinsics and compile-time builtins (#14279)

Nick Fitzgeraldb7764a705c24
diff --git a/Cargo.toml b/Cargo.toml
index a95a92d793..61666ce647 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -165,7 +165,7 @@ features = [
'memory-protection-keys',
'component-model-async',
'component-model-bytes',
- 'gc-copying'
+ 'gc-copying',
]
[target.'cfg(windows)'.dev-dependencies]
@@ -523,6 +523,7 @@ default = [
"debug-builtins",
"component-model",
"component-model-async",
+ "compile-time-builtins",
"threads",
"gc",
"gc-copying",
@@ -589,6 +590,7 @@ component-model = [
"wasmtime-cli-flags/component-model",
"wasmtime-wizer?/component-model",
]
+compile-time-builtins = ["component-model", "wasmtime/compile-time-builtins"]
wat = ["dep:wat", "wasmtime/wat"]
cache = ["dep:wasmtime-cache", "wasmtime-cli-flags/cache"]
parallel-compilation = ["wasmtime-cli-flags/parallel-compilation"]
diff --git a/crates/cli-flags/src/lib.rs b/crates/cli-flags/src/lib.rs
index 5d8e45214a..9ed7e31ba0 100644
--- a/crates/cli-flags/src/lib.rs
+++ b/crates/cli-flags/src/lib.rs
@@ -285,6 +285,55 @@ wasmtime_option_group! {
/// corruption in compiled code.
pub metadata_for_gc_heap_corruption: Option<bool>,
+ /// Expose Wasmtime's unsafe intrinsics to the Wasm being compiled under
+ /// the given instance import name, which defaults to
+ /// `unsafe-intrinsics` when the name is omitted.
+ ///
+ /// The unsafe intrinsics are a set of raw, unchecked load and store
+ /// operations on the host's address space, along with the address of
+ /// the store's data. They may only be used with components, not core
+ /// Wasm modules.
+ ///
+ /// This is wildly unsafe: the Wasm is given the ability to read and
+ /// write arbitrary host memory. Only use this with Wasm that you trust
+ /// as much as you trust the CLI itself.
+ ///
+ /// When `-C compile-time-builtin` is also given, the intrinsics are
+ /// exposed only to the compile-time builtins and not to the main Wasm
+ /// program.
+ ///
+ /// See the API documentation for
+ /// `CodeBuilder::expose_unsafe_intrinsics` for more details.
+ #[serde(default)]
+ #[serde(deserialize_with = "crate::opt::deserialize_cli_parse_wrapper")]
+ #[serde(serialize_with = "crate::opt::serialize_cli_parse_wrapper")]
+ pub unsafe_intrinsics: Option<UnsafeIntrinsicsImport>,
+
+ /// Define a compile-time builtin: satisfy the `<name>` instance import
+ /// of the main component with the component at `<path>` at compile
+ /// time, rather than with a host-defined import at instantiation time.
+ ///
+ /// May be specified multiple times, once per builtin. Compile-time
+ /// builtins may only be used with components, not core Wasm modules,
+ /// and require `-C unsafe-intrinsics`.
+ ///
+ /// The `<name>=` prefix may be omitted, in which case `<name>` defaults
+ /// to the file name of `<path>` without its extension. For example
+ /// `-C compile-time-builtin=path/to/my-host-api.wat` satisfies the
+ /// `my-host-api` import. Note that a `<path>` which itself contains an
+ /// `=` is interpreted as the `<name>=<path>` form; pass the explicit
+ /// form to disambiguate.
+ ///
+ /// Compile-time builtins are part of your trusted compute base: they
+ /// are given access to the unsafe intrinsics described above. Calls
+ /// into them become direct calls, so pass `-C inlining=y` to let them
+ /// be inlined into their callers.
+ ///
+ /// See the API documentation for
+ /// `CodeBuilder::compile_time_builtin_binary` for more details.
+ #[serde(skip)]
+ pub compile_time_builtin: Vec<CompileTimeBuiltin>,
+
#[prefixed = "cranelift"]
#[serde(default)]
/// Set a cranelift-specific option. Use `wasmtime settings` to see
@@ -621,6 +670,20 @@ pub struct KeyValuePair {
pub value: String,
}
+/// The instance import name under which Wasmtime's unsafe intrinsics are
+/// exposed to the Wasm being compiled.
+#[derive(Debug, Clone, PartialEq)]
+pub struct UnsafeIntrinsicsImport(pub String);
+
+/// A compile-time builtin.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CompileTimeBuiltin {
+ /// The instance import name that this satisfies in the main component.
+ pub name: String,
+ /// The path to the component that implements this builtin.
+ pub path: PathBuf,
+}
+
/// Common options for commands that translate WebAssembly modules
#[derive(Clone)]
#[cfg_attr(feature = "clap", derive(clap::Parser))]
@@ -1419,6 +1482,11 @@ impl CommonOptions {
// arbitrary code-defined caches.
cache: None,
cache_config: None,
+
+ // These are configured per-`CodeBuilder`, so they cannot be
+ // recovered here.
+ unsafe_intrinsics: None,
+ compile_time_builtin: Vec::new(),
},
debug: DebugOptions {
address_map: Some(engine.get_generate_address_map()),
diff --git a/crates/cli-flags/src/opt.rs b/crates/cli-flags/src/opt.rs
index 54ffd4256d..a472062837 100644
--- a/crates/cli-flags/src/opt.rs
+++ b/crates/cli-flags/src/opt.rs
@@ -5,7 +5,7 @@
//! specifying options in a struct-like syntax where all other boilerplate about
//! option parsing is contained exclusively within this module.
-use crate::{KeyValuePair, WasiNnGraph};
+use crate::{CompileTimeBuiltin, KeyValuePair, UnsafeIntrinsicsImport, WasiNnGraph};
#[cfg(feature = "clap")]
use clap::builder::{StringValueParser, TypedValueParser, ValueParserFactory};
#[cfg(feature = "clap")]
@@ -14,7 +14,7 @@ use clap::error::{Error, ErrorKind};
use serde::de::{self, Visitor};
use std::fmt;
use std::num::NonZeroU32;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
use std::str::FromStr;
use std::time::Duration;
use wasmtime::error::Context;
@@ -705,6 +705,63 @@ impl WasmtimeOptionValue for KeyValuePair {
}
}
+impl WasmtimeOptionValue for UnsafeIntrinsicsImport {
+ const VAL_HELP: &'static str = "[=name]";
+ fn parse(val: Option<&str>) -> Result<Self> {
+ match val {
+ None => Ok(UnsafeIntrinsicsImport("unsafe-intrinsics".to_string())),
+ Some("") => bail!("the unsafe intrinsics import name cannot be empty"),
+ Some(val) => Ok(UnsafeIntrinsicsImport(val.to_string())),
+ }
+ }
+
+ fn display(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+impl WasmtimeOptionValue for CompileTimeBuiltin {
+ const VAL_HELP: &'static str = "=[<name>=]<path>";
+ fn parse(val: Option<&str>) -> Result<Self> {
+ let val = String::parse(val)?;
+
+ if let Some((name, path)) = val.split_once('=') {
+ if name.is_empty() {
+ bail!("the compile-time builtin's name cannot be empty in `{val}`");
+ }
+ if path.is_empty() {
+ bail!("the compile-time builtin's path cannot be empty in `{val}`");
+ }
+ return Ok(CompileTimeBuiltin {
+ name: name.to_string(),
+ path: PathBuf::from(path),
+ });
+ }
+
+ // No `<name>` was given: derive it from the file name of `<path>`, with
+ // its extension removed.
+ let path = PathBuf::from(&val);
+ let name = path
+ .file_stem()
+ .ok_or_else(|| format_err!("cannot derive a compile-time builtin name from `{val}`"))?
+ .to_str()
+ .ok_or_else(|| {
+ format_err!("compile-time builtin name derived from `{val}` is not valid UTF-8")
+ })?
+ .to_string();
+ if name.is_empty() {
+ bail!("compile-time builtin name derived from `{val}` is empty");
+ }
+ Ok(CompileTimeBuiltin { name, path })
+ }
+
+ fn display(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ // Always write the canonical `<name>=<path>` form so that this
+ // round-trips back through `parse` regardless of the file name.
+ write!(f, "{}={}", self.name, Path::display(&self.path))
+ }
+}
+
pub trait OptionContainer<T> {
fn push(&mut self, val: T);
fn get<'a>(&'a self) -> impl Iterator<Item = &'a T>
diff --git a/src/code_builder.rs b/src/code_builder.rs
new file mode 100644
index 0000000000..191779373a
--- /dev/null
+++ b/src/code_builder.rs
@@ -0,0 +1,34 @@
+use wasmtime::Result;
+use wasmtime_cli_flags::CommonOptions;
+
+/// Apply the `-C unsafe-intrinsics` and `-C compile-time-builtin` options in
+/// `common` to `code`.
+pub fn configure_code_builder(
+ common: &CommonOptions,
+ code: &mut wasmtime::CodeBuilder<'_>,
+) -> Result<()> {
+ if let Some(name) = &common.codegen.unsafe_intrinsics {
+ // SAFETY: the user opted into this by passing flags that are documented
+ // as unsafe.
+ unsafe {
+ code.expose_unsafe_intrinsics(name.0.clone());
+ }
+ }
+
+ #[cfg(feature = "compile-time-builtins")]
+ for builtin in &common.codegen.compile_time_builtin {
+ // SAFETY: the user opted into this by passing flags that are documented
+ // as unsafe.
+ unsafe {
+ code.compile_time_builtins_binary_or_text_file(builtin.name.clone(), &builtin.path)?;
+ }
+ }
+
+ #[cfg(not(feature = "compile-time-builtins"))]
+ wasmtime::ensure!(
+ common.codegen.compile_time_builtin.is_empty(),
+ "support for compile-time-builtins disabled at compile time",
+ );
+
+ Ok(())
+}
diff --git a/src/commands/compile.rs b/src/commands/compile.rs
index c6c1ad0f03..3422869622 100644
--- a/src/commands/compile.rs
+++ b/src/commands/compile.rs
@@ -80,6 +80,7 @@ impl CompileCommand {
let mut code = CodeBuilder::new(&engine);
code.wasm_binary_or_text_file(&self.module)?;
+ crate::code_builder::configure_code_builder(&self.common, &mut code)?;
let output = self.output.take().unwrap_or_else(|| {
let mut output: PathBuf = self.module.file_name().unwrap().into();
diff --git a/src/commands/hot_blocks.rs b/src/commands/hot_blocks.rs
index 439d61a700..a60a394354 100644
--- a/src/commands/hot_blocks.rs
+++ b/src/commands/hot_blocks.rs
@@ -208,6 +208,7 @@ impl HotBlocksCommand {
let mut code = CodeBuilder::new(&engine);
code.wasm_binary_or_text(wasm_bytes, Some(&self.module))?;
+ crate::code_builder::configure_code_builder(&self.run.common, &mut code)?;
let serialized = match code.hint() {
#[cfg(feature = "component-model")]
diff --git a/src/common.rs b/src/common.rs
index 769854337b..2d3cab0e75 100644
--- a/src/common.rs
+++ b/src/common.rs
@@ -285,6 +285,7 @@ impl RunCommon {
None => {
let mut code = wasmtime::CodeBuilder::new(engine);
code.wasm_binary_or_text(bytes, Some(path))?;
+ crate::code_builder::configure_code_builder(&self.common, &mut code)?;
match code.hint() {
Some(wasmtime::CodeHint::Component) => {
#[cfg(feature = "component-model")]
diff --git a/src/lib.rs b/src/lib.rs
index 4bc3898c83..7476c852c4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -6,6 +6,9 @@
pub mod commands;
+#[cfg(any(feature = "cranelift", feature = "winch"))]
+pub(crate) mod code_builder;
+
#[cfg(any(feature = "run", feature = "wizer"))]
pub(crate) mod common;
diff --git a/tests/all/cli_tests.rs b/tests/all/cli_tests.rs
index 3c6d9ce51e..5e230add13 100644
--- a/tests/all/cli_tests.rs
+++ b/tests/all/cli_tests.rs
@@ -3598,3 +3598,220 @@ fn environment_configuration() -> Result<()> {
)?;
Ok(())
}
+
+#[test]
+fn unsafe_intrinsics_bare_flag() -> Result<()> {
+ // The bare flag defaults the import name to `unsafe-intrinsics`, which is
+ // what the component imports.
+ run_wasmtime(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics",
+ "tests/all/cli_tests/unsafe-intrinsics.wat",
+ ])?;
+ Ok(())
+}
+
+#[test]
+fn unsafe_intrinsics_named() -> Result<()> {
+ run_wasmtime(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics=unsafe-intrinsics",
+ "tests/all/cli_tests/unsafe-intrinsics.wat",
+ ])?;
+
+ // Exposing the intrinsics under a different name leaves the component's
+ // import unsatisfied.
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics=some-other-name",
+ "tests/all/cli_tests/unsafe-intrinsics.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("component imports instance `unsafe-intrinsics`"),
+ "bad stderr: {stderr}"
+ );
+
+ Ok(())
+}
+
+#[test]
+fn unsafe_intrinsics_rejects_core_module() -> Result<()> {
+ let output = get_wasmtime_command()?
+ .args(&["-C", "unsafe-intrinsics", "tests/all/cli_tests/simple.wat"])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("can only be used with components"),
+ "bad stderr: {stderr}"
+ );
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtins() -> Result<()> {
+ // The main component traps unless both builtins are actually linked in and
+ // return their expected values.
+ run_wasmtime(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics",
+ "-C",
+ "inlining=y",
+ "-C",
+ "compile-time-builtin=host-api-a=tests/all/cli_tests/host-api-a.wat",
+ "-C",
+ "compile-time-builtin=host-api-b=tests/all/cli_tests/host-api-b.wat",
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])?;
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtin_name_defaults_to_file_stem() -> Result<()> {
+ // Both fixtures' file stems are exactly the import names they satisfy, so
+ // the `<name>=` prefix can be omitted.
+ run_wasmtime(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-a.wat",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-b.wat",
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])?;
+
+ // A file whose stem is *not* the import name leaves `host-api-b`
+ // unsatisfied.
+ let td = TempDir::new()?;
+ let other = td.path().join("some-other-name.wat");
+ std::fs::copy("tests/all/cli_tests/host-api-b.wat", &other)?;
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-a.wat",
+ "-C",
+ &format!("compile-time-builtin={}", other.display()),
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(stderr.contains("host-api-b"), "bad stderr: {stderr}");
+
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtins_require_intrinsics() -> Result<()> {
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-Wcomponent-model",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-a.wat",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-b.wat",
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("must configure the unsafe-intrinsics import"),
+ "bad stderr: {stderr}"
+ );
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtin_bad_syntax() -> Result<()> {
+ // Empty value: there is no file stem to derive a name from.
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-C",
+ "compile-time-builtin=",
+ "tests/all/cli_tests/simple.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("cannot derive a compile-time builtin name"),
+ "bad stderr: {stderr}"
+ );
+
+ // Empty name in the explicit `<name>=<path>` form.
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-C",
+ "compile-time-builtin==host-api-a.wat",
+ "tests/all/cli_tests/simple.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("name cannot be empty"),
+ "bad stderr: {stderr}"
+ );
+
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtin_missing_file() -> Result<()> {
+ let output = get_wasmtime_command()?
+ .args(&[
+ "-Wcomponent-model",
+ "-C",
+ "unsafe-intrinsics",
+ "-C",
+ "compile-time-builtin=host-api-a=tests/all/cli_tests/does-not-exist.wat",
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])
+ .output()?;
+ assert!(!output.status.success());
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ stderr.contains("tests/all/cli_tests/does-not-exist.wat"),
+ "bad stderr: {stderr}"
+ );
+ Ok(())
+}
+
+#[test]
+fn compile_time_builtins_compile_subcommand() -> Result<()> {
+ let td = TempDir::new()?;
+ let cwasm = td.path().join("compile-time-builtin-main.cwasm");
+ run_wasmtime(&[
+ "compile",
+ "-C",
+ "unsafe-intrinsics",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-a.wat",
+ "-C",
+ "compile-time-builtin=tests/all/cli_tests/host-api-b.wat",
+ "-o",
+ cwasm.to_str().unwrap(),
+ "tests/all/cli_tests/compile-time-builtin-main.wat",
+ ])?;
+
+ run_wasmtime(&[
+ "-Wcomponent-model",
+ "--allow-precompiled",
+ cwasm.to_str().unwrap(),
+ ])?;
+
+ Ok(())
+}
diff --git a/tests/all/cli_tests/compile-time-builtin-main.wat b/tests/all/cli_tests/compile-time-builtin-main.wat
new file mode 100644
index 0000000000..f3e7bae18f
--- /dev/null
+++ b/tests/all/cli_tests/compile-time-builtin-main.wat
@@ -0,0 +1,34 @@
+;; A component whose two instance imports are meant to be satisfied at compile
+;; time by `host-api-a.wat` and `host-api-b.wat`. It traps unless both builtins
+;; are actually wired up and return their expected values.
+(component
+ (import "host-api-a" (instance $a
+ (export "get" (func (result u32)))))
+ (import "host-api-b" (instance $b
+ (export "get" (func (result u32)))))
+
+ (core func $a-get (canon lower (func $a "get")))
+ (core func $b-get (canon lower (func $b "get")))
+
+ (core module $m
+ (import "" "a-get" (func $a-get (result i32)))
+ (import "" "b-get" (func $b-get (result i32)))
+ (func (export "run") (result i32)
+ (if (i32.ne (call $a-get) (i32.const 42))
+ (then unreachable))
+ (if (i32.ne (call $b-get) (i32.const 100))
+ (then unreachable))
+ i32.const 0)
+ )
+
+ (core instance $i
+ (instantiate $m
+ (with "" (instance (export "a-get" (func $a-get))
+ (export "b-get" (func $b-get))))))
+
+ (func $run (result (result))
+ (canon lift (core func $i "run")))
+
+ (instance (export (interface "wasi:cli/[email protected]"))
+ (export "run" (func $run)))
+)
diff --git a/tests/all/cli_tests/host-api-a.wat b/tests/all/cli_tests/host-api-a.wat
new file mode 100644
index 0000000000..dece871cac
--- /dev/null
+++ b/tests/all/cli_tests/host-api-a.wat
@@ -0,0 +1,15 @@
+;; A compile-time builtin implementing the `host-api-a` import of
+;; `compile-time-builtin-main.wat`.
+;;
+;; Note that the file stem is the same as the import name it satisfies, so that
+;; `-C compile-time-builtin=path/to/host-api-a.wat` works without an explicit
+;; name.
+(component
+ (core module $m
+ (func (export "get") (result i32)
+ i32.const 42)
+ )
+ (core instance $i (instantiate $m))
+ (func (export "get") (result u32)
+ (canon lift (core func $i "get")))
+)
diff --git a/tests/all/cli_tests/host-api-b.wat b/tests/all/cli_tests/host-api-b.wat
new file mode 100644
index 0000000000..f12e59361f
--- /dev/null
+++ b/tests/all/cli_tests/host-api-b.wat
@@ -0,0 +1,11 @@
+;; A compile-time builtin implementing the `host-api-b` import of
+;; `compile-time-builtin-main.wat`. See `host-api-a.wat`.
+(component
+ (core module $m
+ (func (export "get") (result i32)
+ i32.const 100)
+ )
+ (core instance $i (instantiate $m))
+ (func (export "get") (result u32)
+ (canon lift (core func $i "get")))
+)
diff --git a/tests/all/cli_tests/unsafe-intrinsics.wat b/tests/all/cli_tests/unsafe-intrinsics.wat
new file mode 100644
index 0000000000..28bfec587b
--- /dev/null
+++ b/tests/all/cli_tests/unsafe-intrinsics.wat
@@ -0,0 +1,31 @@
+;; A component that uses Wasmtime's unsafe intrinsics, exposed via
+;; `-C unsafe-intrinsics`.
+;;
+;; This only reads the address of the store's data and asserts that it is
+;; non-null; it never dereferences that pointer, so it does not depend on the
+;; layout of the `wasmtime` CLI's store data.
+(component
+ (import "unsafe-intrinsics" (instance $intrinsics
+ (export "store-data-address" (func (result u64)))))
+
+ (core func $store-data-address
+ (canon lower (func $intrinsics "store-data-address")))
+
+ (core module $m
+ (import "" "store-data-address" (func $store-data-address (result i64)))
+ (func (export "run") (result i32)
+ (if (i64.eqz (call $store-data-address))
+ (then unreachable))
+ i32.const 0)
+ )
+
+ (core instance $i
+ (instantiate $m
+ (with "" (instance (export "store-data-address" (func $store-data-address))))))
+
+ (func $run (result (result))
+ (canon lift (core func $i "run")))
+
+ (instance (export (interface "wasi:cli/[email protected]"))
+ (export "run" (func $run)))
+)