Merge upstream/main into feat/webui-compression

Resolve conflicts against ~55 upstream commits since 37eefb4: - Makefile: keep upstream parallel-build fixes (machine_init.c, SUBDIRSCLEAN, html_data grouped target) and retain minify+gzip pipeline (-z, html_min, .css/.ico) - tools: retain gzip support (zlib, -lz) lost in upstream revert - httpd/httpd.c: keep Content-Encoding: gzip alongside upstream GET walk, config upload, syslog/hostname changes - html: port upstream HTML/JS changes into SPA (single-page) bundle: * i18n: add port_col_devices / port_devices keys (en/ja/zh) * ports: add Connected devices column, devRender/devWalk via walkL2 (8c3df64) * config: add syslog port, extended stp/igmp/bw patterns, conf_toggle handling * system: show /cmd output in console (console_out), 401 handling * l2: hide delete for CPU entry, delL2Button, sort/filter improvements * navigation: add STP entry - SPA: integrate new STP page (stp.html/js) as page-stp section with sectionInits.stp, bridge/prio handling, per-port config/status tables - Remove per-page HTML/JS files (now bundled) and standalone stp.html/js Verified: tools build, html_min generation (main.js 93k->81k->19k gzip, 8 files), html_data.h gzip sizes, main.js syntax check.
2026-10-29 17:54:14 +08:00 · 2026-09-06 04:45:46 +09:00
commit d245249385
@@ -64,3 +64,33 @@ Writing 0x1 to register 0x7850 will transmit the frame. The Ethernet frame
 checksum and the TCP checksum are automatically calculated (offloaded) by the
 ASIC before transmitting on the wire.

+
+## The RTL tag words
+
+The frame header uses the Realtek Remote Control Protocol (RRCP) format or
+the like.
+
+The `flags` word:
+
+```
+bit15 EFID_EN | 14:12 EFID | 11 PRI_EN | 10:8 PRI |
+bit7  KEEP    | 6 VSEL     | 5 LEARN_DIS         | 4:0 VIDX
+```
+
+All fields are in network byte order.
+
+* `EFID_EN`, `EFID`: look the destination up under this filtering ID
+  instead of the port's own
+* `PRI_EN`, `PRI`: force the given priority on the frame
+* `KEEP`: keep the 802.1Q tagging of the frame exactly as injected,
+  bypassing the egress tagging rules of the port
+* `VSEL`, `VIDX`: classify the frame into the VLAN at this index of the
+  VLAN table
+* `LEARN_DIS`: do not learn the source address from this frame
+
+The `pmask` word: bit 15 is `ALLOW`, bits 14 to 0 are a port mask.
+
+* `ALLOW` clear: the mask is the egress set, the frame goes to exactly
+  the ports given
+* `ALLOW` set: the ASIC looks the destination up as usual and the mask
+  only limits which ports the result may use
@@ -15,7 +15,7 @@ and sold by Mokerlink.
 The device is fully supported:
 - All 4 2.5GBASE-T RJ45 ports work at 10/100/1000/2500 Mbps
 - The SFP+ port supports 1G, 2.5G and 10G modules 
- LEDs work with the same indiciations as the OEM firmware (use KP_9000_6XHML_X2 in machine.h if building yourself or the corresponding pre-compiled binary)
+- LEDs work with the same indiciations as the OEM firmware (use KP_9000_6XHML_X2_V1_1 in machine.h if building yourself or the corresponding pre-compiled binary)
 - untested due to missing Hardware: SFP+ ports equipped with 1G or 2.5G SFPs.

 ### Hardware overview
@@ -0,0 +1,79 @@
+# FG-8GT-1SX
+
+Following is documentation for unmanaged switch marked as `FG-8GT-1SX`.
+
+Original software is running UART on 9600 baud rate.
+
+Using SPI clamp in-board is the only method for initial installation.
+
+### Brands
+
+| Brand   | Type       | Managed | PCB        | Flash       | Chip RTL      |
+|---------|------------|---------|------------|-------------|---------------|
+| Ruiying | RY-8GT-1SX | No      | FG-8GT-1SX | GD25Q80ESIG | 8373N + 8224N |
+
+### What works
+
+- All eight 2.5GBASE-T RJ45 ports at 10/100/1000/2500 Mbps
+- SFP port with 1G/2.5G/10G modules
+- LEDs
+
+### PCB overview
+
+**Board markings**
+
+- Top silkscreen: FG-8GT-1SX
+
+Top side:
+
+<img src="photos/FG-8GT-1SX/PCB-top.jpg" width="600" />
+
+Bottom:
+
+<img src="photos/FG-8GT-1SX/PCB-bottom.jpg" width="600" />
+
+### Serial console
+
+The PCB has five unpopulated through-holes near the SoC, with a white rectangle surrouding them, labeled as `J18` and a triangle points to the square shaped first pin.
+
+This is where the "expected" UART header should be soldered at, with redundant 3V3 VCC, but also with missing 0Ω resistors between TX/RX and SoC, so simply soldering a header would not work. One need also add the missing resistors or solder the pads together, while making sure not connecting unrelated pads.
+
+Numbered from the triangle, the header pinout is:
+
+| Position | Signal | GPIO   | Status      |
+|----------|--------|--------|-------------|
+| 1        | GND    | GND    | Internal    |
+| 2        | TX     | GPIO31 | Unconnected |
+| 3        | RX     | GPIO32 | Unconnected |
+| 4        | 3V3    | -      | Internal    |
+| 5        | 3V3    | -      | Internal    |
+
+There're four resistor pads near the header.
+
+| Resistor ID | SoC Side    | Header Side |
+|-------------|-------------|-------------|
+| R1240       | TX / GPIO31 | Pin 2       |
+| R1243       | 3V3         | -           |
+| R1242       | 3V3         | Pin 3       |
+| R1241       | RX / GPIO32 | -           |
+
+To get TX working, solder a 0Ω resistor between the pads for R1240 or solder them together.
+
+For RX However, the designer certainly made a mistake, as the SoC-side lines to the resistor expected for Rx (R1242) and 3V3 (R1241) are swapped. For RX to work, the R1241 SoC side and R1242 header side shall be connected, so either:
+
+- Solder: R1241 SoC side -> R1241 header side -> R1242 header side
+- Jump wire: R1241 SoC side -> R1242 header side
+
+Be sure not to bring R1242 SoC side to the connection as that would wire Rx to 3v3.
+
+A complete working serial header should look like following on this PCB:
+
+<img src="photos/FG-8GT-1SX/Serial.png" width="600" />
+
+- **Settings**: 115200 baud / 8N1 / 3.3V TTL
+- Connect a USB-TTL adapter: adapter GND → pin 1, RX → pin 2, TX → pin 3
+
+### Power supply
+
+Input power is delivered via barell plug, `12V 1A` adapter was provided.
+
@@ -1,17 +1,36 @@
-# Keeplink KP-9000-6XH-X2
+# Keeplink KP-9000-6XH-X2 / KP-9000-6XHML-X2

-Following is documentation for unmanaged switch marked as `KP-9000-6XH-X2`.
+Following is documentation for switches marked as `KP-9000-6XH-X2` or
+`KP-9000-6XHML-X2`.

 Using SPI clamp in-board is the only method for initial installation.

 ### Label specifications

 - **Name**: 4X 2.5G RJ45 Port + 2 X 10G SFP+ Port  
- **Model**: KP-9000-6XH-X2  
+- **Model**: KP-9000-6XH-X2 / KP-9000-6XHML-X2
 - **Ports**:  
  - 4 × RJ45: 10/100/1000/2500 Mbps  
  - 2 × SFP+: 1000 / 2500 / 10000 Mbps  

+### Machine target
+
+These devices exist with different PCB revisions. Select the machine target by
+the PCB silkscreen, not by the label on the case. The `6XH` / `6XHML`
+distinction appears to be a stock firmware, SKU or label difference, not a
+reliable indicator of PCB wiring. The PCB revision defines the hardware layout.
+
+| PCB silkscreen | Known labels / devices | Recommended machine target | Equivalent target | Legacy target |
+| --- | --- | --- | --- | --- |
+| `2M-PCB43-V1.1` | Mokerlink 2G040210GSM web-managed 4+2 switch | `MACHINE_KP_9000_6XHML_X2_V1_1` | `MACHINE_KP_9000_6XH_X2_V1_1` | `MACHINE_KP_9000_6XHML_X2` |
+| `2M-PCB43-V1.2` | `KP-9000-6XHML-X2` | `MACHINE_KP_9000_6XHML_X2_V1_2` | `MACHINE_KP_9000_6XH_X2_V1_2` | `MACHINE_KP_9000_6XHML_X2` |
+| `2M-PCB43-V2.1` | `KP-9000-6XH-X2`, `KP-9000-6XHML-X2` | `MACHINE_KP_9000_6XH_X2_V2_1` or `MACHINE_KP_9000_6XHML_X2_V2_1` | same V2.1 layout | `MACHINE_KP_9000_6XH_X2` |
+
+The V1.1 and V1.2 boards currently use the same V1.x GPIO, SFP, port and LED
+layout. The V2.1 board uses a different V2.1 layout with custom LED muxing.
+Legacy targets are preserved for compatibility with already-tested devices, but
+new builds should prefer the explicit PCB-revision targets.
+
 ### What works

 - All four 2.5GBASE-T RJ45 ports at 10/100/1000/2500 Mbps
@@ -19,7 +38,7 @@ Using SPI clamp in-board is the only method for initial installation.
 - LEDs
 - untested due to missing Hardware: SFP+ ports equipped with 1G or 2.5G SFPs.

-### Hardware overview
+### Hardware overview: 2M-PCB43-V2.1

 Front side:

@@ -44,6 +63,24 @@ Bottom

 <img src="photos/2M-PCB43-V2.1-unmanaged/2M-PCB43-V2.1-bottom.jpg" width="600" />

+### Hardware overview: 2M-PCB43-V1.1 / V1.2
+
+The V1.1 board has been reported in the Mokerlink 2G040210GSM web-managed 4+2
+switch. The V1.2 board has been seen in managed `KP-9000-6XHML-X2` devices.
+Both use the same V1.x layout.
+
+Label:
+
+<img src="photos/KP-9000-6XHML-X2/label.jpg" width="600" />
+
+Top side:
+
+<img src="photos/KP-9000-6XHML-X2/pcb_top.jpg" width="600" />
+
+Bottom:
+
+<img src="photos/KP-9000-6XHML-X2/pcb_bottom.jpg" width="600" />
+
 ## Reset Button

 There's an unpopulated Reset button on the front left side of the PCB.
@@ -54,4 +91,3 @@ The front case has already the hole in the metal case, you just have to punch a
 ## Power supply

 Input power is delivered via barell plug, `12V 1A` adapter was provided.
-
@@ -0,0 +1,97 @@
+Hisource Hi-K0402WS V2
+
+RTL8372-based 4×2.5G + 2×SFP+ unmanaged switch.
+
+Using SPI clamp in-board is the only method for initial installation.
+
+### Label specifications
+
+- **Manufacturer**: HISOURCE
+- **Model**: Hi-K0402WS V2
+- **Ports**:
+  - 4 × RJ45: 10/100/1000/2500 Mbps
+  - 2 × SFP+: 1G / 2.5G / 10G
+
+### What works
+
+- All four 2.5GBASE-T RJ45 ports at 10/100/1000/2500 Mbps
+- Both SFP+ ports supporting 1G, 2.5G and 10G modules
+- LEDs: amber (2.5G) and green (1G/100M/10M) per copper port; combined link/act on SFP ports
+
+### PCB overview
+
+**Board markings**
+- PCB-K0402WS-V2.0
+- DIP-K0402WS-V2.0
+
+**Key components**
+- U1: SPI NOR flash, 2 MiB
+- S1: unpopulated slide switch footprint (three through-holes used as serial console)
+
+Front panel
+
+<img src="photos/PCB-K0402WS-V2.0/chassis-front.jpg" width="400" />
+
+Bottom label
+
+<img src="photos/PCB-K0402WS-V2.0/chassis-bottom.jpg" width="400" />
+
+Top side (PCB)
+
+<img src="photos/PCB-K0402WS-V2.0/PCB-top.jpg" width="300" />
+
+### Port layout
+
+| Front panel position | Logical port | Physical port | Type    |
+|----------------------|--------------|---------------|---------|
+| SFP left             | 8            | 5             | SFP+    |
+| RJ45 1               | 4            | 1             | Copper  |
+| RJ45 2               | 5            | 2             | Copper  |
+| RJ45 3               | 6            | 3             | Copper  |
+| RJ45 4               | 7            | 4             | Copper  |
+| SFP right            | 3            | 6             | SFP+    |
+
+### Serial console
+
+The PCB has three unpopulated through-holes intended for a slide switch, directly connected to UART0.
+Numbered from the left (SFP port side), the pinout is:
+
+| Position (left→right) | Signal | GPIO                     |
+|-----------------------|--------|--------------------------|
+| 1 (leftmost)          | RX     | GPIO32\_UART0\_RX (32)   |
+| 2 (middle)            | GND    | GND                      |
+| 3 (rightmost)         | TX     | GPIO31\_UART0\_TX (31)   |
+
+- **Settings**: 115200 baud / 8N1 / 3.3V TTL
+- Connect a USB-TTL adapter: adapter TX → pin 1, GND → pin 2, adapter RX → pin 3
+
+### LED configuration
+
+Copper ports use LED SET0, SFP ports use LED SET1.
+
+| SET  | LED0                                             | LED2                                              |
+|------|--------------------------------------------------|---------------------------------------------------|
+| SET0 | Amber — lights on 2.5G link                      | Green — lights on 1G / 100M / 10M link            |
+| SET1 | All speeds — lights on any link with activity    | —                                                 |
+
+LED pad to physical port mapping:
+
+| GPIO pads | Port                    |
+|-----------|-------------------------|
+| GPIO8–11  | Physical port 5 (left SFP)  |
+| GPIO12–14 | Physical port 1 (RJ45 1)    |
+| GPIO15–17 | Physical port 2 (RJ45 2)    |
+| GPIO18–20 | Physical port 3 (RJ45 3)    |
+| GPIO21–23 | Physical port 4 (RJ45 4)    |
+| GPIO24–27 | Physical port 6 (right SFP) |
+
+### SFP GPIO assignments
+
+| SFP              | pin\_detect (ModAbs)        | pin\_los               | SerDes | I2C SDA              | I2C SCL                  |
+|------------------|-----------------------------|------------------------|--------|----------------------|--------------------------|
+| Left (logical 8) | GPIO30\_ACL\_BIT3\_EN       | GPIO37                 | SDS1   | GPIO39\_I2C\_SDA4    | GPIO40\_I2C\_SCL3\_MDC1  |
+| Right (logical 3)| GPIO50\_I2C\_SCL2\_UART1\_TX | GPIO51\_I2C\_SDA2\_UART1\_RX | SDS0 | GPIO41\_I2C\_SDA3\_MDIO1 | GPIO40\_I2C\_SCL3\_MDC1 |
+
+GPIO assignments were verified by observing GPIO state changes during SFP module insertion/removal
+and cross-checked against an original firmware register dump.
+`pin_tx_disable` is GPIO\_NA on both ports (original firmware keeps all GPIOs as inputs).
@@ -19,6 +19,9 @@ of the device just above the big label, might be covered by a QC sticker.

 <img src="photos/PCB-K0402WS-V3.0/Ztyuav_Z-QWYT0402_label.jpg" width="300" />

+* Siscolink SL-G0402F
+
+<img src="photos/PCB-K0402WS-V3.0/Siscolink SL-G0402F.jpg" width="300"/>
 ### Programming

 Using SPI clamp in-board is the only method for initial installation.
@@ -1,9 +1,11 @@
-### ZX-SWTGW215AS
+# ZX-SWTGW215AS

 ## Brands
+
 |Brand|Type|Managed|PCB|Flash|Chip RTL|
 |---|---|---|---|---|---|
-| Lianguo | ZX-SWTGW215AS | Yes | PCB-SWTG115AS-V2.0 | FM25Q16A | 8272 |
+| Lianguo | ZX-SWTGW215AS | Yes | PCB-SWTG115AS-V2.0 | FM25Q16A | 8372 |
+| sold as Lianguo, actual device unbranded | ZX-SWTGW215AS | Yes | PCB-SWTG115AS-V2.1 | W25Q16JVSIQ (2MiB) | 8372 |

 ## RTLPlayground target

@@ -12,13 +14,23 @@ Use machine target `MACHINE_LIANGUO_ZX_SWTGW215AS` for this device.
 Physical hardware verification: 5x RJ45 ports + 1x SFP port. 
 Port 5 RJ45 is interfaced through a RTL8221B IC.

-## PCB
+## Label (V2.0)

-<img src="photos/ZX-SWTGW215AS/pcb_top.jpg" width="300" />
+<img src="photos/ZX-SWTGW215AS-V2.0/label.jpg" width="300" />

-# Connectors
+## PCB (V2.0)

-## Port overview
+<img src="photos/ZX-SWTGW215AS-V2.0/pcb_top.jpg" width="300" />
+<img src="photos/ZX-SWTGW215AS-V2.0/pcb_bottom.jpg" width="300" />
+
+## PCB (V2.1)
+
+<img src="photos/ZX-SWTGW215AS-V2.1/pcb-top.jpg" width="300" />
+<img src="photos/ZX-SWTGW215AS-V2.1/pcb-bottom.jpg" width="300" />
+
+## Connectors
+
+### Port overview

 ```
 ┌──────────────────────────────────────────────────────────────────────────────────┐
@@ -36,7 +48,7 @@ Port 5 RJ45 is interfaced through a RTL8221B IC.
 | RJ45 | 3, 4, 5, 6, 7 | 1-5 | 
 | SFP | 8 | 6 |

-## J4
+### J4

 * Location: SFP connector `J4`.
 * Connected to: 10GMAC number 8, SerDes 1.
@@ -48,10 +60,11 @@ Port 5 RJ45 is interfaced through a RTL8221B IC.
 |5|	MODDEF1 – SCL     | GPIO40	| I2C SCL |
 |6|	MODDEF0 – PRESENT | GPIO30 | Detect |
 |8|	LOS	              | GPIO37 | RX Loss of Signal |
-### Notes
+
+#### Notes
 * Not all signals were mapped mechanically, hence they've been left out of documentation.

-## T3, Slave Interface
+### T3, Slave Interface

 This connector goes to U4 `I2C EEPROM` and U10 `SPI FLASH` (mappings identical to SWTG024AS).

@@ -65,11 +78,12 @@ For detailed Slave Interface functionality and protocol information, see [T3 doc
 |4| VCC |
 |5| 33R -> U10-P2 | SPI-DO/D1 | 
 |6| U10-P1 | SPI-CS |
-### Notes
+
+#### Notes
 * 1 pin is square shaped.


-## T5, Serial Console
+### T5, Serial Console

 |`T5` pin|GPIO|Signal|
 |---|---|---|
@@ -77,10 +91,11 @@ For detailed Slave Interface functionality and protocol information, see [T3 doc
 | 2 | GND | |
 | 3 | GPIO32 | U0RXD (Input) |
 | 4 | 3V3 | |
-### Notes
+
+#### Notes
 * 1 pin is square shaped.

-## T8
+### T8

 |`T8` pin|GPIO|Signal|
 |---|---|---|
@@ -91,18 +106,19 @@ For detailed Slave Interface functionality and protocol information, see [T3 doc
 | 5 | GPIO47 | |
 | 6 | GPIO49 | |

-### Notes
+#### Notes
 * 1 pin is square shaped.
 * Mapping unverified but assumed the same as [LIANGUO SWTG024AS](SWTG024AS.md#t8).

-# Reset Circuit
+## Reset Circuit
 | Function | GPIO |
 |---|---|
 | Reset button | GPIO54 |
+
 ### Notes
 * Circuit is active-low

-# GPIO
+## GPIO

 Note: T3/U4/U10-related signal annotations below are copied from [LIANGUO SWTG024AS T3 section](SWTG024AS.md#t3-slave-interface) as well as T8 port from [LIANGUO SWTG024AS T8 section](SWTG024AS.md#t8). They should be treated as assumed identical for ZX-SWTGW215AS as it has not been 100% confirmed true at the moment. 

@@ -141,7 +157,7 @@ Note: T3/U4/U10-related signal annotations below are copied from [LIANGUO SWTG02
 | 40000000 | GPIO30 | J4-6 | SFP DETECT |  | GPIO62 |   |  |
 | 80000000 | GPIO31 | T5-1 | U0TXD |  | GPIO63 |   |  |

-# LEDs
+## LEDs

 | NAME | GPIO | Port(s) | Function | Notes |
 | ---- | ---- | ---- | ---- | ---- |
@@ -162,3 +178,6 @@ Note: T3/U4/U10-related signal annotations below are copied from [LIANGUO SWTG02

 While [SWTG024AS.md](SWTG024AS.md) can be used as a general reference for hardware concepts and interface specifications, this device should not be assumed to be identical beside the difference implicitely highlighted below. Not all information has been validated for compatibility with the SWTG215AS. Consult the SWTG024AS documentation with caution and verify any critical details against this device's.

+## Flashing
+
+For devices with Winbond 25Q16JVSIQ, flashing is possible for example using flashprog with device "W25Q16.V". Note that you should not overwrite the whole flash to keep device-specific data (like the MAC address at 0x1fc000). Also, creating a backup of the entire falsh before is of course a very good idea.
@@ -65,3 +65,36 @@ ASIC and flushing the table in order to quickly forget the learned entries.
 3c:18:a0:7e:11:00 0x0001  learned 5
 1c:2a:a3:23:00:02 0x0001  learned 7
 ```
+
+## Static multicast entries
+
+Slow-protocol frames such as LACPDUs and STP BPDUs have to reach the CPU
+without being flooded to the other ports. No bridge relays these frames:
+their addresses are in the set that 802.1D-2004 clause 7.12.6 forbids a
+bridge to forward, and what travels the network is the information, with
+every bridge regenerating BPDUs of its own on its designated ports. The reserved-multicast *trap* action
+cannot do that on this hardware, because its destination is an external CPU
+attached to a physical port, which these boards do not populate. The protocol
+modules therefore leave the reserved-multicast action at *forward* and constrain
+the egress with a static L2 multicast entry instead: the lookup hits the entry's
+own port mask rather than the VLAN flood mask. Verified on a SWTGW218AS both
+ways, with the CPU bit cleared, where delivery stops, and with the CPU bit alone,
+where nothing egresses.
+
+`port_l2mc_set()` writes one such entry. The SMI layout is the L2 multicast
+variant of the table entry:
+
+```
+DATA_IN_A = MAC bytes 5..2                            -> c2 00 00 <mac_last>
+DATA_IN_B = MAC[1..0] | vid<<16 | IVL<<29 | pmask[1:0]<<30
+DATA_IN_C = pmask[9:2]
+```
+
+Lookups are IVL, so an entry made for VID 0 is never matched and a caller adds
+one entry per PVID in use. The write goes through the table access register
+with the table selector set to the L2 lookup table, `TBL_L2_UNICAST` in the
+code, a name that despite appearances covers the multicast entries as well.
+The hardware hashes MAC and VID to pick the bucket slot by itself.
+Writing the same MAC and VID again replaces the entry rather than adding a
+second one, so a caller can retarget the mask at will, for instance back to all
+ports to restore flooding.
@@ -0,0 +1,155 @@
+# Spanning Tree (STP / RSTP)
+
+The switch can take part in a spanning tree (IEEE 802.1D / 802.1w) so that
+redundant links between bridges are blocked instead of forming a loop. The
+implementation elects a root bridge from the BPDUs it receives, promotes ports
+to forwarding once their listen period expires, ages the root out when it goes
+silent, and blocks a port on which it sees its own BPDU.
+
+STP can be enabled and controlled via the web interface or the command line,
+as follows:
+
+## Quick start
+
+```
+stp on                  # start participating
+stp off                 # stop, all ports back to forwarding
+```
+
+Live status is on the Spanning Tree page of the web UI (or `/stp.json`),
+and on the serial console via `stp status`.
+
+With no other bridge around, the switch elects itself root and every port ends
+up forwarding — you can leave it on safely. Put the settings in the startup
+config to make them survive a reboot:
+
+```
+stp prio 15
+stp port 1 edge on
+stp on
+```
+
+## Hardware background
+
+BPDUs are addressed to `01:80:C2:00:00:00`, a reserved link-local group. The
+ASIC's Reserved-Multicast action for that address decides what happens to the
+frame.
+
+Forwarding to the CPU port works normally: the 8051 sits behind an ordinary
+port of the internal switch and is an ordinary member of a forwarding mask.
+The *trap* action does not deliver to it. Its destination is an external CPU
+attached to a physical port (`cpuTag_externalCpuPort_set`, `EXT_CPU_CTRL` in
+the vendor SDK), which these boards do not populate. The ACL trap and
+redirect actions do not deliver to the 8051 either.
+
+Delivery therefore uses the *forward* action, constrained to the CPU port
+by a static L2 multicast entry (`port_l2mc_set()`), one per VLAN in use:
+
+* while STP runs, the entry's member mask is the CPU port only — BPDUs reach
+  the CPU and are not flooded to other ports, as a participating bridge
+  requires;
+* with STP off, the same entries are retargeted to all ports, restoring the
+  transparency an unmanaged switch is expected to have, so a surrounding
+  spanning tree can span *through* this device.
+
+A BPDU delivered this way is an ordinary frame to the port's ingress logic
+and passes through its acceptable-frame-type filter. BPDUs are untagged, so a
+port set to admit tagged frames only (`ingress <port>t`) never delivers one
+to the CPU. `stp_setup()` prints a warning for every STP-enabled port in that
+state.
+
+Port states live in `RTL837X_MSTP_STATES (0x5310)`, two bits per port:
+`00` disabled, `01` blocking, `10` learning, `11` forwarding. A port in
+blocking forwards nothing between ports, but it still sends what the CPU
+hands it and still passes a received BPDU up to the CPU, which is what lets
+loop detection go on working on a port it has already blocked.
+
+## Timers
+
+`stp_timers()` runs at 50 Hz (the main loop idles on the 200 Hz system tick and
+STP is called every fourth pass), which is what `STP_HZ` in `rtl837x_stp.h`
+encodes. All configured values are in seconds:
+
+| setting | default | range |
+|---|---|---|
+| `stp hello <n>` | 2 | 1–10 |
+| `stp maxage <n>` | 20 | 6–40 |
+| `stp fwd <n>` | 15 | 4–30 |
+| `stp txhold <n>` | 6 | 1–10 |
+
+A port entering the tree spends `fwd` seconds in blocking before it forwards
+(an edge port skips the wait). Root information is discarded after `maxage`
+seconds without a BPDU, and the switch then reclaims the root role.
+
+## Topology changes
+
+A change on a local non-edge port (the link coming or going, a port promoted
+to forwarding) flushes the addresses learned on it and sets the TC flag in
+our BPDUs for `maxage + fwd` seconds. A TC flag received in a BPDU is passed
+on: the switch flushes the other non-edge ports once and keeps the flag in
+its own BPDUs until one hello after the last flagged frame, so the
+notification crosses the switch instead of dying at it. A legacy TCN is
+acknowledged with TCA and then treated like a local change.
+
+## Bridge settings
+
+```
+stp prio <0-15>         # bridge priority = n * 4096, default 8 (32768)
+stp version rstp|stp    # RST BPDUs (default) or legacy Config BPDUs
+stp hello|maxage|fwd|txhold <seconds>
+```
+
+The bridge with the lowest priority wins the root election; ties are broken by
+the MAC address. If you do not want this switch to become the root of an
+existing network, give it a worse priority than the current root — `stp prio 15`
+(61440) is the usual "never me" value.
+
+## Per-port settings
+
+```
+stp port <1-9> on|off              # take part in STP, or stay plain forwarding
+stp port <1-9> edge on|off|auto    # host-facing port handling (default: auto)
+stp port <1-9> cost <0-200000000>  # path cost, 0 = automatic (20000)
+stp port <1-9> prio <0-240>        # port priority, steps of 16
+stp port <1-9> guard none|bpdu|root
+stp port <1-9> filter on|off       # neither send nor accept BPDUs
+stp port <1-9> p2p auto|on|off
+```
+
+**edge** — an edge port forwards immediately and does not trigger a
+topology change when its link comes and goes; `auto` promotes a port to edge
+after three seconds without a BPDU, and demotes it as soon as one arrives. Use
+`edge on` for ports where only hosts are attached.
+
+**guard** — `bpdu` disables a port as soon as a BPDU arrives on it (a host port
+should never see one); `root` keeps a port from ever becoming the path to the
+root, which protects an existing topology from a newly attached bridge that
+claims a better priority.
+
+**filter** — the port neither sends nor accepts BPDUs. Useful when the device
+on the far side reacts badly to them (some unmanaged switches with loop
+prevention cut the link) but you still want STP on the rest of the ports.
+
+## Status
+
+The Spanning Tree page shows the elected root (priority and MAC), the path cost
+to it, the root port, the topology-change counter and, per port, the live state
+read from the ASIC together with the configured options. The same data is
+available as JSON:
+
+```
+GET /stp.json
+```
+
+The `stp status` command prints the same view on the serial console.
+
+## Limitations
+
+* One spanning-tree instance; no MSTP, no per-VLAN trees.
+* No proposal/agreement handshake — an RST-capable neighbour will still
+  converge, but through the timers rather than the fast transition.
+* Port roles are approximated: the root port and designated ports are
+  distinguished, alternate/backup are not.
+* Topology changes propagate away from the root only: nothing is announced
+  on the root port (no TCN and no BPDUs at all), so bridges upstream rely on
+  their own detection.
@@ -7,6 +7,7 @@ The following devices have been tested and are fully working:
 | Davuaz   | Da-K6501W       | No      | [PCB-K0501W-V2.0](devices/K0501W_V2_0.md)                                 |       | 5 + 1 |
 | FOXNEO   | FNS-1200P       | No      | [PCB-K0402W-U13-V2.0](devices/FNS-1200P.md)                               | 2M    | 4 + 2 |
 | Hisource | Hi-K0402WS      | No      | [PCB-K0402WS-V3.0](devices/PCB-K0402WS-V3.0.md)                           |       | 4 + 2 |
+| Hisource | Hi-K0402WS      | No      | [PCB-K0402WS-V2.0](devices/PCB-K0402WS-V2.0.md)                           | 2M    | 4 + 2 |
 | Hisource | Hi-K0801WS      | No      | [PCB-KO801W-V2.0](devices/HI-K0801WS.md)                                  |       | 8 + 1 |
 | hongyavision | LG-SG5T1    | No      | [PCB-SWTG024AS-V2.0_16895](devices/SWTG024AS-V2.0.md)                     | 0.5M  | 5 + 1 |
 | Horaco   | HC-SWTGW215AS   | Yes     | [SWTG024AS-A-V2.0.1_19650 5C 1SFP](devices/SWTG024AS-A-V2.0.1_5C_1SFP.md) | ?     | 5 + 1 |
@@ -15,13 +16,16 @@ The following devices have been tested and are fully working:
 | Horaco   | ZX310S-4T2XT    | Yes     | [PCB-SL310S-4T2XT-V1.0.0-22273](devices/ZX310S-4T2XT.md)                  | 2M    | 6     |
 | Horaco   | ZX-SG4T2        | No      | [SWTG024AS-A-V2.0.1_19650_4C_2SFP](devices/SWTG024AS-A-V2.0.1_4C_2SFP.md) | 0.5M  | 4 + 2 |
 | Horaco   | ZX-SWTG124AS    | Yes     | [SWTG024AS-v2.0](devices/SWTG024AS.md)                                    |       | 4 + 2 |
-| Keeplink | KP-9000-6XH-X2  | No      | [2M-PCB43-V2.1](devices/KP-9000-6XH-X2.md)                                |       | 4 + 2 |
+| Keeplink | KP-9000-6XH-X2 / KP-9000-6XHML-X2 | No/Yes | [2M-PCB43-V1.2 / V2.1](devices/KP-9000-6XH-X2.md) |       | 4 + 2 |
 | keepLINK | KP-9000-9XHML-X | Yes     | [2M-PCB23-V2.2](devices/2M-PCB23-V2_2.md)                                 | 2M    | 8 + 1 |
 | keepLINK | KP-9000-9XHML-X | Yes     | [2M-PCB23-V3.1](devices/2M-PCB23-V3_1.md)                                 | 2M    | 8 + 1 |
 | LIANGUO  | SWTG024AS       | No      | [SWTG024AS-v2.0-17452](devices/SWTG024AS.md)                              | 0.5M  | 4 + 2 |
-| Lianguo  | ZX-SWTGW215AS   | Yes     | [PCB-SWTG115AS-V2.0](devices/SWTGW215AS.md)                               | 2M    | 5 + 1 |
+| Lianguo  | ZX-SWTGW215AS   | Yes     | [PCB-SWTG115AS-V2.0 / PCB-SWTG115AS-V2.1](devices/SWTGW215AS.md)          | 2M    | 5 + 1 |
+| Mokerlink| 2G040210GSM     | Yes     | [2M-PCB43-V1.1](devices/2M-PCB43-V1.1.md)                                 |       | 4 + 2 |
 | Mokerlink| ZX-SWTGW218AS   | Yes     | [SWTG118AS-V2.0-16029](devices/SWTGW218AS.md)                             | 2M    | 8 + 1 |
 | Ruiying  | RY-4GT-2SX      | No      | [FG-4GT-2SX_V2.0](devices/FG-4GT-2SX_V2.0.md)                             | 4M    | 4 + 2 |
+| Ruiying  | RY-8GT-1SX      | No      | [FG-8GT-1SX](devices/FG-8GT-1SX.md)                                       | 1M    | 8 + 1 |
+| SiscoLink | SL-G0402F      | No      | [PCB-K0402WS-V3.0](devices/PCB-K0402WS-V3.0.md)                           |       | 4 + 2 |
 | Sodola   | SL-SWTG124AS-D  | Yes     | [SWTG024AS-v2.0-17452](devices/SWTG024AS.md)                              | 2M    | 4 + 2 |
 | Steamemo | IG204-V1        | No      | [PB-2131](devices/STEAMEMO_IG204_V1.md)                                   |       | 4 + 2 |
 | TrendNet | TEG-S562        | No      | [TEG-S563/EU H/W: V1.0R](devices/TEG-S562.md)                             | 2M    | 4 + 2 |
@@ -29,6 +33,10 @@ The following devices have been tested and are fully working:
 | XikeStor | SKS3200-8E1X    | Yes     | [SWTG118AS-V2.1-17462](devices/SWTGW218AS.md)                             | 2M    | 8 + 1 |
 | Ztyuav   | Z-QWYT0402      | No      | [PCB-K0402WS-V3.0](devices/PCB-K0402WS-V3.0.md)                           |       | 4 + 2 |

+For KP-9000-6XH-X2 / KP-9000-6XHML-X2 / Mokerlink 2G040210GSM devices, select
+the machine target by PCB revision. The ML/non-ML or managed/unmanaged label
+alone does not identify the wiring.
+
 Other device based on RTL8272/3 that may work are described here: [Up-N-Atoms 2.5 GBit RTL Switch hacking guide](https://github.com/up-n-atom/SWTG118AS)

 Many of the RTL8272/3 devices come in versions with PoE support. The RTLPlayground usually also
@@ -69,9 +69,9 @@ void vlan_delete(uint16_t vlan) __banked;
 # VLAN configuration on the Serial Console
 For testing the following commands are provided on the serial console:
 ```
-vlan <VLAN-ID> p[t/u]...
-  create or set vlan with given ID and the list of ports as members, a t
-  behind a port defines the port as a tagged member, the u is optional
+vlan <VLAN-ID> p[t]...
+  create or set vlan with given ID and the list of ports as members, a `t`
+  behind a port defines the port as a tagged member.

 vlan <VLAN-ID> d
  deletes the VLAN