Module codec 

Pure BPDU codec — IEEE 802.1D-2004 (STP) and 802.1w (RSTP).

Nothing in this file touches a socket, a capture handle, the LLM or AppState. It is a total function from structured values to bytes and back, which is the only part of this protocol that can be proved correct in this environment: the raw 802.3 transport in mod.rs needs CAP_NET_RAW//dev/bpf* and has never been executed. See src/server/stp/CLAUDE.md for exactly what is proved and what is not.

Wire layout

A BPDU is carried in an 802.3 length-encapsulated frame with an 802.2 LLC header, not in an EtherType-II frame:

 0.. 6  destination MAC   01:80:C2:00:00:00 (the Bridge Group Address)
 6..12  source MAC        the transmitting bridge port
12..14  length            octets of MAC client data: 3 (LLC) + BPDU length
14..17  LLC               DSAP 0x42, SSAP 0x42, control 0x03 (unnumbered information)
17..    BPDU              35 bytes (config), 36 (RST), or 4 (TCN)

Configuration BPDU body (802.1D-2004 §9.3.1), offsets relative to the start of the BPDU:

 0.. 2  protocol identifier   always 0x0000
 2      protocol version      0 = STP, 2 = RSTP
 3      BPDU type             0x00 config, 0x02 RST, 0x80 TCN
 4      flags                 see BpduFlags
 5..13  root identifier       priority(4b) | system ID extension(12b) | MAC(6)
13..17  root path cost
17..25  bridge identifier     same packing as the root identifier
25..27  port identifier       priority(4b) | port number(12b)
27..29  message age           1/256 s
29..31  max age               1/256 s
31..33  hello time            1/256 s
33..35  forward delay         1/256 s
35      version 1 length      RST BPDUs only, always 0x00

Two things this file exists to get right

Timers are in 1/256-second units, not seconds. The default values every capture shows are max age 20 s = 0x1400, hello time 2 s = 0x0200, forward delay 15 s = 0x0F00. An implementation that writes seconds directly produces a BPDU claiming a 20/256-second max age, which a real bridge will act on. tests/server/stp/codec_test.rs asserts these byte pairs against literals.

The 16-bit priority field is two fields. Since 802.1t / 802.1Q the high 4 bits are the bridge priority and the low 12 bits are the system ID extension (in practice the VLAN id). So priority is only expressible in steps of 4096, and 0x8001 is priority 32768 on VLAN 1 — not “priority 32769”. Both halves are surfaced separately by BridgeId so the model never has to pack them itself.

Structs

BpduFlags

The BPDU flags octet, as structured booleans plus the port role.

BridgeId

A bridge identifier: 4-bit priority, 12-bit system ID extension, 6-byte MAC.

ConfigBpdu

A Configuration BPDU (802.1D type 0x00) or a Rapid Spanning Tree BPDU (802.1w type 0x02).

Frame8023

A decoded 802.3 + LLC frame with the BPDU body extracted.

PortId

A port identifier: 4-bit priority, 12-bit port number.

Enums

Bpdu

Any BPDU this codec understands.

PortRole

RSTP port role, flags bits 2-3 (802.1w §9.3.3).

Constants

BPDU_TYPE_CONFIG

BPDU_TYPE_RST

BPDU_TYPE_TCN

BRIDGE_PRIORITY_MAX

The largest expressible bridge priority (15 * 4096).

BRIDGE_PRIORITY_STEP

Bridge priority occupies the top 4 bits of a 16-bit field, so it moves in steps of 4096.

CONFIG_BPDU_LEN

ETHERNET_HEADER_LEN

802.3 MAC header: destination(6) + source(6) + length(2).

LLC_CONTROL

LLC_DSAP

802.2 LLC header for the Spanning Tree Protocol: DSAP/SSAP 0x42, UI control 0x03.

LLC_HEADER_LEN

LLC_SSAP

MAX_8023_LENGTH

The largest value the 802.3 length field can carry as a length.

MIN_ETHERNET_FRAME_LEN

Minimum 802.3 frame excluding the FCS. Shorter frames are padded on transmit.

PORT_NUMBER_MAX

The largest expressible port number (12 bits).

PORT_PRIORITY_MAX

The largest expressible port priority (15 * 16).

PORT_PRIORITY_STEP

Port priority occupies the top 4 bits of the 16-bit port identifier.

PROTOCOL_ID

RST_BPDU_LEN

STP_MULTICAST_MAC

The Bridge Group Address every BPDU is sent to (802.1D-2004 Table 7-9).

SYSTEM_ID_EXTENSION_MAX

The largest expressible system ID extension (12 bits).

TCN_BPDU_LEN

TIMER_TICKS_PER_SECOND

Timer fields are expressed in units of 1/256 second.

VERSION_RSTP

VERSION_STP

Functions

decode_frame

Parse an 802.3 + LLC frame and hand back the BPDU body.

encode_frame

Wrap a BPDU body in an 802.3 + LLC frame, padded to the 60-octet minimum.

encode_tcn_bpdu

The complete four-octet Topology Change Notification BPDU.

format_mac

Render six octets as aa:bb:cc:dd:ee:ff.

parse_mac

Parse aa:bb:cc:dd:ee:ff (or the - separated form) into six octets.

seconds_to_ticks

Seconds → the 1/256-second unit the wire uses.

ticks_to_seconds

The 1/256-second unit the wire uses → seconds.