et_soc1/lib.rs
1//! Host-side Rust interface to the Esperanto ET-SoC-1 RISC-V accelerator.
2//!
3//! This crate speaks the ET-SoC-1 PCIe kernel driver's character-device
4//! protocol directly: it opens `/dev/etN_ops`, discovers the device DRAM region,
5//! loads kernels, launches them on selected shires, moves results back over DMA,
6//! and extracts on-device trace buffers, all without the vendor C++ runtime.
7//!
8//! # Layers
9//!
10//! * [`Device`] is the high-level handle. It owns a [`transport::Transport`],
11//! a DRAM bump allocator, and the command tag counter. Key methods:
12//! - [`Device::load_kernel`], [`Device::alloc`], [`Device::launch`],
13//! [`Device::memcpy_d2h`], [`Device::extract_cm_trace`] -- the core
14//! synchronous API.
15//! - [`Device::launch_async`] / [`Device::wait_launch`] -- fire-and-forget
16//! kernel submission returning a [`PendingLaunch`] handle; enables
17//! double-buffering (overlap kernel execution with host DMA on a second
18//! submission queue). A response stash parks out-of-order completions so
19//! concurrent in-flight commands do not lose each other's results.
20//! - [`Device::memcpy_h2d_opts`] / [`Device::memcpy_d2h_opts`] -- DMA
21//! variants that accept a [`DmaOptions`] builder; `DmaOptions::on_sq(n)`
22//! routes the transfer to submission queue `n`, allowing concurrent
23//! host-to-device DMA while a kernel runs on queue 0.
24//! - [`LaunchOptions::without_barrier`] / [`LaunchOptions::on_sq`] --
25//! builder methods for advanced launch control.
26//! * [`transport`] abstracts the command channel. [`transport::IoctlTransport`]
27//! targets real hardware; under the `emu` feature, `transport::FfiTransport`
28//! drives the SDK software emulator through the vendor C++ device-layer, so a
29//! host without a card can develop and test.
30//! * [`trace`] is a standalone, pure-Rust decoder for the et-trace buffer
31//! layout, usable on any captured buffer independently of a live device.
32//!
33//! # Quick start
34//!
35//! Add `et-rs = "0.5"` to `Cargo.toml` (the library is named `et_soc1` in Rust
36//! source, matching the C/C++ SDK convention), then:
37//!
38//! ```no_run
39//! use et_soc1::{Device, Error, LaunchOptions, TraceConfig};
40//! use et_soc1::trace::{DecodedEntry, TraceBuffer};
41//!
42//! fn main() -> et_soc1::Result<()> {
43//! let elf = std::fs::read("hello.elf").map_err(|e| Error::Io {
44//! op: "read kernel ELF",
45//! source: e,
46//! })?;
47//!
48//! // Open device 0 (/dev/et0_ops) and query its DRAM geometry.
49//! let device = Device::open(0)?;
50//!
51//! // Load the kernel before any alloc() calls so it lands at the DRAM
52//! // base, matching its link address.
53//! let kernel = device.load_kernel(&elf)?;
54//!
55//! // Allocate an 8 MiB trace buffer in device DRAM.
56//! let trace_buf = device.alloc(8 * 1024 * 1024)?;
57//!
58//! // Launch on shire 0 with a barrier and full user tracing.
59//! let opts = LaunchOptions::new(0x1)
60//! .with_trace(TraceConfig::full(trace_buf, 0x1))
61//! .with_args(vec![0u8; 64]);
62//! device.launch(&kernel, &opts)?;
63//!
64//! // Copy the trace buffer to host memory and decode it.
65//! let mut host = vec![0u8; trace_buf.size as usize];
66//! device.memcpy_d2h(trace_buf.addr, &mut host)?;
67//!
68//! if let Ok(tb) = TraceBuffer::parse(&host) {
69//! for entry in tb.entries() {
70//! if let DecodedEntry::String(s) = entry.decoded() {
71//! println!("[hart {}] {}", entry.hart_id, s.trim_end());
72//! }
73//! }
74//! }
75//! Ok(())
76//! }
77//! ```
78//!
79//! Substitute `Device::open_emulator("/opt/et", "/tmp/et-run")?` for
80//! `Device::open(0)?` when building with `--features emu` to target the SDK
81//! software emulator rather than real hardware.
82//!
83//! # Hardware versus emulator
84//!
85//! The default ioctl backend requires a real card with the `et` kernel driver
86//! loaded. The `emu` feature adds an FFI backend over the vendor device-layer's
87//! emulator (`Device::open_emulator`), which needs neither hardware nor the
88//! driver. Both paths build the identical device-ops command bytes, so the
89//! [`proto`], [`device`] and [`trace`] code is exercised the same way against
90//! each. The [`trace`] decoder and the [`proto`] builders are additionally
91//! testable with no device at all.
92
93mod elf;
94mod error;
95mod ffi;
96mod ioctl;
97
98pub mod blas;
99pub mod buffer;
100pub mod device;
101pub mod proto;
102pub mod topology;
103pub mod trace;
104pub mod transport;
105
106pub use buffer::{DeviceBuffer, PaddedArray};
107pub use device::{
108 AllocMark, Device, DeviceRegion, DmaOptions, LaunchOptions, LaunchResult, LaunchTiming,
109 LoadedKernel, PendingLaunch, TraceConfig,
110};
111pub use error::{Error, Result};
112// Re-exported from the shared ABI crate so the typed launch API
113// (`Device::launch_spmd`) and the shared constants are usable without depending
114// on `et-abi` directly.
115pub use blas::{GemmError, alloc_tensor_matrix, sgemm};
116pub use et_abi::{
117 CACHE_LINE, CachePadded, DeviceArgs, DevicePod, GEMM_TILE_N, GemmArgs, TENSOR_ALIGN,
118};
119pub use topology::{HARTS_PER_NEIGHBOURHOOD, HARTS_PER_SHIRE, Topology};
120pub use transport::{
121 DeviceConfig, DeviceProperties, DramInfo, IoctlTransport, PoppedResponse, Transport,
122};
123
124#[cfg(feature = "emu")]
125pub use transport::FfiTransport;