|
| 1 | +# `riscv32im-risc0-zkvm-elf` |
| 2 | + |
| 3 | +**Tier: 3** |
| 4 | + |
| 5 | +RISC Zero's Zero Knowledge Virtual Machine (zkVM) implementing the RV32IM instruction set. |
| 6 | + |
| 7 | +## Target maintainers |
| 8 | + |
| 9 | +- Frank Laub, `[email protected]`, https://github.com/flaub |
| 10 | +- Jeremy Bruestle, `[email protected]`, https://github.com/jbruestle |
| 11 | +- Erik Kaneda, `[email protected]`, https://github.com/SchmErik |
| 12 | + |
| 13 | +## Background |
| 14 | + |
| 15 | +This target is an execution environment to produce a proof of execution of |
| 16 | +a RISC-V ELF binary and any output that the developer of the binary wishes to |
| 17 | +display publicly. In order to do this, the target will execute the ELF to |
| 18 | +generate a receipt containing the output of the computation along with a |
| 19 | +cryptographic seal. This receipt can be verified to ensure the integrity of the |
| 20 | +computation and its result. This target is implemented as software only; it has |
| 21 | +no hardware implementation. |
| 22 | + |
| 23 | +We have a cargo extension called [cargo-risczero] that allow users to generate |
| 24 | +project templates, install tools for improved user experience, build the binary |
| 25 | +using a docker environment and test programs. |
| 26 | + |
| 27 | +## Requirements |
| 28 | + |
| 29 | +The target only supports cross compilation and no host tools. The target |
| 30 | +supports `alloc` with a default allocator and has experimental support for |
| 31 | +`std`. The target expects the binaries to be in ELF. |
| 32 | + |
| 33 | +The target's execution environment is single threaded, non-preemptive, and does |
| 34 | +not support any privileged instructions, nor unaligned accesses. At the time of |
| 35 | +writing the VM has 192 MB of memory and text/data, heap, and stack need to be |
| 36 | +with in the address range `0x400` - `0x0C000000`. The binaries themselves expect |
| 37 | +no operating system and can be thought of as running on bare-metal. The target |
| 38 | +does not use `#[target_feature(...)]` or `-C target-feature=` values. |
| 39 | + |
| 40 | +Calling `extern "C"` on the target uses the C calling convention outlined in the |
| 41 | +[RISC-V specification]. |
| 42 | + |
| 43 | +## Building for the zkVM |
| 44 | + |
| 45 | +Programs for the zkVM could be built by adding it to the `target` list in |
| 46 | +`config.toml`. However, we recommend building programs in our starter template |
| 47 | +generated by the [cargo-risczero] utility and the [risc0-build] crate. This |
| 48 | +crate calls `rustc` with `-C "link-arg=-Ttext=` so that it maps the text in the |
| 49 | +appropriate location as well as generating variables that represent the ELF and |
| 50 | +a unique ID associated with the ELF. The starter template provides developers |
| 51 | +with system calls that are useful to zero knowledge computing such as writing to |
| 52 | +the public output, hashing using sha256, and multiply big integers. |
| 53 | + |
| 54 | +## Building Rust programs |
| 55 | + |
| 56 | +Rust does not yet ship pre-compiled artifacts for this target. To compile for |
| 57 | +this target, you will either need to build Rust with the target enabled (see |
| 58 | +"Building the target" above). We do not recommend using `build-std` as we have |
| 59 | +run into issues building core in the past on our starter template. An alternate |
| 60 | +solution is to download the risc0 tool chain by running `cargo risczero install`. |
| 61 | + |
| 62 | +## Testing |
| 63 | + |
| 64 | +Note: the target is implemented as a software emulator called the zkVM and there |
| 65 | +is no hardware implementation of the target. |
| 66 | + |
| 67 | +The most practical way to test the target program is to use our starter template |
| 68 | +that can be generated by using the `cargo risczero new` command. The template |
| 69 | +generates a sample "host" and "guest" code. The guest code compiled to the |
| 70 | +target (which is RV32IM) whereas the "host" code is compiled to run on the |
| 71 | +programmer's machine running either a Linux distribution or macOS. The host |
| 72 | +program is responsible for running the guest binary on the zkVM and retrieving |
| 73 | +its public output. |
| 74 | + |
| 75 | +The target currently does not support running the Rust test suite. |
| 76 | + |
| 77 | +## Cross-compilation toolchains and C code |
| 78 | + |
| 79 | +Compatible C code can be built for this target on any compiler that has a RV32IM |
| 80 | +target. On clang and ld.lld linker, it can be generated using the |
| 81 | +`-march=rv32im`, `-mabi=ilp32` with llvm features flag `features=+m` and llvm |
| 82 | +target `riscv32-unknown-none`. |
| 83 | + |
| 84 | +[RISC-V specification]: https://riscv.org/wp-content/uploads/2015/01/riscv-calling.pdf |
| 85 | +[cargo-risczero]: https://docs.rs/cargo-risczero/latest/cargo_risczero/ |
| 86 | +[risc0-build]: https://crates.io/crates/risc0-build |
0 commit comments