doc: move the L2 multicast and tag word details out of the code

Review asked for this directly: the hardware layout above port_l2mc_set()
would be better as documentation than as a comment, keeping only the two
lines that say what the function does.

doc/l2.md gains a section on static multicast entries, why delivery uses
the forward action rather than the trap, and the SMI layout of the entry.
doc/CpuPort.md gains the layout of the tag's flags and pmask words, with
the byte order trap that cost an afternoon: writing the flags constant raw
instead of through HTONS puts 0x0020 on the wire as 0x2000, which is EFID
rather than LEARN_DIS, and the ASIC then leaves the 0x8899 header on the
frame.

The comments those paragraphs came from are replaced by a pointer to the
file that now holds them.

doc/CpuPort.md

@@ -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

doc/l2.md

@@ -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.