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}