Files
innesco-rs/docs/porting-notes.md
T
BobBot eff04cfa10
ci / test (push) Canceled after 0s
ci / build-arm64 (push) Canceled after 0s
feat(ecs): slice 1 — I2C field model, board registers, pixel (ports of _fields/board/pixel.py)
- innesco-ecs: declarative I2cField (byte/enum/bool/int) with the exact
  read-modify-write semantics of _fields.py, incl. the raw-byte getter quirk
- Board: mux, fastin_src, external_dac, sel_data_en_src, si_clk_oe,
  si_clk_in, analog_power, direction_register + config_crystal sequencer
- Pixel: power/frontend/adj/ctrl + finetune_dac nibble logic
- 7 integration tests against a fake data_server (register-file mock)
- faithful-port findings #7 (enum codes wider than mask don't round-trip
  in Python either) and #8 (crystal hi/lo aliasing) documented
- 21 tests green across the workspace
2026-11-12 23:19:23 +00:00

3.8 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)

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

Faithful-port findings (bugs/quirks in the original, mirrored exactly)

  1. i2c_enum codes do not always round-trip through the getter. The Python setter writes enum_code & mask, but several enums define codes wider than their mask (fastin_src LVDS=0xFF with mask 0x01, external_dac OFF=0xFF/0x02, sel_data_en_src J14=0xFF/0x04, si_clk_oe ON=0xFF/0x08). After such a write, the masked read yields a code that is not an enum key, so the getter returns the hex fallback (e.g. "01") instead of the name. The Rust port reproduces this exactly; a future cleanup (agreed to be deferred) would store masked codes.
  2. config_crystal hi/lo aliasing: the high byte of each register address is written to subaddress 0x01 of the controller (0x75), so a row whose low byte IS 0x01 overwrites the next row's hi byte. Mirrored as-is.

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