- 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)
2.9 KiB
2.9 KiB
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)
- 64-bit arithmetic where C overflows 32-bit. In
decoding.c,tot = raw_tot * dco0_periods_fs[address]isuint32_tand theasic_timestampcorrection is computed inint/int32— withcnt=4and 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_subforasic_timestampinstead of uint64 wrap). Golden values are unchanged; corner cases no longer silently wrap. - Strict socket reads.
protocol.pyloops onrecv()until the read timeout and can silently return truncated responses. The Rust client reads exactly header+payload or returnsProtocolError::UnexpectedEof. - Malformed words: skip and count, never crash. The C aborts the packet
on a bad header; Python returned
None. Here:Decoder::decodeskips the word and bumpsstats.n_bad_headers; a non-13-multiple packet length is a hardDecodeError(misframed stream is a real bug, not garbage). - Calibration state is per-
Decoder, not process-global. The C keepsdco0/dco1_periods_fsin thread-local static state; a Rust struct field makes multi-stream decoding explicit and thread-safe. - 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). position_to_addressbuilt like_bindings.py. The lazy inverse table is constructed by enumeratingdecode_positionover all 4096 addresses (which is exactly where the Pythonix/iyshadowing bug lived — not reproduced here; see_bindings.pyhistory in the original repo).
Domain constants (kept identical)
- Quadrants: NE=0, SE=1, SW=2, NW=3 (
decoding.cdefines). - Frame types (high nibble byte[0]): 0b1000 data/calibration, 0b1001 timeframe.
- Integration times: code 0..3 → 400/800/1600/3200 ns.
bxidtick: 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).