🚧 kona-common crate

Cargo.toml

@@ -12,7 +12,7 @@ homepage = "https://github.com/anton-rs/kona"
 exclude = ["**/target", "benches/", "tests"]
 
 [workspace.dependencies]
-anyhow = "1.0.75"
+anyhow = { version = "1.0.75", default-features = false }
 tracing = "0.1.40"
 
 [profile.dev]

README.md

@@ -33,7 +33,13 @@ This repository also contains an implementation of the [`op-program` specificati
 
 ## Overview
 
-*TODO*
+*todo*
+
+```
+crates
+├── `common-client`: A suite of utilities for developing `client` programs to be ran on top of Fault Proof VMs.
+└── `common-host`: A suite of utilities for developing `host` programs.
+```
 
 ## Credits
 

build/Makefile

@@ -0,0 +1,5 @@
+all: cannon
+
+.PHONY: cannon
+cannon:
+	docker build -t cannon-pipeline:latest -f cannon/cannon.dockerfile ./cannon

build/README.md

@@ -0,0 +1,22 @@
+# `kona-build`
+
+This directory contains the [`cross`][cross] 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.
+
+### Compiling Programs
+
+```
+docker run \
+    --rm \
+    --platform linux/amd64 \
+    -v `pwd`/:/workdir \
+    -w="/workdir" \
+    cannon-pipeline:latest cargo build --release -Zbuild-std
+```
+
+[cross]: https://github.com/cross-rs/cross

build/cannon/cannon.dockerfile

@@ -0,0 +1,41 @@
+# This image and the `mips-unknown-none` target were derived from `BadBoiLabs`'s
+# `cannon-rs` project.
+#
+# https://github.com/BadBoiLabs/Cannon-rs
+
+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++-mips-linux-gnu \
+  libc6-dev-mips-cross \
+  binutils-mips-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}"
+
+# Add the special cannon build target
+COPY ./mips-unknown-none.json .
+
+# 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_mips_unknown_none=mips-linux-gnu-gcc \
+  CXX_mips_unknown_none=mips-linux-gnu-g++ \
+  CARGO_TARGET_MIPS_UNKNOWN_NONE_LINKER=mips-linux-gnu-gcc \
+  RUSTFLAGS="-Clink-arg=-e_start -C llvm-args=-mno-check-zero-division" \
+  CARGO_BUILD_TARGET="/mips-unknown-none.json" \
+  RUSTUP_TOOLCHAIN=${RUST_VERSION}

build/cannon/mips-unknown-none.json

@@ -0,0 +1,19 @@
+{
+  "arch": "mips",
+  "cpu": "mips32",
+  "llvm-target": "mips-unknown-none",
+  "data-layout": "E-m:m-p:32:32-i8:8:32-i16:16:32-i64:64-n32-S64",
+  "target-endian": "big",
+  "target-pointer-width": "32",
+  "target-c-int-width": "32",
+  "os": "none",
+  "features": "+soft-float,+mips32,-mips32r2",
+  "max-atomic-width": "0",
+  "linker": "rust-lld",
+  "linker-flavor": "ld.lld",
+  "executables": true,
+  "panic-strategy": "abort",
+  "relocation-model": "static",
+  "emit-debug-gdb-scripts": false,
+  "singlethread": true
+}

crates/common/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
-name = "common"
-description = "common crate"
+name = "kona-common"
+description = "Common traits and utilities for Kona"
 version = { workspace = true }
 edition = { workspace = true }
 authors = { workspace = true }
@@ -9,3 +9,9 @@ repository = { workspace = true }
 homepage = { workspace = true }
 
 [dependencies]
+# workspace
+anyhow.workspace = true
+
+# external
+num = { version = "0.4.1", default-features = false }
+good_memory_allocator = "0.1.7"

crates/common/README.md

@@ -1,3 +1,5 @@
 # `kona-common`
 
+A suite of utilities for developing `host` programs and verifiable `client` executables.
+
 *TODO*

crates/common/src/lib.rs

@@ -7,5 +7,7 @@
 )]
 #![deny(unused_must_use, rust_2018_idioms)]
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+#![cfg_attr(not(test), no_std)]
 
-// TODO
+pub mod malloc;
+pub mod traits;

crates/common/src/malloc.rs

@@ -0,0 +1,44 @@
+//! This module contains an implementation of a basic memory allocator for client programs in
+//! running on top of various FPVMs. The allocator is a linked list allocator based on the
+//! `dlmalloc` algorithm, which is a well-known and widely used allocator software such
+//! as OS Kernels.
+
+#[cfg(not(test))]
+use good_memory_allocator::SpinLockedAllocator;
+
+/// The global allocator for the program in the `test` profile uses the standard allocator.
+#[cfg(test)]
+#[global_allocator]
+static ALLOCATOR: std::alloc::System = std::alloc::System;
+
+/// The global allocator for the program in other profiles uses the [SpinLockedAllocator].
+#[cfg(not(test))]
+#[global_allocator]
+static ALLOCATOR: SpinLockedAllocator = SpinLockedAllocator::empty();
+
+/// Initialize the [SpinLockedAllocator] with the following parameters:
+/// * `heap_start_addr` is the starting address of the heap memory region,
+/// * `heap_size` is the size of the heap memory region in bytes.
+///
+/// # Safety
+/// This function is unsafe because the caller must ensure:
+/// * The allocator has not already been initialized.
+/// * The provided memory region must be valid, non-null, and not used by anything else.
+/// * After aligning the start and end addresses, the size of the heap must be > 0, or the function
+///   will panic.
+#[cfg_attr(test, allow(unused_variables))]
+pub unsafe fn init_allocator(heap_start_addr: usize, heap_size: usize) {
+    #[cfg(not(test))]
+    ALLOCATOR.init(heap_start_addr, heap_size)
+}
+
+/// Initialize heap memory for the `client` program with
+#[macro_export]
+macro_rules! init_heap {
+    ($size:expr) => {{
+        use kona_common::malloc::init_allocator;
+
+        static mut HEAP: [u8; $size] = [0u8; $size];
+        unsafe { init_allocator(HEAP.as_ptr() as usize, $size) }
+    }};
+}

crates/common/src/traits/mod.rs

@@ -0,0 +1,10 @@
+//! Contains common traits for the `client` role.
+//!
+//! When developing a new `client` program, these traits are implemented on an
+//! architecture-specific type that provides the concrete implementation of the
+//! kernel interfaces. The `client` program then uses these traits to perform operations
+//! without needing to know the underlying implementation, which allows the same `client`
+//! program to be compiled and ran on different target FPVM architectures.
+
+mod syscall;
+pub use syscall::KernelIO;

crates/common/src/traits/syscall.rs

@@ -0,0 +1,31 @@
+//! Defines the [KernelIO] trait, which describes the functionality of several
+//! system calls inside of the FPVM kernel. This trait is to be implemented by the
+//! `client` program, and then used by the `kernel` to perform IO operations.
+
+use anyhow::Result;
+use num::Unsigned;
+
+/// The [KernelIO] trait describes the functionality of several system calls inside of
+/// the FPVM kernel. Commonly, FPVMs delegate IO operations to custom file descriptors in
+/// the `client` program.
+///
+///
+/// The `RS` type parameter is the size of the registers in the VM. On MIPS32 for example,
+/// this would be 32, and on RISC-V/64 this would be 64.
+///
+/// In cases where the set of system calls defined in this trait need to be extended, an
+/// additional trait should be created that extends this trait.
+pub trait KernelIO<RS: Unsigned> {
+    /// Associated type for the file descriptors available.
+    type FileDescriptor;
+
+    /// Write the given buffer to the given file descriptor.
+    fn write(fd: Self::FileDescriptor, buf: &[u8]) -> Result<RS>;
+
+    /// Read from the given file descriptor into the passed buffer.
+    fn read(fd: Self::FileDescriptor, buf: &mut [u8]) -> Result<RS>;
+
+    /// Exit the process with the given exit code. The implementation of this function
+    /// should always panic after invoking the `EXIT` syscall.
+    fn exit(code: RS) -> !;
+}