docs: link-local frame transparency on kernel links — spec and per-datapath sections

A Linux bridge standing in for a cable does not forward the IEEE 802.1D
reserved range (01:80:c2:00:00:00-0f) by default, so LACP/LLDP/802.1X never
crossed a kernel-datapath link while the UDP relay carried them fine. uBridge
now opens every enslave'd port's IFLA_BRPORT_GROUP_FWD_MASK to 0xfffd at
brctl addif time (branch feature/bridge-tap-l2only, commits 0284500/03a18f1/
cf4e494), which the six kernel-datapath feature docs now document as a
section: STP, LACP, 802.1X and LLDP/DCBX cross; 802.3x PAUSE / PFC stays
dropped — br_handle_frame()'s case 0x01 discards it unconditionally, no mask
can enable it, and PFC labs must use a relay link. The full contract, kernel
references and requirements live in the new design spec, marked landed.

docs/features/docker-kernel-datapath.md

@@ -333,6 +333,27 @@ Semantics:
   nothing — older servers, failed probe — keep the full list;
   apply-time validation (409) stays the guard.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
 ## uBridge command surface
 
 No uBridge changes were needed beyond the marker module's `*_kernel` commands

docs/features/dynamips-kernel-datapath.md

@@ -93,6 +93,27 @@ filters are one tc netem qdisc per anchor plus cls_bpf/eBPF drops. A relay
 port keeps its Dynamips NIO and the node's uBridge relay bridge
 (`DYNAMIPS-*`) with userspace filters, exactly as before.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
 ## Relay fallback
 
 A uBridge without the tap module keeps the node relay-only: `_prepare_tap_datapath`

docs/features/ethernet-switch-kernel-datapath.md

@@ -118,6 +118,32 @@ sequence by hand against uBridge (held TAPs, no server involved) did not
 reproduce it, and the in-place reconcile removes the operation entirely —
 the failure mode no longer exists by construction.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
+The switch node's own bridge ports carry the same mask: the builtin
+Ethernet switch is a transparent L2 segment in GNS3, not a protocol
+endpoint, so LACP/LLDP between two peers crosses it (a physical switch
+would terminate them itself).
+
 ## Verified
 
 Unit level (all under `tests/`): the switch's kernel-port lifecycle (join

docs/features/iol-docker-kernel-datapath.md

@@ -122,6 +122,27 @@ traffic stops both ways. The runner itself is unaware of the link state
 (netiomux has no carrier signal), exactly as on the relay datapath where
 suspend rode the synthetic frequency_drop filter instead.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
 ## Relay fallback
 
 Missing either capability, the node runs relay-only: links ride

docs/features/iou-kernel-datapath.md

@@ -101,6 +101,27 @@ one tc netem qdisc per anchor plus cls_bpf/eBPF drops — the port's
 userspace `iol_bridge add_packet_filter` filters carry relay links only and
 are never combined with tc on the same port.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
 ## Relay fallback
 
 A uBridge without `iol_bridge add_nio_tap` (old build) keeps the node on the

docs/features/qemu-kernel-datapath.md

@@ -110,6 +110,27 @@ Identical to Docker's kernel links, on the TAP: `capture start_kernel <tap>`
 direction is impaired once. `frequency_drop`/`quota`/`window_drop` run as the
 eBPF classifier on the anchor's clsact egress.
 
+## Link-local frames (LACP, LLDP, 802.1X, STP)
+
+The bridge stands in for a cable, but the kernel's `br_handle_frame()` does
+not forward the IEEE 802.1D reserved range (`01:80:c2:00:00:00`-`0f`) by
+default — LACP, LLDP/DCBX and 802.1X would never cross a kernel link while
+the UDP relay carries them fine. uBridge therefore opens every port's
+per-port `group_fwd_mask` (`IFLA_BRPORT_GROUP_FWD_MASK`) to `0xfffd` at
+`brctl addif` time (Linux 4.15+, best-effort on older kernels). The
+bridge-level knob cannot do this: `BR_GROUPFWD_RESTRICTED` rejects bits 0-2,
+so LACP is reachable per port only.
+
+Result on kernel links: ordinary multicast, STP/RSTP, LACP, 802.1X and
+LLDP/DCBX all cross; **802.3x PAUSE / PFC does not** — `case 0x01` in
+`br_handle_frame()` drops it unconditionally and no mask can enable it.
+That is a documented limit, not a regression (PFC's hardware semantics are
+out of emulation's reach anyway); a lab that needs PAUSE frames on the wire
+must use a relay link. Verified live by
+`tests/e2e/test_docker_link_local_frames.py` (per-MAC guest-to-guest
+matrix); the contract and kernel references live in
+`docs/design/ubridge-link-local-frame-forwarding-spec.md`.
+
 ## Legacy fallback
 
 A uBridge build without the `tap` module (or without `CAP_NET_ADMIN`) keeps