From eff04cfa1022da9cd5fd68fbd4a3821ddf6c5140 Mon Sep 17 00:00:00 2001 From: BobBot Date: Thu, 12 Nov 2026 23:19:23 +0000 Subject: [PATCH] =?UTF-8?q?feat(ecs):=20slice=201=20=E2=80=94=20I2C=20fiel?= =?UTF-8?q?d=20model,=20board=20registers,=20pixel=20(ports=20of=20=5Ffiel?= =?UTF-8?q?ds/board/pixel.py)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- Cargo.lock | 7 + Cargo.toml | 1 + MEMORY.md | 2 + README.md | 45 ++-- crates/innesco-ecs/Cargo.toml | 11 + crates/innesco-ecs/src/board.rs | 152 +++++++++++++ crates/innesco-ecs/src/fields.rs | 307 ++++++++++++++++++++++++++ crates/innesco-ecs/src/lib.rs | 22 ++ crates/innesco-ecs/src/pixel.rs | 133 +++++++++++ crates/innesco-ecs/tests/ecs_tests.rs | 291 ++++++++++++++++++++++++ docs/porting-notes.md | 14 ++ 11 files changed, 963 insertions(+), 22 deletions(-) create mode 100644 crates/innesco-ecs/Cargo.toml create mode 100644 crates/innesco-ecs/src/board.rs create mode 100644 crates/innesco-ecs/src/fields.rs create mode 100644 crates/innesco-ecs/src/lib.rs create mode 100644 crates/innesco-ecs/src/pixel.rs create mode 100644 crates/innesco-ecs/tests/ecs_tests.rs diff --git a/Cargo.lock b/Cargo.lock index 52ca6fd..38cd35d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14,6 +14,13 @@ dependencies = [ name = "innesco-decoding" version = "0.1.0" +[[package]] +name = "innesco-ecs" +version = "0.1.0" +dependencies = [ + "innesco-protocol", +] + [[package]] name = "innesco-protocol" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 1be2684..416c105 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,6 +3,7 @@ resolver = "2" members = [ "crates/innesco-protocol", "crates/innesco-decoding", + "crates/innesco-ecs", "crates/innesco-cli", ] diff --git a/MEMORY.md b/MEMORY.md index a8f3536..22d028f 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -8,3 +8,5 @@ - 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. +- 2026-11-12: arm64 musl build verified (static, AArch64); craft-anything-cli installed. +- 2026-11-12: slice 1 of OP3 (innesco-ecs: _fields/board/pixel) — 21 tests green; 2 faithful-port findings (enum non-round-trip, crystal hi/lo aliasing). Decisions: polars-rs + S3 crucial (OP1), CI deprioritized. Reminder cron 2026-11-18 09:00 for raw frames. diff --git a/README.md b/README.md index e063b48..d9b079b 100644 --- a/README.md +++ b/README.md @@ -50,35 +50,36 @@ skip-and-count instead of abort on malformed packets). ## Open Points -(user-editable — tell me here what to focus on; details agreed with Lucio 2026-11-12) +(details agreed with Lucio 2026-11-12; user-editable — tell me what to focus on) -1. **Storage layer** (after #3): `storage.py` is a 185-line `ParquetStorage` - thread (queue → parquet → S3/MinIO upload, prometheus counters). - Rust port options: **arrow-rs** (lighter; arrow is SoA-native, closes the - AoS/SoA divergence) vs **polars-rs** (feature parity with notebooks, heavy). - *Decisions needed*: (a) arrow-rs vs polars, (b) S3 in-process vs local-only, - (c) keep the exact Python column schema (notebook compatibility). +1. **Storage layer** (after #3) — *decisions taken*: **polars-rs** for parquet + I/O (feature parity with the notebooks) + **S3/MinIO upload is crucial** + (no local storage on the board — data must be pushed out). Schema need not + be byte-identical, but must keep the notebook query surface: columns + `address, ix, iy, quadrant, tot, adj_ctrl, period, integr_time, v_inj` + (grep of notebooks 02/04/05/06/07) and the file-path conventions + (`results/{date}/analog_power=*/dcos-*.parquet`, `dataset-tag-{n}.parquet` + — duckdb queries use `SELECT *`, so paths matter more than column order). + Original: 185-line `ParquetStorage` thread (queue → parquet → S3). 2. **REST API** (after #3): 7 endpoints in `rest_api.py` (`/ping`, `/metrics`, `/state`, `PUT /chunksize`, `POST /tag`, `POST /daq`, `GET /dataset`). Port: axum + tokio in a separate crate with feature flag (library stays dependency-free). `/state` and `/daq` depend on #3; the other four can be ported independently. -3. **Board/slow-control model** (biggest item): `ecs/` ≈ 2,358 lines - (asic_state 626, mattonella_state 569, quadrant 502, mattonella 426, …) - + `Board.py` 268 + `DataProcessor.py` 425. Suggested slices: - (1) board+pixel 166 lines → (2) mattonella(+state) 995 → (3) asic_state 626 - → (4) quadrant 502 → (5) daq+DataProcessor 574. Mirror-1:1 first (golden - I2C tests comparable with Python), type-state validation later. - Depends only on the (already ported) protocol crate. +3. **Board/slow-control model** — **IN PROGRESS, slice 1 done**: + - ✅ slice 1: `_fields.py` (199 L) + `board.py` (89) + `pixel.py` (77) → + `crates/innesco-ecs` (7 integration tests against a fake data_server, + incl. RMW semantics and the crystal-config sequencer; two faithful-port + findings documented in docs/porting-notes.md #7/#8). + - next: (2) mattonella(+state) 995 L → (3) asic_state 626 → (4) quadrant 502 + → (5) daq+DataProcessor 574. Mirror-1:1 first, type-state validation later. 4. **Real-board validation**: no qemu here, no network to the boards. (a) *A raw frame dump from a real acquisition* (even small) → decoder validated on physical data as an official golden test — **highest value, - zero prerequisites**. (b) network access to a Kria running `data_server` + zero prerequisites. Lucio will try next week; reminder set for + Wed 2026-11-18 09:00.** (b) network access to a Kria running `data_server` → live `innesco-cli ping` + harmless I2C read (`0x7E`). -5. **CI runner**: verified 2026-11-12 — no Actions runs on this Gitea repo - and runner admin endpoint is not accessible → no runner configured. - Self-hosting one here is impossible (no Docker daemon). Options: register - a runner on a machine with Docker, or rely on local - `scripts/build-arm64.sh --run-tests` until then. - -**Recommended order**: 4(a) → 3 → 1 → 2 → 5. +5. **CI runner** — *deprioritized (Lucio 2026-11-12)*: verified 2026-11-12 + that no Actions runner exists on this Gitea and self-hosting is impossible + here (no Docker daemon). Local `scripts/build-arm64.sh --run-tests` is the + working CI substitute. diff --git a/crates/innesco-ecs/Cargo.toml b/crates/innesco-ecs/Cargo.toml new file mode 100644 index 0000000..439264b --- /dev/null +++ b/crates/innesco-ecs/Cargo.toml @@ -0,0 +1,11 @@ +[package] +name = "innesco-ecs" +description = "Slow-control register model for IGNITE64 boards (Rust port of innesco/ecs: _fields.py, board.py, pixel.py)" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +authors.workspace = true + +[dependencies] +innesco-protocol = { path = "../innesco-protocol" } diff --git a/crates/innesco-ecs/src/board.rs b/crates/innesco-ecs/src/board.rs new file mode 100644 index 0000000..76e0ac1 --- /dev/null +++ b/crates/innesco-ecs/src/board.rs @@ -0,0 +1,152 @@ +//! Rust port of `innesco/ecs/board.py` — static registers of the carrier +//! board plus `config_crystal`. + +use std::path::Path; + +use innesco_protocol::{Connection, Request}; + +use crate::fields::{FieldAddress, I2cField}; + +/// Register model of the carrier board (all addresses are board-global, so +/// the fields here carry fixed addresses — no per-instance context needed). +pub struct Board; + +const NONE: Option = None; + +impl Board { + /// Board I2C multiplexer channel. + pub const MUX: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x70), + NONE, + 0x0F, + &[(0, "OFF"), (1, "SW"), (2, "NW"), (4, "SE"), (8, "NE")], + ); + + /// Ingress source for FastIN signals. + pub const FASTIN_SRC: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x01, + &[(0, "J12"), (0xFF, "LVDS")], + ); + + /// External DAC power state. + pub const EXTERNAL_DAC: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x02, + &[(0, "ON"), (0xFF, "OFF")], + ); + + /// Source data. + pub const SEL_DATA_EN_SRC: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x04, + &[(0, "KRIA"), (0xFF, "J14")], + ); + + /// SI_CLK output enable. + pub const SI_CLK_OE: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x08, + &[(0, "OFF"), (0xFF, "ON")], + ); + + /// SI_CLK input. + pub const SI_CLK_IN: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x30, + &[(0x00, "SMA"), (0x10, "KRIA"), (0x20, "NONE"), (0x30, "CRYSTAL")], + ); + + /// Analog power state (note the inverted encoding: 0x00 = ON, 0x40 = OFF). + pub const ANALOG_POWER: I2cField = I2cField::enum_( + FieldAddress::Fixed(0x20), + Some(FieldAddress::Fixed(0x0A)), + 0x40, + &[(0x00, "ON"), (0x40, "OFF")], + ); + + /// PIN direction register ("PIN is configured as I/O"). + pub const DIRECTION_REGISTER: I2cField = + I2cField::byte(FieldAddress::Fixed(0x20), Some(FieldAddress::Fixed(0x00))); + + /// Port of `Board.config_crystal`: parse a CSV of `addr,value` hex pairs + /// and program the crystal controller at `0x75` (write high byte of the + /// register address to subaddress 0x01, then the value to subaddress + /// `addr & 0xFF`). Blank lines, comments (`#`) and malformed lines are + /// skipped (a warning goes to stderr, like the Python `logging.warning`). + /// + /// Returns the number of `(addr, value)` pairs actually written. + pub fn config_crystal( + config_file: &Path, + conn: &mut Connection, + ) -> Result { + let text = std::fs::read_to_string(config_file) + .map_err(|e| CrystalError::Io(config_file.display().to_string(), e))?; + + let mut rows: Vec<(u8, u8, u8)> = Vec::new(); + for line in text.lines() { + let trimmed = line.trim(); + if trimmed.is_empty() || trimmed.starts_with('#') { + continue; + } + match Self::parse_crystal_line(trimmed) { + Some(row) => rows.push(row), + None => eprintln!("warning: skipping invalid line in crystal config: {trimmed}"), + } + } + + conn.send(&Request::Ping { payload: b"Configuring crystal...".to_vec() })?; + for (hi, lo, value) in &rows { + conn.send(&Request::WriteSub { + address: 0x75, + subaddress: 0x01, + payload: vec![*hi], + })?; + conn.send(&Request::WriteSub { + address: 0x75, + subaddress: *lo, + payload: vec![*value], + })?; + } + conn.send(&Request::Ping { payload: b"Crystal configuration complete.".to_vec() })?; + Ok(rows.len()) + } + + /// Line format: `addr,value` — both hex, addr is 16-bit, value 8-bit. + /// (Python accepts decimal-looking tokens too because `int(x, 16)`; here + /// we accept hex with or without the `0x` prefix — same reader audience.) + fn parse_crystal_line(line: &str) -> Option<(u8, u8, u8)> { + let (addr_part, value_part) = line.split_once(',')?; + let addr = u16::from_str_radix(addr_part.trim().trim_start_matches("0x"), 16).ok()?; + let value = u8::from_str_radix(value_part.trim().trim_start_matches("0x"), 16).ok()?; + Some(((addr >> 8) as u8, (addr & 0xFF) as u8, value)) + } +} + +#[derive(Debug)] +pub enum CrystalError { + Io(String, std::io::Error), + Protocol(innesco_protocol::ProtocolError), +} + +impl std::fmt::Display for CrystalError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + CrystalError::Io(path, e) => write!(f, "cannot read {path}: {e}"), + CrystalError::Protocol(e) => write!(f, "protocol error: {e}"), + } + } +} + +impl std::error::Error for CrystalError {} + +impl From for CrystalError { + fn from(e: innesco_protocol::ProtocolError) -> Self { + CrystalError::Protocol(e) + } +} diff --git a/crates/innesco-ecs/src/fields.rs b/crates/innesco-ecs/src/fields.rs new file mode 100644 index 0000000..a66a576 --- /dev/null +++ b/crates/innesco-ecs/src/fields.rs @@ -0,0 +1,307 @@ +//! Rust port of `innesco/ecs/_fields.py`. +//! +//! Each I2C register field is a declarative [`I2cField`] describing +//! (address, subaddress, mask, bit shift, kind). Address/subaddress can be +//! fixed constants or resolved per instance (the Python `from_attribute` +//! closures, used by Pixel). Read-modify-write semantics mirror the Python +//! descriptors byte for byte, including the quirk that the `i2c_byte` +//! *getter* returns the full raw byte (mask NOT applied on read) while the +//! enum/int getters do apply it. + +use innesco_protocol::{Connection, ProtocolError, Request, Response}; + +/// Where a field's I2C address (or subaddress) comes from. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FieldAddress { + Fixed(u8), + /// Python `from_attribute("_mattonella_id")`. + MattonellaId, + /// Python `from_attribute("_pixel_id")`. + PixelId, +} + +/// Per-instance values used to resolve [`FieldAddress::MattonellaId`] / +/// [`FieldAddress::PixelId`]. +#[derive(Debug, Clone, Copy, Default)] +pub struct FieldContext { + pub mattonella_id: u8, + pub pixel_id: u8, +} + +/// Field kind (Python descriptor constructors). +#[derive(Debug, Clone, Copy)] +pub enum Kind { + /// `i2c_byte`: getter returns the RAW byte (no mask on read). + Byte, + /// `i2c_bool`: masked bit test on read, set/clear full mask on write. + Bool, + /// `i2c_int`: `(raw & mask) >> shift` on read. + Int, + /// `i2c_enum`: named values, hex-string fallback for unknown codes. + Enum(&'static [(u8, &'static str)]), +} + +/// Declarative I2C register field (one Python descriptor). +#[derive(Debug, Clone, Copy)] +pub struct I2cField { + pub address: FieldAddress, + pub subaddress: Option, + /// Effective mask (for `i2c_int` this is `(mask << shift) & 0xFF`, + /// exactly like the Python constructor). + pub mask: u8, + pub shift: u8, + pub kind: Kind, +} + +#[derive(Debug)] +pub enum FieldError { + Protocol(ProtocolError), + /// Server answered with a non-zero status (Python would have failed + /// more obscurely; we make it explicit). + Server { status: u8, message: String }, + /// Response carried no I2C data where one byte was required. + EmptyPayload, + /// Value out of range / not a valid enum member (Python `ValueError`). + InvalidValue { value: String, reason: String }, +} + +impl std::fmt::Display for FieldError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + FieldError::Protocol(e) => write!(f, "protocol error: {e}"), + FieldError::Server { status, message } => { + write!(f, "server error {status}: {message}") + } + FieldError::EmptyPayload => write!(f, "empty I2C payload"), + FieldError::InvalidValue { value, reason } => { + write!(f, "invalid value {value}: {reason}") + } + } + } +} + +impl std::error::Error for FieldError {} + +impl From for FieldError { + fn from(e: ProtocolError) -> Self { + FieldError::Protocol(e) + } +} + +impl I2cField { + /// `i2c_byte(...)` — full-byte field, optional validator kept out of v1 + /// (no validator is used in board.py/pixel.py slice). + pub const fn byte(address: FieldAddress, subaddress: Option) -> Self { + I2cField { address, subaddress, mask: 0xFF, shift: 0, kind: Kind::Byte } + } + + /// `i2c_enum(...)` — `values` maps codes to names. + pub const fn enum_( + address: FieldAddress, + subaddress: Option, + mask: u8, + values: &'static [(u8, &'static str)], + ) -> Self { + I2cField { address, subaddress, mask, shift: 0, kind: Kind::Enum(values) } + } + + /// `i2c_bool(...)` — mask is the single bit (or bits) to set/clear. + pub const fn bool_( + address: FieldAddress, + subaddress: Option, + mask: u8, + ) -> Self { + I2cField { address, subaddress, mask, shift: 0, kind: Kind::Bool } + } + + /// `i2c_int(...)` — the Python constructor applies + /// `mask = (mask << shift) & 0xFF` at definition time; same here. + pub const fn int( + address: FieldAddress, + subaddress: Option, + shift: u8, + mask: u8, + ) -> Self { + I2cField { + address, + subaddress, + mask: ((mask as u16) << shift) as u8 & 0xFF, + shift, + kind: Kind::Int, + } + } + + fn resolve(&self, which: FieldAddress, ctx: FieldContext) -> u8 { + match which { + FieldAddress::Fixed(a) => a, + FieldAddress::MattonellaId => ctx.mattonella_id, + FieldAddress::PixelId => ctx.pixel_id, + } + } + + fn bus(&self, ctx: FieldContext) -> (u8, Option) { + ( + self.resolve(self.address, ctx), + self.subaddress.map(|s| self.resolve(s, ctx)), + ) + } + + fn send(&self, conn: &mut Connection, request: &Request) -> Result { + let resp = conn.send(request)?; + if resp.is_error() { + return Err(FieldError::Server { + status: resp.status, + message: resp.message(), + }); + } + Ok(resp) + } + + fn read_one(&self, conn: &mut Connection, ctx: FieldContext) -> Result { + let (address, subaddress) = self.bus(ctx); + let request = match subaddress { + Some(sub) => Request::ReadSub { address, subaddress: sub, length: 1 }, + None => Request::Read { address, length: 1 }, + }; + let resp = self.send(conn, &request)?; + resp.i2c_data() + .first() + .copied() + .ok_or(FieldError::EmptyPayload) + } + + fn write_one( + &self, + conn: &mut Connection, + ctx: FieldContext, + payload: u8, + ) -> Result<(), FieldError> { + let (address, subaddress) = self.bus(ctx); + let request = match subaddress { + Some(sub) => Request::WriteSub { address, subaddress: sub, payload: vec![payload] }, + None => Request::Write { address, payload: vec![payload] }, + }; + self.send(conn, &request)?; + Ok(()) + } + + /// `unchanged` part of a read-modify-write: Python reads the remote byte + /// and keeps everything outside the mask — unless `mask == 0xFF`, where + /// it writes without reading at all. + fn unchanged_part( + &self, + conn: &mut Connection, + ctx: FieldContext, + ) -> Result { + if self.mask == 0xFF { + Ok(0x00) + } else { + Ok(self.read_one(conn, ctx)? & !self.mask) + } + } + + // ------------------------------------------------------------------ + // Readers + // ------------------------------------------------------------------ + + /// `i2c_byte` getter: the FULL raw byte (mask not applied — Python quirk, + /// preserved deliberately). + pub fn read_byte(&self, conn: &mut Connection, ctx: FieldContext) -> Result { + self.read_one(conn, ctx) + } + + /// `i2c_bool` getter: `(raw & mask) != 0`. + pub fn read_bool(&self, conn: &mut Connection, ctx: FieldContext) -> Result { + Ok(self.read_one(conn, ctx)? & self.mask != 0) + } + + /// `i2c_int` getter: `(raw & mask) >> shift`. + pub fn read_int(&self, conn: &mut Connection, ctx: FieldContext) -> Result { + Ok((self.read_one(conn, ctx)? & self.mask) >> self.shift) + } + + /// `i2c_enum` getter: masked code mapped to its name, hex fallback for + /// unknown codes (Python: `enum.get(ret, f"{ret:02X}")`). + pub fn read_enum(&self, conn: &mut Connection, ctx: FieldContext) -> Result { + let ret = self.read_one(conn, ctx)? & self.mask; + let Kind::Enum(values) = self.kind else { + return Err(FieldError::InvalidValue { + value: "read_enum".into(), + reason: "field kind is not Enum".into(), + }); + }; + Ok(match values.iter().find(|(code, _)| *code == ret) { + Some((_, name)) => name.to_string(), + None => format!("{ret:02X}"), + }) + } + + // ------------------------------------------------------------------ + // Writers + // ------------------------------------------------------------------ + + /// `i2c_byte` setter: validate byte range, `update = value & mask`, RMW. + pub fn write_byte( + &self, + conn: &mut Connection, + ctx: FieldContext, + value: u8, + ) -> Result<(), FieldError> { + let unchanged = self.unchanged_part(conn, ctx)?; + self.write_one(conn, ctx, unchanged | (value & self.mask)) + } + + /// `i2c_bool` setter: set or clear the mask bits (always reads current). + pub fn write_bool( + &self, + conn: &mut Connection, + ctx: FieldContext, + value: bool, + ) -> Result<(), FieldError> { + let current = self.read_one(conn, ctx)?; + let updated = if value { current | self.mask } else { current & !self.mask }; + self.write_one(conn, ctx, updated) + } + + /// `i2c_int` setter: validate `0..=(mask >> shift)`, shift into place, RMW. + pub fn write_int( + &self, + conn: &mut Connection, + ctx: FieldContext, + value: u8, + ) -> Result<(), FieldError> { + let max = self.mask >> self.shift; + if value > max { + return Err(FieldError::InvalidValue { + value: value.to_string(), + reason: format!("not in valid range 0-{max}"), + }); + } + let unchanged = self.unchanged_part(conn, ctx)?; + self.write_one(conn, ctx, unchanged | ((value << self.shift) & self.mask)) + } + + /// `i2c_enum` setter: name must be a member; write its code within the + /// mask, RMW otherwise. + pub fn write_enum( + &self, + conn: &mut Connection, + ctx: FieldContext, + name: &str, + ) -> Result<(), FieldError> { + let Kind::Enum(values) = self.kind else { + return Err(FieldError::InvalidValue { + value: name.into(), + reason: "field kind is not Enum".into(), + }); + }; + let Some((code, _)) = values.iter().find(|(_, n)| *n == name) else { + return Err(FieldError::InvalidValue { + value: name.into(), + reason: "not a valid enum member".into(), + }); + }; + let unchanged = self.unchanged_part(conn, ctx)?; + self.write_one(conn, ctx, unchanged | (code & self.mask)) + } +} diff --git a/crates/innesco-ecs/src/lib.rs b/crates/innesco-ecs/src/lib.rs new file mode 100644 index 0000000..e98e35a --- /dev/null +++ b/crates/innesco-ecs/src/lib.rs @@ -0,0 +1,22 @@ +//! Slow-control register model for IGNITE64 boards. +//! +//! Slice 1 of the Board-model port (Open Point 3 in README): +//! * `fields` — Rust port of `innesco/ecs/_fields.py` (i2c_byte/enum/bool/int +//! descriptors, incl. their exact read-modify-write semantics); +//! * `board` — port of `innesco/ecs/board.py` (static board registers, +//! `config_crystal`); +//! * `pixel` — port of `innesco/ecs/pixel.py` (per-instance pixel registers, +//! finetune DAC nibble logic). +//! +//! Divergences from Python (see docs/porting-notes.md): the module-global +//! "current connection" is replaced by explicit `&mut Connection` arguments, +//! and `ValueError`/server errors are returned as `FieldError` instead of +//! raising. + +mod board; +mod fields; +mod pixel; + +pub use board::Board; +pub use fields::{FieldAddress, FieldContext, FieldError, I2cField, Kind}; +pub use pixel::Pixel; diff --git a/crates/innesco-ecs/src/pixel.rs b/crates/innesco-ecs/src/pixel.rs new file mode 100644 index 0000000..74496f1 --- /dev/null +++ b/crates/innesco-ecs/src/pixel.rs @@ -0,0 +1,133 @@ +//! Rust port of `innesco/ecs/pixel.py` — per-instance pixel registers and +//! the finetune-DAC nibble logic. + +use innesco_protocol::Connection; + +use crate::fields::{FieldAddress, FieldContext, FieldError, I2cField}; + +/// One pixel of a mattonella: its registers live at +/// `(address = mattonella_id, subaddress = pixel_id)` (Python +/// `from_attribute("_mattonella_id")` / `("_pixel_id")`). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Pixel { + pub mattonella_id: u8, + pub pixel_id: u8, +} + +impl Pixel { + pub const fn new(mattonella_id: u8, pixel_id: u8) -> Self { + Pixel { mattonella_id, pixel_id } + } + + fn ctx(&self) -> FieldContext { + FieldContext { mattonella_id: self.mattonella_id, pixel_id: self.pixel_id } + } + + /// Pixel power state (mask 0x40). + pub const POWER: I2cField = I2cField::bool_( + FieldAddress::MattonellaId, + Some(FieldAddress::PixelId), + 0x40, + ); + + /// Pixel frontend state (mask 0x80). + pub const FRONTEND: I2cField = I2cField::bool_( + FieldAddress::MattonellaId, + Some(FieldAddress::PixelId), + 0x80, + ); + + /// Pixel adjustment value (bits 5-4). + pub const ADJ: I2cField = + I2cField::int(FieldAddress::MattonellaId, Some(FieldAddress::PixelId), 4, 0x03); + + /// Pixel control value (bits 3-0). + pub const CTRL: I2cField = + I2cField::int(FieldAddress::MattonellaId, Some(FieldAddress::PixelId), 0, 0x0F); + + pub fn power(&self, conn: &mut Connection) -> Result { + Self::POWER.read_bool(conn, self.ctx()) + } + + pub fn set_power(&self, conn: &mut Connection, on: bool) -> Result<(), FieldError> { + Self::POWER.write_bool(conn, self.ctx(), on) + } + + pub fn frontend(&self, conn: &mut Connection) -> Result { + Self::FRONTEND.read_bool(conn, self.ctx()) + } + + pub fn set_frontend(&self, conn: &mut Connection, on: bool) -> Result<(), FieldError> { + Self::FRONTEND.write_bool(conn, self.ctx(), on) + } + + pub fn adj(&self, conn: &mut Connection) -> Result { + Self::ADJ.read_int(conn, self.ctx()) + } + + pub fn set_adj(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> { + Self::ADJ.write_int(conn, self.ctx(), value) + } + + pub fn ctrl(&self, conn: &mut Connection) -> Result { + Self::CTRL.read_int(conn, self.ctx()) + } + + pub fn set_ctrl(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> { + Self::CTRL.write_int(conn, self.ctx(), value) + } + + /// Finetune DAC of this pixel: two pixels share one register at + /// subaddress `0x4C + pixel_id / 2` (even pixel = low nibble, odd pixel = + /// high nibble) — Python `finetune_dac` property. + pub fn finetune_dac(&self, conn: &mut Connection) -> Result { + let raw = Self::finetune_read(conn, self)?; + Ok(if self.pixel_id % 2 == 0 { raw } else { raw >> 4 } & 0x0F) + } + + /// Finetune DAC setter (Python raises for values outside 0-15; here that + /// is a `FieldError::InvalidValue`). + pub fn set_finetune_dac(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> { + if value > 0x0F { + return Err(FieldError::InvalidValue { + value: value.to_string(), + reason: "out of valid range 0-15".into(), + }); + } + let current = Self::finetune_read(conn, self)?; + let new_value = if self.pixel_id % 2 == 0 { + (current & 0xF0) | (value & 0x0F) + } else { + (current & 0x0F) | ((value & 0x0F) << 4) + }; + Self::finetune_write(conn, self, new_value) + } + + fn finetune_subaddress(&self) -> u8 { + 0x4C + self.pixel_id / 2 + } + + fn finetune_read(conn: &mut Connection, px: &Pixel) -> Result { + let resp = conn.send(&innesco_protocol::Request::ReadSub { + address: px.mattonella_id, + subaddress: px.finetune_subaddress(), + length: 1, + })?; + if resp.is_error() { + return Err(FieldError::Server { status: resp.status, message: resp.message() }); + } + resp.i2c_data().first().copied().ok_or(FieldError::EmptyPayload) + } + + fn finetune_write(conn: &mut Connection, px: &Pixel, value: u8) -> Result<(), FieldError> { + let resp = conn.send(&innesco_protocol::Request::WriteSub { + address: px.mattonella_id, + subaddress: px.finetune_subaddress(), + payload: vec![value], + })?; + if resp.is_error() { + return Err(FieldError::Server { status: resp.status, message: resp.message() }); + } + Ok(()) + } +} diff --git a/crates/innesco-ecs/tests/ecs_tests.rs b/crates/innesco-ecs/tests/ecs_tests.rs new file mode 100644 index 0000000..4280fc4 --- /dev/null +++ b/crates/innesco-ecs/tests/ecs_tests.rs @@ -0,0 +1,291 @@ +//! Integration tests for the `innesco-ecs` register model. +//! +//! A minimal fake `data_server` keeps a register file in a HashMap keyed by +//! (address, subaddress): Reads return the stored byte, Writes store the +//! payload, Pings echo. This exercises the exact wire behaviour of the +//! read-modify-write semantics ported from `_fields.py`. + +use std::collections::HashMap; +use std::io::{Read, Write}; +use std::net::TcpListener; +use std::time::Duration; + +use innesco_ecs::{Board, FieldContext, Pixel}; +use innesco_protocol::Connection; + +/// Fake data_server: HashMap register file + operation log. +struct FakeServer { + handle: std::thread::JoinHandle<()>, + port: u16, + /// shared state: register file (addr, sub) -> byte + regs: std::sync::Arc>>, + pings: std::sync::Arc>>>, +} + +impl FakeServer { + fn start() -> Self { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let port = listener.local_addr().unwrap().port(); + let regs = std::sync::Arc::new(std::sync::Mutex::new(HashMap::new())); + let pings = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); + let (r, p) = (regs.clone(), pings.clone()); + let handle = 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; + } + 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 { + 0xC1 => { + p.lock().unwrap().push(data.clone()); + 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(); + } + 0x10 | 0x12 => { + // Write: data = addr [, sub] payload + let (addr, sub, payload) = if opcode == 0x12 { + (data[0], data[1], &data[2..]) + } else { + (data[0], 0xFF, &data[1..]) + }; + for (i, v) in payload.iter().enumerate() { + // No-subaddress ops address the register directly; + // multi-byte no-sub writes are not used by slice 1. + let s = if sub == 0xFF && i == 0 { 0xFF } else { sub }; + r.lock().unwrap().insert((addr, s), *v); + } + sock.write_all(&[0, 0, 0, 0, 0]).unwrap(); + } + 0x11 | 0x13 => { + // Read: data = addr [, sub] len + let (addr, sub, length) = if opcode == 0x13 { + (data[0], data[1], u16::from_be_bytes([data[2], data[3]])) + } else { + (data[0], 0xFF, u16::from_be_bytes([data[1], data[2]])) + }; + let mut payload = vec![0u8]; // i2c status + for _ in 0..length { + let s = if sub == 0xFF { 0xFF } else { sub }; + let default = 0u8; + payload.push(*r.lock().unwrap().get(&(addr, s)).unwrap_or(&default)); + } + let mut resp = vec![0u8]; + resp.extend_from_slice(&(payload.len() as u32).to_be_bytes()); + resp.extend_from_slice(&payload); + sock.write_all(&resp).unwrap(); + } + _ => sock.write_all(&[1, 0, 0, 0, 4, b'e', b'r', b'r', b'!']).unwrap(), + } + } + }); + FakeServer { handle, port, regs, pings } + } + + fn connect(&self) -> Connection { + Connection::connect("127.0.0.1", self.port, Duration::from_secs(5)).unwrap() + } + + fn get(&self, addr: u8, sub: u8) -> u8 { + *self.regs.lock().unwrap().get(&(addr, sub)).unwrap_or(&0) + } + + fn set(&self, addr: u8, sub: u8, value: u8) { + self.regs.lock().unwrap().insert((addr, sub), value); + } + + fn ping_count(&self) -> usize { + self.pings.lock().unwrap().len() + } +} + +const CTX: FieldContext = FieldContext { mattonella_id: 0, pixel_id: 0 }; + +#[test] +fn mux_enum_roundtrip_and_rmw() { + let server = FakeServer::start(); + let mut conn = server.connect(); + + // Empty register: writing NE (0x8, mask 0x0F) goes out as 0x08. + Board::MUX.write_enum(&mut conn, CTX, "NE").unwrap(); + assert_eq!(server.get(0x70, 0xFF), 0x08); + assert_eq!(Board::MUX.read_enum(&mut conn, CTX).unwrap(), "NE"); + + // Preset the OTHER nibble: RMW must preserve it. + server.set(0x70, 0xFF, 0x40); + Board::MUX.write_enum(&mut conn, CTX, "SW").unwrap(); + assert_eq!(server.get(0x70, 0xFF), 0x41); + + // Invalid member is rejected client-side. + assert!(Board::MUX.write_enum(&mut conn, CTX, "NOPE").is_err()); + + // Unknown code falls back to the hex string (Python `enum.get(ret, ..)`). + server.set(0x70, 0xFF, 0x03); + assert_eq!(Board::MUX.read_enum(&mut conn, CTX).unwrap(), "03"); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn board_0x20_sub_0x0a_fields() { + let server = FakeServer::start(); + let mut conn = server.connect(); + + // FASTIN_SRC: J12=0x00 / LVDS=0xFF, mask 0x01 -> only bit 0 lands. + Board::FASTIN_SRC.write_enum(&mut conn, CTX, "LVDS").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x01); + // Faithful-to-Python quirk: LVDS=0xFF & mask 0x01 = 0x01, which is NOT an + // enum key, so the read falls back to the hex string "01" (the Python + // descriptor behaves identically; see docs/porting-notes.md). + assert_eq!(Board::FASTIN_SRC.read_enum(&mut conn, CTX).unwrap(), "01"); + + // EXTERNAL_DAC (mask 0x02) shares the same byte: preserve bit 0. + Board::EXTERNAL_DAC.write_enum(&mut conn, CTX, "OFF").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x03); // 0x01 | 0x02 + + // SI_CLK_IN uses mask 0x30: KRIA = 0x10. + Board::SI_CLK_IN.write_enum(&mut conn, CTX, "KRIA").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x13); + assert_eq!(Board::SI_CLK_IN.read_enum(&mut conn, CTX).unwrap(), "KRIA"); + + // ANALOG_POWER inverted encoding: ON=0x00 (clears bit 6), OFF=0x40. + Board::ANALOG_POWER.write_enum(&mut conn, CTX, "OFF").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x53); + assert_eq!(Board::ANALOG_POWER.read_enum(&mut conn, CTX).unwrap(), "OFF"); + Board::ANALOG_POWER.write_enum(&mut conn, CTX, "ON").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x13); + assert_eq!(Board::ANALOG_POWER.read_enum(&mut conn, CTX).unwrap(), "ON"); + + // SEL_DATA_EN_SRC mask 0x04: J14=0xFF & 0x04 = 0x04 -> hex fallback "04" + // on read (same non-round-trip quirk as FASTIN_SRC; Python-identical). + Board::SEL_DATA_EN_SRC.write_enum(&mut conn, CTX, "J14").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x17); + assert_eq!(Board::SEL_DATA_EN_SRC.read_enum(&mut conn, CTX).unwrap(), "04"); + + // SI_CLK_OE mask 0x08. + Board::SI_CLK_OE.write_enum(&mut conn, CTX, "ON").unwrap(); + assert_eq!(server.get(0x20, 0x0A), 0x1F); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn direction_register_full_byte() { + let server = FakeServer::start(); + let mut conn = server.connect(); + + // i2c_byte with mask 0xFF: write without prior read, full byte. + Board::DIRECTION_REGISTER.write_byte(&mut conn, CTX, 0xA5).unwrap(); + assert_eq!(server.get(0x20, 0x00), 0xA5); + // The getter returns the RAW byte (mask not applied) — Python quirk kept. + assert_eq!(Board::DIRECTION_REGISTER.read_byte(&mut conn, CTX).unwrap(), 0xA5); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn pixel_bools_share_one_byte() { + let server = FakeServer::start(); + let mut conn = server.connect(); + let px = Pixel::new(5, 3); // registers at (0x05, 0x03) + + px.set_power(&mut conn, true).unwrap(); + assert_eq!(server.get(0x05, 0x03), 0x40); + px.set_frontend(&mut conn, true).unwrap(); + assert_eq!(server.get(0x05, 0x03), 0xC0); + // power still true after touching frontend + assert!(px.power(&mut conn).unwrap()); + assert!(px.frontend(&mut conn).unwrap()); + + px.set_power(&mut conn, false).unwrap(); + assert_eq!(server.get(0x05, 0x03), 0x80); + assert!(!px.power(&mut conn).unwrap()); + assert!(px.frontend(&mut conn).unwrap()); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn pixel_adj_ctrl_int_fields() { + let server = FakeServer::start(); + let mut conn = server.connect(); + let px = Pixel::new(0, 7); + + // ADJ mask 0x03 shift 4, CTRL mask 0x0F shift 0: same byte, RMW combines. + px.set_adj(&mut conn, 2).unwrap(); + assert_eq!(server.get(0x00, 0x07), 0x20); + px.set_ctrl(&mut conn, 9).unwrap(); + assert_eq!(server.get(0x00, 0x07), 0x29); + assert_eq!(px.adj(&mut conn).unwrap(), 2); + assert_eq!(px.ctrl(&mut conn).unwrap(), 9); + + // Range checks (Python ValueError). + assert!(px.set_adj(&mut conn, 4).is_err()); + assert!(px.set_ctrl(&mut conn, 16).is_err()); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn pixel_finetune_dac_nibbles() { + let server = FakeServer::start(); + let mut conn = server.connect(); + + // Even pixel (id 2): low nibble of register 0x4C + 1 = 0x4D. + let even = Pixel::new(1, 2); + even.set_finetune_dac(&mut conn, 7).unwrap(); + assert_eq!(server.get(0x01, 0x4D), 0x07); + assert_eq!(even.finetune_dac(&mut conn).unwrap(), 7); + + // Odd pixel (id 3): high nibble of the SAME register. + let odd = Pixel::new(1, 3); + odd.set_finetune_dac(&mut conn, 12).unwrap(); + assert_eq!(server.get(0x01, 0x4D), 0xC7); // 0x0C << 4 | 0x07 + assert_eq!(even.finetune_dac(&mut conn).unwrap(), 7); // untouched + assert_eq!(odd.finetune_dac(&mut conn).unwrap(), 12); + + // Out of range (Python ValueError "out of valid range 0-15"). + assert!(Pixel::new(1, 2).set_finetune_dac(&mut conn, 16).is_err()); + + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} + +#[test] +fn config_crystal_parses_and_writes() { + let server = FakeServer::start(); + let mut conn = server.connect(); + + let path = std::env::temp_dir().join("innesco-rs-crystal-test.cfg"); + std::fs::write( + &path, + "# comment\n\n0x0140, 0x2A\n0x0201, 0xFF\nNOT A LINE\n0x0302,0x7F\n", + ) + .unwrap(); + + let n = Board::config_crystal(&path, &mut conn).unwrap(); + assert_eq!(n, 3); + // Register address high byte -> sub 0x01, value -> sub (addr & 0xFF). + // Note: row 2 (0x0201) writes its lo byte (0xFF) to sub 0x01, then row 3 + // rewrites sub 0x01 with hi=0x03 — the final hi is 0x03. + assert_eq!(server.get(0x75, 0x01), 0x03); + assert_eq!(server.get(0x75, 0x40), 0x2A); + assert_eq!(server.get(0x75, 0x02), 0x7F); + // Two pings bracket the sequence. + assert_eq!(server.ping_count(), 2); + + let _ = std::fs::remove_file(&path); + drop(conn); // close the connection so the fake server loop exits + server.handle.join().unwrap(); +} diff --git a/docs/porting-notes.md b/docs/porting-notes.md index 53ad11e..529dc4b 100644 --- a/docs/porting-notes.md +++ b/docs/porting-notes.md @@ -35,6 +35,20 @@ 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) + +7. **`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. +8. **`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).