Skip to content

Commit 5a97525

Browse files
authored
Merge pull request #689 from stlankes/wasm
rename wasmtime-demo to hermit-wasm
2 parents b058023 + f1204b6 commit 5a97525

File tree

21 files changed

+389
-140
lines changed

21 files changed

+389
-140
lines changed

Cargo.lock

Lines changed: 210 additions & 98 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ members = [
2222
"examples/dns",
2323
"examples/mutex",
2424
"examples/wasm-test",
25-
"examples/wasmtime",
25+
"examples/hermit-wasm",
2626
"examples/vsock",
2727
"hermit",
2828
"hermit-abi",
File renamed without changes.
Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,34 @@
11
[package]
2-
name = "wasmtime-demo"
2+
name = "hermit-wasm"
33
version = "0.1.0"
4-
edition = "2021"
4+
edition = "2024"
55
authors = ["Stefan Lankes <slankes@eonerc.rwth-aachen.de>"]
6+
repository = "https://github.com/hermit-os/examples/hermit-wasm"
7+
description = "Running WASM modules inside a lightweight virtual machine"
68
readme = "README.md"
79
license = "MIT/Apache-2.0"
810
keywords = ["wasm", "webassembly"]
11+
categories = ["os", "wasm"]
12+
13+
[lib]
14+
name = "hermit_wasm"
915

1016
[features]
1117
default = []
1218
ci = []
1319

1420
[dependencies]
1521
anyhow = "1.0"
22+
clap = { version ="4.5", features = ["derive", "env"] }
23+
chrono = { version = "0.4" }
1624
bitflags = "2.5"
1725
cfg-if = "1"
1826
log = { version = "0.4" } #, features = ["kv_unstable"]}
19-
simple_logger = { version = "5.0", default-features = false }
27+
env_logger = { version = "0.11", default-features = false }
2028
wasmtime = { version = "32", default-features = false, features = ["std", "runtime", "cranelift", "threads", "parallel-compilation", "custom-virtual-memory"] } #"pooling-allocator", "incremental-cache", "wat", "gc", "component-model"] }
2129
zerocopy = { version = "0.8", default-features = false, features = ["alloc", "derive", "simd-nightly"] }
2230

2331
[target.'cfg(target_os = "hermit")'.dependencies]
24-
hermit = { path = "../../hermit", default-features = false, features = ["acpi", "pci", "fsgsbase", "fs", "tcp", "dhcpv4", "mmap"] }
25-
hermit-abi = { path = "../../hermit-abi", default-features = false }
32+
hermit = { version = "=0.11", path = "../../hermit", default-features = false, features = ["acpi", "pci", "fsgsbase", "fs", "tcp", "dhcpv4", "mmap"] }
33+
hermit-abi = { version = "=0.5", path = "../../hermit-abi", default-features = false }
2634
wasi = { version = "0.11" }
File renamed without changes.

examples/hermit-wasm/README.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Hermit-WASM - Running WASM modules inside lightweight Virtual Machine
2+
3+
Hermit-Wasm is able to run WASM Modules on top of the Unikernel [Hermit](https://hermit-os.org/) inside a lightweight virtual machine. Its purpose is to enable applications to safely run untrusted or third party Wasm code within a VM with very low latency/overhead.
4+
5+
The current version of _Hermit-WASM_ requires the Rust's nightly compiler and is a prototype, which just supports the target [wasm32-wasip1](https://doc.rust-lang.org/rustc/platform-support/wasm32-wasip1.html) and [wasm32-wasip1-threads](https://doc.rust-lang.org/rustc/platform-support/wasm32-wasip1-threads.html). In addition, _Hermit-WASM_ realizes only a subset of the required [bindings](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md).
6+
7+
## Requirements
8+
9+
* [`rustup`](https://www.rust-lang.org/tools/install)
10+
* Install required toolchains: `rustup target add wasm32-wasip1`
11+
12+
## Building from source
13+
14+
To build from source, simply checkout the code and use `cargo build` with a hermit target. The following commands build _Hermit-WASM_ for a _x86_64_ processor:
15+
16+
```sh
17+
# clone Hermit repository
18+
git clone --recurse-submodules https://github.com/hermit-os/hermit-rs.git
19+
# build Hermit-WASM
20+
cargo build -Zbuild-std=std,panic_abort -Zbuild-std-features=compiler-builtins-mem --target aarch64-unknown-hermit -p hermit-wasm --release
21+
```
22+
23+
To build _Hermit-WASM_ for other architecture, replace _x86_64-unknown-hermit_ by _aarch64-unknown-hermit_ for the x86 architecture or _riscv64gc-unknown-hermit_ for RISC-V architecture.
24+
25+
## Usage
26+
27+
This guideline assumes that Linux is used as host operating system on top of x86_64 processor. In addition, the host offers KVM to accelerate the virtual machine.
28+
29+
If Qemu is used as hypervisor, download the loader binary from its [releases page](https://github.com/hermit-os/loader/releases) and start the hypervisor as followed:
30+
31+
```sh
32+
qemu-system-x86_64 --enable-kvm -display none -serial stdio -kernel hermit-loader-x86_64 -cpu host -device isa-debug-exit,iobase=0xf4,iosize=0x04 -smp 1 -m 2G -initrd path_to_hermit-wasm
33+
```
34+
35+
_path_to_hermit_wasm_ should be replaced by your local path to the binary. Without any arguments, _Hermit-WASM_ starts a [WASM module](https://github.com/hermit-os/hermit-rs/tree/main/examples/wasm-test), which is included in the binary.
36+
37+
To load a WASM module from the file system, a local directory has to be mounted within the virtual machine.
38+
_Hermit_ supports the usage of [virtiofsd](https://github.com/hermit-os/hermit-rs/wiki/Advanced-Configuration-Features#using-virtiofs-to-share-a-file-system-only-required-when-using-qemu) to mount a local directory.
39+
40+
As alternative, [uhyve](https://github.com/hermit-os/uhyve) can be used, which offers direct access to a local directory. In the following example, a local file is mounted to _/root/module.wasm_.
41+
42+
```sh
43+
uhyve -c 1 -m 1GiB --file-isolation none --file-mapping path_to_module.wasm:/root/module.wasm target/x86_64-unknown-hermit/release/hermit-wasm -- -- -f /root/module.wasm
44+
```
45+
46+
In this example, _path_to_module.wasm_ should be also replace by a local path to a WASM module.
47+
48+
## Credits
49+
50+
A similar project is this area is [Hyperlight-Wasm](https://github.com/hyperlight-dev/hyperlight-wasm). As far as known, _Hyperlight-Wasm_ supports only _x86_ systems, while _Hermit-WASM_ is also running on _aarch64_ and _RISC-V_ processors.
51+
52+
## Licensing
53+
54+
Licensed under either of
55+
56+
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
57+
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
58+
59+
at your option.
60+
61+
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
62+
63+
## Contribution
64+
65+
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
66+
67+
Hermit-WASM is being developed on [GitHub](https://github.com/hermit-os/hermit-rs/examples/hermit-wasm).
68+
Create your own fork, send us a pull request, and chat with us on [Zulip](https://hermit.zulipchat.com/).
File renamed without changes.

0 commit comments

Comments
 (0)