Skip to main content

cache_test/
cache_test.rs

1//! Cache-coherence test: verifies that `cache_writeback` makes Minion-written
2//! data visible to host DMA, and instruments the launch to diagnose faults.
3//!
4//! Each primary Minion hart writes its global Minion index into its own
5//! cache-line-padded output cell and calls `cache_writeback` before `fence`.
6//! The host downloads the output array and asserts every cell holds the
7//! expected Minion index.
8//!
9//! # Previously known intermittent fault (resolved in 0.6.1)
10//!
11//! Prior to 0.6.1 this example intermittently produced EXCEPTION (status 2) at
12//! 16 or more shires at a rate of 50-90 percent with a non-deterministic faulting-
13//! shire mask. Root cause: `alloc_padded` was called before `load_kernel`, placing
14//! the output buffer at DRAM base (`0x8005801000`) -- the same address to which
15//! `load_kernel` DMA-writes kernel code. Each Minion wrote its index into live
16//! kernel code pages; `flush_va` then flushed those dirty lines to DRAM,
17//! corrupting the kernel image. Calling `load_kernel` first (as documented on
18//! that method) places the output buffer after the kernel's loaded extent and
19//! eliminates the fault. Confirmed: two clean passes at 32 shires on aifoundry3
20//! (2026-09-18) immediately after the fix.
21//!
22//! The fault was NOT caused by the kernel binary, the instruction gap between
23//! `csrw flush_va` and `csrwi tensor_wait`, the writeback destination, the launch
24//! BARRIER flag, the exception buffer, or the pre-writeback fence (all tested and
25//! ruled out during diagnosis; the Rust kernel ELF and a 5-NOP-gap C variant each
26//! passed 20/20 at 32 shires via a C++ host).
27//!
28//! # Diagnostic controls
29//!
30//! An optional shire count narrows a concurrency-dependent fault (run on 1 shire
31//! versus all 32); an optional destination level narrows a DDR-specific fault
32//! (flush to L2/L3 instead of Mem).
33//!
34//! `ET_NO_BARRIER=1` clears the launch BARRIER flag. Tested and refuted: the
35//! failure rate is unchanged with the barrier on or off, so the firmware
36//! barrier/drain path is not the trigger. Retained as a documented control.
37//!
38//! `ET_EXC_BUFFER=1` additionally supplies a U-mode exception buffer and, on a
39//! launch exception, decodes the execution context the firmware leaves there
40//! (`mcause`, `mepc`, `mtval`), distinguishing an illegal instruction (cache-op
41//! feature gate) from a page/access fault (the flush path). Off by default: on the
42//! current card firmware a non-zero exception buffer is itself rejected with
43//! EXCEPTION (status 2) regardless of kernel correctness, and firmware writes
44//! nothing into it, so it is reserved for probing a firmware build that supports
45//! the feature.
46//!
47//! # Usage
48//! ```text
49//! cargo run --example cache_test -- <cache-test-rs.elf> [shires] [dest]
50//! ```
51//! `shires` selects the lowest `shires` present shires and defaults to all; `dest` is 1 = L2, 2 = L3, 3 = Mem (default,
52//! the only host-visible level).
53
54use std::process::ExitCode;
55
56use et_abi::{CacheTestArgs, DeviceArgs, MINIONS_PER_SHIRE};
57use et_soc1::{Device, LaunchOptions};
58
59/// Size of the exception buffer: the firmware writes an `execution_context_t`
60/// (type, cycles, hart_id, sepc, sstatus, stval, scause, user_error, 31 GPRs =
61/// 312 bytes) here on a U-mode trap; 512 bytes gives margin and 64-byte alignment.
62const EXC_BUF_LEN: usize = 512;
63
64/// Byte written over the output buffer before launch; cells of shires outside
65/// the launch mask must still hold it afterwards.
66const SENTINEL: u8 = 0xFF;
67
68/// The sentinel as read back through a `u32` cell.
69const SENTINEL_WORD: u32 = u32::from_ne_bytes([SENTINEL; 4]);
70
71fn main() -> ExitCode {
72    match run() {
73        Ok(()) => ExitCode::SUCCESS,
74        Err(e) => {
75            eprintln!("error: {e}");
76            ExitCode::FAILURE
77        }
78    }
79}
80
81fn run() -> et_soc1::Result<()> {
82    let argv: Vec<String> = std::env::args().collect();
83    let kernel_path = argv.get(1).cloned().unwrap_or_else(|| {
84        eprintln!("usage: cache_test <cache-test-rs.elf> [shires] [dest:1=L2,2=L3,3=Mem]");
85        std::process::exit(2);
86    });
87    let elf = std::fs::read(&kernel_path).map_err(|e| et_soc1::Error::io("read kernel ELF", e))?;
88
89    let device = Device::open(0)?;
90    let topo = device.topology()?;
91    let max_shires = topo.num_shires() as usize;
92
93    // Narrowing controls. `shires` (default all) isolates concurrency-dependent
94    // faults; `dest` (default 3 = Mem) isolates the DDR writeback path.
95    let n_shires = argv
96        .get(2)
97        .and_then(|s| s.parse::<usize>().ok())
98        .map(|k| k.clamp(1, max_shires))
99        .unwrap_or(max_shires);
100    let dest: u64 = argv.get(3).and_then(|s| s.parse().ok()).unwrap_or(3);
101    // The lowest `n_shires` present shires. Cells are indexed by physical
102    // shire, so the output spans every shire up to the highest launched one and
103    // `n_shires` in the arguments is that extent, not the count.
104    let mut shire_mask = 0u64;
105    for shire in (0..u64::BITS)
106        .filter(|&s| topo.shire_mask & (1 << s) != 0)
107        .take(n_shires)
108    {
109        shire_mask |= 1 << shire;
110    }
111    let shire_extent = (u64::BITS - shire_mask.leading_zeros()) as usize;
112    let n_cells = shire_extent * MINIONS_PER_SHIRE as usize;
113    let n_minions = n_shires * MINIONS_PER_SHIRE as usize;
114    let launched = |cell: usize| shire_mask & (1 << (cell / MINIONS_PER_SHIRE as usize)) != 0;
115
116    println!(
117        "Device: {} shires present (mask {:#x}); running {} shire(s) (mask {:#x}), {} Minions, dest = {}",
118        max_shires,
119        topo.shire_mask,
120        n_shires,
121        shire_mask,
122        n_minions,
123        dest_name(dest),
124    );
125
126    // Kernel must be loaded first so it lands at DRAM base (its link address).
127    // Allocating output before load_kernel would place the output buffer at
128    // DRAM base and kernel code would then DMA-overwrite it.
129    let kernel = device.load_kernel(&elf)?;
130
131    // Output: one u32 per Minion, each on its own 64-byte cache line, prefilled
132    // with the sentinel. Every Minion index is below it, so an unwritten cell
133    // cannot pass verification.
134    let output = device.alloc_padded::<u32>(n_cells)?;
135    device.fill(output.region(), SENTINEL)?;
136
137    let args = CacheTestArgs {
138        output: output.addr(),
139        n_shires: shire_extent as u64,
140        dest,
141    };
142
143    // Opt-in exception-context capture. Setting a non-zero exception_buffer is a
144    // firmware-supported feature only on some builds: on the current card build
145    // it is itself rejected with EXCEPTION (status 2) regardless of kernel
146    // correctness, and firmware leaves the buffer untouched. It is therefore off
147    // by default (the launch then mirrors the passing double_buffer path) and
148    // enabled only via ET_EXC_BUFFER=1 for probing a future firmware.
149    let exc = if std::env::var_os("ET_EXC_BUFFER").is_some() {
150        // Pre-zeroed so a non-fault run leaves recognisable zeros.
151        let region = device.alloc(EXC_BUF_LEN as u64)?;
152        device.memcpy_h2d(&[0u8; EXC_BUF_LEN], region.addr)?;
153        println!(
154            "ET_EXC_BUFFER set: capturing U-mode context @ {:#x}",
155            region.addr
156        );
157        Some(region)
158    } else {
159        None
160    };
161
162    println!("Launching cache_writeback test ...");
163    let mut opts = LaunchOptions::new(shire_mask).with_args(args.as_bytes().to_vec());
164    // ET_NO_BARRIER clears the launch BARRIER flag (diagnostic). Tested and
165    // refuted: a stress loop measured the same 50-90 percent EXCEPTION rate with
166    // the barrier on or off, so the firmware barrier/drain path is not the fault
167    // trigger. Retained so the comparison can be reproduced without recompiling.
168    if std::env::var_os("ET_NO_BARRIER").is_some() {
169        opts = opts.without_barrier();
170    }
171    if let Some(ref region) = exc {
172        opts.exception_buffer = region.addr;
173    }
174    if let Err(e) = device.launch(&kernel, &opts) {
175        // Decode the U-mode context the firmware saved before returning the error.
176        if let Some(ref region) = exc {
177            let mut raw = vec![0u8; EXC_BUF_LEN];
178            device.memcpy_d2h(region.addr, &mut raw)?;
179            print_exception(&raw);
180        }
181        return Err(e);
182    }
183    println!("Kernel returned.");
184
185    // Download the per-Minion outputs (strips 64-byte padding).
186    let results = device.download_padded(&output)?;
187
188    let mut failures = 0_usize;
189    for (i, &val) in results.iter().enumerate() {
190        let expected = if launched(i) { i as u32 } else { SENTINEL_WORD };
191        if val != expected {
192            eprintln!("  FAIL output[{i}] = {val:#010x}  (expected {expected:#010x})");
193            failures += 1;
194        }
195    }
196
197    if failures == 0 {
198        println!("cache_writeback PASSED: all {} cells correct", n_cells);
199        Ok(())
200    } else {
201        Err(et_soc1::Error::Protocol(format!(
202            "cache_writeback FAILED: {failures}/{n_cells} cells incorrect"
203        )))
204    }
205}
206
207fn dest_name(dest: u64) -> &'static str {
208    match dest {
209        1 => "L2",
210        2 => "L3",
211        _ => "Mem",
212    }
213}
214
215/// Decode the `execution_context_t` the firmware writes into the exception buffer
216/// on a U-mode trap (fields in declaration order, `packed, aligned(64)`).
217fn print_exception(raw: &[u8]) {
218    if raw.len() < 56 {
219        eprintln!("  exception buffer too short to decode");
220        return;
221    }
222    let rd = |o: usize| u64::from_le_bytes(raw[o..o + 8].try_into().unwrap());
223    let ty = rd(0); // context type (0 if firmware wrote nothing)
224    let hart_id = rd(16);
225    let mepc = rd(24); // sepc: PC of the faulting instruction
226    let mstatus = rd(32);
227    let mtval = rd(40); // stval: faulting address or instruction bits
228    let mcause = rd(48); // scause: trap cause
229
230    if ty == 0 && mepc == 0 && mcause == 0 {
231        eprintln!("  exception buffer empty: firmware saved no U-mode context here");
232        return;
233    }
234    eprintln!("  U-mode exception context (first faulting hart):");
235    eprintln!("    hart_id = {hart_id}");
236    eprintln!("    mcause  = {mcause:#x}  ({})", mcause_name(mcause));
237    eprintln!("    mepc    = {mepc:#x}  (faulting instruction PC)");
238    eprintln!("    mtval   = {mtval:#x}  (faulting address / instruction bits)");
239    eprintln!("    mstatus = {mstatus:#x}");
240}
241
242/// Human-readable RISC-V trap cause (synchronous exceptions only).
243fn mcause_name(cause: u64) -> &'static str {
244    if cause >> 63 != 0 {
245        return "interrupt";
246    }
247    match cause & 0xff {
248        0 => "instruction address misaligned",
249        1 => "instruction access fault",
250        2 => "illegal instruction",
251        3 => "breakpoint",
252        4 => "load address misaligned",
253        5 => "load access fault",
254        6 => "store/AMO address misaligned",
255        7 => "store/AMO access fault",
256        8 => "environment call from U-mode",
257        12 => "instruction page fault",
258        13 => "load page fault",
259        15 => "store/AMO page fault",
260        _ => "other/unknown",
261    }
262}