Expand description
Host-side Rust interface to the Esperanto ET-SoC-1 RISC-V accelerator.
This crate speaks the ET-SoC-1 PCIe kernel driver’s character-device
protocol directly: it opens /dev/etN_ops, discovers the device DRAM region,
loads kernels, launches them on selected shires, moves results back over DMA,
and extracts on-device trace buffers, all without the vendor C++ runtime.
§Layers
Deviceis the high-level handle. It owns atransport::Transport, a DRAM bump allocator, and the command tag counter. Key methods:Device::load_kernel,Device::alloc,Device::launch,Device::memcpy_d2h,Device::extract_cm_trace– the core synchronous API.Device::launch_async/Device::wait_launch– fire-and-forget kernel submission returning aPendingLaunchhandle; enables double-buffering (overlap kernel execution with host DMA on a second submission queue). A response stash parks out-of-order completions so concurrent in-flight commands do not lose each other’s results.Device::memcpy_h2d_opts/Device::memcpy_d2h_opts– DMA variants that accept aDmaOptionsbuilder;DmaOptions::on_sq(n)routes the transfer to submission queuen, allowing concurrent host-to-device DMA while a kernel runs on queue 0.LaunchOptions::without_barrier/LaunchOptions::on_sq– builder methods for advanced launch control.
transportabstracts the command channel.transport::IoctlTransporttargets real hardware; under theemufeature,transport::FfiTransportdrives the SDK software emulator through the vendor C++ device-layer, so a host without a card can develop and test.traceis a standalone, pure-Rust decoder for the et-trace buffer layout, usable on any captured buffer independently of a live device.
§Quick start
Add et-rs = "0.5" to Cargo.toml (the library is named et_soc1 in Rust
source, matching the C/C++ SDK convention), then:
use et_soc1::{Device, Error, LaunchOptions, TraceConfig};
use et_soc1::trace::{DecodedEntry, TraceBuffer};
fn main() -> et_soc1::Result<()> {
let elf = std::fs::read("hello.elf").map_err(|e| Error::Io {
op: "read kernel ELF",
source: e,
})?;
// Open device 0 (/dev/et0_ops) and query its DRAM geometry.
let device = Device::open(0)?;
// Load the kernel before any alloc() calls so it lands at the DRAM
// base, matching its link address.
let kernel = device.load_kernel(&elf)?;
// Allocate an 8 MiB trace buffer in device DRAM.
let trace_buf = device.alloc(8 * 1024 * 1024)?;
// Launch on shire 0 with a barrier and full user tracing.
let opts = LaunchOptions::new(0x1)
.with_trace(TraceConfig::full(trace_buf, 0x1))
.with_args(vec![0u8; 64]);
device.launch(&kernel, &opts)?;
// Copy the trace buffer to host memory and decode it.
let mut host = vec![0u8; trace_buf.size as usize];
device.memcpy_d2h(trace_buf.addr, &mut host)?;
if let Ok(tb) = TraceBuffer::parse(&host) {
for entry in tb.entries() {
if let DecodedEntry::String(s) = entry.decoded() {
println!("[hart {}] {}", entry.hart_id, s.trim_end());
}
}
}
Ok(())
}Substitute Device::open_emulator("/opt/et", "/tmp/et-run")? for
Device::open(0)? when building with --features emu to target the SDK
software emulator rather than real hardware.
§Hardware versus emulator
The default ioctl backend requires a real card with the et kernel driver
loaded. The emu feature adds an FFI backend over the vendor device-layer’s
emulator (Device::open_emulator), which needs neither hardware nor the
driver. Both paths build the identical device-ops command bytes, so the
proto, device and trace code is exercised the same way against
each. The trace decoder and the proto builders are additionally
testable with no device at all.
Re-exports§
pub use buffer::DeviceBuffer;pub use buffer::PaddedArray;pub use device::AllocMark;pub use device::Device;pub use device::DeviceRegion;pub use device::DmaOptions;pub use device::LaunchOptions;pub use device::LaunchResult;pub use device::LaunchTiming;pub use device::LoadedKernel;pub use device::PendingLaunch;pub use device::TraceConfig;pub use blas::GemmError;pub use blas::alloc_tensor_matrix;pub use blas::sgemm;pub use topology::Topology;pub use transport::DeviceConfig;pub use transport::DeviceProperties;pub use transport::DramInfo;pub use transport::IoctlTransport;pub use transport::PoppedResponse;pub use transport::Transport;
Modules§
- blas
- Host-side BLAS launcher for the ET-SoC-1 tensor extension.
- buffer
- Typed device-memory buffers layered over the byte-oriented DMA primitives.
- device
- The high-level
Devicehandle: DRAM allocation, kernel loading, launch, device-to-host DMA and trace extraction. - proto
- Device-ops RPC wire format: command builders and response parsers.
- topology
- Compute topology of the ET-SoC-1.
- trace
- Pure-Rust decoder for the et-trace buffer layout.
- transport
- The
Transportabstraction and its concrete backends.
Structs§
- Cache
Padded - A wrapper that aligns
Tto a cache-line boundary. - Gemm
Args - Arguments for the single-precision general matrix multiplication (sGEMM)
kernel (
sgemm-rs), implementing C = alphaAB + beta*C.
Enums§
- Error
- Errors surfaced by the host-side interface.
Constants§
- CACHE_
LINE - ET-SoC-1 cache-line size, in bytes.
- GEMM_
TILE_ N - Number of f32 output columns produced per TensorFMA32 call (BCOLS=3 gives 4*(3+1) = 16 columns). Each tile row occupies exactly 64 bytes in the FP register file. N need not be a multiple of this value; the last tile column may be partial, with the hardware writing 64 bytes per row regardless – the caller reads only the N valid columns from the 64-byte-aligned allocation.
- HARTS_
PER_ NEIGHBOURHOOD - Harts per neighbourhood on the ET-SoC-1 (architectural constant).
- HARTS_
PER_ SHIRE - Harts per compute shire on the ET-SoC-1 (architectural constant).
- TENSOR_
ALIGN - Required alignment for all matrix pointers and row strides used with the ET-SoC-1 tensor-load/store instructions. TensorLoad and TensorStore each require the source or destination address to be 64-byte aligned.
Traits§
- Device
Args - A plain-old-data kernel-argument struct exchanged between host and device.
- Device
Pod - Types that may be copied verbatim between host and device memory.
Type Aliases§
- Result
- The result type returned throughout
et_soc1.