double_buffer/double_buffer.rs
1//! Double-buffered launch demonstration.
2//!
3//! Exercises three features added in v0.5.0:
4//!
5//! 1. **`Device::launch_async` + `Device::wait_launch`**: fire a kernel onto
6//! the device without blocking, then collect the result later.
7//! 2. **Response stash**: if the kernel's completion arrives on the CQ while
8//! the host is waiting for a different command (a concurrent DMA, for
9//! example), it is parked automatically and returned by `wait_launch`.
10//! 3. **`DmaOptions::on_sq`**: route DMA commands to a separate submission
11//! queue so the firmware can process them concurrently with a running kernel.
12//!
13//! # Pattern
14//!
15//! ```text
16//! Phase A: launch_async + wait_launch
17//!
18//! launch_async(all shires) ──────────────────────────────────┐
19//! wait_launch() │ kernel running
20//! verify output_a │
21//! ┘
22//!
23//! Phase B: response stash + concurrent DMA
24//!
25//! launch_async(all shires) ──────────────────────────────────┐
26//! while kernel (possibly) runs on SQ 0: │ concurrent
27//! memcpy_h2d_opts(staging, SQ 1) ─────────────────────────┤ DMA on SQ 1
28//! wait_launch() ─────────── response may come from stash │
29//! verify output_b ┘
30//! ```
31//!
32//! In a real inference loop the "staging DMA" would upload the next batch's
33//! input matrix while the current batch's kernel runs. Here it uploads a
34//! 64 KB block to demonstrate the SQ routing and stash paths on hardware.
35//!
36//! # Usage
37//!
38//! ```text
39//! cargo run --example double_buffer -- <path-to-cache-test-rs.elf>
40//! ```
41
42use std::process::ExitCode;
43
44use et_abi::{CacheTestArgs, DeviceArgs, MINIONS_PER_SHIRE};
45use et_soc1::{Device, DmaOptions, LaunchOptions};
46
47// Size of the staging DMA used in Phase B to create a meaningful overlap
48// window (large enough that the kernel's response may arrive first).
49const STAGING_BYTES: usize = 64 * 1024;
50
51/// Byte written over both output arrays before launch.
52const SENTINEL: u8 = 0xFF;
53
54/// The sentinel as read back through a `u32` cell.
55const SENTINEL_WORD: u32 = u32::from_ne_bytes([SENTINEL; 4]);
56
57fn main() -> ExitCode {
58 match run() {
59 Ok(()) => ExitCode::SUCCESS,
60 Err(e) => {
61 eprintln!("error: {e}");
62 ExitCode::FAILURE
63 }
64 }
65}
66
67fn run() -> et_soc1::Result<()> {
68 let kernel_path = std::env::args().nth(1).unwrap_or_else(|| {
69 eprintln!("usage: double_buffer <cache-test-rs.elf>");
70 std::process::exit(2);
71 });
72
73 let elf = std::fs::read(&kernel_path).map_err(|e| et_soc1::Error::io("read kernel ELF", e))?;
74
75 let device = Device::open(0)?;
76 let topo = device.topology()?;
77 let n_shires = topo.num_shires() as usize;
78 let n_minions = n_shires * MINIONS_PER_SHIRE as usize;
79 // Cells are indexed by physical shire, so the arrays span every shire up to
80 // the highest present one and the kernel receives that extent; cells of
81 // absent shires must keep the sentinel.
82 let shire_extent = (u64::BITS - topo.shire_mask.leading_zeros()) as usize;
83 let n_cells = shire_extent * MINIONS_PER_SHIRE as usize;
84 let present = |cell: usize| topo.shire_mask & (1 << (cell / MINIONS_PER_SHIRE as usize)) != 0;
85
86 println!(
87 "Device: {} shires (mask {:#x}), {} Minions",
88 n_shires, topo.shire_mask, n_minions,
89 );
90
91 let kernel = device.load_kernel(&elf)?;
92
93 // Two separate output arrays: each Minion writes its global index to its
94 // own 64-byte-padded cell.
95 // Both are prefilled with the sentinel so an unwritten cell fails.
96 let out_a = device.alloc_padded::<u32>(n_cells)?;
97 let out_b = device.alloc_padded::<u32>(n_cells)?;
98 device.fill(out_a.region(), SENTINEL)?;
99 device.fill(out_b.region(), SENTINEL)?;
100
101 // Device region used as the staging target for the Phase B DMA.
102 // Content does not matter; we just need a valid writable region.
103 let staging = device.alloc(STAGING_BYTES as u64)?;
104 let staging_data = vec![0u8; STAGING_BYTES];
105
106 // -----------------------------------------------------------------------
107 // Phase A: basic launch_async + wait_launch
108 // -----------------------------------------------------------------------
109 println!("\nPhase A: launch_async + wait_launch");
110
111 let args_a = CacheTestArgs {
112 output: out_a.addr(),
113 n_shires: shire_extent as u64,
114 dest: 3, // Mem: writeback to DDR for host visibility
115 };
116 let opts_a = LaunchOptions::new(topo.shire_mask)
117 .without_barrier() // first launch: no prior command to wait for
118 .with_args(args_a.as_bytes().to_vec());
119
120 let pending_a = device.launch_async(&kernel, &opts_a)?;
121 println!(" kernel A fired (async, SQ 0)");
122
123 let _r = device.wait_launch(pending_a)?;
124 println!(" kernel A complete");
125
126 let results_a = device.download_padded(&out_a)?;
127 check("A", &results_a, &present)?;
128
129 // -----------------------------------------------------------------------
130 // Phase B: response stash + concurrent DMA on SQ 1
131 // -----------------------------------------------------------------------
132 println!("\nPhase B: kernel (SQ 0) overlapped with DMA (SQ 1)");
133
134 let args_b = CacheTestArgs {
135 output: out_b.addr(),
136 n_shires: shire_extent as u64,
137 dest: 3, // Mem: writeback to DDR for host visibility
138 };
139 let opts_b = LaunchOptions::new(topo.shire_mask)
140 // barrier=true (default): wait for prior SQ 0 commands (kernel A is
141 // already done, so this barrier is immediate).
142 .with_args(args_b.as_bytes().to_vec());
143
144 // Fire kernel B asynchronously.
145 let pending_b = device.launch_async(&kernel, &opts_b)?;
146 println!(" kernel B fired (async, SQ 0)");
147
148 // While kernel B may be running on SQ 0, DMA 64 KB on SQ 1.
149 // The firmware can schedule both streams concurrently. If kernel B's CQ
150 // response arrives during this DMA wait, `collect_response` stashes it;
151 // `wait_launch` below retrieves it from the stash without re-polling.
152 device.memcpy_h2d_opts(&staging_data, staging.addr, &DmaOptions::new().on_sq(1))?;
153 println!(" {} KB staging DMA complete (SQ 1)", STAGING_BYTES / 1024);
154
155 // Collect kernel B's result, possibly from the stash.
156 let _r = device.wait_launch(pending_b)?;
157 println!(" kernel B complete");
158
159 let results_b = device.download_padded(&out_b)?;
160 check("B", &results_b, &present)?;
161
162 println!("\ndouble_buffer PASSED");
163 Ok(())
164}
165
166/// Asserts that `results[i] == i` for every cell of a present shire and that
167/// every other cell still holds the sentinel.
168fn check(label: &str, results: &[u32], present: &dyn Fn(usize) -> bool) -> et_soc1::Result<()> {
169 let mut failures = 0_usize;
170 for (i, &val) in results.iter().enumerate() {
171 let expected = if present(i) { i as u32 } else { SENTINEL_WORD };
172 if val != expected {
173 eprintln!(" FAIL out_{label}[{i}] = {val:#010x} (expected {expected:#010x})");
174 failures += 1;
175 }
176 }
177 let n_cells = results.len();
178 if failures == 0 {
179 println!(" output_{label}: all {n_cells} cells correct");
180 Ok(())
181 } else {
182 Err(et_soc1::Error::Protocol(format!(
183 "output_{label}: {failures}/{n_cells} cells incorrect"
184 )))
185 }
186}