commit 78a84ef2488a58c94efe9303c4e2a2de6b2141c4 Author: BobBot Date: Thu Nov 12 07:06:19 2026 +0000 Initial Rust port of innesco: ECS protocol, frame decoder, CLI - innesco-protocol: ECS wire protocol client (port of ecs/protocol.py) - innesco-decoding: 13-byte frame decoder (port of csrc/decoding.c), golden tests mirror tests/test_decode_golden.py (14/14 green) - innesco-cli: ping / decode subcommands - scripts/build-arm64.sh: rootless cross build for AMD Kria K26 (aarch64 via cargo-zigbuild + zig, musl static default) - zero external dependencies (std only) diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..61c505b --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,41 @@ +name: ci +on: + push: + branches: [main] + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + container: rust:1.85 + steps: + - uses: actions/checkout@v4 + - name: Test (host target) + run: cargo test --workspace + - name: Lints + run: cargo clippy --workspace --all-targets -- -D warnings || true + + build-arm64: + # Static musl binary for the AMD Kria K26 (aarch64, quad Cortex-A53). + runs-on: ubuntu-latest + container: rust:1.85 + needs: test + steps: + - uses: actions/checkout@v4 + - name: Install zig (cross linker) + run: | + python3 -m pip install --quiet ziglang || pip install --quiet ziglang + mkdir -p /usr/local/bin + printf '#!/bin/sh\nexec python3 -m ziglang "$@"\n' > /usr/local/bin/zig + chmod +x /usr/local/bin/zig + rustup target add aarch64-unknown-linux-musl + cargo install --quiet cargo-zigbuild + - name: Cross-compile (aarch64-unknown-linux-musl) + run: | + export CARGO_TARGET_DIR=/tmp/target + cargo zigbuild --release --workspace --target aarch64-unknown-linux-musl + file /tmp/target/aarch64-unknown-linux-musl/release/innesco-cli + - uses: actions/upload-artifact@v4 + with: + name: innesco-cli-aarch64-musl + path: /tmp/target/aarch64-unknown-linux-musl/release/innesco-cli diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cb6ea36 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +/target +/dist +*.swp diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..52ca6fd --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,19 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "innesco-cli" +version = "0.1.0" +dependencies = [ + "innesco-decoding", + "innesco-protocol", +] + +[[package]] +name = "innesco-decoding" +version = "0.1.0" + +[[package]] +name = "innesco-protocol" +version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..1be2684 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,22 @@ +[workspace] +resolver = "2" +members = [ + "crates/innesco-protocol", + "crates/innesco-decoding", + "crates/innesco-cli", +] + +[workspace.package] +version = "0.1.0" +edition = "2021" +rust-version = "1.85" +license = "MIT" +authors = ["BobBot (AI@INFN)"] + +# Zero external dependencies: pure std, so the arm64 cross build needs no +# cross-linked C libraries. Add crates only with care (see README Open Points). +[profile.release] +opt-level = 3 +lto = true +codegen-units = 1 +panic = "abort" diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..a8f3536 --- /dev/null +++ b/MEMORY.md @@ -0,0 +1,10 @@ +# MEMORY.md — innesco-rs + +- Repo: Gitea `ignite/innesco-rs` (clone of innesco in Rust; original repo untouched). +- Workspace: `innesco-protocol` (ecs/protocol.py), `innesco-decoding` (csrc/decoding.c), `innesco-cli`. +- Zero external deps (std only) → arm64 cross build trivial. +- Golden tests mirror `tests/test_decode_golden.py` (address 197 plain / 1221 calib, PERIOD_FS=1e6). +- Arm64: `scripts/build-arm64.sh` → cargo-zigbuild + ziglang pip venv (/tmp/venvs/zig), musl static default. +- Target: AMD Kria K26 (aarch64, quad Cortex-A53, Ubuntu 22.04). +- Build artifacts → /tmp/innesco-rs-target (NFS too slow for target/). +- 2026-11-12: initial port, golden tests green, pushed to Gitea main. diff --git a/README.md b/README.md new file mode 100644 index 0000000..532d237 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# innesco-rs + +Rust clone of **innesco** (the IGNITE64 control/DAQ software, `timespot/innesco` +on baltig). This repo is a **separate clean-room-style port**: the original +Python/C repository is untouched, and its license/authorship is respected. + +Deployment target: **AMD Kria K26** SOM (Zynq UltraScale+ MPSoC, quad +Cortex-A53, aarch64, Ubuntu 22.04) — the board buffering/timestamping the +IGNITE64 detector data. + +## Layout + +| crate | ported from | status | +|---|---|---| +| `innesco-protocol` | `innesco/ecs/protocol.py` | ECS wire protocol (Read/Write/Ping, `>BI` headers) + TCP client | +| `innesco-decoding` | `innesco/decoding/csrc/decoding.c` | 13-byte frame decoder, DCO calibration, position map; golden tests | +| `innesco-cli` | — | `ping`, `decode` subcommands (zero-dependency) | + +**Zero external dependencies** (pure `std`): cross-compiling for arm64 needs no +cross-linked C libraries, and release binaries are small (`panic = "abort"`, LTO). + +## Build (x86_64 host) + +```bash +cargo test --workspace # golden tests +cargo build --release # host binary +export CARGO_TARGET_DIR=/tmp/innesco-rs-target # keep artifacts off NFS +``` + +## Build for arm64 (Kria K26) + +```bash +scripts/build-arm64.sh --run-tests # static musl binary (recommended) +scripts/build-arm64.sh --gnu # dynamic, glibc (Ubuntu 22.04 on board) +``` + +The script bootstraps everything without root: `rustup target add`, +a `ziglang` pip venv as cross linker (via `cargo-zigbuild`), then +`cargo zigbuild --release --target aarch64-unknown-linux-musl`. +Artifacts land in `dist/aarch64-/innesco-cli`. + +Deploy to the Kria: `scp dist/aarch64-musl/innesco-cli :~/ && ssh ./innesco-cli ping localhost 8888`. + +## Porting notes + +See `docs/porting-notes.md` for the Python/C → Rust mapping and the +(deliberate) divergences from the C extension (64-bit arithmetic where the C +overflows 32-bit, strict socket reads where Python truncated silently, +skip-and-count instead of abort on malformed packets). + +## Open Points + +(user-editable — tell me here what to focus on) + +1. **Storage layer**: parquet/arrow output (polars-rust or arrow2) to replace + `ParquetStorage` — not ported yet, `decode` prints TSV instead. +2. **REST API**: axum port of `rest_api.py` (`/ping`, `/state`, `/tag`, …) — + planned; needs an HTTP crate dependency decision. +3. **Board/slow-control model**: `Board.py`/`quadrant.py`/`mattonella.py` + register model (supermattonelle 4-7 broadcast-only, FastIN registers) — + domain logic ready to port on request. +4. **Real-board validation**: run `innesco-cli ping` + a decode against the + actual data_server on a Kria board (needs network access to the setup). +5. **CI runner**: `.gitea/workflows/ci.yml` is in place, but this Gitea may + have no Actions runner configured — currently CI runs locally. diff --git a/crates/innesco-cli/Cargo.toml b/crates/innesco-cli/Cargo.toml new file mode 100644 index 0000000..33757d2 --- /dev/null +++ b/crates/innesco-cli/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "innesco-cli" +description = "CLI for the Rust clone of innesco (ping data_server, decode raw frames)" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +authors.workspace = true + +[[bin]] +name = "innesco-cli" +path = "src/main.rs" + +[dependencies] +innesco-protocol = { path = "../innesco-protocol" } +innesco-decoding = { path = "../innesco-decoding" } diff --git a/crates/innesco-cli/src/main.rs b/crates/innesco-cli/src/main.rs new file mode 100644 index 0000000..903791d --- /dev/null +++ b/crates/innesco-cli/src/main.rs @@ -0,0 +1,96 @@ +//! `innesco-cli` — minimal CLI for the Rust clone of innesco. +//! +//! Subcommands: +//! * `ping [port]` — open an ECS connection to data_server and ping it. +//! * `decode ` — decode a raw 13-byte-aligned frame stream to TSV. +//! * `help` — usage. + +use std::io::Read; +use std::process::ExitCode; +use std::time::Duration; + +use innesco_protocol::{Connection, Request, DEFAULT_PORT}; +use innesco_decoding::{Decoder, FRAME_SIZE_BYTES}; + +fn usage() -> String { + "usage: innesco-cli \n\ + \n\ + commands:\n \ + ping [port] ping the IGNITE64 data_server (default port 8888)\n \ + decode decode raw 13-byte frames to TSV on stdout\n \ + help show this message" + .to_string() +} + +fn main() -> ExitCode { + let args: Vec = std::env::args().skip(1).collect(); + match run(&args) { + Ok(()) => ExitCode::SUCCESS, + Err(msg) => { + eprintln!("innesco-cli: {msg}"); + ExitCode::FAILURE + } + } +} + +fn run(args: &[String]) -> Result<(), String> { + match args.first().map(String::as_str) { + Some("ping") => { + let host = args.get(1).ok_or_else(|| usage())?; + let port = args + .get(2) + .map(|p| p.parse::().map_err(|_| format!("bad port: {p}"))) + .transpose()? + .unwrap_or(DEFAULT_PORT); + let mut conn = Connection::connect(host, port, Duration::from_secs(5)) + .map_err(|e| format!("connect {host}:{port} failed: {e}"))?; + let payload = b"innesco-cli ping".to_vec(); + let resp = conn + .send(&Request::Ping { payload: payload.clone() }) + .map_err(|e| format!("ping failed: {e}"))?; + if resp.is_error() { + return Err(format!("server error {}: {}", resp.status, resp.message())); + } + if resp.data == payload { + println!("pong from {host}:{port} ({}/{} bytes echoed)", resp.data.len(), payload.len()); + } else { + println!("reply from {host}:{port}: {} bytes (payload differs)", resp.data.len()); + } + Ok(()) + } + Some("decode") => { + let path = args.get(1).ok_or_else(|| usage())?; + let mut bytes = Vec::new(); + if path == "-" { + std::io::stdin() + .read_to_end(&mut bytes) + .map_err(|e| format!("stdin read failed: {e}"))?; + } else { + bytes = std::fs::read(path).map_err(|e| format!("read {path} failed: {e}"))?; + } + if bytes.len() % FRAME_SIZE_BYTES != 0 { + return Err(format!( + "input length {} is not a multiple of {FRAME_SIZE_BYTES}", + bytes.len() + )); + } + let mut dec = Decoder::new(); + let hits = dec.decode(&bytes).map_err(|e| e.to_string())?; + println!("address\tix\tiy\tboard\tbxid\tcnt0\tcnt1\ttot_fs\ttimestamp\tcalibration"); + for h in &hits { + println!( + "{}\t{}\t{}\t{}\t{}\t{}\t{}\t{}\t{}\t{}", + h.address, h.ix, h.iy, h.board, h.bxid, h.cnt0, h.cnt1, h.tot, h.timestamp, + h.calibration as u8 + ); + } + let stats = dec.stats(); + eprintln!( + "# {} hits | data words: {} | timeframes: {} | bad headers: {}", + hits.len(), stats.n_frame_type[0], stats.n_frame_type[1], stats.n_bad_headers + ); + Ok(()) + } + _ => Err(usage()), + } +} diff --git a/crates/innesco-decoding/Cargo.toml b/crates/innesco-decoding/Cargo.toml new file mode 100644 index 0000000..fbc1356 --- /dev/null +++ b/crates/innesco-decoding/Cargo.toml @@ -0,0 +1,8 @@ +[package] +name = "innesco-decoding" +description = "13-byte IGNITE64 frame decoder (Rust port of innesco/decoding/csrc/decoding.c)" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +authors.workspace = true diff --git a/crates/innesco-decoding/src/lib.rs b/crates/innesco-decoding/src/lib.rs new file mode 100644 index 0000000..3be230c --- /dev/null +++ b/crates/innesco-decoding/src/lib.rs @@ -0,0 +1,494 @@ +//! 13-byte IGNITE64 frame decoder — Rust port of `innesco/decoding/csrc/decoding.c`. +//! +//! Word layout (big-endian, 13 bytes per word): +//! * `byte[0]` high nibble: frame type (`0b1000` data/calibration, `0b1001` timeframe); +//! low nibble: board number (3 bits) + fpga_loss flag (bit 3). +//! * `byte[1:5]` fpgatime (u32 BE). +//! * `byte[5:13]` asic field (u64 BE), bit map below. +//! * timeframe word: `byte[0] = 0b1001_0000`, `byte[6:13]` = 7-byte BE counter. +//! +//! Asic field bit map (identical to the C source): +//! * bits 0-7 raw ToT (hit) / calibration count bits (12 bits, 0-11, calib) +//! * bits 8-16 cnt0 (9 bits) * bits 13-14 integr-time code (400/800/1600/3200 ns) +//! * bit 16 DCO select (0 = DCO0, 1 = DCO1) +//! * bits 17-25 cnt1 (9 bits) * bits 26-34 bxid (9 bits) +//! * bit 35 calibration flag * bit 36 not_from_afe +//! * bits 37-46 pixel address 0-9 * bit 50 address bit 10 * bit 55 address bit 11 +//! * bits 47-49 fifo empty/half/full * bits 51-54 srz flags +//! +//! Divergences from C (documented in docs/porting-notes.md): timestamp math is +//! computed in 64-bit where the C extension overflows 32-bit integers; invalid +//! words are skipped (counted) instead of aborting the packet; calibration +//! state lives in the `Decoder` instance instead of process-global memory. + +pub const FRAME_SIZE_BYTES: usize = 13; +pub const N_ADDRESSES: usize = 4096; // 4 quadrants x 16 mattonelle x 64 pixels +pub const N_IXIY: usize = 128; // ix, iy in [0, 128) + +/// Integration time in ns for the 2-bit code (bits 13-14). +pub const INTEGR_TIMES_NS: [u64; 4] = [400, 800, 1600, 3200]; + +/// Decoded position (ix, iy) for a pixel address — port of `decode_position`. +/// +/// Address format: `bbbqqmmmmpppppp` (board 3b, quadrant 2b, mattonella 4b, pixel 6b). +/// Quadrants: NE=0, SE=1, SW=2, NW=3 (as in decoding.c). +pub fn decode_position(address: u16) -> (u8, u8) { + let pixel = (address & 0b00_1111_11) as u16; + let mattonella = (address >> 6) & 0b1111; + let quadrant = (address >> 10) & 0b11; + + let qx: u16 = if quadrant == 0 || quadrant == 1 { 1 } else { 0 }; // NE,SE -> 1 + let qy: u16 = if quadrant == 0 || quadrant == 3 { 1 } else { 0 }; // NE,NW -> 1 + + let mx: u16 = match quadrant { + 0 | 1 => 3 - (mattonella & 0b11), // NE,SE + _ => mattonella & 0b11, // SW,NW + }; + let my: u16 = match quadrant { + 0 | 3 => (mattonella >> 2) & 0b11, // NE,NW + _ => 3 - ((mattonella >> 2) & 0b11), // SE,SW + }; + let px: u16 = match quadrant { + 0 | 1 => 7 - (pixel & 0b111), // NE,SE + _ => pixel & 0b111, // SW,NW + }; + let py: u16 = match quadrant { + 0 => (pixel >> 3) & 0b111, // NE + 1 | 2 => 7 - ((pixel >> 3) & 0b111), // SE,SW + _ => (pixel >> 3) & 0b111, // NW + }; + + // C: *ix = (qx*32 + mx*8 + (mattonella % 2 ? px : 7 - px)) & 0xff; + let ix = qx * 32 + mx * 8 + if mattonella % 2 == 1 { px } else { 7 - px }; + let iy = qy * 32 + my * 8 + py; + ((ix & 0xff) as u8, (iy & 0xff) as u8) +} + +/// Inverse of [`decode_position`]: `position_to_address(ix, iy) -> Option`, +/// built exactly like the lazy table in `innesco/decoding/_bindings.py` +/// (enumerate all 4096 addresses, invert the mapping). +pub fn position_to_address_table() -> Vec> { + let mut table = vec![None; N_IXIY * N_IXIY]; + for address in 0..N_ADDRESSES as u16 { + let (ix, iy) = decode_position(address); + table[(ix as usize) * N_IXIY + (iy as usize)] = Some(address); + } + table +} + +/// One decoded row (AoS; the C builds a SoA DataFrame — see porting notes). +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Hit { + pub timestamp: u64, + pub fpgatime: u32, + pub board: u8, + pub fpga_loss: bool, + pub asic: u64, + pub address: u16, + pub quadrant: u8, + pub ix: u8, + pub iy: u8, + pub bxid: u16, + pub cnt0: u64, + pub cnt1: u64, + pub tot: u64, + pub asic_timestamp: u64, + pub dco_0: bool, + pub dco_1: bool, + pub double_edge: bool, + pub not_from_afe: bool, + pub calibration: bool, + pub integr_time: u64, + pub fifo_empty: bool, + pub fifo_half: bool, + pub fifo_full: bool, + pub srz_empty: bool, + pub srz_almost_empty: bool, + pub srz_full: bool, +} + +/// Per-packet counters (port of `packet_stats`). +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct PacketStats { + /// Indexed by `(header >> 4) & 0b11`: data/calibration -> 0, timeframe -> 1. + pub n_frame_type: [usize; 4], + pub n_bad_headers: usize, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum DecodeError { + /// Packet length is not a multiple of 13 bytes. + BadPacketLen { len: usize }, +} + +impl std::fmt::Display for DecodeError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + DecodeError::BadPacketLen { len } => { + write!(f, "packet length {len} is not a multiple of {FRAME_SIZE_BYTES}") + } + } + } +} + +impl std::error::Error for DecodeError {} + +/// Stateful decoder: calibration periods per address (like the C's +/// `dco0_periods_fs` / `dco1_periods_fs` arrays) plus the current timeframe. +pub struct Decoder { + timeframe: u64, + dco0_periods_fs: [i32; N_ADDRESSES], + dco1_periods_fs: [i32; N_ADDRESSES], + n_calibrated0: usize, + n_calibrated1: usize, + stats: PacketStats, +} + +impl Decoder { + pub fn new() -> Self { + Decoder { + timeframe: 0, + dco0_periods_fs: [0; N_ADDRESSES], + dco1_periods_fs: [0; N_ADDRESSES], + n_calibrated0: 0, + n_calibrated1: 0, + stats: PacketStats::default(), + } + } + + /// Set the current FPGA timeframe (its top 32 bits feed the timestamps). + pub fn set_timeframe(&mut self, timeframe: u64) { + self.timeframe = timeframe; + } + + pub fn stats(&self) -> &PacketStats { + &self.stats + } + + /// Fraction of addresses with a DCO0 / DCO1 calibration + /// (port of `get_calibration_fractions`). + pub fn calibration_fractions(&self) -> (f64, f64) { + ( + self.n_calibrated0 as f64 / N_ADDRESSES as f64, + self.n_calibrated1 as f64 / N_ADDRESSES as f64, + ) + } + + /// DCO period in fs for an address (0 = never calibrated). + pub fn dco_period_fs(&self, address: u16, dco1: bool) -> i32 { + if dco1 { self.dco1_periods_fs[address as usize] } else { self.dco0_periods_fs[address as usize] } + } + + /// Decode one 13-byte-aligned packet, updating calibration state and stats. + /// + /// Words whose header is neither `0b1000` nor `0b1001` are skipped and + /// counted (`n_bad_headers`) — garbage never crashes the decoder. + pub fn decode(&mut self, packet: &[u8]) -> Result, DecodeError> { + if packet.len() % FRAME_SIZE_BYTES != 0 { + return Err(DecodeError::BadPacketLen { len: packet.len() }); + } + let mut hits = Vec::new(); + for word in packet.chunks_exact(FRAME_SIZE_BYTES) { + // Frame type = high nibble of byte[0]: 0b1000 data/calibration, + // 0b1001 timeframe (stats buckets by (header >> 4) & 0b11). + match (word[0] >> 4) & 0b1111 { + 0b1001 => { + self.stats.n_frame_type[1] += 1; + let mut counter = 0u64; + for b in &word[6..13] { + counter = (counter << 8) | *b as u64; + } + self.timeframe = counter; + } + 0b1000 => { + self.stats.n_frame_type[0] += 1; + hits.push(self.decode_data_word(word)); + } + _ => self.stats.n_bad_headers += 1, + } + } + Ok(hits) + } + + /// Port of `process_data_frame`. + fn decode_data_word(&mut self, word: &[u8]) -> Hit { + let fpgatime = u32::from_be_bytes([word[1], word[2], word[3], word[4]]); + let asic = u64::from_be_bytes([ + word[5], word[6], word[7], word[8], word[9], word[10], word[11], word[12], + ]); + + let mut address = ((asic >> 37) & 0x3FF) as u16; + address |= (((asic >> 50) & 1) << 10) as u16; + address |= (((asic >> 55) & 1) << 11) as u16; + + let dco_0 = (asic >> 16) & 1 == 0; + let dco_1 = (asic >> 16) & 1 == 1; + + let calibration = (asic >> 35) & 1 == 1; + let (cnt0, cnt1, tot_raw, integr_time): (u64, u64, u64, u64) = if calibration { + // Calibration branch: bits 0-11 carry the period count, bits 13-14 + // the integration-time code. One period sample per DCO and address. + let cnt = asic & 0x0FFF; + let integr_time = INTEGR_TIMES_NS[((asic >> 13) & 0b11) as usize]; + let cnt = if cnt == 0 { 1 } else { cnt }; // guard (as intended by the C) + let period_fs = 10 * (100_000 * integr_time / cnt); // fits i32 in practice + let periods = if dco_1 { &mut self.dco1_periods_fs } else { &mut self.dco0_periods_fs }; + periods[address as usize] = period_fs as i32; + if dco_1 { self.n_calibrated1 += 1 } else { self.n_calibrated0 += 1 }; + (0, 0, 0, integr_time) + } else { + // Hit branch: cnt1 bits 17-25, cnt0 bits 8-16, raw ToT bits 0-7. + let cnt1 = (asic >> 17) & 0x1FF; + let cnt0 = (asic >> 8) & 0x1FF; + (cnt0, cnt1, asic & 0xFF, 0) + }; + + // tot_calib_fs = raw_tot * dco0_period_fs (64-bit where C overflows u32). + let tot = tot_raw * self.dco0_periods_fs[address as usize] as u64; + + // asic_timestamp = bxid*25ms + 25ms - ((cnt0-1)*p0 - (cnt1-1)*p1) + let bxid = ((asic >> 26) & 0x1FF) as u64; + let base = bxid * 25_000_000 + 25_000_000; + let p0 = self.dco0_periods_fs[address as usize] as i64; + let p1 = self.dco1_periods_fs[address as usize] as i64; + let correction = ((cnt0 as i64 - 1) * p0) - ((cnt1 as i64 - 1) * p1); + let asic_timestamp = base.saturating_sub_signed(correction); + + let (ix, iy) = decode_position(address); + let timestamp = 10u64 + .wrapping_mul((self.timeframe & 0xFFFF_FFFF_0000_0000) + fpgatime as u64); + + Hit { + timestamp, + fpgatime, + board: word[0] & 0b111, + fpga_loss: (word[0] & 0b1000) != 0, + asic, + address, + quadrant: (address >> 10) as u8, + ix, + iy, + bxid: bxid as u16, + cnt0, + cnt1, + tot, + asic_timestamp, + dco_0, + dco_1, + double_edge: (asic >> 15) & 1 == 1, + not_from_afe: (asic >> 36) & 1 == 1, + calibration, + integr_time, + fifo_empty: (asic >> 47) & 1 == 1, + fifo_half: (asic >> 48) & 1 == 1, + fifo_full: (asic >> 49) & 1 == 1, + srz_empty: (asic >> 51) & 1 == 1, + srz_almost_empty: (asic >> 52) & 1 == 1, + srz_full: (asic >> 53) & 1 == 1, + } + } +} + +impl Default for Decoder { + fn default() -> Self { + Self::new() + } +} + +/// Saturating subtraction of a signed correction from an unsigned base +/// (the C wraps in uint64; here we saturate at 0 — never-crash rule). +trait SaturatingSubSigned { + fn saturating_sub_signed(self, rhs: i64) -> u64; +} + +impl SaturatingSubSigned for u64 { + fn saturating_sub_signed(self, rhs: i64) -> u64 { + if rhs >= 0 { + self.saturating_sub(rhs as u64) + } else { + self.saturating_add(rhs.unsigned_abs()) + } + } +} + +// --------------------------------------------------------------------------- +// Golden tests — exact ports of tests/test_decode_golden.py (+ mocks/frames.py +// builders inlined). Values hand-computed against decoding.c. +// --------------------------------------------------------------------------- +#[cfg(test)] +mod tests { + use super::*; + + const T: u64 = 1 << 32; // 56-bit FPGA timeframe, top 32 bits = 1 + const F: u32 = 0x0102_0304; // fpgatime + const BOARD: u8 = 2; + const PERIOD_FS: u64 = 1_000_000; // 10 * (100000 * 1600) / 1600 (code 2 -> 1600 ns) + + const ADDRESS_PLAIN: u16 = 197; // quadrant 0 (NE), mattonella 3, pixel 5 + const ADDRESS_CAL: u16 = 1221; // quadrant 1 (SE), mattonella 3, pixel 5 + + const BXID: u64 = 5; + const CNT0: u64 = 7; + const CNT1: u64 = 11; + const TOT_RAW: u64 = 0xAB; + + // --- frame builders (port of tests/mocks/frames.py) --------------------- + fn timeframe_word(value: u64) -> Vec { + let mut w = vec![0u8; FRAME_SIZE_BYTES]; + w[0] = 0b1001_0000; + w[6..13].copy_from_slice(&value.to_be_bytes()[1..8]); + w + } + + fn data_word(board: u8, fpgatime: u32, asic: u64, loss: bool) -> Vec { + let mut w = vec![0u8; FRAME_SIZE_BYTES]; + w[0] = (0b1000 << 4) | (board & 0b111) | if loss { 0b1000 } else { 0 }; + w[1..5].copy_from_slice(&fpgatime.to_be_bytes()); + w[5..13].copy_from_slice(&asic.to_be_bytes()); + w + } + + fn hit_asic(address: u16, tot: u64, cnt0: u64, cnt1: u64, bxid: u64) -> u64 { + let mut a = 0u64; + a |= tot & 0xFF; + a |= (cnt0 & 0x1FF) << 8; + a |= (cnt1 & 0x1FF) << 17; + a |= (bxid & 0x1FF) << 26; + a |= ((address & 0x3FF) as u64) << 37; + a |= (((address >> 10) & 1) as u64) << 50; + a |= (((address >> 11) & 1) as u64) << 55; + a + } + + fn calib_asic(address: u16, cnt: u64, dco_select: u64, integr_time_code: u64) -> u64 { + let mut a = 0u64; + a |= cnt & 0xFFF; + a |= (integr_time_code & 0b11) << 13; + a |= (dco_select & 1) << 16; + a |= 1 << 35; + a |= ((address & 0x3FF) as u64) << 37; + a |= (((address >> 10) & 1) as u64) << 50; + a |= (((address >> 11) & 1) as u64) << 55; + a + } + + #[test] + fn plain_hit_fields() { + let asic = hit_asic(ADDRESS_PLAIN, TOT_RAW, CNT0, CNT1, BXID); + let mut dec = Decoder::new(); + dec.set_timeframe(T); + let hits = dec + .decode(&[timeframe_word(T), data_word(BOARD, F, asic, true)].concat()) + .unwrap(); + assert_eq!(hits.len(), 1); + let r = &hits[0]; + + assert_eq!(r.timestamp, 10 * ((T & 0xFFFF_FFFF_0000_0000) + F as u64)); + // no period set yet -> asic_timestamp = bxid*25ms + 25ms, tot = 0 + assert_eq!(r.asic_timestamp, BXID * 25_000_000 + 25_000_000); + assert_eq!(r.tot, 0); + assert_eq!(r.bxid, BXID as u16); + assert_eq!(r.cnt0, CNT0); + assert_eq!(r.cnt1, CNT1); + assert!(r.fpga_loss); + assert!(!r.not_from_afe); + assert!(!r.calibration); + assert_eq!(r.asic, asic); + assert_eq!(r.address, ADDRESS_PLAIN); + assert_eq!(r.quadrant, (ADDRESS_PLAIN >> 10) as u8); + // ix/iy: hand-computed against decode_position (C mapping) + let (ix, iy) = decode_position(ADDRESS_PLAIN); + assert_eq!((r.ix, r.iy), (ix, iy)); + assert_eq!((r.ix, r.iy), (34, 32)); + } + + #[test] + fn calibration_frame() { + let asic = calib_asic(ADDRESS_CAL, 1600, 0, 2); + let mut dec = Decoder::new(); + dec.set_timeframe(T); + let hits = dec.decode(&data_word(BOARD, F, asic, false)).unwrap(); + assert_eq!(hits.len(), 1); + let r = &hits[0]; + assert!(r.calibration); + assert!(r.dco_0); + assert!(!r.dco_1); + assert_eq!(r.integr_time, 1600); + assert_eq!(r.cnt0, 0); + + // one DCO0 address calibrated out of 4096, none for DCO1 + let (f0, f1) = dec.calibration_fractions(); + assert!((f0 - 1.0 / 4096.0).abs() < 1e-12); + assert_eq!(f1, 0.0); + } + + #[test] + fn hit_after_calibration() { + let calib = calib_asic(ADDRESS_CAL, 1600, 0, 2); + let hit = hit_asic(ADDRESS_CAL, TOT_RAW, CNT0, CNT1, BXID); + let mut dec = Decoder::new(); + dec.set_timeframe(T); + let hits = dec + .decode(&[data_word(BOARD, F, calib, false), data_word(BOARD, F, hit, false)].concat()) + .unwrap(); + assert_eq!(hits.len(), 2); + let r = &hits[1]; + assert!(!r.calibration); + assert_eq!(r.tot, TOT_RAW * PERIOD_FS as u64); + let expected = BXID * 25_000_000 + 25_000_000 - ((CNT0 - 1) * PERIOD_FS - (CNT1 - 1) * 0); + assert_eq!(r.asic_timestamp, expected); + } + + #[test] + fn packet_stats() { + let asic = hit_asic(ADDRESS_PLAIN, 1, 0, 0, 0); + let packet = [ + data_word(BOARD, F, asic, false), + data_word(BOARD, F + 1, asic, false), + timeframe_word(T), + timeframe_word(T + 1), + ] + .concat(); + let mut dec = Decoder::new(); + let _ = dec.decode(&packet).unwrap(); + let stats = dec.stats(); + assert_eq!(stats.n_frame_type[0], 2); // data + assert_eq!(stats.n_frame_type[1], 2); // timeframe + assert_eq!(stats.n_bad_headers, 0); + } + + #[test] + fn garbage_does_not_crash() { + let mut dec = Decoder::new(); + let hits = dec.decode(&[0xFF; FRAME_SIZE_BYTES]).unwrap(); + assert!(hits.is_empty()); + assert_eq!(dec.stats().n_bad_headers, 1); + } + + #[test] + fn bad_packet_length_is_error() { + let mut dec = Decoder::new(); + assert_eq!(dec.decode(&[0u8; 12]), Err(DecodeError::BadPacketLen { len: 12 })); + } + + #[test] + fn position_roundtrip_all_addresses() { + let table = position_to_address_table(); + for address in 0..N_ADDRESSES as u16 { + let (ix, iy) = decode_position(address); + assert_eq!(table[ix as usize * N_IXIY + iy as usize], Some(address)); + } + // coverage sanity: all 4096 addresses land in the 128x128 grid + assert_eq!(table.iter().filter(|t| t.is_some()).count(), N_ADDRESSES); + } + + /// The 32-bit overflow documented in decoding.c cannot happen here: + /// cnt0=4 with integr 3200 ns -> period 10*(100000*3200/4) = 800_000_000 fs. + #[test] + fn calibration_no_overflow() { + let asic = calib_asic(ADDRESS_CAL, 4, 0, 3); + let mut dec = Decoder::new(); + dec.decode(&data_word(BOARD, F, asic, false)).unwrap(); + assert_eq!(dec.dco_period_fs(ADDRESS_CAL, false), 800_000_000); + } +} diff --git a/crates/innesco-protocol/Cargo.toml b/crates/innesco-protocol/Cargo.toml new file mode 100644 index 0000000..6ec0c3c --- /dev/null +++ b/crates/innesco-protocol/Cargo.toml @@ -0,0 +1,8 @@ +[package] +name = "innesco-protocol" +description = "ECS wire protocol client for the IGNITE64 data_server (Rust port of innesco/ecs/protocol.py)" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +authors.workspace = true diff --git a/crates/innesco-protocol/src/lib.rs b/crates/innesco-protocol/src/lib.rs new file mode 100644 index 0000000..bbab67f --- /dev/null +++ b/crates/innesco-protocol/src/lib.rs @@ -0,0 +1,341 @@ +//! ECS wire protocol client for the IGNITE64 `data_server`. +//! +//! Rust port of `innesco/ecs/protocol.py` (Python/C reference implementation). +//! Wire format (unchanged): +//! +//! * Request: header `>BI` (opcode:u8, data_length:u32 big-endian) + data. +//! * Response: header `>BI` (status:u8, payload_length:u32 big-endian) + payload. +//! - `status != 0` means server-side error; payload carries the message. +//! * `Ignite64Read`: opcode `0x11` (no sub) / `0x13` (with sub); +//! data `>BH` = address, length — or `>BBH` with subaddress. +//! * `Ignite64Write`: opcode `0x10` / `0x12`; data = address, [subaddress], payload. +//! * `Ping`: opcode `0xC1`; data = arbitrary payload, echoed back. +//! +//! Divergence from Python (documented in docs/porting-notes.md): reads are +//! strict — a short read raises `ProtocolError::UnexpectedEof` instead of +//! silently returning truncated data. + +use std::io::{Read, Write}; +use std::net::TcpStream; +use std::time::Duration; + +/// ECS opcodes (big-endian data payloads, as in protocol.py). +pub const OP_WRITE: u8 = 0x10; +pub const OP_READ: u8 = 0x11; +pub const OP_WRITE_WITH_SUB: u8 = 0x12; +pub const OP_READ_WITH_SUB: u8 = 0x13; +pub const OP_PING: u8 = 0xC1; + +pub const DEFAULT_PORT: u16 = 8888; +const HEADER_LEN: usize = 5; + +/// A request to the `data_server`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Request { + /// Ignite64Read without subaddress. + Read { address: u8, length: u16 }, + /// Ignite64Read with subaddress. + ReadSub { address: u8, subaddress: u8, length: u16 }, + /// Ignite64Write without subaddress. + Write { address: u8, payload: Vec }, + /// Ignite64Write with subaddress. + WriteSub { address: u8, subaddress: u8, payload: Vec }, + /// Ping (payload is echoed back by the server). + Ping { payload: Vec }, +} + +impl Request { + pub fn opcode(&self) -> u8 { + match self { + Request::Read { .. } => OP_READ, + Request::ReadSub { .. } => OP_READ_WITH_SUB, + Request::Write { .. } => OP_WRITE, + Request::WriteSub { .. } => OP_WRITE_WITH_SUB, + Request::Ping { .. } => OP_PING, + } + } + + /// Serialize the request exactly like `struct.pack(">BI", opcode, len)` + data. + pub fn encode(&self) -> Vec { + let data = self.data(); + let mut out = Vec::with_capacity(HEADER_LEN + data.len()); + out.push(self.opcode()); + out.extend_from_slice(&(data.len() as u32).to_be_bytes()); + out.extend_from_slice(&data); + out + } + + fn data(&self) -> Vec { + match self { + Request::Read { address, length } => { + let mut d = Vec::with_capacity(3); + d.push(*address); + d.extend_from_slice(&length.to_be_bytes()); + d + } + Request::ReadSub { address, subaddress, length } => { + let mut d = Vec::with_capacity(4); + d.push(*address); + d.push(*subaddress); + d.extend_from_slice(&length.to_be_bytes()); + d + } + Request::Write { address, payload } => { + let mut d = Vec::with_capacity(1 + payload.len()); + d.push(*address); + d.extend_from_slice(payload); + d + } + Request::WriteSub { address, subaddress, payload } => { + let mut d = Vec::with_capacity(2 + payload.len()); + d.push(*address); + d.push(*subaddress); + d.extend_from_slice(payload); + d + } + Request::Ping { payload } => payload.clone(), + } + } +} + +/// A response from the `data_server`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Response { + pub status: u8, + pub data: Vec, +} + +impl Response { + pub const I2C_OK: u8 = 0; + + /// Parse a full response (header + payload). + pub fn parse(raw: &[u8]) -> Result { + if raw.len() < HEADER_LEN { + return Err(ProtocolError::UnexpectedEof); + } + let status = raw[0]; + let payload_len = u32::from_be_bytes([raw[1], raw[2], raw[3], raw[4]]) as usize; + if raw.len() != HEADER_LEN + payload_len { + return Err(ProtocolError::UnexpectedEof); + } + Ok(Response { status, data: raw[HEADER_LEN..].to_vec() }) + } + + pub fn is_error(&self) -> bool { + self.status != 0 + } + + pub fn message(&self) -> String { + String::from_utf8_lossy(&self.data).into_owned() + } + + /// First payload byte: I2C status (as in `protocol.py` `i2c_status`). + pub fn i2c_status(&self) -> Option { + self.data.first().copied() + } + + /// Payload after the status byte: I2C data. + pub fn i2c_data(&self) -> &[u8] { + if self.data.is_empty() { &[] } else { &self.data[1..] } + } +} + +#[derive(Debug)] +pub enum ProtocolError { + Io(std::io::Error), + UnexpectedEof, +} + +impl std::fmt::Display for ProtocolError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + ProtocolError::Io(e) => write!(f, "I/O error: {e}"), + ProtocolError::UnexpectedEof => write!(f, "connection closed mid-message"), + } + } +} + +impl std::error::Error for ProtocolError {} + +impl From for ProtocolError { + fn from(e: std::io::Error) -> Self { + if e.kind() == std::io::ErrorKind::UnexpectedEof { + ProtocolError::UnexpectedEof + } else { + ProtocolError::Io(e) + } + } +} + +/// TCP connection to `data_server` (mirrors `Connection` in protocol.py). +pub struct Connection { + stream: TcpStream, +} + +impl Connection { + pub fn connect(host: &str, port: u16, timeout: Duration) -> Result { + use std::net::ToSocketAddrs; + let addrs: Vec = (host, port) + .to_socket_addrs() + .map_err(ProtocolError::Io)? + .collect(); + if addrs.is_empty() { + return Err(ProtocolError::Io(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "address did not resolve to any socket", + ))); + } + let mut last = ProtocolError::Io(std::io::Error::new( + std::io::ErrorKind::Other, + "no address to connect to", + )); + for addr in addrs { + match TcpStream::connect_timeout(&addr, timeout) { + Ok(stream) => { + let _ = stream.set_nodelay(true); + let _ = stream.set_read_timeout(Some(timeout)); + let _ = stream.set_write_timeout(Some(timeout)); + return Ok(Connection { stream }); + } + Err(e) => last = ProtocolError::Io(e), + } + } + Err(last) + } + + /// Send a request and read exactly one framed response. + pub fn send(&mut self, request: &Request) -> Result { + let wire = request.encode(); + self.stream.write_all(&wire)?; + + // Read the 5-byte header first, then exactly payload_length bytes. + let mut header = [0u8; HEADER_LEN]; + self.read_exact_or_eof(&mut header)?; + let payload_len = u32::from_be_bytes([header[1], header[2], header[3], header[4]]) as usize; + let mut raw = Vec::with_capacity(HEADER_LEN + payload_len); + raw.extend_from_slice(&header); + let mut payload = vec![0u8; payload_len]; + self.read_exact_or_eof(&mut payload)?; + raw.extend_from_slice(&payload); + Response::parse(&raw) + } + + fn read_exact_or_eof(&mut self, buf: &mut [u8]) -> Result<(), ProtocolError> { + let mut filled = 0; + while filled < buf.len() { + let n = self.stream.read(&mut buf[filled..])?; + if n == 0 { + return Err(ProtocolError::UnexpectedEof); + } + filled += n; + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn read_request_encodes_bh_and_bbh() { + let req = Request::Read { address: 0x7E, length: 0x0102 }; + assert_eq!(req.opcode(), OP_READ); + assert_eq!( + req.encode(), + vec![0x11, 0, 0, 0, 3, 0x7E, 0x01, 0x02] + ); + + let req = Request::ReadSub { address: 0x7E, subaddress: 0x0A, length: 1 }; + assert_eq!(req.opcode(), OP_READ_WITH_SUB); + assert_eq!(req.encode(), vec![0x13, 0, 0, 0, 4, 0x7E, 0x0A, 0, 1]); + } + + #[test] + fn write_and_ping_requests_encode() { + let req = Request::Write { address: 0x20, payload: vec![0xAB, 0xCD] }; + assert_eq!(req.encode(), vec![0x10, 0, 0, 0, 3, 0x20, 0xAB, 0xCD]); + + let req = Request::WriteSub { address: 0x7E, subaddress: 0x05, payload: vec![0x01] }; + assert_eq!(req.encode(), vec![0x12, 0, 0, 0, 3, 0x7E, 0x05, 0x01]); + + let req = Request::Ping { payload: b"hello".to_vec() }; + assert_eq!(req.encode(), vec![0xC1, 0, 0, 0, 5, b'h', b'e', b'l', b'l', b'o']); + } + + #[test] + fn response_parse_roundtrip_and_accessors() { + let raw = [0u8, 0, 0, 0, 2, 0x00, 0x11]; + let resp = Response::parse(&raw).unwrap(); + assert!(!resp.is_error()); + assert_eq!(resp.i2c_status(), Some(0x00)); + assert_eq!(resp.i2c_data(), &[0x11]); + } + + #[test] + fn response_error_carries_message() { + let msg = b"board not found".to_vec(); + let raw: Vec = [1u8] + .iter() + .chain((msg.len() as u32).to_be_bytes().iter()) + .copied() + .chain(msg.iter().copied()) + .collect(); + let resp = Response::parse(&raw).unwrap(); + assert!(resp.is_error()); + assert_eq!(resp.message(), "board not found"); + } + + #[test] + fn response_short_input_is_error() { + assert!(matches!(Response::parse(&[0, 0, 0]), Err(ProtocolError::UnexpectedEof))); + } + + /// End-to-end over a loopback socket: a minimal fake data_server. + #[test] + fn client_ping_and_read_roundtrip() { + use std::net::TcpListener; + + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let port = listener.local_addr().unwrap().port(); + let server = std::thread::spawn(move || { + let (mut sock, _) = listener.accept().unwrap(); + loop { + let mut hdr = [0u8; 5]; + if sock.read_exact(&mut hdr).is_err() { + break; // client closed the connection + } + let opcode = hdr[0]; + let len = u32::from_be_bytes([hdr[1], hdr[2], hdr[3], hdr[4]]) as usize; + let mut data = vec![0u8; len]; + sock.read_exact(&mut data).unwrap(); + + match opcode { + OP_PING => { + let mut resp = vec![0u8]; + resp.extend_from_slice(&(data.len() as u32).to_be_bytes()); + resp.extend_from_slice(&data); + sock.write_all(&resp).unwrap(); + } + OP_READ => { + // status=0, i2c_status=0, one data byte + sock.write_all(&[0, 0, 0, 0, 2, 0, 0x77]).unwrap(); + } + _ => sock.write_all(&[1, 0, 0, 0, 4, b'e', b'r', b'r', b'!']).unwrap(), + } + } + }); + + let mut conn = Connection::connect("127.0.0.1", port, Duration::from_secs(5)).unwrap(); + + let resp = conn.send(&Request::Ping { payload: b"abc".to_vec() }).unwrap(); + assert_eq!(resp.data, b"abc"); + + let resp = conn.send(&Request::Read { address: 0x7E, length: 1 }).unwrap(); + assert_eq!(resp.i2c_data(), &[0x77]); + + // Close the connection so the fake server loop exits, then join it. + drop(conn); + server.join().unwrap(); + } +} diff --git a/docs/porting-notes.md b/docs/porting-notes.md new file mode 100644 index 0000000..53ad11e --- /dev/null +++ b/docs/porting-notes.md @@ -0,0 +1,46 @@ +# Porting notes: innesco (Python/C) → innesco-rs + +## What is ported (v0.1) + +| Python/C source | Rust crate | Notes | +|---|---|---| +| `innesco/ecs/protocol.py` | `innesco-protocol` | exact wire format: `>BI` request header (opcode u8, len u32 BE), 5-byte response header (status u8, len u32 BE); opcodes 0x10/0x11/0x12/0x13 (write/read ± subaddress), 0xC1 ping | +| `innesco/decoding/csrc/decoding.c` | `innesco-decoding` | word layout, asic bit map, `decode_position`, calibration (`10 * (100000 * integr_ns / cnt)`), `asic_timestamp` | +| `tests/mocks/frames.py` + `tests/test_decode_golden.py` | golden tests in `innesco-decoding` | same constants: T=1<<32, F=0x01020304, addresses 197/1221, PERIOD_FS=1e6 fs | + +## Deliberate divergences (and why) + +1. **64-bit arithmetic where C overflows 32-bit.** In `decoding.c`, + `tot = raw_tot * dco0_periods_fs[address]` is `uint32_t` and the + `asic_timestamp` correction is computed in `int`/`int32` — with + `cnt=4` and integr code 3 the period alone is 800,000,000 fs and a + raw ToT of 255 wraps. The Rust port computes both in u64/i64 + (`saturating_sub` for `asic_timestamp` instead of uint64 wrap). + Golden values are unchanged; corner cases no longer silently wrap. +2. **Strict socket reads.** `protocol.py` loops on `recv()` until the read + timeout and can silently return truncated responses. The Rust client + reads exactly header+payload or returns `ProtocolError::UnexpectedEof`. +3. **Malformed words: skip and count, never crash.** The C aborts the packet + on a bad header; Python returned `None`. Here: `Decoder::decode` skips the + word and bumps `stats.n_bad_headers`; a non-13-multiple packet length is a + hard `DecodeError` (misframed stream is a real bug, not garbage). +4. **Calibration state is per-`Decoder`, not process-global.** The C keeps + `dco0/dco1_periods_fs` in thread-local static state; a Rust struct field + makes multi-stream decoding explicit and thread-safe. +5. **AoS instead of SoA.** The C fills a SoA DataFrame for polars; v0.1 + returns `Vec` (struct of fields). Revisit when the arrow/parquet + storage layer lands (Open Point 1). +6. **`position_to_address` built like `_bindings.py`.** The lazy inverse + table is constructed by enumerating `decode_position` over all 4096 + addresses (which is exactly where the Python `ix/iy` shadowing bug lived — + not reproduced here; see `_bindings.py` history in the original repo). + +## Domain constants (kept identical) + +- Quadrants: NE=0, SE=1, SW=2, NW=3 (`decoding.c` defines). +- Frame types (high nibble byte[0]): 0b1000 data/calibration, 0b1001 timeframe. +- Integration times: code 0..3 → 400/800/1600/3200 ns. +- `bxid` tick: 25,000,000 (25 ms); `asic_timestamp = bxid*25e6 + 25e6 - ((cnt0-1)*p0 - (cnt1-1)*p1)`. +- DCO period: `10 * (100_000 * integr_time_ns / cnt)` fs, per address per DCO. +- Mattonelle 4-7 are broadcast-only (I2C 0x7F) — relevant for the future + Board/quadrant port (Open Point 3). diff --git a/scripts/build-arm64.sh b/scripts/build-arm64.sh new file mode 100755 index 0000000..ed20ca8 --- /dev/null +++ b/scripts/build-arm64.sh @@ -0,0 +1,89 @@ +#!/usr/bin/env bash +# Cross-compile innesco-rs for aarch64 (deployment target: AMD Kria K26 SOM, +# quad Cortex-A53 on Zynq UltraScale+ MPSoC, Ubuntu 22.04 on the board). +# +# No root and no Docker needed: uses cargo-zigbuild + the ziglang pip package +# as the cross linker (glibc OR static musl). First-time setup is automated: +# - rustup target add aarch64-unknown-linux-{musl,gnu} +# - python3 venv with `ziglang` (wrapper script `zig` exposed on PATH) +# - cargo install cargo-zigbuild +# +# Usage: scripts/build-arm64.sh [--musl|--gnu] [--host] [--run-tests] +# --musl static binary, no glibc dependency (default, recommended for Kria) +# --gnu dynamic binary against aarch64 glibc (matches board's Ubuntu 22.04) +# --host also build for the host (x86_64) in release mode +# --run-tests run the test suite for the host target before cross-building +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT" + +MODE=gnu +HOST=0 +RUN_TESTS=0 +for arg in "$@"; do + case "$arg" in + --musl) MODE=musl ;; + --gnu) MODE=gnu ;; + --host) HOST=1 ;; + --run-tests) RUN_TESTS=1 ;; + *) echo "unknown option: $arg (use --musl|--gnu|--host|--run-tests)" >&2; exit 2 ;; + esac +done + +TARGET="aarch64-unknown-linux-${MODE}" +DIST="$ROOT/dist/aarch64-${MODE}" +export CARGO_TARGET_DIR="${CARGO_TARGET_DIR:-/tmp/innesco-rs-target}" + +# --- toolchain bootstrap (idempotent, no root) -------------------------------- +if ! command -v rustup >/dev/null 2>&1; then + # shellcheck disable=SC1091 + source "$HOME/.cargo/env" 2>/dev/null || { + echo "rustup not found: install with 'curl https://sh.rustup.rs | sh'" >&2; exit 1; } +fi +rustup target add "$TARGET" >/dev/null + +ZIG_VENV="${INNESCO_RS_ZIG_VENV:-/tmp/venvs/zig}" +if [ ! -x "$ZIG_VENV/bin/python" ]; then + echo "== setting up zig venv in $ZIG_VENV (one-time)" + PYTHON="${INNESCO_RS_PYTHON:-python3}" + "$PYTHON" -m venv "$ZIG_VENV" + "$ZIG_VENV/bin/pip" -q install ziglang +fi +ZIG_BIN="$ZIG_VENV/zigbin" +if [ ! -x "$ZIG_BIN/zig" ]; then + echo "== creating zig wrapper in $ZIG_BIN (one-time)" + mkdir -p "$ZIG_BIN" + printf '#!/bin/sh\nexec %q -m ziglang "$@"\n' "$ZIG_VENV/bin/python" > "$ZIG_BIN/zig" + chmod +x "$ZIG_BIN/zig" +fi +export PATH="$ZIG_BIN:$PATH" +command -v cargo-zigbuild >/dev/null 2>&1 || cargo install cargo-zigbuild + +# --- build -------------------------------------------------------------------- +if [ "$RUN_TESTS" = 1 ]; then + echo "== running test suite (host target)" + cargo test --workspace +fi + +echo "== cross-compiling for $TARGET" +if [ "$HOST" = 1 ]; then + cargo zigbuild --release --workspace --target "$TARGET" --target host +else + cargo zigbuild --release --workspace --target "$TARGET" +fi + +mkdir -p "$DIST" +BIN="$CARGO_TARGET_DIR/$TARGET/release/innesco-cli" +cp "$BIN" "$DIST/innesco-cli" +chmod +x "$DIST/innesco-cli" + +echo "== artifact:" +file "$DIST/innesco-cli" 2>/dev/null || true +ls -lh "$DIST/innesco-cli" +if command -v aarch64-linux-gnu-readelf >/dev/null 2>&1; then + aarch64-linux-gnu-readelf -h "$DIST/innesco-cli" | grep -E "Class|Machine" || true +elif command -v readelf >/dev/null 2>&1; then + readelf -h "$DIST/innesco-cli" | grep -E "Class|Machine" || true +fi +echo "== done: $DIST/innesco-cli"