1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
//! 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
//!
//! * [`Device`] is the high-level handle. It owns a [`transport::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 a [`PendingLaunch`] handle; 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 a [`DmaOptions`] builder; `DmaOptions::on_sq(n)`
//! routes the transfer to submission queue `n`, 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.
//! * [`transport`] abstracts the command channel. [`transport::IoctlTransport`]
//! targets real hardware; under the `emu` feature, `transport::FfiTransport`
//! drives the SDK software emulator through the vendor C++ device-layer, so a
//! host without a card can develop and test.
//! * [`trace`] is 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:
//!
//! ```no_run
//! 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.
pub use ;
pub use ;
pub use ;
// Re-exported from the shared ABI crate so the typed launch API
// (`Device::launch_spmd`) and the shared constants are usable without depending
// on `et-abi` directly.
pub use ;
pub use ;
pub use ;
pub use ;
pub use FfiTransport;