From 81446789dc1415303168ba87d1938f755d2dbfca Mon Sep 17 00:00:00 2001
From: Dennis Brentjes <d.brentjes@gmail.com>
Date: Sat, 10 Oct 2026 20:21:41 +0200
Subject: [PATCH] w5100/w5500: annotate the intentionally-unreferenced register
 map

An AST audit for dead code flags seven register-address constants that nothing
in the tree references.  They are staying, and the files now say why at the
point of definition, so the next audit does not re-litigate them: the map costs
no logic and is kept COMPLETE on purpose, because three separate hardware bugs
came out of guessing it (the 0x4000-vs-0x8000 buffer base, NETLCKR, and the
60.3 ms settle).  A partial map invites re-guessing the missing half.  _TMSR in
particular documents where the second byte of the RMSR/TMSR = 0x55 burst lands.

Also fixed a real readability defect found while reading them: _RST_LOW_DEFAULT
and its two-line comment sat WEDGED BETWEEN _NETLCKR and the continuation of
_NETLCKR's own comment, so the sentence explaining the network lock finished on
the line declaring _NETLCK_UNLOCK.  NETLCKR's note is now whole and in one
place, and _RST_LOW_DEFAULT sits after the register map with the 60.3 ms settle
mentioned alongside it, since the two waits are easy to confuse.

VERIFIED: generated RTLIL identical (9874 lines), so this is comment-only.
Both masters' testbenches pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 exi_bba/w5100_parallel_master.py | 23 +++++++++++++++++------
 exi_bba/w5500_spi_master.py      |  5 +++++
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/exi_bba/w5100_parallel_master.py b/exi_bba/w5100_parallel_master.py
index ccddb02..4ed429d 100644
--- a/exi_bba/w5100_parallel_master.py
+++ b/exi_bba/w5100_parallel_master.py
@@ -49,12 +49,12 @@ _GAR0      = 0x0001   # Gateway IP, 4 bytes
 _SUBR0     = 0x0005   # Subnet mask, 4 bytes
 _SHAR0     = 0x0009   # Source MAC, 6 bytes
 _SIPR0     = 0x000F   # Source IP, 4 bytes
-_NETLCKR   = 0x0071   # W5100S Network Lock Register (WO) — GWR/SUBR/SHAR/SIPR are
-
-# Default RSTn low time before release (sync cycles).  24_000 @ 24 MHz = 1 ms;
-# the W5100S datasheet minimum is ~2 us, so this is generous on purpose.
-_RST_LOW_DEFAULT = 24_000
-_NETLCK_UNLOCK = 0x3A #   writable ONLY while NETLCKR==0x3A (default 0x00 = locked)
+# W5100S Network Lock Register (write-only).  GWR/SUBR/SHAR/SIPR are writable
+# ONLY while NETLCKR holds the unlock value; its default 0x00 means locked, and
+# every network-config write is silently dropped until it is unlocked.  The
+# original W5100 has no such register.
+_NETLCKR   = 0x0071
+_NETLCK_UNLOCK = 0x3A
 _IR        = 0x0015   # Interrupt register
 _IMR       = 0x0016   # Interrupt mask
 _RMSR      = 0x001A   # RX memory size (2 bits/socket)
@@ -69,6 +69,17 @@ _S0_TX_WR  = 0x0424   # Socket 0 TX write pointer
 _S0_RX_RSR = 0x0426   # Socket 0 RX received size (2 bytes)
 _S0_RX_RD  = 0x0428   # Socket 0 RX read pointer
 
+# ⚠️ Some entries above are intentionally unreferenced (_IR, _TMSR, _S0_SR,
+# _S0_TX_FSR, _S0_TX_RD).  They cost no logic and the map is kept COMPLETE on
+# purpose: three separate hardware bugs came out of guessing it, so a partial
+# map invites re-guessing the half that is missing.  _TMSR in particular
+# documents where the second byte of the RMSR/TMSR = 0x55 burst lands.
+
+# Default RSTn low time before release, in sync cycles.  24_000 at 24 MHz is
+# 1 ms, against a W5100S datasheet minimum of ~2 us -- generous on purpose,
+# since the chip then needs 60.3 ms more before it answers at all.
+_RST_LOW_DEFAULT = 24_000
+
 # Per-socket register/buffer geometry (2 KB per socket, RMSR/TMSR=0x55).
 # The UDP-test socket number is configurable; addresses are computed from it in
 # __init__ (see _socket_addrs).  Socket-n register block base = 0x0400+n*0x100,
diff --git a/exi_bba/w5500_spi_master.py b/exi_bba/w5500_spi_master.py
index 092e158..c77d79f 100644
--- a/exi_bba/w5500_spi_master.py
+++ b/exi_bba/w5500_spi_master.py
@@ -44,6 +44,11 @@ _W5500_S0_TX_FSR = 0x0020  # Socket 0 TX Free Size (2 bytes)
 _W5500_S0_TX_WR  = 0x0024  # Socket 0 TX Write Pointer
 _W5500_S0_RX_RSR = 0x0026  # Socket 0 RX Received Size (2 bytes)
 _W5500_S0_RX_RD  = 0x0028  # Socket 0 RX Read Pointer
+
+# ⚠️ _W5500_S0_RXBUF_SIZE, _W5500_S0_TXBUF_SIZE and _W5500_S0_TX_FSR are
+# intentionally unreferenced: the chip's 2 KB-per-socket defaults are what this
+# master uses, and the map is kept complete so nobody has to re-derive the
+# missing half from the datasheet.  They cost no logic.
 _W5500_S0_IMR  = 0x002C   # Socket 0 Interrupt Mask
 
 # Control byte = (BSB << 3) | (RWB << 2) | OM.