diff options
| -rw-r--r-- | ARCHITECTURE.md | 32 | ||||
| -rw-r--r-- | CHANGELOG.md | 27 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 39 | ||||
| -rw-r--r-- | Cargo.toml | 2 | ||||
| -rw-r--r-- | README.md | 2 |
5 files changed, 55 insertions, 47 deletions
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7aaa99c..2890089 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,27 +1,23 @@ # TinyWasm's Architecture TinyWasm follows the general Runtime Structure described in the [WebAssembly Specification](https://webassembly.github.io/spec/core/exec/runtime.html). -Some key differences are: -- **Type Storage**: Types are inferred from usage context rather than stored explicitly, with all values held as `u64`. -- **Stack Design**: Implements a specific stack for values, labels, and frames to simplify the implementation and enable optimizations. -- **Bytecode Format**: Adopts a custom bytecode format to reduce memory usage and improve performance by allowing direct execution without the need for decoding. -- **Global State Access**: Allows cross-module access to the `Store`'s global state, optimizing imports and exports access. Access requires a module instance reference, maintaining implicit ownership through a reference count. -- **Non-thread-safe Store**: Designed for efficiency in single-threaded applications. -- **JIT Compilation Support**: Prepares for JIT compiler integration with function instances designed to accommodate `WasmFunction`, `HostFunction`, or future `JitFunction`. -- **`no_std` Environment Support**: Offers compatibility with `no_std` environments by allowing disabling of `std` feature -- **Call Frame Execution**: Executes call frames in a single loop rather than recursively, using a single stack for all frames, facilitating easier pause, resume, and step-through. +Key runtime layout: -## Bytecode Format +- Values are stored in four fixed-capacity typed stacks: `stack_32` (`i32`/`f32`), `stack_64` (`i64`/`f64`), `stack_128` (`v128`), and `stack_ref` (`funcref`/`externref`). +- Locals are allocated in those value stacks. Each `CallFrame` stores `locals_base`, and local ops index from that base. +- Calls use a separate fixed-capacity `CallStack` of `CallFrame`s. +- Structured control (`block`/`loop`/`if`/`br*`) is lowered during parsing to jump-oriented instructions: `Jump`, `JumpIfZero`, `BranchTable*`, `DropKeep*`, and `Return`. +- The interpreter executes this lowered bytecode in a single iterative loop. -To improve performance and reduce code size, instructions are encoded as enum variants instead of opcodes. -This allows preprocessing the bytecode into a more memory aligned format, which can be loaded directly into memory and executed without decoding later. This can skip the decoding step entirely on resource-constrained devices where memory is limited. See this [blog post](https://wasmer.io/posts/improving-with-zero-copy-deserialization) by Wasmer -for more details which inspired this design. +## Precompiled Modules -Some instructions are split into multiple variants to reduce the size of the enum (e.g. `br_table` and `br_label`). -Additionally, label instructions contain offsets relative to the current instruction to make branching faster and easier to implement. -Also, `End` instructions are split into `End` and `EndBlock`. Others are also combined, especially in cases where the stack can be skipped. +`TinyWasmModule` can be serialized to `.twasm` (`serialize_twasm`) and loaded later (`from_twasm`). +This allows deployments that execute precompiled modules without enabling the parser in the runtime binary. -See [instructions.rs](./crates/types/src/instructions.rs) for the full list of instructions. +See: -This is a area that can still be improved. While being able to load pre-processes bytecode directly into memory is nice, in-place decoding could achieve similar speeds, see [A fast in-place interpreter for WebAssembly](https://arxiv.org/abs/2205.01183). +- [visit.rs](./crates/parser/src/visit.rs) +- [instructions.rs](./crates/types/src/instructions.rs) +- [value_stack.rs](./crates/tinywasm/src/interpreter/stack/value_stack.rs) +- [call_stack.rs](./crates/tinywasm/src/interpreter/stack/call_stack.rs) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7452dbf..b9b5fcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,19 +12,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Support for the custom memory 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 -- Groundwork for the `simd` proposal +- Support for the fixed-width `simd` proposal +- Support for the `relaxed_simd` proposal +- Support for the `wide_arithmetic` 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`) +- 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 +### 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 are configured via `engine::Config` + ### 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 -- Increased MSRV to 1.83.0 -- `tinywasm::Error` is now `non_exhaustive`, `Error::ParseError` has been rename to `Error::Parser` and `Error::Twasm` has been added. +- `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 ### 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)) ## [0.8.0] - 2024-08-29 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2302bef..9c713bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,12 @@ # Contributing -Thank you for considering contributing to this project! This document outlines the process for contributing to this project. For small changes or bug fixes, feel free to open a pull request directly. For larger changes, please open an issue first to discuss the proposed changes. Also, please ensure that you open up your pull request against the `next` branch and [allow maintainers of the project to edit your code](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +Thank you for considering a contribution. For small fixes, feel free to open a pull request directly. For larger changes, please open an issue first so we can discuss the approach. Please target the `next` branch and [allow maintainers to edit your PR branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). -## 1. Clone the Repository +## Code of Conduct -Ensure you clone this repository with the `--recursive` flag to include the submodules: +This project follows the [Contributor Covenant 3.0 Code of Conduct](https://www.contributor-covenant.org/version/3/0/code_of_conduct/). -```bash -git clone --recursive https://github.com/explodingcamera/tinywasm.git -``` - -If you have already cloned the repository, you can initialize the submodules with: - -```bash -git submodule update --init --recursive -``` - -This is required to run the WebAssembly test suite. - -## 2. Set up the Development Environment +## Development This project mostly uses a pretty standard Rust setup. Some common tasks: @@ -32,14 +20,17 @@ $ cargo test # Run only the WebAssembly MVP (1.0) test suite $ cargo test-wasm-1 -# Run only the full WebAssembly test suite (2.0) +# Run only the full WebAssembly 2.0 test suite $ cargo test-wasm-2 -# Run a specific test (run without arguments to see available tests) -$ cargo test --test {test_name} +# Run only the full WebAssembly 3.0 test suite +$ cargo test-wasm-3 # Run a single WAST test file -$ cargo test-wast {path} +$ cargo test-wast ./wasm-testsuite/data/wasm-v1/{file}.wast + +# Run custom wasm tests from crates/tinywasm/tests/wasm-custom +$ cargo test-wasm-custom # Run a specific example (run without arguments to see available examples) # The wasm test files required to run the `wasm-rust` examples are not @@ -51,20 +42,20 @@ $ cargo run --example {example_name} ### Profiling -Either [samply](https://github.com/mstange/samply/) or [cargo-flamegraph](https://github.com/flamegraph-rs/flamegraph) are recommended for profiling. +Use [samply](https://github.com/mstange/samply/) for profiling. Example usage: ```bash cargo install --locked samply -cargo samply --example wasm-rust -- selfhosted +samply record -- cargo run --release --example wasm-rust -- selfhosted ``` -# Commits +## Commits This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. For pull requests, the commit messages will be squashed so you don't need to worry about this too much. However, it is still recommended to follow this convention for consistency. -# Branches +## Branches - `main`: The main branch. This branch is used for the latest stable release. - `next`: The next branch. Development happens here. @@ -19,7 +19,7 @@ serde={version="1.0", features=["derive"]} [workspace.package] version="0.9.0-alpha.0" -rust-version="1.93" +rust-version="1.90" edition="2024" license="MIT OR Apache-2.0" authors=["Henry Gressmann <mail@henrygressmann.de>"] @@ -8,7 +8,7 @@ ## Current Status -`tinywasm` passes all WebAssembly MVP and WebAssembly 2.0 tests from the [WebAssembly core testsuite](https://github.com/WebAssembly/testsuite) and is able to run most WebAssembly programs. Additionally, support for WebAssembly 3.0 is mostly done. See the [Supported Proposals](#supported-proposals) section for more information. +`tinywasm` passes 100% of WebAssembly MVP and WebAssembly 2.0 tests from the [WebAssembly core testsuite](https://github.com/WebAssembly/testsuite) and is able to run most WebAssembly programs. Additionally, support for WebAssembly 3.0 is on the way. See the [Supported Proposals](#supported-proposals) section for more information. ## Usage |