Skip to main content

Crate et_soc1

Crate et_soc1 

Source
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

§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 Device handle: 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 Transport abstraction and its concrete backends.

Structs§

CachePadded
A wrapper that aligns T to a cache-line boundary.
GemmArgs
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§

DeviceArgs
A plain-old-data kernel-argument struct exchanged between host and device.
DevicePod
Types that may be copied verbatim between host and device memory.

Type Aliases§

Result
The result type returned throughout et_soc1.