From 06fbe079014f8534eba21956d73e4be6022f0058 Mon Sep 17 00:00:00 2001 From: Erik Kaneda Date: Wed, 15 Nov 2023 16:57:22 -0800 Subject: [PATCH] Add target description for `riscv32im-risc0-zkvm-elf` Co-authored-by: Frank Laub --- src/doc/rustc/src/SUMMARY.md | 1 + src/doc/rustc/src/platform-support.md | 1 + .../riscv32im-risc0-zkvm-elf.md | 86 +++++++++++++++++++ 3 files changed, 88 insertions(+) create mode 100644 src/doc/rustc/src/platform-support/riscv32im-risc0-zkvm-elf.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 1c8e1d1e316..1998b008dc8 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -47,6 +47,7 @@ - [mipsisa\*r6\*-unknown-linux-gnu\*](platform-support/mips-release-6.md) - [nvptx64-nvidia-cuda](platform-support/nvptx64-nvidia-cuda.md) - [powerpc64-ibm-aix](platform-support/aix.md) + - [riscv32im-risc0-zkvm-elf](platform-support/riscv32im-risc0-zkvm-elf.md) - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md) - [riscv32*-unknown-none-elf](platform-support/riscv32imac-unknown-none-elf.md) - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 9e5c1ed8748..f648a60b6c4 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -338,6 +338,7 @@ target | std | host | notes [`powerpc64-ibm-aix`](platform-support/aix.md) | ? | | 64-bit AIX (7.2 and newer) `riscv32gc-unknown-linux-gnu` | | | RISC-V Linux (kernel 5.4, glibc 2.33) `riscv32gc-unknown-linux-musl` | | | RISC-V Linux (kernel 5.4, musl + RISCV32 support patches) +[`riscv32im-risc0-zkvm-elf`](platform-support/riscv32im-risc0-zkvm-elf.md) | ? | | RISC Zero's zero-knowledge Virtual Machine (RV32IM ISA) [`riscv32imac-unknown-xous-elf`](platform-support/riscv32imac-unknown-xous-elf.md) | ? | | RISC-V Xous (RV32IMAC ISA) [`riscv32imc-esp-espidf`](platform-support/esp-idf.md) | ✓ | | RISC-V ESP-IDF [`riscv32imac-esp-espidf`](platform-support/esp-idf.md) | ✓ | | RISC-V ESP-IDF diff --git a/src/doc/rustc/src/platform-support/riscv32im-risc0-zkvm-elf.md b/src/doc/rustc/src/platform-support/riscv32im-risc0-zkvm-elf.md new file mode 100644 index 00000000000..1fdd594012c --- /dev/null +++ b/src/doc/rustc/src/platform-support/riscv32im-risc0-zkvm-elf.md @@ -0,0 +1,86 @@ +# `riscv32im-risc0-zkvm-elf` + +**Tier: 3** + +RISC Zero's Zero Knowledge Virtual Machine (zkVM) implementing the RV32IM instruction set. + +## Target maintainers + +- Frank Laub, `frank@risczero.com`, https://github.com/flaub +- Jeremy Bruestle, `jeremy@risczero.com`, https://github.com/jbruestle +- Erik Kaneda, `erik@risczero.com`, https://github.com/SchmErik + +## Background + +This target is an execution environment to produce a proof of execution of +a RISC-V ELF binary and any output that the developer of the binary wishes to +display publicly. In order to do this, the target will execute the ELF to +generate a receipt containing the output of the computation along with a +cryptographic seal. This receipt can be verified to ensure the integrity of the +computation and its result. This target is implemented as software only; it has +no hardware implementation. + +We have a cargo extension called [cargo-risczero] that allow users to generate +project templates, install tools for improved user experience, build the binary +using a docker environment and test programs. + +## Requirements + +The target only supports cross compilation and no host tools. The target +supports `alloc` with a default allocator and has experimental support for +`std`. The target expects the binaries to be in ELF. + +The target's execution environment is single threaded, non-preemptive, and does +not support any privileged instructions, nor unaligned accesses. At the time of +writing the VM has 192 MB of memory and text/data, heap, and stack need to be +with in the address range `0x400` - `0x0C000000`. The binaries themselves expect +no operating system and can be thought of as running on bare-metal. The target +does not use `#[target_feature(...)]` or `-C target-feature=` values. + +Calling `extern "C"` on the target uses the C calling convention outlined in the +[RISC-V specification]. + +## Building for the zkVM + +Programs for the zkVM could be built by adding it to the `target` list in +`config.toml`. However, we recommend building programs in our starter template +generated by the [cargo-risczero] utility and the [risc0-build] crate. This +crate calls `rustc` with `-C "link-arg=-Ttext=` so that it maps the text in the +appropriate location as well as generating variables that represent the ELF and +a unique ID associated with the ELF. The starter template provides developers +with system calls that are useful to zero knowledge computing such as writing to +the public output, hashing using sha256, and multiply big integers. + +## Building Rust programs + +Rust does not yet ship pre-compiled artifacts for this target. To compile for +this target, you will either need to build Rust with the target enabled (see +"Building the target" above). We do not recommend using `build-std` as we have +run into issues building core in the past on our starter template. An alternate +solution is to download the risc0 tool chain by running `cargo risczero install`. + +## Testing + +Note: the target is implemented as a software emulator called the zkVM and there +is no hardware implementation of the target. + +The most practical way to test the target program is to use our starter template +that can be generated by using the `cargo risczero new` command. The template +generates a sample "host" and "guest" code. The guest code compiled to the +target (which is RV32IM) whereas the "host" code is compiled to run on the +programmer's machine running either a Linux distribution or macOS. The host +program is responsible for running the guest binary on the zkVM and retrieving +its public output. + +The target currently does not support running the Rust test suite. + +## Cross-compilation toolchains and C code + +Compatible C code can be built for this target on any compiler that has a RV32IM +target. On clang and ld.lld linker, it can be generated using the +`-march=rv32im`, `-mabi=ilp32` with llvm features flag `features=+m` and llvm +target `riscv32-unknown-none`. + +[RISC-V specification]: https://riscv.org/wp-content/uploads/2015/01/riscv-calling.pdf +[cargo-risczero]: https://docs.rs/cargo-risczero/latest/cargo_risczero/ +[risc0-build]: https://crates.io/crates/risc0-build