emul: Runtime and build scripts

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
     "ceno_emul",
+    "ceno_rt",
     "gkr",
     "gkr-graph",
     "mpcs",

ceno_emul/Cargo.toml

@@ -9,3 +9,4 @@ anyhow = { version = "1.0", default-features = false }
 tracing = { version = "0.1", default-features = false, features = [
     "attributes",
 ] }
+elf = { version = "0.7.4" }

ceno_emul/src/elf.rs

@@ -0,0 +1,112 @@
+// Based on: https://github.com/risc0/risc0/blob/6b6daeafa1545984aa28581fca56d9ef13dcbae6/risc0/binfmt/src/elf.rs
+//
+// Copyright 2024 RISC Zero, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+extern crate alloc;
+
+use alloc::collections::BTreeMap;
+
+use crate::addr::WORD_SIZE;
+use anyhow::{anyhow, bail, Context, Result};
+use elf::{endian::LittleEndian, file::Class, ElfBytes};
+
+/// A RISC Zero program
+pub struct Program {
+    /// The entrypoint of the program
+    pub entry: u32,
+
+    /// The initial memory image
+    pub image: BTreeMap<u32, u32>,
+}
+
+impl Program {
+    /// Initialize a RISC Zero Program from an appropriate ELF file
+    pub fn load_elf(input: &[u8], max_mem: u32) -> Result<Program> {
+        let mut image: BTreeMap<u32, u32> = BTreeMap::new();
+        let elf = ElfBytes::<LittleEndian>::minimal_parse(input)
+            .map_err(|err| anyhow!("Elf parse error: {err}"))?;
+        if elf.ehdr.class != Class::ELF32 {
+            bail!("Not a 32-bit ELF");
+        }
+        if elf.ehdr.e_machine != elf::abi::EM_RISCV {
+            bail!("Invalid machine type, must be RISC-V");
+        }
+        if elf.ehdr.e_type != elf::abi::ET_EXEC {
+            bail!("Invalid ELF type, must be executable");
+        }
+        let entry: u32 = elf
+            .ehdr
+            .e_entry
+            .try_into()
+            .map_err(|err| anyhow!("e_entry was larger than 32 bits. {err}"))?;
+        if entry >= max_mem || entry % WORD_SIZE as u32 != 0 {
+            bail!("Invalid entrypoint");
+        }
+        let segments = elf.segments().ok_or(anyhow!("Missing segment table"))?;
+        if segments.len() > 256 {
+            bail!("Too many program headers");
+        }
+        for segment in segments.iter().filter(|x| x.p_type == elf::abi::PT_LOAD) {
+            let file_size: u32 = segment
+                .p_filesz
+                .try_into()
+                .map_err(|err| anyhow!("filesize was larger than 32 bits. {err}"))?;
+            if file_size >= max_mem {
+                bail!("Invalid segment file_size");
+            }
+            let mem_size: u32 = segment
+                .p_memsz
+                .try_into()
+                .map_err(|err| anyhow!("mem_size was larger than 32 bits {err}"))?;
+            if mem_size >= max_mem {
+                bail!("Invalid segment mem_size");
+            }
+            let vaddr: u32 = segment
+                .p_vaddr
+                .try_into()
+                .map_err(|err| anyhow!("vaddr is larger than 32 bits. {err}"))?;
+            if vaddr % WORD_SIZE as u32 != 0 {
+                bail!("vaddr {vaddr:08x} is unaligned");
+            }
+            let offset: u32 = segment
+                .p_offset
+                .try_into()
+                .map_err(|err| anyhow!("offset is larger than 32 bits. {err}"))?;
+            for i in (0..mem_size).step_by(WORD_SIZE) {
+                let addr = vaddr.checked_add(i).context("Invalid segment vaddr")?;
+                if addr >= max_mem {
+                    bail!(
+                        "Address [0x{addr:08x}] exceeds maximum address for guest programs [0x{max_mem:08x}]"
+                    );
+                }
+                if i >= file_size {
+                    // Past the file size, all zeros.
+                    image.insert(addr, 0);
+                } else {
+                    let mut word = 0;
+                    // Don't read past the end of the file.
+                    let len = core::cmp::min(file_size - i, WORD_SIZE as u32);
+                    for j in 0..len {
+                        let offset = (offset + i + j) as usize;
+                        let byte = input.get(offset).context("Invalid segment offset")?;
+                        word |= (*byte as u32) << (j * 8);
+                    }
+                    image.insert(addr, word);
+                }
+            }
+        }
+        Ok(Program { entry, image })
+    }
+}

ceno_emul/src/lib.rs

@@ -12,3 +12,6 @@ pub use vm_state::VMState;
 
 mod rv32im;
 pub use rv32im::{DecodedInstruction, EmuContext, InsnCategory, InsnKind};
+
+mod elf;
+pub use elf::Program;

ceno_emul/src/rv32im.rs

@@ -97,7 +97,7 @@ pub enum TrapCause {
     LoadAccessFault(ByteAddr),
     StoreAddressMisaligned(ByteAddr),
     StoreAccessFault,
-    EnvironmentCallFromUserMode,
+    EcallError,
 }
 
 #[derive(Clone, Debug, Default)]

ceno_emul/src/tracer.rs

@@ -77,6 +77,10 @@ impl StepRecord {
     pub fn memory_op(&self) -> Option<WriteOp> {
         self.memory_op.clone()
     }
+
+    pub fn is_busy_loop(&self) -> bool {
+        self.pc.before == self.pc.after
+    }
 }
 
 #[derive(Debug)]

ceno_emul/src/vm_state.rs

@@ -6,6 +6,7 @@ use crate::{
     platform::Platform,
     rv32im::{DecodedInstruction, Emulator, Instruction, TrapCause},
     tracer::{Change, StepRecord, Tracer},
+    Program,
 };
 use anyhow::{anyhow, Result};
 use std::iter::from_fn;
@@ -35,6 +36,19 @@ impl VMState {
         }
     }
 
+    pub fn new_from_elf(platform: Platform, elf: &[u8]) -> Result<Self> {
+        let mut state = Self::new(platform);
+        let program = Program::load_elf(elf, u32::MAX).unwrap();
+        for (addr, word) in program.image.iter() {
+            let addr = ByteAddr(*addr).waddr();
+            state.init_memory(addr, *word);
+        }
+        if program.entry != state.platform.pc_start() {
+            return Err(anyhow!("Invalid entrypoint {:x}", program.entry));
+        }
+        Ok(state)
+    }
+
     pub fn succeeded(&self) -> bool {
         self.succeeded
     }
@@ -62,7 +76,11 @@ impl VMState {
     fn step(&mut self, emu: &Emulator) -> Result<StepRecord> {
         emu.step(self)?;
         let step = self.tracer().advance();
-        Ok(step)
+        if step.is_busy_loop() && !self.succeeded() {
+            Err(anyhow!("Stuck in loop {}", "{}"))
+        } else {
+            Ok(step)
+        }
     }
 }
 
@@ -76,7 +94,7 @@ impl EmuContext for VMState {
             self.succeeded = true;
             Ok(true)
         } else {
-            self.trap(TrapCause::EnvironmentCallFromUserMode)
+            self.trap(TrapCause::EcallError)
         }
     }
 

ceno_emul/tests/data/README.md

@@ -0,0 +1,7 @@
+### Generate test programs:
+
+```bash
+cd ceno_rt
+cargo build --release --examples
+cp ../target/riscv32im-unknown-none-elf/release/examples/ceno_rt_{mini,panic,mem} ../ceno_emul/tests/data/
+```

ceno_emul/tests/test_elf.rs

@@ -0,0 +1,35 @@
+use anyhow::Result;
+use ceno_emul::{ByteAddr, EmuContext, StepRecord, VMState, CENO_PLATFORM};
+
+#[test]
+fn test_ceno_rt_mini() -> Result<()> {
+    let program_elf = include_bytes!("./data/ceno_rt_mini");
+    let mut state = VMState::new_from_elf(CENO_PLATFORM, program_elf)?;
+    let _steps = run(&mut state)?;
+    Ok(())
+}
+
+#[test]
+fn test_ceno_rt_panic() -> Result<()> {
+    let program_elf = include_bytes!("./data/ceno_rt_panic");
+    let mut state = VMState::new_from_elf(CENO_PLATFORM, program_elf)?;
+    let res = run(&mut state);
+
+    assert!(matches!(res, Err(e) if e.to_string().contains("EcallError")));
+    Ok(())
+}
+
+#[test]
+fn test_ceno_rt_mem() -> Result<()> {
+    let program_elf = include_bytes!("./data/ceno_rt_mem");
+    let mut state = VMState::new_from_elf(CENO_PLATFORM, program_elf)?;
+    let _steps = run(&mut state)?;
+
+    let value = state.peek_memory(ByteAddr(CENO_PLATFORM.ram_start()).waddr());
+    assert_eq!(value, 6765, "Expected Fibonacci 20, got {}", value);
+    Ok(())
+}
+
+fn run(state: &mut VMState) -> Result<Vec<StepRecord>> {
+    state.iter_until_success().collect()
+}

ceno_rt/.cargo/config.toml

@@ -0,0 +1,13 @@
+[target.riscv32im-unknown-none-elf]
+rustflags = [
+  "-C", "link-arg=-Tmemory.x",
+  #"-C", "link-arg=-Tlink.x", // Script from riscv_rt.
+  "-C", "link-arg=-Tceno_link.x",
+]
+
+[build]
+target = "riscv32im-unknown-none-elf"
+
+[profile.release]
+panic = "abort"
+lto = true

ceno_rt/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "ceno_rt"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+riscv = "0.11.1"
+riscv-rt = "0.12.2"

ceno_rt/README.md

@@ -0,0 +1,25 @@
+# Ceno VM Runtime
+
+This crate provides the runtime for program running on the Ceno VM. It provides:
+
+- Configuration of compilation and linking.
+- Program startup and termination.
+- Memory setup.
+
+### Build examples
+
+```bash
+rustup target add riscv32im-unknown-none-elf
+
+cargo build --release --examples
+```
+
+### Development tools
+
+```bash
+cargo install cargo-binutils
+rustup component add llvm-tools
+
+# Look at the disassembly of a compiled program.
+cargo objdump --release --example ceno_rt_mini -- --all-headers --disassemble
+```