Skip to main content

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}