"""LAN7800 EEPROM image model. Pure, hardware-free representation of a LAN7800 EEPROM image (a raw .bin of 256 or 512 bytes) plus typed accessors for the fields the Core v1 tool edits: signature, MAC, VID/PID/bcdDevice (across the SS/HS/FS descriptor blocks), string descriptors, and serial. Layout facts come from docs/01-eeprom-mechanism.md (datasheet DS00001992G Table 10-2 + lan78xx.c). Anything the doc flagged "VERIFY against a real dump" is centralized here as a named constant with a comment so it can be corrected in one place once a physical adapter is available. """ from __future__ import annotations from dataclasses import dataclass, field from typing import Optional # ---- constants (authoritative: lan78xx.c + datasheet Table 10-2) ---------- EEPROM_MAGIC = 0x78A5 # ethtool -E magic for LAN78xx SIG_OFFSET = 0x00 SIG_VALUE = 0xA5 # byte0; device ignores EEPROM if != 0xA5 MAC_OFFSET = 0x01 MAC_LEN = 6 MICROCHIP_OUI = (0x00, 0x80, 0x0F) MAX_EEPROM_SIZE = 512 SIZES = (256, 512) # String descriptor pointer table: 5 entries at 0x25..0x2E, each (len, word_off). STR_TABLE_OFFSET = 0x25 STR_NAMES = ("manufacturer", "product", "serial", "configuration", "interface") # Config Flags 0..3: four 32-bit LE words at 0x13/0x17/0x1B/0x1F (docs/01). CONFIG_FLAGS_OFFSET = 0x13 CONFIG_FLAGS_COUNT = 4 # Device-descriptor block pointers (word units). VID/PID/bcdDevice live inside. # LAN7800 exposes SuperSpeed + HighSpeed + FullSpeed descriptor blocks. DESC_PTRS = {"ss": 0x31, "hs": 0x35, "fs": 0x39} # offsets within a standard USB device descriptor: DD_VID = 8 # idVendor (LE u16) DD_PID = 10 # idProduct (LE u16) DD_BCDDEV = 12 # bcdDevice (LE u16) DD_LEN = 18 # bLength of a device descriptor (0x12) # LAN7800 identity guard — this tool is LAN7800 ONLY. LAN7800_VID = 0x0424 LAN7800_PID = 0x7800 # MAC octet order in EEPROM. RESOLVED against real hardware (2026-07-30): the # lan78xx driver reads EEPROM offset 0x01 as addr[0], i.e. NATURAL order, so # MAC AA:BB:CC:DD:EE:FF is stored AA BB CC DD EE FF (0x01=AA ... 0x06=FF). # The datasheet doc's "little-endian FF EE DD CC BB AA" note was WRONG: entering # the device's known MAC 00:80:0F:78:00:00 under LE produced the byte-reverse # 00:00:78:0F:80:00 on the wire. Natural order is confirmed correct. MAC_LITTLE_ENDIAN = False class EepromError(Exception): pass @dataclass class DescriptorView: kind: str # ss / hs / fs ptr_word: int # raw pointer value (word units) byte_offset: int # resolved byte offset of the descriptor block present: bool looks_valid: bool # bLength==0x12 and bDescriptorType==0x01 vid: Optional[int] = None pid: Optional[int] = None bcd_device: Optional[int] = None @dataclass class StringView: name: str length_field: int word_offset: int byte_offset: int present: bool value: Optional[str] = None @dataclass class Eeprom: data: bytearray # ---- construction ------------------------------------------------------ @classmethod def from_bytes(cls, raw: bytes) -> "Eeprom": if len(raw) not in SIZES: # tolerate any length up to 512 by padding to the nearest known size if len(raw) == 0 or len(raw) > MAX_EEPROM_SIZE: raise EepromError( f"unexpected EEPROM length {len(raw)}; expected one of {SIZES}") size = 256 if len(raw) <= 256 else 512 buf = bytearray(raw) + bytearray(size - len(raw)) return cls(buf) return cls(bytearray(raw)) @classmethod def blank(cls, size: int = MAX_EEPROM_SIZE) -> "Eeprom": if size not in SIZES: raise EepromError(f"size must be one of {SIZES}") return cls(bytearray(size)) @classmethod def default_template(cls, size: int = MAX_EEPROM_SIZE) -> "Eeprom": """A sensible DEFAULT LAN7800 image: 0xA5 signature, a Microchip-OUI MAC placeholder (00:80:0F:00:00:00), and SS/HS/FS USB device-descriptor blocks carrying VID 0x0424 / PID 0x7800 / bcdDevice 0x0300. Strings are left blank. This is the single source of truth for the webapp's default pre-populated fields. Descriptor blocks sit at 0x60/0x80/0xA0, clear of the fixed LED/GPIO register offsets.""" import struct e = cls.blank(size) e.set_signature() e.set_mac("00:80:0F:00:00:00") dd = struct.pack(" bytes: return bytes(self.data) @property def size(self) -> int: return len(self.data) # ---- low-level helpers ------------------------------------------------- def _u16le(self, off: int) -> int: if off + 1 >= self.size: raise EepromError(f"read u16 out of range at 0x{off:02X}") return self.data[off] | (self.data[off + 1] << 8) def _put_u16le(self, off: int, val: int) -> None: if off + 1 >= self.size: raise EepromError(f"write u16 out of range at 0x{off:02X}") self.data[off] = val & 0xFF self.data[off + 1] = (val >> 8) & 0xFF def _u32le(self, off: int) -> int: return (self.data[off] | (self.data[off + 1] << 8) | (self.data[off + 2] << 16) | (self.data[off + 3] << 24)) def _put_u32le(self, off: int, val: int) -> None: for i in range(4): self.data[off + i] = (val >> (8 * i)) & 0xFF # ---- config flags ------------------------------------------------------ def config_flags(self) -> list[int]: return [self._u32le(CONFIG_FLAGS_OFFSET + 4 * i) for i in range(CONFIG_FLAGS_COUNT)] def set_config_flag(self, i: int, val: int) -> None: if not 0 <= i < CONFIG_FLAGS_COUNT: raise EepromError(f"config flag index must be 0..{CONFIG_FLAGS_COUNT-1}") if not 0 <= val <= 0xFFFFFFFF: raise EepromError("config flag must be a 32-bit value") self._put_u32le(CONFIG_FLAGS_OFFSET + 4 * i, val) # ---- signature --------------------------------------------------------- @property def signature(self) -> int: return self.data[SIG_OFFSET] @property def has_signature(self) -> bool: return self.signature == SIG_VALUE def set_signature(self) -> None: self.data[SIG_OFFSET] = SIG_VALUE # ---- MAC --------------------------------------------------------------- @property def mac(self) -> str: octets = self.data[MAC_OFFSET:MAC_OFFSET + MAC_LEN] if MAC_LITTLE_ENDIAN: octets = octets[::-1] return ":".join(f"{b:02X}" for b in octets) def set_mac(self, mac: str) -> None: octets = parse_mac(mac) stored = octets[::-1] if MAC_LITTLE_ENDIAN else octets self.data[MAC_OFFSET:MAC_OFFSET + MAC_LEN] = bytes(stored) # ---- descriptor blocks (VID/PID/bcdDevice) ----------------------------- def descriptor(self, kind: str) -> DescriptorView: if kind not in DESC_PTRS: raise EepromError(f"unknown descriptor kind {kind!r}") ptr_off = DESC_PTRS[kind] ptr_word = self._u16le(ptr_off) byte_off = ptr_word * 2 present = ptr_word != 0 and byte_off + DD_LEN <= self.size view = DescriptorView(kind=kind, ptr_word=ptr_word, byte_offset=byte_off, present=present, looks_valid=False) if present: b_len = self.data[byte_off] b_type = self.data[byte_off + 1] view.looks_valid = (b_len == DD_LEN and b_type == 0x01) view.vid = self._u16le(byte_off + DD_VID) view.pid = self._u16le(byte_off + DD_PID) view.bcd_device = self._u16le(byte_off + DD_BCDDEV) return view def descriptors(self) -> list[DescriptorView]: return [self.descriptor(k) for k in DESC_PTRS] def _set_desc_field(self, field_off: int, val: int) -> list[str]: """Write a u16 field into every present descriptor block. Returns the list of blocks touched (kinds).""" touched = [] for d in self.descriptors(): if d.present: self._put_u16le(d.byte_offset + field_off, val) touched.append(d.kind) if not touched: raise EepromError( "no USB device-descriptor block present to write into; " "load a base image that already has descriptor pointers") return touched def set_vid(self, vid: int) -> list[str]: _check_u16(vid, "VID") return self._set_desc_field(DD_VID, vid) def set_pid(self, pid: int) -> list[str]: _check_u16(pid, "PID") return self._set_desc_field(DD_PID, pid) def set_bcd_device(self, bcd: int) -> list[str]: _check_u16(bcd, "bcdDevice") return self._set_desc_field(DD_BCDDEV, bcd) # ---- string descriptors ------------------------------------------------ def string(self, name: str) -> StringView: if name not in STR_NAMES: raise EepromError(f"unknown string {name!r}; one of {STR_NAMES}") idx = STR_NAMES.index(name) entry = STR_TABLE_OFFSET + idx * 2 length_field = self.data[entry] word_off = self.data[entry + 1] byte_off = word_off * 2 present = length_field != 0 and word_off != 0 and byte_off < self.size sv = StringView(name=name, length_field=length_field, word_offset=word_off, byte_offset=byte_off, present=present) if present: sv.value = self._read_usb_string(byte_off) return sv def strings(self) -> list[StringView]: return [self.string(n) for n in STR_NAMES] def _read_usb_string(self, off: int) -> Optional[str]: # USB string descriptor: bLength, bDescriptorType(0x03), UTF-16LE payload if off + 1 >= self.size: return None b_len = self.data[off] b_type = self.data[off + 1] if b_type != 0x03 or b_len < 2 or off + b_len > self.size: return None payload = self.data[off + 2:off + b_len] try: return payload.decode("utf-16-le", errors="replace") except Exception: return None def set_string_inplace(self, name: str, value: str) -> None: """Overwrite an existing string descriptor IN PLACE. v1 constraint: the new UTF-16LE payload must fit within the existing descriptor's byte length (we do not relocate/repack the string heap in v1 — that is an ADVANCED item). Shorter strings are zero-padded and bLength is updated. Raises if it would not fit or the string is absent. """ sv = self.string(name) if not sv.present: raise EepromError( f"string {name!r} is absent in this image; v1 can edit existing " f"strings in place but not allocate new ones (ADVANCED)") encoded = value.encode("utf-16-le") capacity = self.data[sv.byte_offset] # existing bLength (incl. 2-byte header) new_len = 2 + len(encoded) if new_len > capacity: raise EepromError( f"string {name!r}: new value needs {new_len} bytes but the " f"existing slot holds {capacity}; in-place edit only in v1") off = sv.byte_offset self.data[off] = new_len self.data[off + 1] = 0x03 self.data[off + 2:off + 2 + len(encoded)] = encoded # zero any leftover tail within the old slot for i in range(off + new_len, off + capacity): self.data[i] = 0x00 # ---- module helpers ------------------------------------------------------- def parse_mac(mac: str) -> list[int]: parts = mac.replace("-", ":").split(":") if len(parts) != 6: raise EepromError(f"invalid MAC {mac!r}: need 6 octets") try: octets = [int(p, 16) for p in parts] except ValueError: raise EepromError(f"invalid MAC {mac!r}: non-hex octet") if any(o < 0 or o > 0xFF for o in octets): raise EepromError(f"invalid MAC {mac!r}: octet out of range") return octets def parse_u16(text) -> int: if isinstance(text, int): val = text else: t = str(text).strip().lower() try: val = int(t, 16) if t.startswith("0x") else int(t, 0) except ValueError: raise EepromError( f"invalid 16-bit value {text!r}: expected decimal or 0x-hex") _check_u16(val, "value") return val def _check_u16(val: int, label: str) -> None: if not isinstance(val, int) or val < 0 or val > 0xFFFF: raise EepromError(f"{label} must be a 16-bit value (0..0xFFFF), got {val!r}")