From 9e33971388654f7d1586c1d7adb0961ec39141b3 Mon Sep 17 00:00:00 2001 From: Views2k <292889387+Views2k@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:11:34 -0600 Subject: [PATCH] Prepare scene playback for every layout and add Pro Max and SONiC groundwork The resident scene compiler moves to resident_scene.py and uses the canonical connector count of the hardware profile, so a scene covers every connector of all 25 layouts without stacking or internal records. The player script gets its port count and optical masks from the profile, the AWK renderer takes the port count as an argument, and reconnecting checks the renderer's hash as well as the player's before reusing a running player. On the Pro XG 8 PoE the scene data and the player commands are unchanged; switch playback stays limited to that model. pro_max.py adds a bounded packet codec and transaction planner for the six Pro Max connector layouts, sonic_lighting.py decodes Campus Aggregation/Core MCU snapshots, and tools/device-helpers/pro-max-io.c holds a fixed-device I2C transfer core whose test build excludes device access. None of them performs I/O from EE or enables output on those models. HARDWARE-QUALIFICATION.md records what each establishes and what remains. --- CHANGELOG.md | 4 + docs/DEVELOPMENT.md | 1 + docs/HARDWARE-QUALIFICATION.md | 32 +- src/etherlighting_evolved/device_playback.py | 134 ++---- src/etherlighting_evolved/pro_max.py | 278 +++++++++++ src/etherlighting_evolved/resident/frames.awk | 28 +- src/etherlighting_evolved/resident/player.sh | 24 +- src/etherlighting_evolved/resident_scene.py | 121 +++++ src/etherlighting_evolved/sonic_lighting.py | 71 +++ tests/test_pro_max.py | 444 ++++++++++++++++++ tests/test_pro_max_io.py | 338 +++++++++++++ tests/test_resident_scene.py | 262 +++++++++++ tests/test_sonic_lighting.py | 99 ++++ tools/device-helpers/pro-max-io.c | 297 ++++++++++++ 14 files changed, 2016 insertions(+), 117 deletions(-) create mode 100644 src/etherlighting_evolved/pro_max.py create mode 100644 src/etherlighting_evolved/resident_scene.py create mode 100644 src/etherlighting_evolved/sonic_lighting.py create mode 100644 tests/test_pro_max.py create mode 100644 tests/test_pro_max_io.py create mode 100644 tests/test_resident_scene.py create mode 100644 tests/test_sonic_lighting.py create mode 100644 tools/device-helpers/pro-max-io.c diff --git a/CHANGELOG.md b/CHANGELOG.md index 56501d0..3819094 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased + +- The lighting player that a switch runs from its memory takes its port layout from the switch's hardware profile, and EE now checks both the player and its renderer before reusing a running player. The first connection after the update replaces a running player once and keeps its saved scene. Switch playback is still available only on the USW-Pro-XG-8-PoE. + ## 0.6.0 This release removes API routes, saves schedules and port names in a format that 0.5.1 cannot read, keeps the fan mode for each switch in a new place, and moves the build to Python 3.14, Node.js 24.18.0 and .NET 10. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index b613c7f..645314a 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -11,6 +11,7 @@ Follow [WORKFLOW.md](WORKFLOW.md) for branches, pull request checks and releases - The `dev` Python extras for tests and linting. - The .NET 10 SDK (`global.json`) and the packages pinned by the desktop projects’ lock files. EE Quality restores the check project with `dotnet restore desktop/EtherlightingEvolved.Native.Check/EtherlightingEvolved.Native.Check.csproj --locked-mode`. - The packaging dependencies in `requirements-ci.txt`, including PyInstaller and Pillow, and Inno Setup 6.7 for Windows Setup. +- A C11 compiler for the Pro Max device helper tests: the MSVC x64 tools on Windows, or Clang or GCC on macOS and Linux. The tests find the installed compiler and build the helper with device access left out. EE does not need a compiler to run. Build scripts check for tools and dependencies; they do not install them. Create the Python environment once from the repository root: diff --git a/docs/HARDWARE-QUALIFICATION.md b/docs/HARDWARE-QUALIFICATION.md index 75a85b2..877d626 100644 --- a/docs/HARDWARE-QUALIFICATION.md +++ b/docs/HARDWARE-QUALIFICATION.md @@ -8,7 +8,7 @@ The November 14, 2026 inventory covers all 25 Etherlighting models in the curren Ubiquiti's model-specific release API was checked for all 25 platforms on November 14 at 23:51:59–23:52:00 UTC. Nine platforms point to two updated 7.6.11+17272 images. The other sixteen point to images already examined in the November 1 review. Release-channel metadata describes the available artifact, not an update observed on every controller. -All six image hashes were compared with the official release metadata. The two newly downloaded images matched their official lengths and SHA-256 hashes. Microsoft Defender found no threats in those archives or their extracted files. Firmware was inspected as data, without running its programs or connecting to a switch. +All six image hashes were compared with the official release metadata. The two newly downloaded images matched their official lengths and SHA-256 hashes. Microsoft Defender found no threats in those archives or their extracted files. Firmware was inspected as data without running its programs. Separate read-only storage metadata from the previously accepted Pro XG 8 establishes its RAM-backed persistent directory and 1 MiB configuration partition; it does not verify a saved EE archive or reboot recovery. ## Model matrix @@ -72,10 +72,15 @@ The vendor host mapping is now traced across all 192 connector rows in the six m The connector map is source-qualified for these exact model/firmware profiles. Each connector has a unique output ID, and those IDs are disjoint from the extra MCU records on every model. The status-bit map is a separate index space; its different ordering does not establish a routing defect. Extra MCU records must stay outside connector command masks. Physical output acceptance remains unobserved. The next adapter also needs bounded packet encoding and independent completion checks: acknowledgment occurs before execution, so successful submission is not confirmation that a queued command completed. -The MCU has a bounded readback lead: selecting register 0x10 snapshots current RGBW and retains the selected-record echo. A checked echo plus eight color bytes can corroborate the selected record's observed MCU values. The host transfer, response lengths and interleaving behavior still need qualification. This is not a completed adapter or confirmation of animation behavior, unique command execution or physical light output. +The MCU has a bounded readback lead: selecting register 0x10 snapshots current RGBW and retains the selected-record echo. A checked echo plus eight color bytes reports a captured MCU register snapshot. The same register window can be overwritten with staged channel values without changing the selector; an echo match alone does not establish freshness or execution. The host transfer, response lengths and interleaving behavior still need qualification. This is not a completed adapter or confirmation of animation behavior, unique command execution or physical light output. Ownership also requires proof. Mode 3 suppresses ordinary link/PoE writers, but locate and controller device-type changes have separate paths. A controller change can retain the same mode. Restoring a cached mode would risk overwriting newer controller intent. No output adapter should use broad configuration locks, stop vendor services or infer exclusive ownership from this mode alone. + +`pro_max.py` contains the bounded packet codec and a transport-independent transaction planner for all six connector layouts. It distinguishes transfer acceptance from a matching register snapshot, checks exact lengths, bounds read retries and never retransmits an uncertain write. It performs no I/O and grants no output ownership. The fixed-device helper in `tools/device-helpers/pro-max-io.c` implements the reviewed `I2C_RDWR` framing with exact completed-message counts. Its parser allows only the reviewed packets and short register reads, fixed bus/address and model-specific connector bounds. Partial or failed writes are never replayed. Compiler-backed tests inject syscall results; their build excludes device access entirely. The separate Linux wrapper requires an explicit build macro and is not packaged or invoked by EE. Target compilation, actual firmware admission, concurrent-writer exclusion, intent observation and restoration remain integration gates. + +The controller's global configuration lock is not an output lease. Some vendor handlers abandon a controller action when that lock is held. EE must not hold it to prevent lighting changes. + ## Campus aggregation and core adapter work The SONiC daemon and MCU use a separate protocol. The current MCU's Aggregation table contains 54 physical output records plus two sentinel records; Core has 32 physical records plus two sentinels. Those internal records do not expand the public port map. @@ -86,13 +91,34 @@ MCU selector register 0x10 can snapshot the selected port's active channels; reg Mode 3 suppresses normal link events, but direct color writes bypass it. Controller-policy reconciliation and completion-aware cleanup remain required before output admission. + +`sonic_lighting.py` binds the captured MCU hash and board ID to the canonical 54- or 32-port layout. Its decoder validates the nine-byte selector/RGBW snapshot and a later selector echo. The result is a register observation; matching echoes do not exclude an intervening change or prove ownership. No transport or output admission is added by this module. + +## Resident scenes and startup + +The numeric scene compiler and AWK renderer now use the canonical connector count for all 25 layouts, including optical-only models and the last connector of larger switches. Stacking and internal records stay outside the scene. Offline tests exercise actual renderer output, Activity Glow input changes, atomic scene replacement and rejection of incomplete layouts. The common ubus player can be built for each of the 17 qualified command layouts. Runtime admission remains separate: the new compiler and generator do not establish per-model sensor compatibility, command timing or reboot behavior. + +Reconnect now checks both the player and renderer hashes before reusing a resident process. A changed renderer triggers the existing drained replacement path. Earlier ten-port scenes keep their format and normal editor workflow. + +| Firmware families | Models | Persistent storage evidence | Startup gate | +| --- | ---: | --- | --- | +| USPM16, USWED72 | 10 | Vendor configuration archive restores `/etc/persistent` | Vendor cron is a candidate; archive writer and configuration transaction qualification remain open | +| USWED42, USWF001, USWF004 | 13 | Configuration archive and existing eMMC mount at `/mnt/data` | Saved cron can start a launcher after isolated reboot; concurrent configuration edits and later UniFi ownership remain unresolved | +| USWF066 | 2 | Persistent disk under `/host`; writable root overlay is RAM | Traced startup producer emits fixed vendor commands; no scoped EE startup extension established | + +The ARM boot script can format an entire eMMC device when expected partitions are missing. EE must never call that initializer to obtain storage. A future persistent package needs a verified existing mount, an EE-owned directory, atomic settings replacement, bounded writes and removal through Handoff. Copying a service into a RAM overlay alone does not survive reboot. Saved cron plus an archived launcher provides a candidate isolated-reboot path on the non-SONiC firmware. The inspected BusyBox cron requires a five-field schedule; a conventional `@reboot` job is not accepted. An eventual launcher must be idempotent, check complete saved generations and current device identity, honor Handoff, and keep counters and periodic writes in RAM. + +The fully decoded ARM archive uses two 512 KiB slots with 24-byte headers. Its 16 MiB input guard is not persistent capacity. Storage budgeting must cover the entire compressed configuration and archive, not just EE files. A future installer must preserve existing cron sections and jobs: duplicate user sections overwrite the same generated crontab. Controller provisioning replaces the configuration rather than merging these keys. A compare-before-rename check is not a proven transaction boundary against that writer. + +On Campus Aggregation/Core, the real LINUXCFG START consumer receives fixed VRRP commands from its normal producer. The ordinary full CONFIG_DB save path excludes these two board IDs. The active startup plugin list excludes the ARM cron path, and the root overlay is RAM. Persisting the entire network database would broaden this lighting change into network configuration management and is not used here. No persistent startup registration is shipped or enabled by this work. + ## Launch acceptance Every enabled model/firmware pair must pass identity, schema, exact hash-pair, connector mapping, pacing, stale-connection revocation, interrupted apply, reconnect and cleanup checks. Malformed or cross-family evidence must leave the writer unbound. A firmware update must retain saved settings while requiring fresh qualification on its new connection. The ordinary Lighting, Effects, Automation and Profiles workspace must remain usable. No playback gate or separate effect editor is part of this work. Browser and native topology fixtures cover the model layouts; physical labeling and visible behavior need device acceptance. -Switch-resident playback is currently specific to Pro XG 8 PoE. It uses a RAM-resident player. Other models need their own telemetry, port-map and resource-budget validation before that path is enabled. Isolated reboot recovery and direct UniFi-edit precedence remain open, including on Pro XG 8 PoE. Firmware analysis alone cannot establish those behaviors. +Switch-resident playback is currently specific to Pro XG 8 PoE. It uses a RAM-resident player. Other models need their own telemetry and resource-budget validation before that path is enabled. Isolated reboot recovery and direct UniFi-edit precedence remain open, including on Pro XG 8 PoE. Firmware analysis alone cannot establish those behaviors. Before enabling a new family, a controlled device acceptance run must verify every physical port at bounded brightness, an unchanged nonselected port, link/PoE stability, sustained CPU/memory and command latency, loss of the desktop/SSH connection, explicit handoff and recovery. Reboot testing requires a supported persistent startup mechanism and separate authorization for the network interruption. Public release notes must describe only the model/firmware behavior actually accepted. diff --git a/src/etherlighting_evolved/device_playback.py b/src/etherlighting_evolved/device_playback.py index 6b90732..c4fe17c 100644 --- a/src/etherlighting_evolved/device_playback.py +++ b/src/etherlighting_evolved/device_playback.py @@ -11,11 +11,8 @@ import time from pathlib import Path -from .color import BLACK -from .effects import create_effect -from .effects.base import RenderContext -from .effects.library import DAYLIGHT_PALETTES -from .hardware import PRO_XG8 +from .hardware import PRO_XG8, HardwareProfile +from .resident_scene import compile_scene_data from .transport import TransportError LOCATION = "/tmp/ee-lighting-playback-v1" @@ -38,93 +35,7 @@ def supported(switch): def compile_scene(engine) -> tuple[str, str]: if not supported(engine.switch) or engine.mode != "running": raise ValueError("Start lighting on the verified Pro XG 8 PoE before saving to the switch.") - settings = {p: [0, p, 0, 0, 1, engine.brightness, engine.gamma] for p in range(1, 11)} - inputs = {} - groups = [] - for group, zone in enumerate(engine.zones, 1): - fx = create_effect(zone.effect.id, len(zone.ports), zone.effect.params_json()) - groups.append((zone.ports, fx, RenderContext(len(zone.ports)))) - for i, p in enumerate(zone.ports): - if fx.id == "activity_glow": - settings[p][:5] = [group, p, fx.p["minimum_mbps"], int(fx.p["include_uplinks"]), fx.p["speed"]] - elif fx.id == "traffic": - settings[p][3:5] = [int(fx.p["include_uplinks"]), fx.p["smoothing"]] - inputs[p] = [1, int(fx.p["custom_uplink"])] - elif fx.id == "traffic_trails": - settings[p][2:5] = [fx.p["max_mbps"], int(fx.p["include_uplinks"]), fx.p["speed"]] - inputs[p] = [2, i, len(zone.ports), fx.p["width"]] - elif fx.id == "poe_usage": - settings[p][4] = fx.p["speed"] - inputs[p] = [3] - elif fx.id == "daylight": - stops = DAYLIGHT_PALETTES[fx.p["palette"]] - inputs[p] = [4, fx.p["night_brightness"], len(stops)] - for hour, color in stops: - inputs[p].extend([hour, *color.precise_channels]) - elif fx.category in {"time", "data"}: - raise ValueError(f"{fx.name} has no offline sensor mapping.") - if p in engine.sfp: - settings[p][5] *= engine.sfp[p].brightness / 100 - grouped = {p for ports, _, _ in groups for p in ports} - independent = {} - for p in engine.sfp.keys() - grouped: - if engine.sfp_sync.mode == "ethernet": - source = engine.sfp_sync.source_port - settings[p][1] = source - settings[p][5] = settings[source][5] - else: - light = engine.sfp[min(engine.sfp) if engine.sfp_sync.mode == "together" else p] - if light.mode == "unmanaged": - settings[p][1] = 0 - else: - independent[p] = light - settings[p][5] *= light.brightness / 100 - for p, override in engine.overrides.items(): - inputs.pop(p, None) - settings[p][:2] = [0, p] - if override.brightness is not None: - settings[p][5] = override.brightness - for p in engine.sfp.keys() - grouped: - if engine.sfp_sync.mode == "ethernet": - settings[p][5] = settings[engine.sfp_sync.source_port][5] - rows = [] - for index in range(120): - t = index / 4 - colors = {p: (BLACK, BLACK) for p in settings} - extra = {p: (BLACK, BLACK) for p in settings} - for ports, fx, ctx in groups: - if fx.id == "activity_glow": - palette = fx.colors(t) - for p in ports: - colors[p] = palette["idle_color"], palette["active_color"] - elif fx.id in {"traffic", "traffic_trails", "poe_usage"}: - palette = fx.colors(t) - for p in ports: - if fx.id == "poe_usage": - colors[p] = palette["no_power_color"], palette["low_color"] - extra[p] = palette["high_color"], BLACK - else: - colors[p] = palette["idle_color"], palette["busy_color"] - extra[p] = palette["offline_color"], palette.get("uplink_color", BLACK) - elif fx.id != "daylight": - for p, color in zip(ports, fx.render(t, ctx), strict=True): - colors[p] = color, color - for p, light in independent.items(): - color = light.render(t, p) - colors[p] = color, color - for p, override in engine.overrides.items(): - colors[p] = override.color, override.color - pairs = list(colors.values()) - if any(fields[0] in {1, 2, 3} for fields in inputs.values()): - pairs.extend(extra.values()) - channels = (c for pair in pairs for col in pair for c in col.precise_channels) - rows.append(" ".join(format(c, ".7g") for c in channels)) - if all(row == rows[0] for row in rows): - rows = rows[:1] - limit = max(1, min(10, int(engine.max_commands))) - config = "".join(" ".join(str(n) for n in [p, *values, limit, *inputs.get(p, [])]) + "\n" - for p, values in settings.items()) - return config, "\n".join(rows) + "\n" + return compile_scene_data(engine, engine.switch.hardware_profile) class PlaybackRecord: @@ -180,13 +91,37 @@ def _owned(owner): return f'd={LOCATION}; {_CHECK_DIRECTORY} && cd "$d" && [ "$(cat owner)" = {owner} ] || exit 1\n' -async def stage(transport, owner, config, palette): +def player_script(profile: HardwareProfile = PRO_XG8) -> str: + """Bind the common ubus player to the canonical profile's connector map.""" + if not isinstance(profile, HardwareProfile): + raise ValueError("A canonical hardware profile is required") + profile.require_output() + if profile.protocol != "ubus-mcu": + raise ValueError("This player requires the qualified ubus lighting protocol") + ports = profile.copper_ports + profile.optical_ports + if ports != tuple(range(1, len(ports) + 1)): + raise ValueError("The player needs a contiguous connector layout") + lines = [f"port_count={len(ports)}", "optical_ports='" + " ".join(map(str, profile.optical_ports)) + "'", + "optical_mask() {", ' case "$1" in'] + for port in profile.optical_ports: + mask = int(profile.sfp_mask(port), 16) + lines.append(f" {port}) printf '%s' '{mask >> 32:x} {mask & 0xffffffff:x}';;") + lines.extend([" *) return 1;;", " esac", "}"]) + template = (_RUNTIME / "player.sh").read_text("ascii") + before, body = template.split("# BEGIN PORT LAYOUT\n") + _, after = body.split("# END PORT LAYOUT\n") + return before + "# BEGIN PORT LAYOUT\n" + "\n".join(lines) + "\n# END PORT LAYOUT\n" + after + + +async def stage(transport, owner, config, palette, *, profile=PRO_XG8): + script = player_script(profile) if not _OWNER.fullmatch(owner): raise ValueError("Invalid playback owner") init = f'umask 077\n{_PREFLIGHT} && mkdir -m 700 {LOCATION} && cd {LOCATION} && printf "%s" {owner} > owner' if await _run(transport, init + " && echo reserved") != "reserved": raise TransportError("The switch could not reserve its RAM playback directory.") - files = {name: (_RUNTIME / name).read_text("ascii") for name in _FILES[:2]} + files = {"frames.awk": (_RUNTIME / "frames.awk").read_text("ascii"), + "player.sh": script} files.update(config=config, palette=palette) await _upload(transport, owner, files) @@ -276,14 +211,17 @@ async def release(self): await _run(self.transport, command) -async def upgrade_player(transport, owner): +async def upgrade_player(transport, owner, *, profile=PRO_XG8): """Upgrade an earlier RAM player in its own directory, keeping its committed scene.""" - script = (_RUNTIME / "player.sh").read_text("ascii") + script = player_script(profile) digest = hashlib.sha256(script.encode("ascii")).hexdigest() command = _owned(owner) + 'sha256sum player.sh | cut -d" " -f1' - if await _run(transport, command) == digest and await status(transport, owner) == "playing": - return renderer = (_RUNTIME / "frames.awk").read_text("ascii") + renderer_digest = hashlib.sha256(renderer.encode("ascii")).hexdigest() + if (await _run(transport, command) == digest + and await _run(transport, _owned(owner) + 'sha256sum frames.awk | cut -d" " -f1') == renderer_digest + and await status(transport, owner) == "playing"): + return await _upload(transport, owner, {"player.next": script, "frames.edit": renderer}) if not await drain(transport, owner): raise TransportError("The saved lighting process changed.") diff --git a/src/etherlighting_evolved/pro_max.py b/src/etherlighting_evolved/pro_max.py new file mode 100644 index 0000000..d4af50e --- /dev/null +++ b/src/etherlighting_evolved/pro_max.py @@ -0,0 +1,278 @@ +"""Pro Max packet encoding and bounded, transport-independent register observation. + +These objects describe transfers; they do not open a device or grant output qualification. +Controller observations must come from the integration's qualified ownership mechanism. +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass, field +from enum import Enum +from types import MappingProxyType + + +@dataclass(frozen=True, slots=True) +class ProMaxLayout: + key: str + sysid: str + board_id: int + copper_count: int + optical_count: int + + @property + def port_count(self) -> int: + return self.copper_count + self.optical_count + + def record(self, port: int) -> int: + if PRO_MAX_LAYOUTS.get(self.key) is not self: + raise ValueError("Unrecognized Pro Max layout") + if type(port) is not int or not 1 <= port <= self.port_count: + raise ValueError("Port is outside the Pro Max connector layout") + return port - 1 + + +PRO_MAX_LAYOUTS = MappingProxyType({layout.key: layout for layout in ( + ProMaxLayout("USPM16", "ed71", 3, 16, 2), + ProMaxLayout("USPM16P", "ed70", 3, 16, 2), + ProMaxLayout("USPM24", "ed5c", 2, 24, 2), + ProMaxLayout("USPM24P", "ed5b", 2, 24, 2), + ProMaxLayout("USPM48", "ed5e", 1, 48, 4), + ProMaxLayout("USPM48P", "ed5d", 1, 48, 4), +)}) + + +def resolve_layout(key: str, sysid: str, board_id: int) -> ProMaxLayout: + layout = PRO_MAX_LAYOUTS.get(key) if isinstance(key, str) else None + if (layout is None or sysid != layout.sysid or type(board_id) is not int + or board_id != layout.board_id): + raise ValueError("Pro Max board identity does not match its connector layout") + return layout + + +def crc8(payload: bytes) -> int: + """CRC-8/SMBUS over the payload, excluding the command byte.""" + if type(payload) is not bytes: + raise ValueError("A packet payload must be immutable bytes") + crc = 0 + for byte in payload: + crc ^= byte + for _ in range(8): + crc = ((crc << 1) ^ (0x07 if crc & 0x80 else 0)) & 0xff + return crc + + +def _rgbw(value: tuple[int, int, int, int]) -> bytes: + if (type(value) is not tuple or len(value) != 4 + or any(type(component) is not int or not 0 <= component <= 65535 for component in value)): + raise ValueError("RGBW must contain four unsigned 16-bit components") + return b"".join(component.to_bytes(2, "big") for component in value) + + +def steady_packet(layout: ProMaxLayout, port: int, rgbw: tuple[int, int, int, int], *, apply: bool = True) -> bytes: + if type(apply) is not bool: + raise ValueError("Apply must be a boolean") + payload = bytes((layout.record(port), 8)) + _rgbw(rgbw) + bytes((int(apply),)) + return b"\x20" + payload + bytes((crc8(payload),)) + + +def _mask(layout: ProMaxLayout, ports: tuple[int, ...]) -> bytes: + if type(ports) is not tuple or not ports or len(ports) > layout.port_count: + raise ValueError("Choose a nonempty tuple of Pro Max connectors") + mask = 0 + for port in ports: + bit = 1 << layout.record(port) + if mask & bit: + raise ValueError("A connector appears more than once") + mask |= bit + return mask.to_bytes(7, "big") + + +def scoped_commit_packet(layout: ProMaxLayout, ports: tuple[int, ...]) -> bytes: + payload = bytes(7) + _mask(layout, ports) + return b"\x25" + payload + bytes((crc8(payload),)) + + +def fade_packet(layout: ProMaxLayout, ports: tuple[int, ...], *, seconds: int, mode: int = 0) -> bytes: + """Enroll already-staged targets from steady state in one scoped native fade.""" + if type(seconds) is not int or seconds not in (1, 2, 3): + raise ValueError("Native fade duration must be 1, 2, or 3 seconds") + if type(mode) is not int or mode not in (0, 1): + raise ValueError("Scoped native mode must be 0 or 1") + payload = bytes((2 + mode, 0x10 | (8 + seconds))) + bytes(5) + _mask(layout, ports) + return b"\x00" + payload + bytes((crc8(payload),)) + + +def decode_snapshot(layout: ProMaxLayout, port: int, reply: bytes) -> tuple[int, int, int, int]: + record = layout.record(port) + if type(reply) is not bytes or len(reply) != 9 or reply[0] != record: + raise ValueError("Snapshot registers do not identify the requested connector") + return tuple(int.from_bytes(reply[index:index + 2], "big") for index in (1, 3, 5, 7)) + + +class ProMaxState(Enum): + READY = "ready" + VERIFYING = "verifying" + SNAPSHOT_MATCHED = "snapshot_matched" + UNCERTAIN = "uncertain" + REVOKED = "revoked" + + +@dataclass(frozen=True, slots=True) +class ControllerObservation: + """An integration's controller revision, sampled after the specified transfer.""" + + revision: bytes = field(repr=False) + after_transfer: int + sampled_at: float + + +@dataclass(frozen=True, slots=True) +class ProMaxTransfer: + sequence: int + purpose: str + request: bytes + read_length: int = 0 + + +def _time(value: float) -> bool: + return type(value) in (int, float) and math.isfinite(value) and value >= 0 + + +class ProMaxTransaction: + """Plan one steady write and compare snapshot registers without retransmitting it. + + A driver must verify transfer byte counts and obtain fresh controller observations. + This planner performs no I/O and cannot admit hardware or acquire controller ownership. + SNAPSHOT_MATCHED means captured registers match the target. It does not prove + command execution, steady behavior, controller ownership, or physical LED output. + Other writers can change cached RGBW bytes without changing the selector echo. + """ + + def __init__(self, layout: ProMaxLayout, port: int, rgbw: tuple[int, int, int, int], *, + observation: ControllerObservation, now: float, timeout: float = 0.5, + snapshot_attempts: int = 3) -> None: + self.packet = steady_packet(layout, port, rgbw) + if not _time(now) or not _time(timeout) or not 0 < timeout <= 5: + raise ValueError("A transaction needs a finite deadline of at most five seconds") + if type(snapshot_attempts) is not int or not 1 <= snapshot_attempts <= 10: + raise ValueError("Snapshot attempts must be between one and ten") + if (not isinstance(observation, ControllerObservation) + or type(observation.revision) is not bytes or not 1 <= len(observation.revision) <= 64 + or type(observation.after_transfer) is not int or observation.after_transfer != 0 + or not _time(observation.sampled_at) or observation.sampled_at != now): + raise ValueError("A transaction needs a current initial controller observation") + self.layout, self.port, self.target = layout, port, rgbw + self.state = ProMaxState.READY + self.reason = "" + self._revision = observation.revision + self._last_time = now + self._deadline = now + timeout + self._earliest = now + self._last_completed_at = now + self._issued_at = now + self._completed = 0 + self._pending: ProMaxTransfer | None = None + self._purpose = "write" + self._remaining = snapshot_attempts + + @property + def next_at(self) -> float: + return self._earliest + + @property + def terminal(self) -> bool: + return self.state in (ProMaxState.SNAPSHOT_MATCHED, ProMaxState.UNCERTAIN, ProMaxState.REVOKED) + + def _stop(self, state: ProMaxState, reason: str) -> None: + self.state, self.reason, self._pending = state, reason, None + + def _check(self, observation: ControllerObservation, now: float, after_transfer: int) -> bool: + if self.terminal: + return False + if not _time(now) or now < self._last_time: + self._stop(ProMaxState.UNCERTAIN, "invalid_clock") + return False + self._last_time = now + if now >= self._deadline: + self._stop(ProMaxState.UNCERTAIN, "deadline_exceeded") + return False + if (not isinstance(observation, ControllerObservation) + or type(observation.revision) is not bytes or observation.revision != self._revision): + self._stop(ProMaxState.REVOKED, "controller_changed") + return False + if (type(observation.after_transfer) is not int or observation.after_transfer != after_transfer + or not _time(observation.sampled_at) + or not self._last_completed_at <= observation.sampled_at <= now + or now - observation.sampled_at > 0.1): + self._stop(ProMaxState.UNCERTAIN, "stale_controller_observation") + return False + return True + + def next_transfer(self, observation: ControllerObservation, *, now: float) -> ProMaxTransfer | None: + if not self._check(observation, now, self._completed): + return None + if self._pending is not None: + raise RuntimeError("Complete the pending transfer before requesting another") + if now < self._earliest: + return None + record = self.layout.record(self.port) + request, length = { + "write": (self.packet, 0), + "acceptance": (b"\x52", 2), + "select": (bytes((0x10, record)), 0), + "snapshot": (b"\x10", 9), + }[self._purpose] + self._pending = ProMaxTransfer(self._completed + 1, self._purpose, request, length) + self._issued_at = now + self.state = ProMaxState.VERIFYING + return self._pending + + def complete(self, transfer: ProMaxTransfer, *, written: int, reply: bytes, + observation: ControllerObservation, now: float) -> None: + if self.terminal: + return + if not isinstance(transfer, ProMaxTransfer) or transfer is not self._pending: + self._stop(ProMaxState.UNCERTAIN, "unexpected_transfer") + return + if not self._check(observation, now, transfer.sequence): + return + if observation.sampled_at < self._issued_at: + self._stop(ProMaxState.UNCERTAIN, "stale_controller_observation") + return + if (type(written) is not int or written != len(transfer.request) + or type(reply) is not bytes or len(reply) != transfer.read_length): + self._stop(ProMaxState.UNCERTAIN, "incomplete_transfer") + return + self._pending = None + self._completed = transfer.sequence + self._last_completed_at = observation.sampled_at + if transfer.purpose == "write": + self._purpose, self._earliest = "acceptance", now + 0.001 + elif transfer.purpose == "acceptance": + if reply != bytes((self.layout.record(self.port), 0)): + self._stop(ProMaxState.UNCERTAIN, "acceptance_mismatch") + return + self._purpose = "select" + elif transfer.purpose == "select": + self._purpose = "snapshot" + else: + self._remaining -= 1 + try: + matched = decode_snapshot(self.layout, self.port, reply) == self.target + except ValueError: + matched = False + if matched: + self._stop(ProMaxState.SNAPSHOT_MATCHED, "") + elif not self._remaining: + self._stop(ProMaxState.UNCERTAIN, "snapshot_not_matched") + else: + self._purpose, self._earliest = "select", now + 0.02 + + def fail(self) -> None: + if not self.terminal: + self._stop(ProMaxState.UNCERTAIN, "transfer_failed") + + def revoke(self) -> None: + if not self.terminal: + self._stop(ProMaxState.REVOKED, "controller_changed") diff --git a/src/etherlighting_evolved/resident/frames.awk b/src/etherlighting_evolved/resident/frames.awk index 2bc6253..112f1d4 100644 --- a/src/etherlighting_evolved/resident/frames.awk +++ b/src/etherlighting_evolved/resident/frames.awk @@ -18,29 +18,38 @@ function configuration() { # Open the replacement once per frame. A rename during a read leaves this frame # on the old complete scene. Original RAM players pass the same four filenames. BEGIN { + # Earlier players omit this argument and retain their ten-port scene format. + if (port_count == "") port_count=10 + if (port_count !~ /^[1-9][0-9]*$/ || port_count>54) {bad=1; exit 2} + channels=6*port_count scene="scene.active" if ((getline < scene)>0) { edited=1 if (NF!=1 || ($1!=1 && $1!=120)) {bad=1; exit 2} count=$1 - for (row=1;row<=10;row++) { + for (row=1;row<=port_count;row++) { if ((getline < scene)!=1 || NF<9 || $1!=row) {bad=1; exit 2} configuration() if ($2>0 || $10==1 || $10==2) reactive=1 } wanted=int(stamp*4)%count+1 - for (row=1;row<=wanted;row++) if ((getline < scene)!=1 || (NF!=60 && NF!=120)) {bad=1; exit 2} + for (row=1;row<=wanted;row++) if ((getline < scene)!=1 || (NF!=channels && NF!=2*channels)) {bad=1; exit 2} for (i=1;i<=NF;i++) color[i]=$i } close(scene) } FILENAME == "config" { if ($2>0 || $10==1 || $10==2) originalReactive=1 + if (FNR>port_count || NF<9 || $1!=FNR) {bad=1; next} + originalRows=FNR if (!edited) configuration() next } FILENAME == "palette" { - if (!edited && FNR == frame+1) for (i=1; i<=NF; i++) color[i]=$i + if (!edited && FNR == frame+1) { + if (NF!=channels && NF!=2*channels) {bad=1; next} + for (i=1; i<=NF; i++) color[i]=$i + } next } FILENAME == "previous" { @@ -52,7 +61,7 @@ function traffic() { for (i=1; i10) break + if (p>port_count) break if (seen[p]++) { bad=1; break } online[p]=substr($(i+1),3,1)=="U"; trunk[p]=(i>1 && $(i-1)=="U") eligible[p]=online[p] && (uplink[p] || !trunk[p]) @@ -86,7 +95,7 @@ END { while ((poll | getline)>0) traffic() if (close(poll)!=0) bad=1 } - if (bad || !(1 in color) || !(60 in color)) exit 2 + if (bad || originalRows!=port_count || !(1 in color) || !(channels in color)) exit 2 if (needsClock) { clock="date '+%H %M %S'" if ((clock | getline)!=1 || NF!=3) exit 2 @@ -107,7 +116,7 @@ END { } dt=oldtime ? stamp-oldtime : 0 if (dt<0) exit 2 - for (p=1; p<=10; p++) { + for (p=1; p<=port_count; p++) { if ((group[p]>0 || mode[p]==1 || mode[p]==2) && !seen[p]) exit 2 if (dt>0 && valid[p] && oldvalid[p] && eligible[p] && bytes[p]>=oldbytes[p]) rate[p]=(bytes[p]-oldbytes[p])*8/dt @@ -134,18 +143,19 @@ END { target[p]=clamp(log(1+watts[p])/log(61)); powerTarget[p]=watts[p]>0 } } - for (p=1; p<=10; p++) { + for (p=1; p<=port_count; p++) { g=group[p] printf "%d %.6f %.0f %d %.12f %.12f %.12f %d\n",p,stamp,bytes[p],valid[p],level[p],(g>0 ? rate[p]/scale[g] : target[p]),powered[p],powerTarget[p] > "next" s=source[p] + if (s !~ /^[0-9]+$/ || s>port_count) exit 2 if (s==0) continue printf "%d",p for (c=1; c<=3; c++) { lo=color[6*(s-1)+c]; hi=color[6*(s-1)+3+c] value=lo+(hi-lo)*level[s] - aux=color[60+6*(s-1)+c] + aux=color[channels+6*(s-1)+c] if (mode[s]==1 && !online[s]) value=aux - else if (mode[s]==1 && trunk[s] && custom[s]) value=color[60+6*(s-1)+3+c] + else if (mode[s]==1 && trunk[s] && custom[s]) value=color[channels+6*(s-1)+3+c] else if (mode[s]==2) value=online[s] ? value*trail(s) : aux else if (mode[s]==3) value=lo*(1-powered[s])+hi*(powered[s]-level[s])+aux*level[s] else if (mode[s]==4) value=daylightChannel(s,c) diff --git a/src/etherlighting_evolved/resident/player.sh b/src/etherlighting_evolved/resident/player.sh index f34b85a..45f87c9 100644 --- a/src/etherlighting_evolved/resident/player.sh +++ b/src/etherlighting_evolved/resident/player.sh @@ -1,6 +1,17 @@ #!/bin/sh # Runs in the private scene directory on the switch RAM filesystem. umask 077 +# BEGIN PORT LAYOUT +port_count=10 +optical_ports='9 10' +optical_mask() { + case "$1" in + 9) printf '%s' '0 100';; + 10) printf '%s' '0 200';; + *) return 1;; + esac +} +# END PORT LAYOUT mark() { printf '%s\n' "$1" > status.new && mv -f status.new status; } # BusyBox on this firmware supports whole-second sleeps. Count every LED call, # including optical acquisition, and reduce the budget when CPU headroom is low. @@ -18,13 +29,13 @@ set_led() { } pwm() { set_led "{\"port_pwm\":\"$1 $2 $3 $4 0\"}"; } optical() { - case "$1" in 9) mask=100;; 10) mask=200;; *) return 1;; esac - set_led "{\"mcu_mode\":\"soc_port_map steady 0 $mask\"}" + mask=$(optical_mask "$1") || return 1 + set_led "{\"mcu_mode\":\"soc_port_map steady $mask\"}" } prepare() { set_led '{"behavior":"steady"}' || return 1 - for p in 9 10; do - if { if [ -f scene.active ]; then sed -n '2,11p' scene.active; else cat config; fi; } | + for p in $optical_ports; do + if { if [ -f scene.active ]; then awk -v n="$port_count" 'NR>1 && NR<=n+1' scene.active; else cat config; fi; } | awk -v p="$p" '$1==p && $3>0 {found=1} END{exit !found}'; then [ ! -e stop ] && pwm "$p" 0 0 0 && optical "$p" || return 1 fi @@ -77,7 +88,7 @@ while [ ! -e stop ]; do read -r stamp unused < /proc/uptime || break frame=$(awk -v now="$stamp" -v start="$start" -v count="$count" 'BEGIN{print int((now-start)*4)%count}') if [ "$reactive" = 1 ] && ! timeout -t 3 swctrl port show > ports; then mark retrying; sleep 3; continue; fi - if ! awk -v stamp="$stamp" -v frame="$frame" -f frames.awk config palette previous ports > output; then + if ! awk -v port_count="$port_count" -v stamp="$stamp" -v frame="$frame" -f frames.awk config palette previous ports > output; then mark retrying; sleep 3; continue fi mv -f next previous || break @@ -85,8 +96,7 @@ while [ ! -e stop ]; do while read -r port red green blue; do [ ! -e stop ] || break if ! pwm "$port" "$red" "$green" "$blue"; then ok=0; break; fi - # Each write waits for the MCU acknowledgement. The frame delay bounds - # traffic to ten per-port updates per second on this ten-port profile. + # The command budget includes every selected physical connector. done < output [ ! -e stop ] || break if [ "$ok" = 1 ]; then mark playing; sleep 1; else mark retrying; initialized=0; sleep 3; fi diff --git a/src/etherlighting_evolved/resident_scene.py b/src/etherlighting_evolved/resident_scene.py new file mode 100644 index 0000000..8cb3183 --- /dev/null +++ b/src/etherlighting_evolved/resident_scene.py @@ -0,0 +1,121 @@ +"""Numeric scene compilation shared by the desktop and resident renderer.""" +from __future__ import annotations + +from .color import BLACK +from .effects import create_effect +from .effects.base import RenderContext +from .effects.library import DAYLIGHT_PALETTES +from .hardware import PROFILES, HardwareProfile + + +def compile_scene_data(engine, profile: HardwareProfile) -> tuple[str, str]: + """Compile a canonical connector layout into numeric data, without device I/O. + + Compilation does not qualify a transport, sensor source, or startup mechanism. + The transfer owner checks those capabilities separately. + """ + if not isinstance(profile, HardwareProfile) or PROFILES.get(profile.key) is not profile: + raise ValueError("A canonical hardware profile is required") + ports = profile.copper_ports + profile.optical_ports + if ports != tuple(range(1, len(ports) + 1)) or not 1 <= len(ports) <= 54: + raise ValueError("The scene needs a contiguous connector layout") + chosen = [port for zone in engine.zones for port in zone.ports] + if (any(type(port) is not int or port not in ports for port in chosen) + or len(chosen) != len(set(chosen)) + or any(type(port) is not int or port not in ports for port in engine.overrides) + or any(type(port) is not int for port in engine.sfp) + or not set(engine.sfp) <= set(profile.optical_ports) + or any(port in profile.optical_ports and port not in engine.sfp for port in chosen)): + raise ValueError("Scene ports do not match the hardware profile") + if engine.sfp_sync.mode == "ethernet" and engine.sfp_sync.source_port not in profile.copper_ports: + raise ValueError("The optical sync source must be a copper connector") + settings = {p: [0, p, 0, 0, 1, engine.brightness, engine.gamma] for p in ports} + for port in set(profile.optical_ports) - engine.sfp.keys(): + settings[port][1] = 0 + inputs = {} + groups = [] + for group, zone in enumerate(engine.zones, 1): + fx = create_effect(zone.effect.id, len(zone.ports), zone.effect.params_json()) + groups.append((zone.ports, fx, RenderContext(len(zone.ports)))) + for i, p in enumerate(zone.ports): + if fx.id == "activity_glow": + settings[p][:5] = [group, p, fx.p["minimum_mbps"], int(fx.p["include_uplinks"]), fx.p["speed"]] + elif fx.id == "traffic": + settings[p][3:5] = [int(fx.p["include_uplinks"]), fx.p["smoothing"]] + inputs[p] = [1, int(fx.p["custom_uplink"])] + elif fx.id == "traffic_trails": + settings[p][2:5] = [fx.p["max_mbps"], int(fx.p["include_uplinks"]), fx.p["speed"]] + inputs[p] = [2, i, len(zone.ports), fx.p["width"]] + elif fx.id == "poe_usage": + settings[p][4] = fx.p["speed"] + inputs[p] = [3] + elif fx.id == "daylight": + stops = DAYLIGHT_PALETTES[fx.p["palette"]] + inputs[p] = [4, fx.p["night_brightness"], len(stops)] + for hour, color in stops: + inputs[p].extend([hour, *color.precise_channels]) + elif fx.category in {"time", "data"}: + raise ValueError(f"{fx.name} has no offline sensor mapping.") + if p in engine.sfp: + settings[p][5] *= engine.sfp[p].brightness / 100 + grouped = {p for ports, _, _ in groups for p in ports} + independent = {} + for p in engine.sfp.keys() - grouped: + if engine.sfp_sync.mode == "ethernet": + source = engine.sfp_sync.source_port + settings[p][1] = source + settings[p][5] = settings[source][5] + else: + light = engine.sfp[min(engine.sfp) if engine.sfp_sync.mode == "together" else p] + if light.mode == "unmanaged": + settings[p][1] = 0 + else: + independent[p] = light + settings[p][5] *= light.brightness / 100 + for p, override in engine.overrides.items(): + inputs.pop(p, None) + settings[p][:2] = [0, p] + if override.brightness is not None: + settings[p][5] = override.brightness + for p in engine.sfp.keys() - grouped: + if engine.sfp_sync.mode == "ethernet": + settings[p][5] = settings[engine.sfp_sync.source_port][5] + rows = [] + for index in range(120): + t = index / 4 + colors = {p: (BLACK, BLACK) for p in settings} + extra = {p: (BLACK, BLACK) for p in settings} + for ports, fx, ctx in groups: + if fx.id == "activity_glow": + palette = fx.colors(t) + for p in ports: + colors[p] = palette["idle_color"], palette["active_color"] + elif fx.id in {"traffic", "traffic_trails", "poe_usage"}: + palette = fx.colors(t) + for p in ports: + if fx.id == "poe_usage": + colors[p] = palette["no_power_color"], palette["low_color"] + extra[p] = palette["high_color"], BLACK + else: + colors[p] = palette["idle_color"], palette["busy_color"] + extra[p] = palette["offline_color"], palette.get("uplink_color", BLACK) + elif fx.id != "daylight": + for p, color in zip(ports, fx.render(t, ctx), strict=True): + colors[p] = color, color + for p, light in independent.items(): + color = light.render(t, p) + colors[p] = color, color + for p, override in engine.overrides.items(): + colors[p] = override.color, override.color + pairs = list(colors.values()) + if any(fields[0] in {1, 2, 3} for fields in inputs.values()): + pairs.extend(extra.values()) + channels = (c for pair in pairs for col in pair for c in col.precise_channels) + rows.append(" ".join(format(c, ".7g") for c in channels)) + if all(row == rows[0] for row in rows): + rows = rows[:1] + limit = max(1, min(10, int(engine.max_commands))) + config = "".join(" ".join(str(n) for n in [p, *values, limit, *inputs.get(p, [])]) + "\n" + for p, values in settings.items()) + return config, "\n".join(rows) + "\n" + diff --git a/src/etherlighting_evolved/sonic_lighting.py b/src/etherlighting_evolved/sonic_lighting.py new file mode 100644 index 0000000..985886e --- /dev/null +++ b/src/etherlighting_evolved/sonic_lighting.py @@ -0,0 +1,71 @@ +"""Decode captured SONiC MCU port state without issuing device commands.""" + +from __future__ import annotations + +import struct +from dataclasses import dataclass +from types import MappingProxyType + +from .hardware import PROFILES, HardwareProfile + +_MCU_SHA256 = "5bc7567ef4bbd07bc8bc150c73662699e115d992141ed5b2f66d9b03616fb6a0" + + +@dataclass(frozen=True, slots=True) +class SonicLayout: + profile_key: str + board_id: int + port_count: int + + +# MCU 1.20.6 table at 0x174c4: 135-byte rows, two internal slots per board. +_LAYOUTS = MappingProxyType({ + "ECSAGG": SonicLayout("ECSAGG", 8, 54), + "ECSCORE": SonicLayout("ECSCORE", 17, 32), +}) + + +def sonic_layout(profile: HardwareProfile, *, board_id: int, mcu_sha256: str) -> SonicLayout: + """Match a captured board and MCU to a canonical SONiC endpoint layout.""" + if not isinstance(profile, HardwareProfile) or PROFILES.get(profile.key) is not profile: + raise ValueError("A canonical hardware profile is required") + layout = _LAYOUTS.get(profile.key) + if (layout is None or profile.protocol != "sonic-mcu" or profile.family != "USWF066" + or profile.copper_ports or profile.stack_ports + or profile.optical_ports != tuple(range(1, layout.port_count + 1))): + raise ValueError("The hardware profile has no decoded SONiC endpoint layout") + if type(board_id) is not int or board_id != layout.board_id or mcu_sha256 != _MCU_SHA256: + raise ValueError("The captured MCU identity does not match the decoded firmware") + return layout + + +@dataclass(frozen=True, slots=True) +class SonicPortSnapshot: + """MCU software channel values; this observation grants no output ownership.""" + + port: int + channels: tuple[int, int, int, int] + + +def decode_port_snapshot( + layout: SonicLayout, port: int, registers: bytes, *, selector_after: int, +) -> SonicPortSnapshot: + """Decode register bytes 0x10..0x18 and compare a subsequent selector echo. + + The selector handler copies active RGBW16 into snapshot registers, high byte + first (MCU 0xacfa, 0xbb58). These are captured register values, not a wire + request format. Equal selector echoes cannot establish freshness, exclude an + ABA selector change, or prove that the controller has yielded ownership. + """ + if not isinstance(layout, SonicLayout) or _LAYOUTS.get(layout.profile_key) is not layout: + raise ValueError("A decoded SONiC layout is required") + if type(port) is not int or not 1 <= port <= layout.port_count: + raise ValueError("Port is outside the decoded SONiC endpoint layout") + if type(registers) is not bytes or len(registers) != 9: + raise ValueError("The snapshot must contain exactly nine captured register bytes") + if type(selector_after) is not int or not 0 <= selector_after <= 255: + raise ValueError("The subsequent selector echo must be one byte") + selector = port - 1 + if registers[0] != selector or selector_after != selector: + raise ValueError("The snapshot selector changed or names another port") + return SonicPortSnapshot(port, struct.unpack(">4H", registers[1:])) diff --git a/tests/test_pro_max.py b/tests/test_pro_max.py new file mode 100644 index 0000000..829eab6 --- /dev/null +++ b/tests/test_pro_max.py @@ -0,0 +1,444 @@ +"""Packet bounds and transaction behavior against an independent simulated MCU.""" + +from dataclasses import replace + +import pytest + +from etherlighting_evolved.hardware import PROFILES +from etherlighting_evolved.pro_max import ( + PRO_MAX_LAYOUTS, + ControllerObservation, + ProMaxState, + ProMaxTransaction, + crc8, + decode_snapshot, + fade_packet, + resolve_layout, + scoped_commit_packet, + steady_packet, +) + +LAYOUTS = tuple(PRO_MAX_LAYOUTS.values()) +RGBW = (0x1234, 0xabcd, 0, 0xffff) + + +def reference_crc(data): + polynomial = int.from_bytes(data + b"\0", "big") + while polynomial.bit_length() >= 9: + polynomial ^= 0x107 << (polynomial.bit_length() - 9) + return polynomial + + +def snapshot(record, rgbw): + return bytes((record,)) + b"".join(value.to_bytes(2, "big") for value in rgbw) + + +class SimulatedMCU: + def __init__(self, layout): + self.layout = layout + self.current = [(0, 0, 0, 0)] * layout.port_count + self.behavior = [1] * layout.port_count + self.staged = {} + self.selected = 0 + self.ack = bytes((0, 0)) + self.snapshot = snapshot(0, self.current[0]) + self.writes = [] + self.queue = [] + self.drop_commands = False + self.drain_immediately = True + self.steal_selection = False + + def run(self, transfer): + request = transfer.request + if request[0] == 0x20: + assert transfer.read_length == 0 and len(request) == 13 + assert reference_crc(request[1:-1]) == request[-1] + record = request[1] + assert record < self.layout.port_count and request[2] == 8 and request[11] == 1 + color = tuple(int.from_bytes(request[index:index + 2], "big") for index in (3, 5, 7, 9)) + self.ack = bytes((record, 0)) + self.writes.append(record) + if not self.drop_commands: + self.queue.append((record, color)) + if self.drain_immediately: + self.drain() + return b"" + if request == b"\x52": + assert transfer.read_length == 2 + return self.ack + if request[0] == 0x10 and len(request) == 2: + assert transfer.read_length == 0 + self.selected = request[1] + self.snapshot = snapshot(self.selected, self.current[self.selected]) + return b"" + assert request == b"\x10" and transfer.read_length == 9 + if self.steal_selection: + return snapshot((self.selected + 1) % self.layout.port_count, RGBW) + return self.snapshot + + def drain(self): + for record, color in self.queue: + self.current[record] = color + self.behavior[record] = 8 + self.queue.clear() + + def stage_selected_color(self, rgbw): + self.staged[self.selected] = rgbw + self.snapshot = snapshot(self.selected, rgbw) + + +class Harness: + def __init__(self, layout=LAYOUTS[0], port=1, **kwargs): + self.now = 0.0 + self.revision = b"controller-revision" + self.completed = 0 + self.mcu = SimulatedMCU(layout) + self.transaction = ProMaxTransaction(layout, port, RGBW, observation=self.observation(), now=0, **kwargs) + self.transfers = [] + + def observation(self, after_transfer=None): + sequence = self.completed if after_transfer is None else after_transfer + return ControllerObservation(self.revision, sequence, self.now) + + def next(self): + self.now = max(self.now, self.transaction.next_at) + transfer = self.transaction.next_transfer(self.observation(), now=self.now) + if transfer is not None: + self.transfers.append(transfer) + return transfer + + def complete(self, transfer, reply=None, written=None, observation=None): + if reply is None: + reply = self.mcu.run(transfer) + self.transaction.complete( + transfer, written=len(transfer.request) if written is None else written, reply=reply, + observation=self.observation(transfer.sequence) if observation is None else observation, now=self.now, + ) + self.completed = transfer.sequence + + def step(self): + transfer = self.next() + assert transfer is not None + self.complete(transfer) + return transfer + + def finish(self): + for _ in range(30): + if self.transaction.terminal: + return + self.step() + pytest.fail("Transaction exceeded the simulator step bound") + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda item: item.key) +def test_connector_identity_and_all_per_connector_packets(layout): + assert resolve_layout(layout.key, layout.sysid, layout.board_id) is layout + assert not PROFILES[layout.key].output_verified + for port in range(1, layout.port_count + 1): + payload = bytes((port - 1, 8)) + bytes.fromhex("1234abcd0000ffff") + b"\1" + assert steady_packet(layout, port, RGBW) == b"\x20" + payload + bytes((reference_crc(payload),)) + assert decode_snapshot(layout, port, snapshot(port - 1, RGBW)) == RGBW + driver = Harness(layout, port) + driver.finish() + assert driver.transaction.state is ProMaxState.SNAPSHOT_MATCHED + assert driver.mcu.writes == [port - 1] + assert driver.mcu.current[port - 1] == RGBW + assert all(color == (0, 0, 0, 0) for index, color in enumerate(driver.mcu.current) if index != port - 1) + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda item: item.key) +def test_mask_never_includes_extra_records_and_preserves_high_bits(layout): + ports = tuple(range(1, layout.port_count + 1)) + packet = scoped_commit_packet(layout, ports) + assert packet[0] == 0x25 and len(packet) == 16 and packet[1:8] == bytes(7) + assert int.from_bytes(packet[8:15], "big") == (1 << layout.port_count) - 1 + assert packet[-1] == reference_crc(packet[1:-1]) + packet = scoped_commit_packet(layout, (layout.port_count,)) + assert int.from_bytes(packet[8:15], "big") == 1 << (layout.port_count - 1) + + +@pytest.mark.parametrize("port", [False, True, -1, 0, 19, 22, 64, 256, 1.0, "1", None]) +def test_invalid_connector_never_reaches_encoder(port): + layout = LAYOUTS[0] + with pytest.raises(ValueError): + steady_packet(layout, port, RGBW) + with pytest.raises(ValueError): + scoped_commit_packet(layout, (port,)) + + +@pytest.mark.parametrize("bad", [(), (1,), (1, 2, 3), (0, 0, 0, 0, 0), [0, 0, 0, 0], + (True, 0, 0, 0), (-1, 0, 0, 0), (65536, 0, 0, 0), (0.0, 0, 0, 0)]) +def test_invalid_color_rejected(bad): + with pytest.raises(ValueError): + steady_packet(LAYOUTS[0], 1, bad) + + +def test_crc_matches_standard_vector_and_independent_polynomial_division(): + assert crc8(b"123456789") == 0xf4 + for value in range(256): + data = bytes((value, 8, 0xff, value, 0, 0, 0xff, 0xff, 0, 1, 1)) + assert crc8(data) == reference_crc(data) + + +def test_foreign_or_modified_layout_and_identity_rejected(): + with pytest.raises(ValueError): + steady_packet(replace(LAYOUTS[0], copper_count=64), 60, RGBW) + for identity in [("USPM16", "ed70", 3), ("USPM16", "ed71", 2), ("USPM16", "ed71", 3.0), + ("USPXG8P", "ed76", 3), ("USPM48", "ed5e", True)]: + with pytest.raises(ValueError): + resolve_layout(*identity) + + +def test_staging_is_explicit_and_does_not_include_a_commit(): + packet = steady_packet(LAYOUTS[0], 18, RGBW, apply=False) + assert packet[0] == 0x20 and packet[1] == 17 and packet[11] == 0 and len(packet) == 13 + assert packet[-1] == reference_crc(packet[1:-1]) + for value in (0, 1, None): + with pytest.raises(ValueError): + steady_packet(LAYOUTS[0], 1, RGBW, apply=value) + + +@pytest.mark.parametrize("ports", [(), [], (1, 1), (1, 19)]) +def test_empty_duplicate_and_unmapped_masks_rejected(ports): + with pytest.raises(ValueError): + scoped_commit_packet(LAYOUTS[0], ports) + + +@pytest.mark.parametrize("mode", (0, 1)) +@pytest.mark.parametrize("seconds", (1, 2, 3)) +def test_fade_enrollment_uses_only_scoped_mode_prefixes(mode, seconds): + packet = fade_packet(LAYOUTS[-1], (1, 52), seconds=seconds, mode=mode) + assert packet[0:3] == bytes((0, mode + 2, 0x10 | (seconds + 8))) + assert packet[3:8] == bytes(5) + assert int.from_bytes(packet[8:15], "big") == (1 << 51) | 1 + assert packet[-1] == reference_crc(packet[1:-1]) + + +@pytest.mark.parametrize("seconds,mode", [(0, 0), (4, 0), (True, 0), (1, True), (1, 2), (1.0, 0)]) +def test_fade_rejects_unreviewed_modes_and_duration(seconds, mode): + with pytest.raises(ValueError): + fade_packet(LAYOUTS[0], (1,), seconds=seconds, mode=mode) + + +def test_crc_acceptance_does_not_claim_command_execution(): + driver = Harness() + driver.mcu.drop_commands = True + driver.step() + driver.step() + assert driver.transaction.state is ProMaxState.VERIFYING + driver.finish() + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.transaction.reason == "snapshot_not_matched" + assert driver.mcu.writes == [0] + assert [item.purpose for item in driver.transfers].count("snapshot") == 3 + + +def test_already_matching_snapshot_does_not_prove_dropped_command_executed(): + driver = Harness() + driver.mcu.current[0] = RGBW + driver.mcu.drop_commands = True + driver.finish() + assert driver.transaction.state is ProMaxState.SNAPSHOT_MATCHED + assert driver.mcu.behavior[0] == 1 + assert driver.mcu.current[0] == RGBW + assert not driver.mcu.queue + + +def test_same_selector_staging_can_match_cache_without_changing_current_color(): + driver = Harness() + driver.mcu.drop_commands = True + for _ in range(3): + driver.step() + driver.mcu.stage_selected_color(RGBW) + driver.step() + assert driver.transaction.state is ProMaxState.SNAPSHOT_MATCHED + assert driver.mcu.selected == 0 + assert driver.mcu.staged[0] == RGBW + assert driver.mcu.current[0] == (0, 0, 0, 0) + assert driver.mcu.behavior[0] == 1 + + +def test_queued_command_can_complete_between_bounded_snapshots(): + driver = Harness() + driver.mcu.drain_immediately = False + for _ in range(4): + driver.step() + assert driver.transaction.state is ProMaxState.VERIFYING + driver.mcu.drain() + driver.finish() + assert driver.transaction.state is ProMaxState.SNAPSHOT_MATCHED + assert driver.mcu.writes == [0] + + +def test_snapshot_is_reselected_instead_of_reading_old_cached_values(): + driver = Harness() + driver.mcu.steal_selection = True + for _ in range(4): + driver.step() + assert driver.transaction.state is ProMaxState.VERIFYING + driver.mcu.steal_selection = False + driver.finish() + assert driver.transaction.state is ProMaxState.SNAPSHOT_MATCHED + assert [item.purpose for item in driver.transfers] == [ + "write", "acceptance", "select", "snapshot", "select", "snapshot", + ] + + +@pytest.mark.parametrize("stage", range(4)) +def test_controller_change_after_any_transfer_revokes_without_restore(stage): + driver = Harness() + for _ in range(stage): + driver.step() + transfer = driver.next() + driver.revision = b"new-controller-choice" + driver.complete(transfer) + assert driver.transaction.state is ProMaxState.REVOKED + assert driver.next() is None + assert len(driver.mcu.writes) == 1 + + +def test_changed_controller_before_first_transfer_yields_no_output(): + driver = Harness() + driver.revision = b"changed" + assert driver.next() is None and not driver.mcu.writes + assert driver.transaction.state is ProMaxState.REVOKED + + +@pytest.mark.parametrize("stage", range(4)) +def test_old_observation_cannot_complete_a_new_transfer(stage): + driver = Harness() + for _ in range(stage): + driver.step() + old = driver.observation() + transfer = driver.next() + driver.complete(transfer, observation=old) + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.transaction.reason == "stale_controller_observation" + + +def test_timestamp_before_dispatch_is_stale_even_with_the_new_sequence(): + driver = Harness() + driver.now = 0.05 + transfer = driver.next() + old = ControllerObservation(driver.revision, transfer.sequence, 0) + driver.complete(transfer, observation=old) + assert driver.transaction.reason == "stale_controller_observation" + + +def test_unrefreshed_observation_cannot_start_a_transfer(): + driver = Harness() + old = driver.observation() + assert driver.transaction.next_transfer(old, now=0.101) is None + assert driver.transaction.reason == "stale_controller_observation" + + +def test_observation_from_the_future_is_rejected(): + driver = Harness() + future = ControllerObservation(driver.revision, 0, 0.1) + assert driver.transaction.next_transfer(future, now=0) is None + assert driver.transaction.reason == "stale_controller_observation" + + +@pytest.mark.parametrize("written,reply", [(0, b""), (-1, b""), (True, b""), (13, b"extra")]) +def test_short_or_ambiguous_write_is_not_retried(written, reply): + driver = Harness() + transfer = driver.next() + driver.complete(transfer, written=written, reply=reply) + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.next() is None and len(driver.transfers) == 1 + + +@pytest.mark.parametrize("reply", [b"", b"\x00", b"\x00\x00\x00", b"\x00\x01", b"\x01\x00"]) +def test_missing_failed_or_other_record_ack_is_not_a_success(reply): + driver = Harness() + driver.step() + driver.complete(driver.next(), reply=reply) + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.next() is None and driver.mcu.writes == [0] + + +@pytest.mark.parametrize("reply", [bytes(8), bytes(10), bytearray(9)]) +def test_incomplete_or_mutable_snapshot_is_not_matched(reply): + driver = Harness() + for _ in range(3): + driver.step() + driver.complete(driver.next(), reply=reply) + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.transaction.reason == "incomplete_transfer" + + +@pytest.mark.parametrize("stage", range(4)) +def test_deadline_expiry_and_clock_rollback_stop_transfer_progress(stage): + for invalid_now, reason in ((0.5, "deadline_exceeded"), (-1, "invalid_clock"), (float("nan"), "invalid_clock")): + driver = Harness() + for _ in range(stage): + driver.step() + transfer = driver.next() + driver.now = invalid_now + driver.complete(transfer) + assert driver.transaction.state is ProMaxState.UNCERTAIN + assert driver.transaction.reason == reason + + +def test_receipt_from_another_transaction_or_replayed_receipt_is_rejected(): + first, second = Harness(), Harness() + foreign = first.next() + second.next() + second.complete(foreign, reply=b"") + assert second.transaction.reason == "unexpected_transfer" + first.complete(foreign) + first.complete(foreign, reply=b"") + assert first.transaction.reason == "unexpected_transfer" + + +def test_duplicate_dispatch_does_not_resend_pending_write(): + driver = Harness() + driver.next() + with pytest.raises(RuntimeError): + driver.next() + assert len(driver.transfers) == 1 + + +def test_pending_transfer_and_readback_are_paced_without_busy_retries(): + driver = Harness() + driver.step() + assert driver.transaction.next_transfer(driver.observation(), now=driver.now) is None + driver.mcu.steal_selection = True + for _ in range(3): + driver.step() + assert driver.transaction.next_transfer(driver.observation(), now=driver.now) is None + assert len(driver.transfers) == 4 + + +def test_a_positive_clock_rollback_is_rejected(): + driver = Harness() + driver.now = 0.1 + transfer = driver.next() + driver.now = 0.05 + driver.complete(transfer) + assert driver.transaction.reason == "invalid_clock" + + +@pytest.mark.parametrize("observation", [None, ControllerObservation(b"", 0, 0), + ControllerObservation(b"x", True, 0), ControllerObservation(b"x", 1, 0), + ControllerObservation(b"x", 0, -1), ControllerObservation(b"x", 0, 0.1)]) +def test_missing_or_stale_initial_controller_observation_rejected(observation): + with pytest.raises(ValueError): + ProMaxTransaction(LAYOUTS[0], 1, RGBW, observation=observation, now=0) + + +def test_failure_and_revocation_are_terminal_and_do_not_generate_cleanup_writes(): + for stop, state in (("fail", ProMaxState.UNCERTAIN), ("revoke", ProMaxState.REVOKED)): + driver = Harness() + transfer = driver.next() + getattr(driver.transaction, stop)() + driver.complete(transfer, reply=b"") + assert driver.transaction.state is state + assert driver.next() is None and not driver.mcu.writes + + +@pytest.mark.parametrize("timeout,attempts", [(0, 3), (6, 3), (float("inf"), 3), (True, 3), (0.5, 0), (0.5, 11), + (0.5, True)]) +def test_invalid_transaction_bounds_rejected(timeout, attempts): + with pytest.raises(ValueError): + Harness(timeout=timeout, snapshot_attempts=attempts) diff --git a/tests/test_pro_max_io.py b/tests/test_pro_max_io.py new file mode 100644 index 0000000..ff9a279 --- /dev/null +++ b/tests/test_pro_max_io.py @@ -0,0 +1,338 @@ +"""Compile the portable native transport core and exercise injected syscall results.""" + +import ctypes +import os +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +from etherlighting_evolved.pro_max import PRO_MAX_LAYOUTS, crc8, fade_packet, scoped_commit_packet, steady_packet + +ROOT = Path(__file__).resolve().parents[1] +SOURCE = ROOT / "tools/device-helpers/pro-max-io.c" +LAYOUTS = tuple(PRO_MAX_LAYOUTS.values()) +RGBW = (0x1234, 0xabcd, 0, 0xffff) +OK, INVALID, IO_ERROR, INCOMPLETE = 0, -1, -2, -3 + + +class Command(ctypes.Structure): + _fields_ = [("sysid", ctypes.c_uint16), ("board", ctypes.c_uint8), + ("request", ctypes.c_uint8 * 16), ("request_length", ctypes.c_uint8), + ("read_length", ctypes.c_uint8)] + + +class Message(ctypes.Structure): + _fields_ = [("address", ctypes.c_uint16), ("flags", ctypes.c_uint16), + ("length", ctypes.c_uint16), ("data", ctypes.POINTER(ctypes.c_uint8))] + + +Sink = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.POINTER(Message), ctypes.c_uint) + + +def run_process(command, **kwargs): + return subprocess.run(command, capture_output=True, text=True, timeout=60, check=False, + creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0, **kwargs) + + +def windows_compiler(): + compiler = shutil.which("cl") + if compiler: + return compiler, os.environ.copy() + vswhere = (Path(os.environ.get("PROGRAMFILES(X86)", "C:/Program Files (x86)")) + / "Microsoft Visual Studio/Installer/vswhere.exe") + if not vswhere.is_file(): + pytest.fail("The native Pro Max fixtures require an existing MSVC C compiler; no tools are installed by tests") + found = run_process([str(vswhere), "-latest", "-products", "*", "-requires", + "Microsoft.VisualStudio.Component.VC.Tools.x86.x64", "-property", "installationPath"]) + if found.returncode or not found.stdout.strip(): + pytest.fail("No installed MSVC x64 toolchain was found for the native Pro Max fixtures") + setup = Path(found.stdout.strip()) / "VC/Auxiliary/Build/vcvars64.bat" + if not setup.is_file() or '"' in str(setup): + pytest.fail("MSVC's existing environment setup is unavailable") + shell = os.environ.get("COMSPEC", "cmd.exe") + if '"' in shell: + pytest.fail("The Windows command processor path is invalid") + setup_env = os.environ.copy() + setup_env["PATH"] = str(Path(os.environ["SYSTEMROOT"]) / "System32") + loaded = run_process(f'"{shell}" /d /s /c "call "{setup}" >nul && set"', env=setup_env) + if loaded.returncode: + pytest.fail("MSVC environment setup failed") + env = os.environ.copy() + for line in loaded.stdout.splitlines(): + name, separator, value = line.partition("=") + if separator and name.upper() in {"PATH", "INCLUDE", "LIB", "LIBPATH"}: + env[name.upper()] = value + compiler = shutil.which("cl", path=env.get("PATH")) + if not compiler: + pytest.fail("MSVC setup did not provide the existing C compiler") + return compiler, env + + +@pytest.fixture(scope="session") +def native_io(tmp_path_factory): + directory = tmp_path_factory.mktemp("pro-max-native-io") + if os.name == "nt": + compiler, env = windows_compiler() + library = directory / "pro-max-io.dll" + command = [compiler, "/nologo", "/std:c11", "/W4", "/WX", "/LD", "/MT", + "/DEE_PRO_MAX_TESTING=1", str(SOURCE), f"/Fe:{library}", + f"/Fo:{directory / 'pro-max-io.obj'}", "/link", "/NOLOGO", + f"/IMPLIB:{directory / 'pro-max-io.lib'}"] + else: + compiler = shutil.which("cc") or shutil.which("clang") or shutil.which("gcc") + if compiler is None: + pytest.fail("The native Pro Max fixtures require an existing C compiler; no tools are installed by tests") + env = os.environ.copy() + library = directory / ("pro-max-io.dylib" if sys.platform == "darwin" else "pro-max-io.so") + shared = "-dynamiclib" if sys.platform == "darwin" else "-shared" + command = [compiler, "-std=c11", "-Wall", "-Wextra", "-Werror", "-fPIC", shared, + "-DEE_PRO_MAX_TESTING=1", str(SOURCE), "-o", str(library)] + result = run_process(command, env=env, cwd=directory) + assert result.returncode == 0, result.stdout + result.stderr + module = ctypes.CDLL(str(library)) + module.ee_pm_validate.argtypes = [ctypes.POINTER(Command)] + module.ee_pm_validate.restype = ctypes.c_int + module.ee_pm_parse.argtypes = [ctypes.c_int, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(Command)] + module.ee_pm_parse.restype = ctypes.c_int + module.ee_pm_transfer.argtypes = [ctypes.POINTER(Command), ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t, + Sink, ctypes.c_void_p, ctypes.POINTER(ctypes.c_int)] + module.ee_pm_transfer.restype = ctypes.c_int + return module + + +def operation(layout, request, read_length=0): + assert len(request) <= 16 + value = Command() + value.sysid, value.board = int(layout.sysid, 16), layout.board_id + value.request_length, value.read_length = len(request), read_length + value.request[:len(request)] = request + return value + + +class MockTransport: + def __init__(self, native, result=None, reply=bytes(range(16))): + self.native, self.result, self.reply = native, result, reply + self.calls = [] + self.callback = Sink(self.dispatch) + + def dispatch(self, _context, messages, count): + self.calls.append([(message.address, message.flags, message.length, + ctypes.string_at(message.data, message.length)) for message in messages[:count]]) + if count == 2: + ctypes.memmove(messages[1].data, self.reply, min(messages[1].length, len(self.reply))) + return count if self.result is None else self.result + + def transfer(self, command, capacity=16): + reply = (ctypes.c_uint8 * 16)(*[0xa5] * 16) + returned = ctypes.c_int(999) + result = self.native.ee_pm_transfer(ctypes.byref(command), reply, capacity, self.callback, + None, ctypes.byref(returned)) + return result, bytes(reply), returned.value + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda value: value.key) +def test_native_steady_transfer_matches_all_connector_packets(native_io, layout): + transport = MockTransport(native_io) + for port in range(1, layout.port_count + 1): + for apply in (False, True): + packet = steady_packet(layout, port, RGBW, apply=apply) + result, reply, returned = transport.transfer(operation(layout, packet)) + assert result == OK and returned == 1 and reply == bytes([0xa5] * 16) + assert transport.calls[-1] == [(0x66, 0, 13, packet)] + assert len(transport.calls) == layout.port_count * 2 + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda value: value.key) +def test_native_masked_and_fade_packets_preserve_exact_frame(native_io, layout): + ports = tuple(range(1, layout.port_count + 1)) + packets = [scoped_commit_packet(layout, ports)] + packets += [fade_packet(layout, ports, seconds=seconds, mode=mode) + for seconds in (1, 2, 3) for mode in (0, 1)] + transport = MockTransport(native_io) + for packet in packets: + assert transport.transfer(operation(layout, packet))[0] == OK + assert transport.calls[-1] == [(0x66, 0, 16, packet)] + + +@pytest.mark.parametrize("register,length", [(0x00, 1), (0x10, 9), (0x24, 15), (0x52, 2)]) +def test_pointer_read_is_one_two_message_transfer(native_io, register, length): + transport = MockTransport(native_io) + result, reply, returned = transport.transfer(operation(LAYOUTS[0], bytes((register,)), length)) + assert result == OK and returned == 2 + assert len(transport.calls) == 1 + assert transport.calls[0] == [(0x66, 0, 1, bytes((register,))), (0x66, 1, length, bytes(length))] + assert reply[:length] == bytes(range(length)) and reply[length:] == bytes([0xa5] * (16 - length)) + + +def test_selection_stays_separate_from_snapshot_pointer_read(native_io): + transport = MockTransport(native_io) + assert transport.transfer(operation(LAYOUTS[0], b"\x10\x11"))[0] == OK + assert transport.transfer(operation(LAYOUTS[0], b"\x10", 9))[0] == OK + assert transport.calls[0] == [(0x66, 0, 2, b"\x10\x11")] + assert len(transport.calls[1]) == 2 + assert transport.transfer(operation(LAYOUTS[0], b"\x10\x11", 9))[0] == INVALID + assert len(transport.calls) == 2 + + +@pytest.mark.parametrize("read_length", [0, 2, 9, 15]) +@pytest.mark.parametrize("returned", [-145, -122, -5, -4, -1, 0, 3]) +def test_uncertain_syscall_never_retries_or_releases_reply(native_io, read_length, returned): + request = {0: steady_packet(LAYOUTS[0], 1, RGBW), 2: b"\x52", 9: b"\x10", 15: b"\x24"}[read_length] + transport = MockTransport(native_io, result=returned) + status, reply, actual = transport.transfer(operation(LAYOUTS[0], request, read_length)) + assert status == (IO_ERROR if returned < 0 else INCOMPLETE) + assert actual == returned and reply == bytes([0xa5] * 16) and len(transport.calls) == 1 + + +def test_one_of_two_messages_is_not_a_successful_read(native_io): + transport = MockTransport(native_io, result=1) + result, reply, returned = transport.transfer(operation(LAYOUTS[0], b"\x10", 9)) + assert result == INCOMPLETE and returned == 1 and reply == bytes([0xa5] * 16) + assert len(transport.calls) == 1 + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda value: value.key) +def test_invalid_records_masks_and_board_pairs_never_call_sink(native_io, layout): + packets = [bytes((0x10, layout.port_count))] + bad_record = bytearray(steady_packet(layout, 1, RGBW)) + bad_record[1] = layout.port_count + bad_record[-1] = crc8(bytes(bad_record[1:-1])) + packets.append(bytes(bad_record)) + for mask in (0, 1 << layout.port_count, 1 << 55): + packet = b"\x25" + bytes(7) + mask.to_bytes(7, "big") + packets.append(packet + bytes((crc8(packet[1:]),))) + transport = MockTransport(native_io) + for packet in packets: + assert transport.transfer(operation(layout, packet))[0] == INVALID + value = operation(layout, steady_packet(layout, 1, RGBW)) + value.board = (layout.board_id % 3) + 1 + assert transport.transfer(value)[0] == INVALID + value.board, value.sysid = layout.board_id, 0xed76 + assert transport.transfer(value)[0] == INVALID + assert not transport.calls + + +@pytest.mark.parametrize("register", [0x01, 0x11, 0x18, 0x19, 0x1a, 0x1f, 0x20, 0x25, 0xff]) +def test_arbitrary_registers_and_global_commit_never_call_sink(native_io, register): + transport = MockTransport(native_io) + for length in (0, 1, 2, 9, 16, 17, 255): + assert transport.transfer(operation(LAYOUTS[0], bytes((register,)), length))[0] == INVALID + assert not transport.calls + + +def test_crc_reserved_fields_behavior_apply_and_lengths_are_checked_in_core(native_io): + transport = MockTransport(native_io) + packet = steady_packet(LAYOUTS[0], 1, RGBW) + for index, value in ((2, 9), (11, 2), (0, 0x21)): + invalid = bytearray(packet) + invalid[index] = value + invalid[-1] = crc8(bytes(invalid[1:-1])) + assert transport.transfer(operation(LAYOUTS[0], bytes(invalid)))[0] == INVALID + for source in (packet, scoped_commit_packet(LAYOUTS[0], (1,)), fade_packet(LAYOUTS[0], (1,), seconds=1)): + invalid = bytearray(source) + invalid[-1] ^= 1 + assert transport.transfer(operation(LAYOUTS[0], bytes(invalid)))[0] == INVALID + for length in (0, 1, 2, 12, 14, 17, 255): + value = operation(LAYOUTS[0], source) + value.request_length = length + assert transport.transfer(value)[0] == INVALID + for source, index, changed in ((scoped_commit_packet(LAYOUTS[0], (1,)), 1, 1), + (fade_packet(LAYOUTS[0], (1,), seconds=1), 1, 0), + (fade_packet(LAYOUTS[0], (1,), seconds=1), 2, 8), + (fade_packet(LAYOUTS[0], (1,), seconds=1), 3, 1)): + invalid = bytearray(source) + invalid[index] = changed + invalid[-1] = crc8(bytes(invalid[1:-1])) + assert transport.transfer(operation(LAYOUTS[0], bytes(invalid)))[0] == INVALID + assert not transport.calls + + +def test_insufficient_reply_capacity_and_null_inputs_never_call_sink(native_io): + transport = MockTransport(native_io) + value = operation(LAYOUTS[0], b"\x10", 9) + assert transport.transfer(value, capacity=8)[0] == INVALID + returned = ctypes.c_int(99) + assert native_io.ee_pm_transfer(ctypes.byref(value), None, 16, transport.callback, + None, ctypes.byref(returned)) == INVALID + assert returned.value == 0 + assert native_io.ee_pm_transfer(None, None, 0, transport.callback, None, None) == INVALID + assert native_io.ee_pm_validate(None) == INVALID + value = operation(LAYOUTS[0], b"\x10\x00") + assert native_io.ee_pm_transfer(ctypes.byref(value), None, 0, Sink(), None, None) == INVALID + assert not transport.calls + + +def parse(native, args): + argv = (ctypes.c_char_p * len(args))(*[value.encode("ascii") for value in args]) + result = Command() + status = native.ee_pm_parse(len(args), argv, ctypes.byref(result)) + return status, result + + +@pytest.mark.parametrize("layout", LAYOUTS, ids=lambda value: value.key) +def test_cli_only_constructs_allowed_operations(native_io, layout): + prefix = ["pro-max-io", layout.sysid, str(layout.board_id)] + for port in (1, layout.port_count): + status, value = parse(native_io, [*prefix, "select", str(port)]) + assert status == OK and value.request_length == 2 and value.read_length == 0 + assert bytes(value.request[:2]) == bytes((0x10, port - 1)) + for name, register, length in (("snapshot", 0x10, 9), ("acceptance", 0x52, 2), + ("masked-acceptance", 0x24, 15), ("mode-observation", 0x00, 1)): + status, value = parse(native_io, [*prefix, name]) + assert status == OK and value.request_length == 1 and value.read_length == length + assert value.request[0] == register + packet = steady_packet(layout, layout.port_count, RGBW) + status, value = parse(native_io, [*prefix, "packet", packet.hex()]) + assert status == OK and bytes(value.request[:value.request_length]) == packet + + +@pytest.mark.parametrize("args", [[], ["tool"], ["tool", "ed71", "3"], + ["tool", "ed71", "3", "snapshot", "extra"], + ["tool", "ed71", "3", "select", "1", "extra"], + ["tool", "ed71", "3", "packet"], + ["tool", "ed71", "3", "packet", "1f00"], + ["tool", "ed71", "3", "packet", "g" * 26], + ["tool", "ed71", "3", "packet", "0" * 33], + ["tool", "ed71", "3", "read", "10"], + ["tool", "ed71", "3", "snapshot; reboot"], + ["tool", "ed71", "3", "--device=/dev/i2c-0"], + ["tool", "ed71", "3", "--address=0x67"], + ["tool", "ed71", "3", "select", "0"], + ["tool", "ed71", "3", "select", "01"], + ["tool", "ed71", "3", "select", "19"], + ["tool", "ed71", "3", "select", "1x"], + ["tool", "ed71", "3", "select", "-1"], + ["tool", "ed71", "3", "select", "999"], + ["tool", "0xed71", "3", "snapshot"], + ["tool", "ed71", "03", "snapshot"], + ["tool", "ed71", "2", "snapshot"], + ["tool", "ed76", "3", "snapshot"]]) +def test_cli_rejects_malformed_or_excess_fields(native_io, args): + assert parse(native_io, args)[0] == INVALID + + +def test_cli_null_fields_leave_output_unchanged(native_io): + output = Command() + ctypes.memset(ctypes.byref(output), 0xa5, ctypes.sizeof(output)) + expected = bytes(output) + valid = [b"pro-max-io", b"ed71", b"3", b"snapshot"] + for index in range(len(valid)): + values = valid.copy() + values[index] = None + argv = (ctypes.c_char_p * len(values))(*values) + assert native_io.ee_pm_parse(len(values), argv, ctypes.byref(output)) == INVALID + assert bytes(output) == expected + assert native_io.ee_pm_parse(4, None, ctypes.byref(output)) == INVALID + assert bytes(output) == expected + argv = (ctypes.c_char_p * len(valid))(*valid) + assert native_io.ee_pm_parse(4, argv, None) == INVALID + + +def test_test_library_has_no_device_entrypoint(native_io): + with pytest.raises(AttributeError): + _ = native_io.main + with pytest.raises(AttributeError): + _ = native_io.linux_transfer diff --git a/tests/test_resident_scene.py b/tests/test_resident_scene.py new file mode 100644 index 0000000..c1bac88 --- /dev/null +++ b/tests/test_resident_scene.py @@ -0,0 +1,262 @@ +import hashlib +import json +import os +import shutil +import subprocess +from dataclasses import replace +from pathlib import Path +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from etherlighting_evolved import device_playback as player +from etherlighting_evolved.color import Color +from etherlighting_evolved.effects import create_effect +from etherlighting_evolved.engine import Override, Zone +from etherlighting_evolved.hardware import PRO_XG8, PROFILES +from etherlighting_evolved.resident_scene import compile_scene_data +from etherlighting_evolved.sfp import SfpLight, SfpSync + + +def scene(profile, effect="static"): + ports = profile.copper_ports + profile.optical_ports + params = {"idle_color": "#000000", "active_color": "#ffffff"} if effect == "activity_glow" else {} + return SimpleNamespace( + switch=SimpleNamespace(hardware_profile=profile, native_breathing=True, sfp_precise=True), + mode="running", brightness=100, gamma=1, max_commands=30, overrides={}, + sfp={port: SfpLight() for port in profile.optical_ports}, sfp_sync=SfpSync(), + zones=[Zone("all", "All", ports, create_effect(effect, len(ports), params))], + ) + + +def renderer(tmp_path, profile, engine): + awk = shutil.which("awk") or "C:/Program Files/Git/usr/bin/awk.exe" + if not Path(awk).is_file(): + pytest.skip("awk is unavailable") + config, palette = compile_scene_data(engine, profile) + for name, data in {"config": config, "palette": palette, "previous": "", "ports": ""}.items(): + (tmp_path / name).write_text(data, encoding="ascii") + shutil.copyfile(Path(player.__file__).with_name("resident") / "frames.awk", tmp_path / "frames.awk") + ports = profile.copper_ports + profile.optical_ports + + def tick(stamp, total=0, *, count=None): + data = "".join(f"{port} U/U 1000F 0 0 {total if port == ports[-1] else 0} 0\n" for port in ports) + (tmp_path / "ports").write_text(data, encoding="ascii") + result = subprocess.run( + [awk, "-v", f"port_count={len(ports) if count is None else count}", "-v", f"stamp={stamp}", + "-v", "frame=0", "-f", "frames.awk", "config", "palette", "previous", "ports"], + cwd=tmp_path, capture_output=True, text=True, timeout=10, + ) + if result.returncode == 0: + (tmp_path / "next").replace(tmp_path / "previous") + return result + + return tick + + +@pytest.mark.parametrize("profile", PROFILES.values(), ids=PROFILES.keys()) +def test_every_canonical_layout_renders_all_connectors_without_stack_ports(tmp_path, profile): + engine = scene(profile) + ports = profile.copper_ports + profile.optical_ports + engine.overrides = {p: Override(Color(p, 100 + p, 255 - p)) for p in ports} + result = renderer(tmp_path, profile, engine)(1) + assert result.returncode == 0, result.stderr + rows = [list(map(int, row.split())) for row in result.stdout.splitlines()] + assert rows == [[p, p * 256, (100 + p) * 256, (255 - p) * 256] for p in ports] + assert not set(profile.stack_ports).intersection(row[0] for row in rows) + + +@pytest.mark.parametrize("profile", PROFILES.values(), ids=PROFILES.keys()) +def test_activity_glow_and_atomic_scene_edit_reach_the_last_connector(tmp_path, profile): + engine = scene(profile, "activity_glow") + tick = renderer(tmp_path, profile, engine) + assert tick(1).returncode == 0 + assert tick(2, 125000).returncode == 0 + result = tick(3, 250000) + assert result.returncode == 0, result.stderr + rows = [list(map(int, row.split())) for row in result.stdout.splitlines()] + assert rows[0][1:] == [0, 0, 0] and rows[-1][1:] == [64084] * 3 + + replacement = scene(profile) + replacement.zones[0].effect = create_effect("static", len(rows), {"color": "#ff0000"}) + config, palette = compile_scene_data(replacement, profile) + (tmp_path / "scene.edit").write_text("1\n" + config + palette, encoding="ascii") + assert tick(4, 375000).stdout.splitlines()[0].split()[1:] == ["0", "0", "0"] + (tmp_path / "scene.edit").replace(tmp_path / "scene.active") + edited = tick(5) + assert edited.returncode == 0, edited.stderr + assert all(row.split()[1:] == ["65280", "0", "0"] for row in edited.stdout.splitlines()) + + +@pytest.mark.parametrize("profile", PROFILES.values(), ids=PROFILES.keys()) +@pytest.mark.parametrize("effect", ["traffic", "traffic_trails", "poe_usage", "rainbow"]) +def test_palette_and_auxiliary_channels_scale_with_layout(profile, effect): + config, palette = compile_scene_data(scene(profile, effect), profile) + count = len(profile.copper_ports) + len(profile.optical_ports) + assert [int(row.split()[0]) for row in config.splitlines()] == list(range(1, count + 1)) + expected = count * (6 if effect == "rainbow" else 12) + assert all(len(row.split()) == expected for row in palette.splitlines()) + assert len(palette.splitlines()) == (120 if effect == "rainbow" else 1) + + +@pytest.mark.parametrize("profile", PROFILES.values(), ids=PROFILES.keys()) +def test_layout_compilation_does_not_bypass_runtime_qualification(profile): + engine = scene(profile) + compile_scene_data(engine, profile) + assert player.supported(engine.switch) == (profile is PRO_XG8) + if profile is not PRO_XG8: + with pytest.raises(ValueError, match="verified Pro XG"): + player.compile_scene(engine) + if profile.output_verified: + script = player.player_script(profile) + assert f"port_count={len(profile.copper_ports) + len(profile.optical_ports)}\n" in script + assert '-v port_count="$port_count"' in script + for port in profile.optical_ports: + mask = int(profile.sfp_mask(port), 16) + assert f"{port}) printf '%s' '{mask >> 32:x} {mask & 0xffffffff:x}';;" in script + else: + with pytest.raises(ValueError, match="not been qualified"): + player.player_script(profile) + + +def test_default_player_layout_is_the_existing_resource(): + assert player.player_script() == (Path(player.__file__).with_name("resident") / "player.sh").read_text("ascii") + + +@pytest.mark.parametrize("fault", ["forged", "stack", "duplicate", "wrong_optical", "optical_sync_source"]) +def test_bad_scene_topology_is_rejected(fault): + profile = PROFILES["ECS24SP"] + engine = scene(profile) + if fault == "forged": + profile = replace(profile) + elif fault == "stack": + engine.overrides[profile.stack_ports[0]] = Override(Color(1, 2, 3)) + elif fault == "duplicate": + engine.zones.append(engine.zones[0]) + elif fault == "wrong_optical": + engine.sfp[1] = SfpLight() + else: + engine.sfp_sync = SfpSync("ethernet", profile.optical_ports[0]) + with pytest.raises(ValueError): + compile_scene_data(engine, profile) + + +@pytest.mark.parametrize("fault", ["missing_row", "duplicate_row", "short_palette", "bad_target", "wrong_count"]) +def test_renderer_discards_incomplete_or_wrong_layout(tmp_path, fault): + profile = PROFILES["ECSAGG"] + tick = renderer(tmp_path, profile, scene(profile)) + config = tmp_path / "config" + rows = config.read_text().splitlines() + if fault == "missing_row": + config.write_text("\n".join(rows[:-1]) + "\n") + elif fault == "duplicate_row": + config.write_text("\n".join([rows[0], *rows[:-1]]) + "\n") + elif fault == "short_palette": + palette = tmp_path / "palette" + palette.write_text(" ".join(palette.read_text().split()[:-1]) + "\n") + elif fault == "bad_target": + parts = rows[-1].split() + parts[2] = "55" + config.write_text("\n".join([*rows[:-1], " ".join(parts)]) + "\n") + assert tick(1, count=55 if fault == "wrong_count" else None).returncode != 0 + + +@pytest.mark.anyio +async def test_unqualified_player_is_rejected_before_any_remote_write(monkeypatch): + async def unexpected(*args): + pytest.fail("An unqualified layout reached the remote transport") + monkeypatch.setattr(player, "_run", unexpected) + with pytest.raises(ValueError, match="not been qualified"): + await player.stage(None, "a" * 48, "", "", profile=PROFILES["ECSAGG"]) + + +@pytest.mark.anyio +@pytest.mark.parametrize("renderer_matches", [True, False]) +async def test_reconnect_checks_both_runtime_files_before_reusing_player(monkeypatch, renderer_matches): + script = player.player_script() + renderer = (Path(player.__file__).with_name("resident") / "frames.awk").read_text("ascii") + replies = [hashlib.sha256(script.encode("ascii")).hexdigest(), + hashlib.sha256(renderer.encode("ascii")).hexdigest() if renderer_matches else "0" * 64, + "ready"] + run = AsyncMock(side_effect=replies) + upload, drain, start = AsyncMock(), AsyncMock(return_value=True), AsyncMock() + monkeypatch.setattr(player, "_run", run) + monkeypatch.setattr(player, "status", AsyncMock(return_value="playing")) + monkeypatch.setattr(player, "_upload", upload) + monkeypatch.setattr(player, "drain", drain) + monkeypatch.setattr(player, "start", start) + await player.upgrade_player(None, "a" * 48) + if renderer_matches: + upload.assert_not_awaited() + drain.assert_not_awaited() + start.assert_not_awaited() + else: + upload.assert_awaited_once_with(None, "a" * 48, {"player.next": script, "frames.edit": renderer}) + drain.assert_awaited_once() + start.assert_awaited_once() + + +@pytest.mark.parametrize("profile", PROFILES.values(), ids=PROFILES.keys()) +def test_unmanaged_optical_connectors_have_no_render_output(tmp_path, profile): + engine = scene(profile) + selected = profile.optical_ports[-1] + ports = profile.copper_ports + (selected,) + engine.zones = [Zone("selected", "Selected", ports, create_effect("static", len(ports), {"color": "#ff0000"}))] + result = renderer(tmp_path, profile, engine)(1) + assert result.returncode == 0, result.stderr + assert [int(row.split()[0]) for row in result.stdout.splitlines()] == list(ports) + + +@pytest.mark.parametrize("profile", [p for p in PROFILES.values() if p.output_verified], + ids=[p.key for p in PROFILES.values() if p.output_verified]) +def test_prepare_acquires_only_the_selected_optical_connector(tmp_path, profile): + shell = shutil.which("sh") or "C:/Program Files/Git/usr/bin/sh.exe" + if not Path(shell).is_file(): + pytest.skip("A shell is unavailable") + engine = scene(profile) + selected = profile.optical_ports[-1] + ports = profile.copper_ports + (selected,) + engine.zones = [Zone("selected", "Selected", ports, create_effect("static", len(ports), {}))] + config, palette = compile_scene_data(engine, profile) + (tmp_path / "config").write_text(config, encoding="ascii") + (tmp_path / "scene.active").write_text("1\n" + config + palette, encoding="ascii") + # Exercise only the generated preparation functions with a recording sink. + # No ubus, device access, telemetry read or player process runs in this test. + script = player.player_script(profile).split("read -r start unused < /proc/uptime", 1)[0] + script += "set_led() { printf '%s\\n' \"$1\"; }\nprepare\n" + (tmp_path / "prepare.sh").write_text(script, encoding="ascii", newline="\n") + env = {**os.environ, "PATH": str(Path(shell).parent) + os.pathsep + os.environ["PATH"]} + result = subprocess.run([shell, "prepare.sh"], cwd=tmp_path, env=env, + capture_output=True, text=True, timeout=10) + assert result.returncode == 0, result.stderr + assert [json.loads(row) for row in result.stdout.splitlines()] == [ + {"behavior": "steady"}, {"port_pwm": f"{selected} 0 0 0 0"}, + {"mcu_mode": f"soc_port_map steady {int(profile.sfp_mask(selected), 16) >> 32:x} " + f"{int(profile.sfp_mask(selected), 16) & 0xffffffff:x}"}, + ] + + +@pytest.mark.parametrize("profile", tuple(p for p in PROFILES.values() if p.output_verified), ids=lambda p: p.key) +def test_player_optical_map_matches_desktop_protocol_for_every_connector(tmp_path, profile): + from etherlighting_evolved.ubus import _named_attributes, _sfp_mode_data + + shell = shutil.which("sh") or "C:/Program Files/Git/usr/bin/sh.exe" + if not Path(shell).is_file(): + pytest.skip("A shell is unavailable") + renderer(tmp_path, profile, scene(profile)) + script = player.player_script(profile).split("read -r start unused < /proc/uptime", 1)[0] + script += "set_led() { printf '%s\\n' \"$1\"; }\n" + script += "\n".join(f"optical {port}" for port in profile.optical_ports) + "\n" + (tmp_path / "map.sh").write_text(script, encoding="ascii", newline="\n") + env = {**os.environ, "PATH": str(Path(shell).parent) + os.pathsep + os.environ["PATH"]} + result = subprocess.run([shell, "map.sh"], cwd=tmp_path, env=env, capture_output=True, + text=True, timeout=10) + assert result.returncode == 0, result.stderr + observed = [json.loads(line)["mcu_mode"] for line in result.stdout.splitlines()] + expected = [] + for port in profile.optical_ports: + [(name, _, value)] = _named_attributes(_sfp_mode_data(port, True, profile=profile)) + assert name == b"mcu_mode" + expected.append(value.rstrip(b"\0").decode("ascii")) + assert observed == expected diff --git a/tests/test_sonic_lighting.py b/tests/test_sonic_lighting.py new file mode 100644 index 0000000..90e00b7 --- /dev/null +++ b/tests/test_sonic_lighting.py @@ -0,0 +1,99 @@ +"""Offline contract checks for captured SONiC MCU register observations.""" + +import struct +from dataclasses import replace + +import pytest + +from etherlighting_evolved.hardware import PROFILES +from etherlighting_evolved.sonic_lighting import ( + SonicLayout, + decode_port_snapshot, + sonic_layout, +) + +MCU = "5bc7567ef4bbd07bc8bc150c73662699e115d992141ed5b2f66d9b03616fb6a0" +BOARDS = (("ECSAGG", 8, 54), ("ECSCORE", 17, 32)) + + +def layout_for(key, board): + return sonic_layout(PROFILES[key], board_id=board, mcu_sha256=MCU) + + +@pytest.mark.parametrize("key,board,count", BOARDS) +def test_every_user_endpoint_decodes_high_byte_first_without_enabling_output(key, board, count): + profile = PROFILES[key] + layout = layout_for(key, board) + for port in range(1, count + 1): + values = (0x1234, 0xABCD, 0xFF00, 0x0102) + snapshot = decode_port_snapshot( + layout, port, bytes([port - 1]) + struct.pack(">4H", *values), selector_after=port - 1, + ) + assert snapshot.port == port + assert snapshot.channels == values + assert profile.firmware_pairs == () + with pytest.raises(ValueError, match="not been qualified"): + profile.require_output() + + +@pytest.mark.parametrize("key,board,count", BOARDS) +def test_internal_slots_and_global_port_zero_are_not_user_endpoints(key, board, count): + layout = layout_for(key, board) + for port in (False, True, 0, -1, count + 1, count + 2, 61, 256, 1.0, "1"): + with pytest.raises(ValueError, match="Port"): + decode_port_snapshot(layout, port, bytes(9), selector_after=0) + + +@pytest.mark.parametrize("key,board,count", BOARDS) +def test_wrong_board_or_firmware_cannot_select_a_layout(key, board, count): + for bad_board in (True, False, str(board), float(board), -1, 0, 17 if board == 8 else 8, 18): + with pytest.raises(ValueError, match="identity"): + sonic_layout(PROFILES[key], board_id=bad_board, mcu_sha256=MCU) + for bad_hash in ("", MCU.upper(), "0" * 64, MCU[:-1], None): + with pytest.raises(ValueError, match="identity"): + sonic_layout(PROFILES[key], board_id=board, mcu_sha256=bad_hash) + + +@pytest.mark.parametrize("profile", [p for p in PROFILES.values() if p.key not in {"ECSAGG", "ECSCORE"}]) +def test_other_firmware_families_cannot_use_sonic_mapping(profile): + with pytest.raises(ValueError, match="SONiC"): + sonic_layout(profile, board_id=8, mcu_sha256=MCU) + + +def test_copied_profiles_or_layouts_cannot_widen_endpoint_bounds(): + for profile in (replace(PROFILES["ECSAGG"]), replace(PROFILES["ECSAGG"], optical_ports=tuple(range(1, 65)))): + with pytest.raises(ValueError, match="canonical"): + sonic_layout(profile, board_id=8, mcu_sha256=MCU) + for layout in (SonicLayout("ECSAGG", 8, 64), replace(layout_for("ECSAGG", 8))): + with pytest.raises(ValueError, match="decoded SONiC layout"): + decode_port_snapshot(layout, 1, bytes(9), selector_after=0) + + +@pytest.mark.parametrize("length", (0, 1, 8, 10, 4096)) +def test_truncated_or_extra_register_data_is_rejected(length): + with pytest.raises(ValueError, match="exactly nine"): + decode_port_snapshot(layout_for("ECSAGG", 8), 1, bytes(length), selector_after=0) + + +@pytest.mark.parametrize("value", (bytearray(9), memoryview(bytes(9)), [0] * 9, "0" * 9, None)) +def test_register_snapshot_must_be_immutable_bytes(value): + with pytest.raises(ValueError, match="exactly nine"): + decode_port_snapshot(layout_for("ECSAGG", 8), 1, value, selector_after=0) + + +@pytest.mark.parametrize("selector,after", ((1, 0), (0, 1), (1, 1), (255, 0), (0, 255))) +def test_misaddressed_or_interleaved_selector_observation_is_rejected(selector, after): + with pytest.raises(ValueError, match="selector changed"): + decode_port_snapshot(layout_for("ECSCORE", 17), 1, bytes([selector]) + bytes(8), selector_after=after) + + +@pytest.mark.parametrize("after", (False, True, -1, 256, 0.0, "0", None)) +def test_invalid_subsequent_selector_echo_is_rejected(after): + with pytest.raises(ValueError, match="one byte"): + decode_port_snapshot(layout_for("ECSCORE", 17), 1, bytes(9), selector_after=after) + + +def test_snapshot_preserves_full_u16_channels_including_auxiliary(): + raw = b"\x00" + struct.pack(">4H", 0, 65535, 65281, 65535) + snapshot = decode_port_snapshot(layout_for("ECSCORE", 17), 1, raw, selector_after=0) + assert snapshot.channels == (0, 65535, 65281, 65535) diff --git a/tools/device-helpers/pro-max-io.c b/tools/device-helpers/pro-max-io.c new file mode 100644 index 0000000..1410e4a --- /dev/null +++ b/tools/device-helpers/pro-max-io.c @@ -0,0 +1,297 @@ +/* Fixed-device Pro Max lighting transfers. Hardware admission belongs to the caller. + * EE_PRO_MAX_TESTING builds only the portable parser and injected transport core. + * EE_PRO_MAX_DEVICE_IO explicitly builds the unintegrated Linux device wrapper. + */ +#if defined(EE_PRO_MAX_DEVICE_IO) && !defined(_POSIX_C_SOURCE) +#define _POSIX_C_SOURCE 200809L +#endif +#include +#include +#include + +#if defined(EE_PRO_MAX_TESTING) && defined(EE_PRO_MAX_DEVICE_IO) +#error The test build must not contain device I/O +#endif + +#if defined(_WIN32) && defined(EE_PRO_MAX_TESTING) +#define EE_EXPORT __declspec(dllexport) +#else +#define EE_EXPORT +#endif + +#define EE_PM_ADDRESS 0x66u +#define EE_PM_LIMIT 16u + +enum ee_pm_status { + EE_PM_OK = 0, + EE_PM_INVALID = -1, + EE_PM_IO_ERROR = -2, + EE_PM_INCOMPLETE = -3 +}; + +struct ee_pm_command { + uint16_t sysid; + uint8_t board; + uint8_t request[EE_PM_LIMIT]; + uint8_t request_length; + uint8_t read_length; +}; + +struct ee_pm_message { + uint16_t address; + uint16_t flags; + uint16_t length; + uint8_t *data; +}; + +typedef int (*ee_pm_sink)(void *, struct ee_pm_message *, unsigned int); + +static unsigned int port_count(uint16_t sysid, uint8_t board) +{ + if ((sysid == 0xed70u || sysid == 0xed71u) && board == 3u) return 18u; + if ((sysid == 0xed5bu || sysid == 0xed5cu) && board == 2u) return 26u; + if ((sysid == 0xed5du || sysid == 0xed5eu) && board == 1u) return 52u; + return 0u; +} + +static uint8_t checksum(const uint8_t *data, size_t length) +{ + unsigned int crc = 0u; + size_t index; + for (index = 0u; index < length; ++index) { + unsigned int bit; + crc ^= data[index]; + for (bit = 0u; bit < 8u; ++bit) + crc = ((crc << 1u) ^ ((crc & 0x80u) ? 0x07u : 0u)) & 0xffu; + } + return (uint8_t)crc; +} + +EE_EXPORT int ee_pm_validate(const struct ee_pm_command *command) +{ + unsigned int count; + const uint8_t *request; + size_t index; + uint64_t mask = 0u; + if (command == NULL) return EE_PM_INVALID; + count = port_count(command->sysid, command->board); + if (count == 0u || command->request_length == 0u || command->request_length > EE_PM_LIMIT) + return EE_PM_INVALID; + request = command->request; + if (command->read_length != 0u) { + if (command->request_length != 1u) return EE_PM_INVALID; + if ((request[0] == 0x00u && command->read_length == 1u) || + (request[0] == 0x10u && command->read_length == 9u) || + (request[0] == 0x24u && command->read_length == 15u) || + (request[0] == 0x52u && command->read_length == 2u)) return EE_PM_OK; + return EE_PM_INVALID; + } + if (request[0] == 0x10u && command->request_length == 2u) + return request[1] < count ? EE_PM_OK : EE_PM_INVALID; + if (request[0] == 0x20u && command->request_length == 13u) { + if (request[1] >= count || request[2] != 8u || request[11] > 1u) + return EE_PM_INVALID; + return checksum(request + 1u, 11u) == request[12] ? EE_PM_OK : EE_PM_INVALID; + } + if (command->request_length != 16u) return EE_PM_INVALID; + if (request[0] == 0x25u) { + for (index = 1u; index < 8u; ++index) + if (request[index] != 0u) return EE_PM_INVALID; + } else if (request[0] == 0x00u) { + if ((request[1] != 2u && request[1] != 3u) || + (request[2] != 0x19u && request[2] != 0x1au && request[2] != 0x1bu)) + return EE_PM_INVALID; + for (index = 3u; index < 8u; ++index) + if (request[index] != 0u) return EE_PM_INVALID; + } else { + return EE_PM_INVALID; + } + for (index = 8u; index < 15u; ++index) mask = (mask << 8u) | request[index]; + if (mask == 0u || (mask >> count) != 0u) return EE_PM_INVALID; + return checksum(request + 1u, 14u) == request[15] ? EE_PM_OK : EE_PM_INVALID; +} + +EE_EXPORT int ee_pm_transfer(const struct ee_pm_command *command, uint8_t *reply, + size_t capacity, ee_pm_sink sink, void *context, int *returned) +{ + uint8_t outgoing[EE_PM_LIMIT]; + uint8_t incoming[EE_PM_LIMIT] = {0}; + struct ee_pm_message messages[2]; + unsigned int count; + int result; + if (returned != NULL) *returned = 0; + if (ee_pm_validate(command) != EE_PM_OK || sink == NULL) return EE_PM_INVALID; + if (command->read_length != 0u && (reply == NULL || capacity < command->read_length)) + return EE_PM_INVALID; + memcpy(outgoing, command->request, command->request_length); + messages[0].address = EE_PM_ADDRESS; + messages[0].flags = 0u; + messages[0].length = command->request_length; + messages[0].data = outgoing; + count = command->read_length == 0u ? 1u : 2u; + if (count == 2u) { + messages[1].address = EE_PM_ADDRESS; + messages[1].flags = 1u; + messages[1].length = command->read_length; + messages[1].data = incoming; + } + result = sink(context, messages, count); + if (returned != NULL) *returned = result; + if (result < 0) return EE_PM_IO_ERROR; + if ((unsigned int)result != count) return EE_PM_INCOMPLETE; + if (command->read_length != 0u) memcpy(reply, incoming, command->read_length); + return EE_PM_OK; +} + +static int hex_digit(char value) +{ + if (value >= '0' && value <= '9') return value - '0'; + if (value >= 'a' && value <= 'f') return value - 'a' + 10; + if (value >= 'A' && value <= 'F') return value - 'A' + 10; + return -1; +} + +static size_t bounded_length(const char *value, size_t limit) +{ + size_t length = 0u; + while (length < limit && value[length] != '\0') ++length; + return length; +} + +static int parse_hex(const char *value, uint8_t *bytes, size_t length) +{ + size_t index; + if (bounded_length(value, length * 2u + 1u) != length * 2u) return EE_PM_INVALID; + for (index = 0u; index < length; ++index) { + int high = hex_digit(value[index * 2u]); + int low = hex_digit(value[index * 2u + 1u]); + if (high < 0 || low < 0) return EE_PM_INVALID; + bytes[index] = (uint8_t)((unsigned int)high * 16u + (unsigned int)low); + } + return EE_PM_OK; +} + +EE_EXPORT int ee_pm_parse(int argc, const char *const *argv, struct ee_pm_command *output) +{ + struct ee_pm_command command = {0}; + uint8_t identity[2]; + int index; + if (output == NULL || argv == NULL || (argc != 4 && argc != 5)) return EE_PM_INVALID; + for (index = 0; index < argc; ++index) + if (argv[index] == NULL) return EE_PM_INVALID; + if (parse_hex(argv[1], identity, 2u) != EE_PM_OK || bounded_length(argv[2], 2u) != 1u || + argv[2][0] < '1' || argv[2][0] > '3') return EE_PM_INVALID; + command.sysid = (uint16_t)((unsigned int)identity[0] * 256u + identity[1]); + command.board = (uint8_t)(argv[2][0] - '0'); + if (strcmp(argv[3], "packet") == 0) { + size_t length; + if (argc != 5) return EE_PM_INVALID; + length = bounded_length(argv[4], 33u); + if (length != 26u && length != 32u) return EE_PM_INVALID; + command.request_length = (uint8_t)(length / 2u); + if (parse_hex(argv[4], command.request, command.request_length) != EE_PM_OK) + return EE_PM_INVALID; + } else if (strcmp(argv[3], "select") == 0) { + unsigned int port = 0u; + size_t length; + size_t digit; + if (argc != 5) return EE_PM_INVALID; + length = bounded_length(argv[4], 3u); + if (length == 0u || length > 2u || argv[4][0] == '0') return EE_PM_INVALID; + for (digit = 0u; digit < length; ++digit) { + if (argv[4][digit] < '0' || argv[4][digit] > '9') return EE_PM_INVALID; + port = port * 10u + (unsigned int)(argv[4][digit] - '0'); + } + if (port == 0u || port > port_count(command.sysid, command.board)) return EE_PM_INVALID; + command.request[0] = 0x10u; + command.request[1] = (uint8_t)(port - 1u); + command.request_length = 2u; + } else { + if (argc != 4) return EE_PM_INVALID; + command.request_length = 1u; + if (strcmp(argv[3], "snapshot") == 0) { + command.request[0] = 0x10u; + command.read_length = 9u; + } else if (strcmp(argv[3], "acceptance") == 0) { + command.request[0] = 0x52u; + command.read_length = 2u; + } else if (strcmp(argv[3], "masked-acceptance") == 0) { + command.request[0] = 0x24u; + command.read_length = 15u; + } else if (strcmp(argv[3], "mode-observation") == 0) { + command.request[0] = 0x00u; + command.read_length = 1u; + } else { + return EE_PM_INVALID; + } + } + if (ee_pm_validate(&command) != EE_PM_OK) return EE_PM_INVALID; + *output = command; + return EE_PM_OK; +} + +#if defined(EE_PRO_MAX_DEVICE_IO) +#if !defined(__linux__) +#error The device wrapper requires target Linux headers +#endif +#include +#include +#include +#include +#include +#include +#include +#include + +static int linux_transfer(void *context, struct ee_pm_message *messages, unsigned int count) +{ + struct i2c_msg native[2]; + struct i2c_rdwr_ioctl_data transfer; + unsigned int index; + int result; + for (index = 0u; index < count; ++index) { + native[index].addr = messages[index].address; + native[index].flags = messages[index].flags; + native[index].len = messages[index].length; + native[index].buf = messages[index].data; + } + transfer.msgs = native; + transfer.nmsgs = count; + result = ioctl(*(int *)context, I2C_RDWR, &transfer); + return result < 0 ? -errno : result; +} + +int main(int argc, char **argv) +{ + struct ee_pm_command command; + struct stat device; + uint8_t reply[EE_PM_LIMIT]; + int descriptor; + int result; + int returned; + unsigned int index; + if (ee_pm_parse(argc, (const char *const *)argv, &command) != EE_PM_OK) { + fputs("Invalid Pro Max lighting operation.\n", stderr); + return 2; + } + descriptor = open("/dev/i2c-104", O_RDWR | O_CLOEXEC | O_NOFOLLOW); + if (descriptor < 0) { + fputs("Cannot open the Pro Max lighting transport.\n", stderr); + return 3; + } + if (fstat(descriptor, &device) != 0 || !S_ISCHR(device.st_mode)) { + close(descriptor); + fputs("Invalid Pro Max lighting transport.\n", stderr); + return 3; + } + result = ee_pm_transfer(&command, reply, sizeof(reply), linux_transfer, &descriptor, &returned); + close(descriptor); + if (result != EE_PM_OK) { + fprintf(stderr, "Lighting transfer could not be confirmed (%d).\n", returned); + return 4; + } + for (index = 0u; index < command.read_length; ++index) printf("%02x", (unsigned int)reply[index]); + putchar('\n'); + return 0; +} +#endif