✨ Example & asterisc build image

.gitignore

@@ -1,2 +1,5 @@
 # Rust target
 target
+
+# Example targets
+examples/**/target

Cargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = ["crates/*"]
+exclude = ["examples/minimal"]
 resolver = "2"
 
 [workspace.package]

README.md

@@ -37,7 +37,8 @@ verify an [L2 output root][g-output-root] from the L1 inputs it was [derived fro
 * [`host`](./bin/host): The host program that runs natively alongside the FPVM, serving as the [Preimage Oracle][g-preimage-oracle] server.
 
 **Build Pipelines**
-*todo*
+* [`cannon`](./build/cannon): Docker image for compiling to the bare-metal `mips-unknown-none` target.
+* [`asterisc`](./build/asterisc): Docker image for compiling to the bare-metal `riscv64gc-unknown-none-elf` target.
 
 **`client` / `host` SDK**
 * [`common`](./crates/common): A suite of utilities for developing `client` programs to be ran on top of Fault Proof VMs.

build/README.md

@@ -1,12 +1,12 @@
 # `kona-build`
 
-This directory contains the [`cross`][cross] docker images and custom `rustc` targets used to build verifiable programs targeting various FPVMs.
+This directory contains the cross compilation docker images and custom `rustc` targets used to build verifiable programs targeting various FPVMs.
 
 ## Usage
 
 ### Building Images
 
-To build the images, run `make` in the root of this directory.
+To build the images, run `just` in the root of this directory.
 
 ### Compiling Programs
 
@@ -23,8 +23,10 @@ docker run \
 
 **asterisc**
 ```
-RUSTFLAGS="-Clink-arg=-e_start -C target-feature=-c" \
-    cargo build --target riscv64gc-unknown-none-elf --release
+docker run \
+    --rm \
+    --platform linux/amd64 \
+    -v `pwd`/:/workdir \
+    -w="/workdir" \
+    asterisc-pipeline:latest cargo build --release -Zbuild-std
 ```
-
-[cross]: https://github.com/cross-rs/cross

build/asterisc/asterisc.dockerfile

@@ -0,0 +1,33 @@
+FROM --platform=linux/amd64 ubuntu:22.04
+
+ENV SHELL=/bin/bash
+ENV DEBIAN_FRONTEND noninteractive
+
+# todo: pin `nightly` version
+ENV RUST_VERSION nightly
+
+RUN apt-get update && apt-get install --assume-yes --no-install-recommends \
+  ca-certificates \
+  build-essential \
+  curl \
+  g++-riscv64-linux-gnu \
+  libc6-dev-riscv64-cross \
+  binutils-riscv64-linux-gnu \
+  llvm \
+  clang \
+  make \
+  cmake \
+  git 
+
+# Install Rustup and Rust
+RUN curl https://sh.rustup.rs -sSf | bash -s -- -y --default-toolchain ${RUST_VERSION} --component rust-src
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Set up the env vars to instruct rustc to use the correct compiler and linker
+# and to build correctly to support the Cannon processor
+ENV CC_riscv64_unknown_none_elf=riscv64-linux-gnu-gcc \
+  CXX_riscv64_unknown_none_elf=riscv64-linux-gnu-g++ \
+  CARGO_TARGET_RISCV64_UNKNOWN_NONE_ELF_LINKER=riscv64-linux-gnu-gcc \
+  RUSTFLAGS="-Clink-arg=-e_start -Ctarget-feature=-c" \
+  CARGO_BUILD_TARGET="riscv64gc-unknown-none-elf" \
+  RUSTUP_TOOLCHAIN=${RUST_VERSION}

build/justfile

@@ -1,3 +1,9 @@
+all: cannon asterisc
+
 # Build the `cannon` program builder image
 cannon:
 	docker build -t cannon-pipeline:latest -f cannon/cannon.dockerfile ./cannon
+
+# Build the `asterisc` program builder image
+asterisc:
+	docker build -t asterisc-pipeline:latest -f asterisc/asterisc.dockerfile ./asterisc

crates/common/src/asterisc/io.rs

@@ -1,7 +1,10 @@
-use crate::{asterisc::syscall, traits::BasicKernelInterface, types::RegisterSize};
+use crate::{
+    asterisc::syscall, io::FileDescriptor, traits::BasicKernelInterface, types::RegisterSize,
+};
 use anyhow::Result;
 
 /// Concrete implementation of the [`KernelIO`] trait for the `riscv64` target architecture.
+#[derive(Debug)]
 pub struct AsteriscIO;
 
 /// Relevant system call numbers for the `riscv64` target architecture.
@@ -13,7 +16,7 @@ pub struct AsteriscIO;
 /// the [BasicKernelInterface] trait is created for the `asterisc` kernel, this list should be extended
 /// accordingly.
 #[repr(u32)]
-pub enum SyscallNumber {
+pub(crate) enum SyscallNumber {
     /// Sets the Exited and ExitCode states to true and $a0 respectively.
     Exit = 93,
     /// Similar behavior as Linux with support for unaligned reads.
@@ -23,7 +26,7 @@ pub enum SyscallNumber {
 }
 
 impl BasicKernelInterface for AsteriscIO {
-    fn write(fd: Self::FileDescriptor, buf: &[u8]) -> Result<RegisterSize> {
+    fn write(fd: FileDescriptor, buf: &[u8]) -> Result<RegisterSize> {
         unsafe {
             Ok(syscall::syscall3(
                 SyscallNumber::Write as usize,
@@ -34,7 +37,7 @@ impl BasicKernelInterface for AsteriscIO {
         }
     }
 
-    fn read(fd: Self::FileDescriptor, buf: &mut [u8]) -> Result<RegisterSize> {
+    fn read(fd: FileDescriptor, buf: &mut [u8]) -> Result<RegisterSize> {
         unsafe {
             Ok(syscall::syscall3(
                 SyscallNumber::Read as usize,

crates/common/src/asterisc/mod.rs

@@ -1,4 +1,4 @@
 //! TODO
 
-pub mod io;
+pub(crate) mod io;
 mod syscall;

crates/common/src/asterisc/syscall.rs

@@ -17,7 +17,7 @@ use core::arch::asm;
 
 /// Issues a raw system call with 1 argument. (e.g. exit)
 #[inline]
-pub unsafe fn syscall1(syscall_number: usize, arg1: usize) -> usize {
+pub(crate) unsafe fn syscall1(syscall_number: usize, arg1: usize) -> usize {
     let mut ret: usize;
     asm!(
         "ecall",
@@ -30,7 +30,12 @@ pub unsafe fn syscall1(syscall_number: usize, arg1: usize) -> usize {
 
 /// Issues a raw system call with 3 arguments. (e.g. read, write)
 #[inline]
-pub unsafe fn syscall3(syscall_number: usize, arg1: usize, arg2: usize, arg3: usize) -> usize {
+pub(crate) unsafe fn syscall3(
+    syscall_number: usize,
+    arg1: usize,
+    arg2: usize,
+    arg3: usize,
+) -> usize {
     let mut ret: usize;
     asm!(
         "ecall",

crates/common/src/cannon/io.rs

@@ -1,8 +1,11 @@
-use crate::{cannon::syscall, traits::BasicKernelInterface, types::RegisterSize};
+use crate::{
+    cannon::syscall, io::FileDescriptor, traits::BasicKernelInterface, types::RegisterSize,
+};
 use anyhow::{anyhow, Result};
 
 /// Concrete implementation of the [BasicKernelInterface] trait for the `MIPS32rel1` target architecture. Exposes a safe
 /// interface for performing IO operations within the FPVM kernel.
+#[derive(Debug)]
 pub struct CannonIO;
 
 /// Relevant system call numbers for the `MIPS32rel1` target architecture.
@@ -14,7 +17,7 @@ pub struct CannonIO;
 /// the [BasicKernelInterface] trait is created for the `Cannon` kernel, this list should be extended
 /// accordingly.
 #[repr(u32)]
-pub enum SyscallNumber {
+pub(crate) enum SyscallNumber {
     /// Sets the Exited and ExitCode states to true and $a0 respectively.
     Exit = 4246,
     /// Similar behavior as Linux/MIPS with support for unaligned reads.
@@ -24,9 +27,7 @@ pub enum SyscallNumber {
 }
 
 impl BasicKernelInterface for CannonIO {
-    type FileDescriptor = crate::io::FileDescriptor;
-
-    fn write(fd: Self::FileDescriptor, buf: &[u8]) -> Result<RegisterSize> {
+    fn write(fd: FileDescriptor, buf: &[u8]) -> Result<RegisterSize> {
         unsafe {
             syscall::syscall3(
                 SyscallNumber::Write as u32,
@@ -38,7 +39,7 @@ impl BasicKernelInterface for CannonIO {
         }
     }
 
-    fn read(fd: Self::FileDescriptor, buf: &mut [u8]) -> Result<RegisterSize> {
+    fn read(fd: FileDescriptor, buf: &mut [u8]) -> Result<RegisterSize> {
         unsafe {
             syscall::syscall3(
                 SyscallNumber::Read as u32,

crates/common/src/cannon/syscall.rs

@@ -38,7 +38,7 @@ use core::arch::asm;
 
 /// Issues a raw system call with 1 argument. (e.g. exit)
 #[inline]
-pub unsafe fn syscall1(n: u32, arg1: u32) -> u32 {
+pub(crate) unsafe fn syscall1(n: u32, arg1: u32) -> u32 {
     let mut err: u32;
     let mut ret: u32;
     asm!(
@@ -67,7 +67,7 @@ pub unsafe fn syscall1(n: u32, arg1: u32) -> u32 {
 
 /// Issues a raw system call with 3 arguments. (e.g. read, write)
 #[inline]
-pub unsafe fn syscall3(n: u32, arg1: u32, arg2: u32, arg3: u32) -> Result<u32, i32> {
+pub(crate) unsafe fn syscall3(n: u32, arg1: u32, arg2: u32, arg3: u32) -> Result<u32, i32> {
     let mut err: u32;
     let mut ret: u32;
     asm!(

crates/common/src/io.rs

@@ -1,8 +1,6 @@
 //! This module contains the [ClientIO] struct, which is used to perform various IO operations
 //! inside of the FPVM kernel within a `client` program.
 
-use crate::{traits::BasicKernelInterface, types::RegisterSize};
-use anyhow::Result;
 use cfg_if::cfg_if;
 
 cfg_if! {
@@ -42,8 +40,8 @@ pub enum FileDescriptor {
 mod native_io {
     extern crate std;
 
-    use super::{BasicKernelInterface, FileDescriptor, RegisterSize, Result};
-    use anyhow::anyhow;
+    use crate::{io::FileDescriptor, traits::BasicKernelInterface, types::RegisterSize};
+    use anyhow::{anyhow, Result};
     use std::{
         fs::File,
         io::{Read, Write},

crates/common/src/lib.rs

@@ -7,6 +7,7 @@
 )]
 #![deny(unused_must_use, rust_2018_idioms)]
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+#![cfg_attr(target_arch = "mips", feature(asm_experimental_arch))]
 #![no_std]
 
 pub mod io;

examples/minimal/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "minimal"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+kona-common = { path = "../../crates/common" }
+
+[profile.dev]
+panic = "abort"
+
+[profile.release]
+panic = "abort"

examples/minimal/README.md

@@ -0,0 +1,3 @@
+# `minimal`
+
+Minimal example program using the SDK.

examples/minimal/justfile

@@ -0,0 +1,17 @@
+# Build for the `cannon` target
+build-cannon *args='':
+  docker run \
+    --rm \
+    --platform linux/amd64 \
+    -v `pwd`/../../:/workdir \
+    -w="/workdir/examples/minimal" \
+    cannon-pipeline:latest cargo build -Zbuild-std $@
+
+# Build for the `asterisc` target
+build-asterisc *args='':
+  docker run \
+    --rm \
+    --platform linux/amd64 \
+    -v `pwd`/../../:/workdir \
+    -w="/workdir/examples/minimal" \
+    asterisc-pipeline:latest cargo build -Zbuild-std $@

examples/minimal/src/main.rs

@@ -0,0 +1,27 @@
+#![no_std]
+#![no_main]
+
+use kona_common::{
+    io::{ClientIO, FileDescriptor},
+    traits::BasicKernelInterface,
+};
+
+extern crate alloc;
+
+const HEAP_SIZE: usize = 0xFFFF;
+
+#[no_mangle]
+pub extern "C" fn _start() {
+    kona_common::alloc_heap!(HEAP_SIZE);
+
+    let _ = ClientIO::write(FileDescriptor::StdOut, b"Hello, world!\n");
+
+    ClientIO::exit(0)
+}
+
+#[panic_handler]
+fn panic(info: &core::panic::PanicInfo) -> ! {
+    let msg = alloc::format!("Panic: {}", info);
+    let _ = ClientIO::write(FileDescriptor::StdErr, msg.as_bytes());
+    ClientIO::exit(2)
+}