Unify memcpy, memmove, memset and commit on one accelerator

bin/cli/README.md

@@ -41,7 +41,7 @@ cargo run -p cli --release -- execute <PROGRAM.elf> [--private-input <FILE>] [--
 |---|---|
 | `--private-input <FILE>` | Pass private input bytes to the guest (read via `get_private_input()`). |
 | `--flamegraph <FILE>` | Generate folded-stack flamegraph output. See [Guest Program Flamegraphs](#guest-program-flamegraphs). |
-| `--cycles` | Count instructions during execution and print the dynamic instruction count. Also reports `Keccak calls` / `Ecsm calls` (accelerator syscall invocations). Combined with `--flamegraph`, the accelerator lines are omitted (the flamegraph path exposes no per-log data). |
+| `--cycles` | Count instructions during execution and print the dynamic instruction count. Also reports `Keccak calls` / `Ecsm calls` / `Dma calls` (accelerator syscall invocations), plus `Dma bytes` copied and the `Dma rows` those copies add to the trace before its power-of-two padding. One guest `memcpy` is chunked into several DMA ecalls, so the byte and row lines, not the call count, are what the copies cost. The lines cover `memcpy`, `memmove` and `memset`, which share one ecall path and one table; the commit byte loop lives in that same table but is not tallied here. Combined with `--flamegraph`, the accelerator lines are omitted (the flamegraph path exposes no per-log data). |
 
 ### Prove
 

bin/cli/src/main.rs

@@ -191,9 +191,12 @@ enum Commands {
         cycle_budget: Option<u64>,
 
         /// Print the dynamic instruction (cycle) count, plus `Keccak calls` /
-        /// `Ecsm calls` (accelerator syscall invocations). The accelerator lines
-        /// are omitted when combined with --flamegraph (that path has no per-log
-        /// data).
+        /// `Ecsm calls` / `Dma calls` (accelerator syscall invocations), and for
+        /// DMA the `Dma bytes` copied and the `Dma rows` those copies add to the
+        /// trace before its power-of-two padding. One `memcpy` is chunked into
+        /// several DMA ecalls, so the byte and row lines, not the call count, are
+        /// what the copies cost. The accelerator lines are omitted when combined
+        /// with --flamegraph (that path has no per-log data).
         #[arg(long)]
         cycles: bool,
     },
@@ -408,6 +411,41 @@ struct FlamegraphCliOptions {
     checkpoint_cycles: Option<u64>,
 }
 
+/// One tally per [`Accelerator`] variant, printed by `execute --cycles`.
+#[derive(Default)]
+struct AccelCounts {
+    keccak: u64,
+    ecsm: u64,
+    dma: u64,
+    /// Bytes copied and DMA table rows those copies consume. Keccak and ECSM
+    /// cost the same per call, so DMA is the only accelerator whose report needs
+    /// a size next to its count: one `memcpy` becomes as many ecalls as the
+    /// guest stub chunks it into, which makes `dma` alone a poor cost proxy.
+    dma_bytes: u64,
+    dma_rows: u64,
+}
+
+impl AccelCounts {
+    /// Exhaustive `match`: a new `Accelerator` variant is a compile error here,
+    /// so it cannot be executed without also being reported. `dst_val` is the
+    /// ECALL's logged operands: `dst_val` is the chunk's byte count for DMA and
+    /// unused for the others; `rows` is the COPY row count the executor derived
+    /// at the ecall. The width follows from `count` alone today, so the row count is
+    /// recoverable from it; the slot is kept because the AIR permits a schedule that
+    /// reads both ends' residues and a future one may.
+    fn tally(&mut self, accelerator: Accelerator, dst_val: u64, rows: u64) {
+        match accelerator {
+            Accelerator::Keccak => self.keccak += 1,
+            Accelerator::Ecsm => self.ecsm += 1,
+            Accelerator::Dma => {
+                self.dma += 1;
+                self.dma_bytes += dst_val;
+                self.dma_rows += rows;
+            }
+        }
+    }
+}
+
 /// Classifies one executed instruction as an accelerator syscall invocation.
 ///
 /// Delegates to the executor's canonical `SyscallNumbers::accelerator()` so the
@@ -461,7 +499,7 @@ fn cmd_execute(
     // below (the flamegraph path drives execution inside the executor and does
     // not expose per-log data). `None` means "not counted", so the accel lines
     // are omitted rather than printed as misleading zeros.
-    let mut accel_counts: Option<(u64, u64)> = None;
+    let mut accel_counts: Option<AccelCounts> = None;
 
     let cycle_count = if let Some(ref output_path) = flamegraph.path {
         // Shared execute+flamegraph path (executor::flamegraph) instead of
@@ -527,14 +565,13 @@ fn cmd_execute(
         };
 
         let mut cycle_count: u64 = 0;
-        let mut keccak_calls: u64 = 0;
-        let mut ecsm_calls: u64 = 0;
-        // Reused per chunk: `(current_pc, a7)` for logs whose a7 matches an
-        // accelerator syscall number. This is a cheap superset — a non-ECALL
+        let mut counts = AccelCounts::default();
+        // Reused per chunk: `(current_pc, a7, dst_val)` for logs whose a7 matches
+        // an accelerator syscall number. This is a cheap superset — a non-ECALL
         // instruction can hold the same value in src1 — that `accelerator_of`
         // confirms below, once the chunk's `&Log` borrow (tied to the executor's
         // `&mut`) is released so the instruction cache can be read again.
-        let mut accel_candidates: Vec<(u64, u64)> = Vec::new();
+        let mut accel_candidates: Vec<(u64, u64, u64, u64)> = Vec::new();
         loop {
             let logs = match executor.resume_budgeted(cycle_count, cycle_budget) {
                 Ok(logs) => logs,
@@ -551,17 +588,20 @@ fn cmd_execute(
                         .map(|s| s.accelerator().is_some())
                         .unwrap_or(false)
                     {
-                        accel_candidates.push((log.current_pc, log.src1_val));
+                        accel_candidates.push((
+                            log.current_pc,
+                            log.src1_val,
+                            log.dst_val,
+                            log.src2_val,
+                        ));
                     }
                 }
             }
             // `logs` is no longer used, so the executor's `&mut` borrow is free
             // and the instruction cache can be read to confirm each candidate.
-            for (pc, a7) in accel_candidates.drain(..) {
-                match accelerator_of(executor.instructions.get(pc), a7) {
-                    Some(Accelerator::Keccak) => keccak_calls += 1,
-                    Some(Accelerator::Ecsm) => ecsm_calls += 1,
-                    None => {}
+            for (pc, a7, dst_val, rows) in accel_candidates.drain(..) {
+                if let Some(accelerator) = accelerator_of(executor.instructions.get(pc), a7) {
+                    counts.tally(accelerator, dst_val, rows);
                 }
             }
             if cycle_budget.is_some_and(|budget| cycle_count >= budget) {
@@ -575,16 +615,19 @@ fn cmd_execute(
         }
 
         if cycles {
-            accel_counts = Some((keccak_calls, ecsm_calls));
+            accel_counts = Some(counts);
         }
         cycle_count
     };
 
     if cycles {
         println!("Cycles: {}", cycle_count);
-        if let Some((keccak_calls, ecsm_calls)) = accel_counts {
-            println!("Keccak calls: {}", keccak_calls);
-            println!("Ecsm calls: {}", ecsm_calls);
+        if let Some(counts) = accel_counts {
+            println!("Keccak calls: {}", counts.keccak);
+            println!("Ecsm calls: {}", counts.ecsm);
+            println!("Dma calls: {}", counts.dma);
+            println!("Dma bytes: {}", counts.dma_bytes);
+            println!("Dma rows: {}", counts.dma_rows);
         }
     }
 
@@ -1151,43 +1194,115 @@ mod tests {
         assert_eq!(continuation_epoch_size(20).unwrap(), 1 << 20);
     }
 
+    /// The chip each syscall must drive, written out here rather than read back
+    /// from `SyscallNumbers::accelerator()`. Comparing the CLI against the
+    /// executor alone would pass if both agreed on the wrong answer — a chip
+    /// demoted to `None` has to fail somewhere, and this is that somewhere.
+    ///
+    /// Cross-checked row by row against `SyscallNumbers::ALL`, which the
+    /// executor's macro generates from the enum, so a new syscall fails the test
+    /// until it gets a row here.
+    const EXPECTED_ACCELERATORS: &[(SyscallNumbers, Option<Accelerator>)] = &[
+        (SyscallNumbers::KeccakPermute, Some(Accelerator::Keccak)),
+        (SyscallNumbers::Ecsm, Some(Accelerator::Ecsm)),
+        (SyscallNumbers::DmaMemcpy, Some(Accelerator::Dma)),
+        (SyscallNumbers::DmaMemset, Some(Accelerator::Dma)),
+        (SyscallNumbers::Print, None),
+        (SyscallNumbers::Panic, None),
+        (SyscallNumbers::Commit, None),
+        (SyscallNumbers::Halt, None),
+        // `hint` drives its own HINT table, but the executor maps it to no
+        // `Accelerator`: the ecall adds no correctness constraint, so there is no
+        // accelerated work to attribute. `execute --cycles` reports no hint line.
+        (SyscallNumbers::Hint, None),
+    ];
+
     // `accelerator_of` must match the prover's `CpuOperation::from_log`: count an
     // invocation only when the instruction is an ECALL AND a7 is the accelerator
-    // syscall number. Covers both accelerators, the non-accelerator syscalls, a
-    // non-ECALL whose src1 collides with an accelerator number, and a cache miss.
+    // syscall number.
     #[test]
     fn accelerator_of_mirrors_prover_classification() {
-        use executor::vm::instruction::execution::{ECSM_SYSCALL_NUMBER, KECCAK_SYSCALL_NUMBER};
-
         let ecall = Instruction::EcallEbreak;
 
-        assert_eq!(
-            accelerator_of(Some(&ecall), KECCAK_SYSCALL_NUMBER),
-            Some(Accelerator::Keccak)
-        );
-        assert_eq!(
-            accelerator_of(Some(&ecall), ECSM_SYSCALL_NUMBER),
-            Some(Accelerator::Ecsm)
-        );
+        for &syscall in SyscallNumbers::ALL {
+            let rows = EXPECTED_ACCELERATORS
+                .iter()
+                .filter(|(listed, _)| *listed == syscall)
+                .count();
+            assert_eq!(
+                rows, 1,
+                "{syscall:?} needs exactly one row in EXPECTED_ACCELERATORS"
+            );
+        }
 
-        // Non-accelerator syscalls (Commit=64, Halt=93) count as neither.
-        assert_eq!(
-            accelerator_of(Some(&ecall), SyscallNumbers::Commit as u64),
-            None
-        );
-        assert_eq!(
-            accelerator_of(Some(&ecall), SyscallNumbers::Halt as u64),
-            None
-        );
+        for &(syscall, expected) in EXPECTED_ACCELERATORS {
+            assert_eq!(
+                accelerator_of(Some(&ecall), syscall.raw()),
+                expected,
+                "ECALL with a7 of {syscall:?} must classify as {expected:?}"
+            );
+            // A non-ECALL instruction whose src1 happens to equal a syscall a7
+            // must not count — this is the `f.ecall &&` guard the prover applies.
+            assert_eq!(
+                accelerator_of(Some(&Instruction::Fence), syscall.raw()),
+                None,
+                "non-ECALL with a7 of {syscall:?} must not count"
+            );
+            // No decoded instruction at the pc (cache miss) counts as neither.
+            assert_eq!(accelerator_of(None, syscall.raw()), None);
+        }
+    }
 
-        // A non-ECALL instruction whose src1 happens to equal an accelerator a7
-        // must not count — this is the `f.ecall &&` guard the prover applies.
-        assert_eq!(
-            accelerator_of(Some(&Instruction::Fence), KECCAK_SYSCALL_NUMBER),
-            None
-        );
+    // Every tallied accelerator gets its own counter: no two variants may share
+    // a field, and each must land in the one the report prints.
+    #[test]
+    fn accel_counts_tallies_each_accelerator_separately() {
+        for &(_, expected_accelerator) in EXPECTED_ACCELERATORS {
+            let Some(accelerator) = expected_accelerator else {
+                continue;
+            };
+            let mut counts = AccelCounts::default();
+            counts.tally(accelerator, 0, 0);
+            assert_eq!(
+                counts.keccak + counts.ecsm + counts.dma,
+                1,
+                "{accelerator:?} must increment exactly one counter"
+            );
+            let expected = match accelerator {
+                Accelerator::Keccak => counts.keccak,
+                Accelerator::Ecsm => counts.ecsm,
+                Accelerator::Dma => counts.dma,
+            };
+            assert_eq!(
+                expected, 1,
+                "{accelerator:?} must increment its own counter"
+            );
+        }
+    }
+
+    // The byte and row lines are what make the DMA report a cost figure rather
+    // than a call count, so they must accumulate across chunked ecalls and use
+    // the executor's row formula — the same one trace generation sizes with.
+    #[test]
+    fn accel_counts_sizes_dma_calls() {
+        let mut counts = AccelCounts::default();
+        // Rows as the executor derives them at each ecall.
+        for bytes in [256, 256, 8, 3, 0] {
+            let rows =
+                executor::vm::instruction::execution::copy_trace_rows(0x1000, 0x2000, bytes, false);
+            counts.tally(Accelerator::Dma, bytes, rows);
+        }
 
-        // No decoded instruction at the pc (cache miss) counts as neither.
-        assert_eq!(accelerator_of(None, KECCAK_SYSCALL_NUMBER), None);
+        assert_eq!(counts.dma, 5, "every DMA ecall counts as one call");
+        assert_eq!(counts.dma_bytes, 523);
+        // The rows are the executor's, derived where src, dst and count are all known;
+        // the report only sums them.
+        assert_eq!(counts.dma_rows, 32 + 32 + 1 + 3 + 1);
+
+        // The other accelerators must leave the DMA size lines alone.
+        let mut others = AccelCounts::default();
+        others.tally(Accelerator::Keccak, 200, 0);
+        others.tally(Accelerator::Ecsm, 32, 0);
+        assert_eq!((others.dma, others.dma_bytes, others.dma_rows), (0, 0, 0));
     }
 }

docs/continuations_design.md

@@ -435,7 +435,7 @@ dropped the "chain is complete" property both rely on.
 
 Registers must also carry across epochs: epoch *i+1* must start from epoch *i*'s
 final register file. Unlike memory, the register file is **small and fixed** (34
-registers / 67 word-addresses, all present every epoch), so it needs no L2G /
+registers / 68 word-addresses, all present every epoch), so it needs no L2G /
 global telescoping — we bind the whole snapshot directly.
 
 **Mechanism (no new bus).** The REGISTER table is the register analog of PAGE — it
@@ -474,13 +474,13 @@ has no verifier-known final state) and preprocesses 2 columns, not 3.
 
 ### Commit index (x254)
 
-The COMMIT chip's running output index lives in a synthetic single-word register
-**x254** (word-address 508), so it rides the **same** register binding above —
+The COPY chip's running output index lives in the synthetic register **x254**
+(word-addresses 508-509), so it rides the **same** register binding above —
 epoch *i*'s `FINI[x254]` becomes epoch *i+1*'s `INIT[x254]`, pinned by the two
 locks like any register. Each epoch therefore indexes its committed bytes from the
 *carried* value, not from `0`:
 
-- the COMMIT trace seeds `current_commit_index` from x254
+- the COPY trace seeds `current_commit_index` from x254
   (`register_state.read_index()` in `trace_builder.rs`), with a debug-assert
   pinning the two in sync every step;
 - the verifier's commit-bus offset (`compute_commit_bus_offset`'s `start_index`)