Skip to content
veloc-rsPublic

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Veloc

Rust 2024 License: MIT

English | 简体中文

Veloc is an experimental compiler infrastructure and WebAssembly runtime written in Rust. It combines a typed SSA IR, reusable analyses and optimizations, a compact register-bytecode interpreter, and an x86-64 native code generator in one workspace.

Veloc is under active development. Public APIs and supported WebAssembly features may change without notice.

Quick start

Veloc uses the nightly toolchain pinned in rust-toolchain.toml. With Rustup installed, Cargo selects and installs it automatically.

git clone https://github.com/veloc-rs/veloc.git
cd veloc
cargo build --workspace --release

Run the bundled CoreMark WebAssembly module with the interpreter:

cargo run --release -p veloc-wasm --bin veloc-wasm -- run \
  crates/veloc-wasm/tests/wasm/coremark.wasm \
  --strategy interpreter

Use the native x86-64 JIT instead:

cargo run --release -p veloc-wasm --bin veloc-wasm -- run crates/veloc-wasm/tests/wasm/coremark.wasm --strategy jit

On x86-64 Linux, run the full JIT CoreMark regression (checks the validation message and CRCs):

CARGO_INCREMENTAL=0 cargo test --release -p veloc-wasm --test jit \
  coremark_validates_under_jit -- --ignored --nocapture

The run command invokes _start by default using the interpreter. Strategies are interpreter, jit, fast-jit (Linux x86-64) and auto (currently JIT). WAT input requires building with --features wat.

--memory-checks auto is the default: native execution uses guard pages on Linux x86-64 and RV64 with glibc, and software bounds checks elsewhere. Use --memory-checks software to force explicit checks. On Linux x86-64 with glibc, interpreter guard pages can also be requested explicitly:

cargo run --release -p veloc-wasm --bin veloc-wasm -- run \
  path/to/module.wasm --strategy interpreter --memory-checks guarded

Guarded execution installs process-wide SIGSEGV/SIGBUS handlers. Native faults return through a C trap boundary; interpreter guards require Rust unwinding. RV64 guarded stores probe their last byte before writing, preserving memory when an unaligned store would cross into a guard page. Explicit guarded object emission is also available during cross compilation; loading it requires a compatible runtime.

Inspect generated code

# Print Veloc IR without executing the module
cargo run -p veloc-wasm --features wat --bin veloc-wasm -- emit path/to/module.wat --emit mir

# Write Veloc IR to a file
cargo run -p veloc-wasm --bin veloc-wasm -- emit path/to/module.wasm --emit mir -o module.veloc-mir

# Print interpreter bytecode
cargo run -p veloc-wasm --bin veloc-wasm -- emit path/to/module.wasm --emit bytecode

# Print optimizer statistics and write a Chrome trace
cargo run -p veloc-wasm --bin veloc-wasm -- run path/to/module.wasm \
  -O 1 --print-stats --trace-file optimizer-trace.json

Run cargo run -p veloc-wasm --bin veloc-wasm -- --help for all CLI options.

The CLI has three commands: run, emit, and inspect. Direct file invocation, --output-ir, and --compile-only are no longer supported. -O0 and -O1 select both MIR and native-code pipelines; other levels are rejected. All --dump-* options print diagnostics to stderr and continue the requested command. emit writes only the requested product, without linking imports or instantiating the module (including its start function).

# Call an export with typed arguments
veloc-wasm run add.wasm --invoke add --arg i32:1 --arg i32:2
# Pass WASI arguments and explicitly selected environment entries
veloc-wasm run app.wasm --env MODE=fast -- input.txt
# Query the same target declarations used by code generation
veloc-wasm inspect cpus --target riscv64
veloc-wasm inspect features --target riscv64
# Cross-compile an ELF object without loading it
veloc-wasm emit module.wasm --emit object --target riscv64 --cpu c908 -o module.o

Text products default to stdout; -o - explicitly selects stdout. Object emission requires -o. Objects reference Veloc's runtime ABI and are not standalone executables. The library uses Config.codegen.opt_level as its single optimization setting; Engine::new and Engine::with_config return Result.

How it works

 WebAssembly                     Experimental C frontend
     │                                    │
     └──────────────┬─────────────────────┘
                    ▼
             Veloc typed SSA IR
                    │
          ┌─────────┴──────────┐
          │ analyses           │ optimizations
          │ use-def/liveness   │ constant folding/DCE
          └─────────┬──────────┘
                    ▼
          ┌─────────┴──────────────┐
          ▼                        ▼
 register-bytecode interpreter    LIR and x86-64 backend
          │                        │
          ▼                        ▼
      execution              ELF object / JIT

WebAssembly and C source are translated into the same Veloc middle-level IR (MIR). From there, the runtime can compile MIR into compact bytecode or lower it through low-level IR (LIR) to native x86-64 code.

Repository layout

Crate Purpose
veloc Top-level facade for the IR, interpreter, and code generator.
veloc-mir Typed SSA IR, builders, data-flow graph, text format, and validator.
veloc-lir Machine-facing IR, operand schemas, register identities, and stage markers.
veloc-analyzer Use-def and liveness analyses.
veloc-optimizer Pass management, metrics, constant folding, and dead-code elimination.
veloc-interpreter IR-to-bytecode compiler and register-bytecode runtime.
veloc-codegen Target-independent LIR pipeline and x86-64 backend.
veloc-spec Typed cross-IR value-rule compiler sharing OpSpec contracts, plus target descriptions and instruction selection.
veloc-wasm WebAssembly translator, runtime, CLI, linker, JIT, and WASI support.
veloc-c Experimental C parser and IR frontend.
veloc-wasm-spec WebAssembly specification test runner.

Development

Build and test the complete workspace:

cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets

Run focused interpreter and WebAssembly tests:

cargo test -p veloc-interpreter
cargo test -p veloc-wasm

The specification runner accepts either a .wast file or a directory from the upstream WebAssembly specification tests:

cargo run --release -p veloc-wasm-spec -- \
  /path/to/wasm-spec/test/core \
  --strategy interp

Replace interp with jit to exercise the native backend.

To use the pinned testsuite submodule, for example the integer suite:

git submodule update --init crates/veloc-wasm/tests/testsuite
CARGO_INCREMENTAL=0 cargo run -p veloc-wasm-spec -- \
  crates/veloc-wasm/tests/testsuite/i32.wast --strategy jit --opt-level 1 --verbose

The runner reports skipped stack-exhaustion assertions separately. Passing CoreMark does not imply full WebAssembly conformance: the complete floating-point suites still require additional lowering, including min/max and saturating conversions.

Documentation

Project status

Veloc is suitable for compiler and runtime experimentation, but is not yet a stable production toolchain. Current priorities include broader WebAssembly coverage, more x86-64 instructions and ABI support, additional optimization passes and targets, completion of the C frontend, and API stabilization.

Issues and pull requests are welcome.

License

Veloc is available under the MIT License.

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages