Merge pull request #397 from DrDoof/feat/stp-lag-entity

stp: treat a link aggregation group as one entity

doc/stp.md

@@ -58,6 +58,32 @@ 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.
 
+## Link aggregation
+
+A LAG (Link Aggregation Group) is handled like an additional port by the STP
+protocol, with its own timers and states. The switch devices support up to 4
+LAGs, which are shown alongside the physical ports in the STP status. A group
+carries its own path cost, priority, edge and guard settings, and gets its own
+row on the Spanning Tree page.
+
+```
+stp lag 1 cost 10000    # the group decides, not its members
+stp lag 1 edge off
+```
+
+LAGs are configured via the `lag` command. Once a port is a member of a LAG it
+can no longer be configured individually for STP, so `stp port <n>` on a member
+tells you which group to configure instead. Membership is re-read from the
+aggregation registers once a second, so a group changing under LACP is picked
+up without any coordination between the two.
+
+The switch hardware does not handle STP state for a LAG as a whole. State
+changes for the members have to be done by the firmware, updating every member
+port, which is possible using a single register write. BPDUs go out through the
+lowest member and carry the group's own port id. Losing one member of a live
+LAG is not a topology change; the logical port only goes down with its last
+link.
+
 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