Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve precompiles doc #1904

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions crates/core/machine/src/syscall/precompiles/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,61 @@ pub fn default_syscall_map() -> HashMap<SyscallCode, Arc<dyn Syscall>> {
}
```

### Update `get_chips_and_costs` method

In the `get_chips_and_costs` method, add the costs of your new syscall to a cost hashmap for later cost estimation.

```rust
pub fn get_chips_and_costs() -> (Vec<Chip<F, Self>>, HashMap<RiscvAirDiscriminants, u64>) {
// other syscall update
let custom_op = Chip::new(RiscvAir::CustomOp(CustomOpChip::default()));
costs.insert(RiscvAirDiscriminants::CustomOp, custom_op.cost());
chips.push(custom_op);
}
```

### Update the `estimate_area` method

In the `estimate_area` method, add the costs of your new syscall to the execution trace aera estimation.

```rust
fn estimate_area(&self) -> u64 {
// other syscall update
let custom_op_events = self.syscall_counts[SyscallCode::CUSTOM_OP];
total_area += (custom_op_events as u64) * costs[&RiscvAirDiscriminants::CustomOp];
total_chips += 1;
}
```

## Expose the precompile by Syscall

Create a new file like `zkvm/entrypoint/src/syscalls/custom_op.rs` and expose your precompile by syscall:

```rust
#[allow(unused_variables)]
#[no_mangle]
pub extern "C" fn syscall_custom_op(x: *mut [u32; N], y: *const [u32; N]) {
#[cfg(target_os = "zkvm")]
unsafe {
asm!(
"ecall",
in("t0") crate::syscalls::CUSTOM_OP,
in("a0") x,
in("a1") y,
);
}

#[cfg(not(target_os = "zkvm"))]
unreachable!()
}
```

Don't forget to add your custom op in `zkvm/entrypoint/src/syscalls/mod.rs`

```rust
pub const CUSTOM_OP: u32 = 0x00_01_01_2C;
```

## Write Unit Tests for the New Precompile
### Create a New SP1 Test Package
Create a new SP1 crate for your custom precompile test package inside the directory
Expand Down