Skip to main content

Crate sf_nano_core

Crate sf_nano_core 

Source
Expand description

§Silverfir-nano

A compact optimizing WebAssembly JIT and interpreter with a shared embedding API. The core supports hosted systems and no_std environments with an allocator. Available WebAssembly proposals and execution engines depend on the target; see engine and target support.

§Installation

[dependencies]
sf-nano-core = "0.7"

For an interpreter-only build:

[dependencies]
sf-nano-core = { version = "0.7", default-features = false, features = ["interp"] }

§Embedding

Create an engine, instantiate a binary WebAssembly module, then obtain and call an exported function:

use sf_nano_core::{Config, Engine, Instance, Value};

// (module (func (export "answer") (result i32) i32.const 42))
let wasm = b"\0asm\x01\0\0\0\x01\x05\x01\x60\0\x01\x7f\x03\x02\x01\0\x07\x0a\x01\x06answer\0\0\x0a\x06\x01\x04\0\x41\x2a\x0b";

let engine = Engine::new(Config::new()).expect("valid configuration");
let mut instance = Instance::new(&engine, wasm, &[]).expect("valid module");
let answer = instance.get_func("answer").expect("exported function");
let mut results = [Value::I32(0)];
instance.call(&answer, &[], &mut results).expect("successful call");
assert_eq!(results, [Value::I32(42)]);

Instance::new and Module::new validate input. Module::new_unchecked is unsafe and requires the caller to establish full WebAssembly semantic validity; encoding WAT or merely decoding binary input is insufficient. Module input is owned, so the source byte slice may be released after construction.

Use Import::func_typed for host functions and Instance::get_export with Import::new for module exports. RuntimeWorld owns linked instances. Function handles belong to their originating instance; passing one to another instance returns an error.

Use Import::alias to bind the same import under another name without changing its identity, type or captured state. Host-created exception tags accept numeric and abstract-reference parameters; tags with concrete module types are linked through Instance::get_export and Import::new so their type context is retained.

Func::to_value produces an opaque function reference. Engine references are bound to their RuntimeWorld; passing them to another world or using them after their owner is freed returns an error. Copying a reference does not keep its owner alive. Null references and labels created with RefValue::hostref or externref are portable between worlds. Labels are integers below 2^27, not owned Rust objects. Raw engine reference encodings are not public API.

Host callbacks must fill every result with a value of the declared type. Incorrect types, missing results and foreign references trap before execution continues. The interpreter currently supports at most eight results from a host function. Caller::throw supports host exceptions; the interpreter can catch them in Wasm, while the current JIT propagates them to the embedding caller even when Wasm declares a matching handler.

Limits::new and Limits::new_64 construct immutable memory/table limits and return WasmError for inconsistent bounds. WASM_PAGE_SIZE is available at the crate root. Runtime configuration and errors are also imported from the root (Config, ConfigError, WasmError).

§Linear memory

Instance::memory and Instance::memory_mut return guarded views that dereference to byte slices. Drop the view before calling or instantiating in the same runtime world. Multiple read views may coexist; a mutable view is exclusive within its world. Conflicting access returns an error. Views keep the memory backing alive even if its original instance is freed.

use sf_nano_core::{Config, Engine, Instance};

// (module (memory 1))
let wasm = b"\0asm\x01\0\0\0\x05\x03\x01\0\x01";
let engine = Engine::new(Config::new()).expect("configuration");
let mut instance = Instance::new(&engine, wasm, &[]).expect("module");
let mut memory = instance.memory_mut().expect("exclusive view");
memory[0] = 42;
drop(memory);
assert_eq!(instance.memory().expect("read view")[0], 42);

During a host callback, access guest memory through Caller::memory or Caller::memory_mut. An external instance view cannot be acquired while its world is executing. A callback’s memory borrow prevents reentrant guest access to that memory until the callback returns.

§Features

The supported minimum Rust version is 1.94. CI checks that compiler separately from current stable. Raising the minimum requires API review.

FeaturePurpose
jitCompile WebAssembly to native machine code.
interpRun the interpreter generated for the target at build time.
guard-pagesEnable JIT memory guards where the target supports them; implies jit.
wasiInclude WASI preview1 host imports on supported hosted targets.
memprofEnable internal diagnostic hooks; embedding types remain unchanged.
interp-count, call-trace, jit-debugOptional execution and compilation diagnostics.

The defaults are jit, interp and guard-pages. Disable defaults to select one engine. At least one engine must be enabled. Config::tier selects among the engines compiled into the package; the default prefers the JIT. Bare-metal applications must provide an allocator and configure their memory budgets; hosted default budgets do not apply there. Disable default features for bare metal: guard-pages, wasi, call-trace, jit-debug, and the allocation profiler require std. There is no separate std feature.

A bare-metal JIT embedder must also supply executable-memory allocation, release, write-permission and instruction-cache synchronization hooks; see the bare-metal hook contract. Interpreter-only builds do not need executable-memory hooks.

WASI imports consume a context built with WasiContextBuilder. Separate import sets isolate arguments, environment and file descriptors. Reusing an import set intentionally shares that context. The repository’s invoke_export example shows file loading, WASI setup and execution. From a repository checkout:

cargo run --release -p sf-nano-core --features wasi --example invoke_export -- module.wasm export_name

That example inherits the host environment and preopens the current directory; choose the context explicitly when embedding untrusted guests.

The sf-nano-tracked-alloc dependency supplies internal allocation helpers. Embedders ordinarily depend only on sf-nano-core; the helper’s diagnostic interface is not part of this crate’s embedding API.

§Engine and target support

Both engines have backends for x86_64, ARM64, RV64, RV32, ARMv7-A and Thumb-2. The interpreter does not execute SIMD or GC instructions. JIT SIMD is available on ARM64 with NEON and on x86_64 with SSSE3 and SSE4.1; the remaining backends reject SIMD modules. On x86_64, the JIT checks CPU support at runtime.

For the supported Wasm feature groups, see the compatibility table. The host exception and result-count limitations described above apply even where the guest instruction set supports exception handling and multi-value.

§Diagnostics

Instance::interpreter_stats collects an owned InterpreterStats snapshot; Instance::function_has_native_code answers a JIT compilation query. Each method is available with its engine feature and returns None for an instance using the other engine. Snapshots retain no runtime borrow. Handler labels are diagnostic display text and can change as the interpreter evolves.

Executable buffers manage their own trap registrations when freed. Embedders do not need a process-wide runtime reset between instances.

§License

Licensed under either MIT or Apache-2.0, at your option. See the included LICENSE-MIT and LICENSE-APACHE files.

Modules§

value_type
WebAssembly 3.0 Type System
wasi
WASI preview1 support for sf-nano-core.

Structs§

Caller
Config
Tunable sizes and limits for one engine.
Engine
The environment modules are instantiated in.
Extern
An exported function, memory, table, global or exception tag.
Func
An export resolved once, so calling it again does not look it up again.
FunctionType
Import
A named host or linked-instance import. Construct it with the associated functions; runtime state and type-context representation are private.
Instance
A module instantiated on one engine.
InstanceId
Stable identity for one instance in one runtime world. An identity from a different world never resolves, even if its slot and generation happen to match.
InterpreterStats
An owned interpreter diagnostic snapshot, collected only when requested. Operation labels describe internal handlers and may change between releases; they are display text, not stable instruction identifiers.
JitStatsSnapshot
Minimal native stats surface for CLI/debug output.
Limits
MemoryView
A read-only view of linear memory.
MemoryViewMut
An exclusive mutable view of linear memory.
Module
A parsed, validated WebAssembly module, ready for instantiation.
RefValue
An opaque reference obtained from Wasm or constructed as a host label. Engine references belong to one runtime world. Copying a handle does not keep an instance alive; using a handle after its owner is freed fails. Raw engine encodings cannot be constructed through the safe public API:
RuntimeWorld
A set of instances that can name each other’s functions.
TagIdentity
Opaque, process-globally-unique tag identity. Zero is reserved as an invalid/null sentinel.
WasmError
An error from parsing, validation, linking, execution or a host callback.
WorldAccess
A cheap, non-owning capability for calling back into a runtime world.

Enums§

ConfigError
Why a Config was rejected.
InstanceInstantiationError
The result of an instantiation that did not produce a usable facade.
Tier
An execution engine compiled into this build.
Value

Constants§

WASM_PAGE_SIZE

Functions§

active_native_backend_name
Which ISA the JIT targets on this build, for embedders that report it.
jit_stats_snapshot
target_has_simd

Type Aliases§

HostFn
A non-capturing host function pointer.