README
¶
WasiVM
WasiVM runs Linux programs compiled to WebAssembly without a Linux kernel. Its kernel is a Go package whose host functions implement the system calls and WASI imports those programs make: processes, signals, pipes, a terminal and a filesystem over a root directory. A BusyBox root filesystem built for wasm32-wasi boots to an interactive shell.
WasiVM is experimental. Spacewave does not include it unless a build opts in.
A Space that loads the spacewave-wasivm plugin can create WebAssembly VMs:
each one boots the kernel on a Space filesystem or a published WasiVM image
and serves its console. A VM on a published image reads its root filesystem
from the CDN as it runs, so creating one copies nothing.
Layout
| Path | Contents |
|---|---|
controller.go |
The plugin: it registers the vm/wasivm ObjectType, its operations, viewer and wizard, and the vm/image/wasivm block type. |
handler.go |
The ObjectType and operation handlers the core plugin calls. |
vm.go |
The VM resource, which runs a kernel for each run of a VM. |
rootfs.go |
Finds the root filesystem of a VM: its own, its image's, or the published image's on the CDN. |
console.go |
The console of each running VM, shared by every attached viewer. |
*.tsx |
The VM viewer and the wizard that creates a VM. |
wasivm-images.ts |
Lists the images published on the CDN and links one into a Space. |
kernel/ |
The kernel: processes, the filesystem, signals, the terminal and the WASI imports. |
kernel/engine/ |
The interface the kernel runs guests through. |
kernel/engine/native/ |
Its implementation on wazero. |
cmd/wasivm/ |
A command that runs one program under the kernel, for debugging it. |
rootfs/ |
The script that builds the BusyBox root filesystem. |
How the kernel works
Each process is a guest module instance. The guest calls the kernel through
wasi_snapshot_preview1 for files, clocks and arguments, and through env
imports for the rest of Linux: vfork and execve, wait4, kill and
sigaction, terminal ioctls, ppoll and more.
vforkandsetjmpcapture the guest's execution state with the engine's snapshots and resume from them, restoring the C stack pointer.- Before a guest runs, the kernel exports its stack pointer and adds a signal trampoline that calls a handler from the guest's function table.
- A process that blocks in a read, a wait or a sleep waits on a channel, so a signal interrupts it at once.
- The filesystem holds
/dev,/procand/tmpin memory over the root directory, which it reads as the guest looks paths up.
Building the root filesystem
The root filesystem comes from the SkiffOS virt/wasm configuration. Building
it takes the host tools Buildroot needs.
plugin/wasivm/rootfs/build-rootfs.sh [skiffos-dir]
Without a directory, the script clones SkiffOS into .tmp/SkiffOS. It writes
the tree to plugin/wasivm/rootfs/out, which Git ignores.
Running a program
go run ./plugin/wasivm/cmd/wasivm --root plugin/wasivm/rootfs/out
go run ./plugin/wasivm/cmd/wasivm -- busybox.wasm sh -c 'echo hello'
The first boots the root filesystem's /bin/sh; --init names another
program. The second runs one BusyBox binary, which also provides its applets.
Flags anywhere on the line belong to wasivm, so -- passes the rest to the
program. --debug logs every system call.
Testing
go test -timeout=300s ./plugin/wasivm/...
The tests that boot BusyBox skip when rootfs/out is missing. The tests that
compare WasiVM with Linux in Docker run with -tags docker_syscall_tests.
Documentation
¶
Overview ¶
Package wasivm_plugin serves WasiVM virtual machines to the Spaces that load the spacewave-wasivm plugin. It registers the vm/wasivm ObjectType, its operations, viewer and creation wizard, and runs each VM's kernel in the plugin process.
Index ¶
- Constants
- Variables
- func NewFactory(b bus.Bus) controller.Factory
- type Config
- func (m *Config) CloneMessageVT() protobuf_go_lite.CloneMessage
- func (m *Config) CloneVT() *Config
- func (this *Config) EqualMessageVT(thatMsg any) bool
- func (this *Config) EqualVT(that *Config) bool
- func (c *Config) EqualsConfig(other config.Config) bool
- func (c *Config) GetConfigID() string
- func (x *Config) MarshalJSON() ([]byte, error)
- func (x *Config) MarshalProtoJSON(s *json.MarshalState)
- func (x *Config) MarshalProtoText() string
- func (m *Config) MarshalToSizedBufferVT(dAtA []byte) (int, error)
- func (m *Config) MarshalToVT(dAtA []byte) (int, error)
- func (m *Config) MarshalVT() (dAtA []byte, err error)
- func (*Config) ProtoMessage()
- func (x *Config) Reset()
- func (m *Config) SizeVT() (n int)
- func (x *Config) String() string
- func (x *Config) UnmarshalJSON(b []byte) error
- func (x *Config) UnmarshalProtoJSON(s *json.UnmarshalState)
- func (m *Config) UnmarshalVT(dAtA []byte) error
- func (c *Config) Validate() error
- type Controller
Constants ¶
const ConfigID = ControllerID
ConfigID is the config identifier.
const ControllerID = "plugin/wasivm"
ControllerID is the controller identifier.
const PluginID = "spacewave-wasivm"
PluginID is the manifest ID of the WasiVM plugin.
Variables ¶
var Version = controller.MustParseVersion("0.0.1")
Version is the component version.
var ViewerEntrypoint bldr_web_bundler.WebBundlerOutput
ViewerEntrypoint is the bundled viewer of a WasiVM.
var WizardEntrypoint bldr_web_bundler.WebBundlerOutput
WizardEntrypoint is the bundled wizard that creates a WasiVM.
Functions ¶
func NewFactory ¶
func NewFactory(b bus.Bus) controller.Factory
NewFactory constructs the component factory.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config configures the WasiVM plugin controller.
func (*Config) CloneMessageVT ¶
func (m *Config) CloneMessageVT() protobuf_go_lite.CloneMessage
func (*Config) EqualMessageVT ¶
func (*Config) EqualsConfig ¶
EqualsConfig checks if the config is equal to another.
func (*Config) GetConfigID ¶
GetConfigID returns the unique string for this configuration type.
func (*Config) MarshalJSON ¶
MarshalJSON marshals the Config to JSON.
func (*Config) MarshalProtoJSON ¶
func (x *Config) MarshalProtoJSON(s *json.MarshalState)
MarshalProtoJSON marshals the Config message to JSON.
func (*Config) MarshalProtoText ¶
func (*Config) MarshalToSizedBufferVT ¶
func (*Config) ProtoMessage ¶
func (*Config) ProtoMessage()
func (*Config) UnmarshalJSON ¶
UnmarshalJSON unmarshals the Config from JSON.
func (*Config) UnmarshalProtoJSON ¶
func (x *Config) UnmarshalProtoJSON(s *json.UnmarshalState)
UnmarshalProtoJSON unmarshals the Config message from JSON.
func (*Config) UnmarshalVT ¶
type Controller ¶
type Controller struct {
*bus.BusController[*Config]
// Holder publishes the registrations and reports when they are ready.
*s4wave_plugin_registration.Holder
// contains filtered or unexported fields
}
Controller registers WasiVM with the core plugin and serves its resources.
func (*Controller) Execute ¶
func (c *Controller) Execute(ctx context.Context) error
Execute registers WasiVM with the core plugin until ctx ends.
func (*Controller) HandleDirective ¶
func (c *Controller) HandleDirective(ctx context.Context, di directive.Instance) ([]directive.Resolver, error)
HandleDirective serves the plugin's resource service and the WasiVM block types.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package binpkg reads Gentoo binary packages: the Packages index of a binary package directory, the runtime closure of a set of packages, and the files of each GPKG archive split into runtime and dev layers.
|
Package binpkg reads Gentoo binary packages: the Packages index of a binary package directory, the runtime closure of a set of packages, and the files of each GPKG archive split into runtime and dev layers. |
|
cmd
|
|
|
wasivm
command
Command wasivm runs a WebAssembly program under the WasiVM kernel, for debugging the kernel outside Spacewave.
|
Command wasivm runs a WebAssembly program under the WasiVM kernel, for debugging the kernel outside Spacewave. |
|
Package display is a host X client of the X server running in a WasiVM.
|
Package display is a host X client of the X server running in a WasiVM. |
|
Package kernel runs Linux programs compiled to WebAssembly.
|
Package kernel runs Linux programs compiled to WebAssembly. |
|
engine
Package engine defines the WebAssembly engine the kernel runs guests on.
|
Package engine defines the WebAssembly engine the kernel runs guests on. |
|
engine/browser
Package browser runs kernel guests on the browser's WebAssembly API.
|
Package browser runs kernel guests on the browser's WebAssembly API. |
|
engine/native
Package native runs kernel guests on wazero.
|
Package native runs kernel guests on wazero. |
|
Package layer builds UnixFS layers from file entries and lays layers onto a root by reference.
|
Package layer builds UnixFS layers from file entries and lays layers onto a root by reference. |
|
Package wayland is a Wayland compositor for the clients in a WasiVM.
|
Package wayland is a Wayland compositor for the clients in a WasiVM. |