Skip to main content

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;