Files
innesco-rs/docs/porting-notes.md
T
BobBot 78a84ef248
ci / test (push) Canceled after 0s
ci / build-arm64 (push) Canceled after 0s
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)
2026-11-12 07:06:19 +00:00

47 lines
2.9 KiB
Markdown

# 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).