From 27004a8738c7a3c32ac4fb6966f32647b4c96db7 Mon Sep 17 00:00:00 2001 From: Henry Date: Sun, 26 Apr 2026 17:55:48 +0200 Subject: docs: rework documentation, prepare pre-release Signed-off-by: Henry --- CHANGELOG.md | 97 ++++++++++++++++++++++++++++-------------------------------- 1 file changed, 46 insertions(+), 51 deletions(-) (limited to 'CHANGELOG.md') diff --git a/CHANGELOG.md b/CHANGELOG.md index 42b2220..1ddae8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,67 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +This release is a major runtime and API rework. It adds support for several newer WebAssembly proposals, introduces the new `Engine` configuration API, rewrites large parts of execution and validation, and changes the internal `twasm` archive format. Benchmarks in the repository currently show roughly 30-90% improvement over 0.8.0 depending on workload and execution mode. + ### Added - Support for the `custom_page_sizes` proposal ([#22](https://github.com/explodingcamera/tinywasm/pull/22) by [@danielstuart14](https://github.com/danielstuart14)) -- Support for the `tail_call` proposal -- Support for the `memory64` proposal -- Support for the `simd` proposal -- Support for the `relaxed_simd` proposal -- Support for the `wide_arithmetic` proposal +- Support for the `tail_call`, `memory64`, `simd`, `relaxed_simd`, `wide_arithmetic`, and `extended_const` proposals ([#37](https://github.com/explodingcamera/tinywasm/pull/37), [#38](https://github.com/explodingcamera/tinywasm/pull/38), [#39](https://github.com/explodingcamera/tinywasm/pull/39)) +- Parse-only support for the `annotations` proposal - New `Engine` API (`tinywasm::Engine` and `engine::Config`) for runtime configuration -- Resumable function execution with fuel/time-budget APIs (`call_resumable`, `resume_with_fuel`, `resume_with_time_budget`, `ExecProgress`) +- Resumable execution APIs: `call_resumable`, `resume_with_fuel`, `resume_with_time_budget`, and `ExecProgress` - Host-function fuel APIs: `FuncContext::charge_fuel` and `FuncContext::remaining_fuel` -- `engine::FuelPolicy` and `engine::Config::fuel_policy` for fuel accounting behavior -- New `canonicalize_nans` feature flag to enable canonicalizing NaN values in the `f32`, `f64`, and `v128` types -- Public API rework for runtime object access: - - export lookups: `func_untyped`/`func`, `memory`, `table`, `global` - - table/global value access: `global_get`, `global_set` - - generic export access: `extern_item` and `ExternItem` - - export iteration: `ModuleInstance::exports` - - module descriptors: `Module::imports`, `Module::exports` - - handle-based runtime objects with explicit store access: `Memory`, `Table`, `Global`, `Function` +- `engine::Config` support for fuel policy, stack sizing, memory backend selection, and trap-on-OOM behavior +- New feature flags: `canonicalize-nans`, `simd-x86`, `guest-debug`, `debug`, and `parallel-parser` +- Top-level parser re-exports behind the `parser` feature: `parse_bytes`, `parse_file`, and `parse_stream` ### Changed -- Locals are now stored in the typed value stacks instead of a separate locals structure -- Structured control flow is fully lowered to jump-oriented internal instructions during parsing -- Stack and call-stack limits can now be configured via `engine::Config` -- Module-internal by-index inspection APIs are now gated behind the `guest_debug` feature - -### Breaking Changes - -- New backwards-incompatible version of the twasm format based on `postcard` (thanks [@dragonnn](https://github.com/dragonnn)) -- `RefNull` has been removed and replaced with new `FuncRef` and `ExternRef` structs -- `Store::new` now takes an `Engine`; use `Store::default()` for default settings -- `Error`, `Trap`, and `LinkingError` are now `#[non_exhaustive]` -- `Trap` variant discriminant values changed (if you cast variants to integers) -- `tinywasm::interpreter` is no longer a public module; `InterpreterRuntime` and `TinyWasmValue` are no longer public API -- `FuncHandle::name` was removed -- Cargo feature `simd` was removed -- Cargo feature `tinywasm-parser` was renamed to`parser` -- Cargo feature `logging` was renamed to `log` -- Increased MSRV to 1.90 -- `Error::ParseError` was renamed to `Error::Parser`, and `Error::Twasm` was added -- `ModuleInstance` export lookup APIs were renamed: - - `exported_func_untyped` -> `func_untyped` - - `exported_func` -> `func` - - `exported_memory` -> `memory` -- `ModuleInstance` mutable export lookup variants were removed: - - `memory_mut`, `table_mut`, `global_mut` - - `extern_item_mut` -- `FuncHandle` / `FuncHandleTyped` were renamed to `Function` / `FunctionTyped` -- `HostFunction::new` / `HostFunction::func` / `HostFunction::typed` now require `&mut Store` -- `Imports::link_module` now takes a `ModuleInstance` instead of a raw module instance id -- `func_typed` now validates the exact wasm signature at lookup time and fails immediately on mismatches +- `Store::new` now takes an `Engine`; use `Store::default()` for default settings. +- `ModuleInstance::func` now validates exact Wasm signatures at lookup time and fails immediately on mismatches. +- Stack and call-stack limits now come from `engine::Config`, and memory allocation is lazy until first access. +- Module-internal by-index inspection APIs are now gated behind `guest-debug`, and runtime `Debug` implementations are gated behind `debug`. +- `Module` is now re-exported directly from `tinywasm_types`; the `module` submodule was removed. +- MSRV increased to 1.95 and the crate now uses Rust 2024. +- `Error`, `Trap`, and `LinkingError` are now `#[non_exhaustive]`. +- `Trap` variant discriminants changed; do not rely on casting variants to integers. +- `HostFunction::new`, `HostFunction::func`, and `HostFunction::typed` now require `&mut Store`, and `Imports::link_module` now takes a `ModuleInstance` instead of a raw module instance id. +- Cargo features were renamed from `tinywasm-parser` to `parser` and from `logging` to `log`. +- `Error::ParseError` was renamed to `Error::Parser`, and `Error::Twasm` was added. +- `FuncHandle` and `FuncHandleTyped` were renamed to `Function` and `FunctionTyped`, and module export lookups moved from `exported_*` to `func_untyped`, `func`, and `memory`. +- The `twasm` archive format is now postcard-based and backwards-incompatible with previous versions (thanks [@dragonnn](https://github.com/dragonnn)). +- The interpreter was refactored around more superinstruction fusion, lower-overhead dispatch, typed-stack locals, jump-oriented lowering, and optional parallel parsing. + +### Removed + +- Cargo feature `simd` was removed. +- `RefNull` was removed and replaced with `FuncRef` and `ExternRef`. +- `tinywasm::interpreter` is no longer a public module. +- `InterpreterRuntime` and `TinyWasmValue` are no longer public API. +- `FuncHandle::name` was removed. +- Mutable `ModuleInstance` export lookup variants `memory_mut`, `table_mut`, `global_mut`, and `extern_item_mut` were removed. ### Fixed -- Fixed archive **no_std** support which was broken in the previous release, and added more tests to ensure it stays working -- `ModuleInstance::exported_memory` and `FuncContext::exported_memory` are now actually immutable ([#41](https://github.com/explodingcamera/tinywasm/pull/41)) -- Check returns in untyped host functions ([#27](https://github.com/explodingcamera/tinywasm/pull/27)) (thanks [@WhaleKit](https://github.com/WhaleKit)) -- `MemoryRefMut::copy_within(src, dst, len)` now follows its documented argument order -- Imported tables created with `Extern::table(ty, init)` now honor the provided init value +- Fixed archive **no_std** support, which was broken in the previous release, and added tests to ensure it stays working. +- `ModuleInstance::memory` and `FuncContext::memory` are now actually immutable ([#41](https://github.com/explodingcamera/tinywasm/pull/41)). +- Untyped host functions now check return values correctly ([#27](https://github.com/explodingcamera/tinywasm/pull/27)) by [@WhaleKit](https://github.com/WhaleKit). +- `MemoryRefMut::copy_within(src, dst, len)` now follows its documented argument order. +- Imported tables created with `Extern::table(ty, init)` now honor the provided init value. +- Fixed unchecked memory offsets causing issues on 32-bit platforms. + +### Migration Notes + +- Replace `Store::new()` with `Store::default()` for default settings, or `Store::new(Engine::new(config))` for custom runtime configuration. +- Rename the cargo features `tinywasm-parser` to `parser` and `logging` to `log`. +- Rename `FuncHandle` to `Function` and `FuncHandleTyped` to `FunctionTyped`. +- Rename module export lookups from `exported_*` methods to `func`, `func_untyped`, and `memory`. +- Regenerate any persisted `twasm` archives; the format is now postcard-based and not backwards compatible with earlier releases. ## [0.8.0] - 2024-08-29 @@ -184,7 +179,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Lots of bug fixes - Full `no_std` support -## [0.3.0] - 2024-01-11 +## [0.2.0] - 2024-01-11 **All Commits**: https://github.com/explodingcamera/tinywasm/compare/v0.1.0...v0.2.0 -- cgit v1.3.1