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)
This commit is contained in:
@@ -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
|
||||
@@ -0,0 +1,3 @@
|
||||
/target
|
||||
/dist
|
||||
*.swp
|
||||
Generated
+19
@@ -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"
|
||||
+22
@@ -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"
|
||||
@@ -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.
|
||||
@@ -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-<musl|gnu>/innesco-cli`.
|
||||
|
||||
Deploy to the Kria: `scp dist/aarch64-musl/innesco-cli <board>:~/ && ssh <board> ./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.
|
||||
@@ -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" }
|
||||
@@ -0,0 +1,96 @@
|
||||
//! `innesco-cli` — minimal CLI for the Rust clone of innesco.
|
||||
//!
|
||||
//! Subcommands:
|
||||
//! * `ping <host> [port]` — open an ECS connection to data_server and ping it.
|
||||
//! * `decode <file|->` — 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 <command>\n\
|
||||
\n\
|
||||
commands:\n \
|
||||
ping <host> [port] ping the IGNITE64 data_server (default port 8888)\n \
|
||||
decode <file|-> decode raw 13-byte frames to TSV on stdout\n \
|
||||
help show this message"
|
||||
.to_string()
|
||||
}
|
||||
|
||||
fn main() -> ExitCode {
|
||||
let args: Vec<String> = 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::<u16>().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()),
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
@@ -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<u16>`,
|
||||
/// 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<Option<u16>> {
|
||||
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<Vec<Hit>, 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<u8> {
|
||||
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<u8> {
|
||||
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);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
@@ -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<u8> },
|
||||
/// Ignite64Write with subaddress.
|
||||
WriteSub { address: u8, subaddress: u8, payload: Vec<u8> },
|
||||
/// Ping (payload is echoed back by the server).
|
||||
Ping { payload: Vec<u8> },
|
||||
}
|
||||
|
||||
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<u8> {
|
||||
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<u8> {
|
||||
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<u8>,
|
||||
}
|
||||
|
||||
impl Response {
|
||||
pub const I2C_OK: u8 = 0;
|
||||
|
||||
/// Parse a full response (header + payload).
|
||||
pub fn parse(raw: &[u8]) -> Result<Self, ProtocolError> {
|
||||
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<u8> {
|
||||
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<std::io::Error> 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<Self, ProtocolError> {
|
||||
use std::net::ToSocketAddrs;
|
||||
let addrs: Vec<std::net::SocketAddr> = (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<Response, ProtocolError> {
|
||||
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<u8> = [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();
|
||||
}
|
||||
}
|
||||
@@ -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<Hit>` (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).
|
||||
Executable
+89
@@ -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"
|
||||
Reference in New Issue
Block a user