MontaukOS/docs/wifi.md

to-do: rewrite & convert to html for docs pages

Wi-Fi

MontaukOS drives Intel AX210-family adapters (the reference part is the AX211). The driver scans, joins open and WPA2/WPA3-PSK networks, and presents itself to the network stack as an ordinary Ethernet interface, so dhcp, ping, nslookup and anything speaking sockets work over Wi-Fi exactly as they do over a cable.

wifi scan                        list nearby networks
wifi connect <ssid> <passphrase> join one
dhcp                             pick up an address
wifi status                      what you are connected to

Layout

kernel/src/Drivers/Net/Wifi/
  IwxTrans.cpp    PCIe transport: MMIO, MSI-X, DMA rings, firmware boot,
                  host commands, RX processing, frame TX, key installation
  IwxFw.cpp       .ucode / .pnvm TLV parsing
  IwxMvm.cpp      post-ALIVE init, NVM, UMAC scan, RX dispatch
  IwxConnect.cpp  MLME: contexts, authenticate, associate, 802.11 <-> Ethernet
  Wpa.cpp         WPA2/WPA3-PSK supplicant (EAPOL 4-way + group rekey)
  Ieee80211.hpp   frame, element and RSN constants
  Wifi.cpp        subsystem facade: probe, scan table, syscalls, netif hooks
kernel/src/Libraries/Crypto.cpp   SHA-1/SHA-256, HMAC, PBKDF2, AES, CMAC
kernel/src/Net/NetIf.cpp          interface registry the Ethernet layer uses

Joining a network

SYS_WIFI_CONNECT blocks until the link is up or the attempt fails, and returns a WIFI_ERR_* code the wifi tool turns into a specific message (wrong passphrase, unsupported security, AP out of range, and so on).

The sequence:

1. Look up the BSS. The SSID is matched against the scan table, strongest signal first. If it is not there, one scan is run automatically and the lookup retried, so wifi connect works without scanning first.
2. Negotiate ciphers. The AP's RSN element (kept verbatim in the scan table) picks the pairwise cipher and AKM. CCMP is preferred over GCMP, plain PSK over PSK-SHA256.
3. Derive the PMK. PBKDF2-HMAC-SHA1 over the passphrase with the SSID as salt, 4096 iterations. A 64-character hex string is taken as a raw PSK instead.
4. Bring up firmware contexts. PHY, MAC, binding and station, then one TX queue on the management TID.
5. Authenticate and associate. Open-system authentication, then an association request carrying the SSID, supported rates and, for encrypted networks, the RSN element the supplicant built. Both are retransmitted up to four times at 400 ms.
6. Run the 4-way handshake. EAPOL-Key messages 1-4, then the pairwise key and the group key go into the firmware with ADD_STA_KEY.
7. Report the link up. Only now does NetIf see wlan0 as usable.

The data path

Once associated the driver translates between 802.11 and Ethernet II:

• TX - an Ethernet frame becomes a to-DS 802.11 data header plus an RFC 1042 LLC/SNAP shim carrying the EtherType. The protected bit is set once keys are installed and the firmware does the CCMP encryption.
• RX - the firmware decrypts and strips the MIC but leaves the 8-byte CCMP header, which is skipped; the LLC/SNAP shim is replaced by an Ethernet header built from addresses 1 and 3. EAPOL frames are diverted to the supplicant instead.

One TX queue carries management frames, EAPOL and non-QoS data. The firmware maps non-QoS data onto the management TID anyway, and the driver never negotiates block-ack sessions that would need per-TID queues.

Threading

The RX path runs under IwxProcessEvents()'s reentrancy guard and must not send a host command - the command's completion is pumped by the very function it would be re-entering. Anything needing a command (post-association context updates, key installation, and therefore the whole EAPOL handshake) is queued and applied from IwxConnectService(), which every idling core calls and which is itself serialized. Transmitting is safe from either context: it only writes a descriptor and rings the doorbell.

Never wait on the clock under a spinlock

kcp::Spinlock::Acquire() does cli, and Timekeeping::GetMilliseconds() is driven by the APIC timer interrupt. A wall-clock timeout inside a spinlock therefore cannot expire: the counter never advances, the loop never ends, and the machine locks solid with interrupts off - no mouse, no keyboard, no scheduler. This is the same trap ApicTimer.cpp documents for the idle path.

IwxSendCmd holds a lock across a wait for the firmware's reply, so that lock is a kcp::Mutex (which keeps interrupts enabled), and the wait carries a spin cap as well as the clock check so it terminates even if the clock is somehow stuck. It also bails immediately once the firmware is known to have asserted, because nothing after that will ever be answered.

A firmware command that goes unanswered now dumps the firmware's own error table on the first timeout - that names the command that asserted - and gives up on the adapter after three, rather than stalling for seconds per command.

Sample the clock after the work, not before it

IwxConnectService() sends host commands, and every one of them is a round trip to the adapter that takes real milliseconds. Each step also stamps the timestamp its deadline is measured from - EnterState() sets g_stateEnteredMs, transmitting sets g_lastTxMs. A now read at the top of the pass is therefore older than the stamps it is about to be compared against, and because these are unsigned counters, now - g_stateEnteredMs wraps to about 2^64 instead of going negative. Every deadline in the pass then reads as long expired.

The symptom was a join that failed the instant it succeeded:

WiFi: [OK] Associated, AID 3
WiFi: [WARNING] Connection failed: timed out while joining the network
WiFi: [INFO] EAPOL frame received (99 bytes)

The two post-association context commands moved the clock forward, the timeout check compared a stale now against the g_stateEnteredMs they had just set, and the contexts came down before the access point's first EAPOL frame could arrive - which is why message 1 shows up after the failure. So the clock is read only once the command-sending work in the pass is done, and the comparisons go through Elapsed(), which refuses to underflow.

Teardown unwinds contexts in the order they depend on each other

Firmware 89 asserts when a context is taken away while another still points at it, and the assert names the command rather than the reason. Three of these have been hit so far:

UMAC error	Cause
0x2010330F	PHY binding and link activation folded into one LINK_CONFIG
0x2010330E	link removed while its station still existed
0x2000320F	link deactivated while the MAC was still marked associated

The last one is the teardown side of the same rule. While MAC_CONFIG.is_assoc is set, the firmware's MAC context owns the link carrying the BSS, so TearDown() sends a MAC_CONFIG MODIFY clearing is_assoc first, and only then removes the station, deactivates the link, removes the link, removes the MAC and drops the PHY context - the order iwl_mvm_mld_vif_cfg_changed_station and the paths below it use on the way down. tests/wifi/ap_mlme.py pins that order.

The interface registry

Net::NetIf replaced the Ethernet layer's direct calls into the E1000 drivers. Drivers register a name, a kind, and three function pointers; the stack sends through NetIf::Active(), which prefers a wired interface with a link and otherwise takes the first interface reporting one. A Wi-Fi-only machine therefore has no link until it joins a network, and a machine with a cable plugged in keeps using it.

SYS_NETSTATUS reports whichever interface is active, so ifconfig shows the wireless counters once Wi-Fi is carrying traffic.

What is supported

Open networks	yes
WPA2-PSK, CCMP or GCMP	yes
WPA2-PSK-SHA256	yes
WPA3 transition mode (PSK advertised alongside SAE)	yes, joins via PSK
Group key rekeying	yes
WPA3-only (SAE)	no
Management frame protection required (MFPR)	no
WEP, original WPA / TKIP	no
802.1X enterprise (EAP)	no
Block-ack aggregation, HT/VHT/HE rates	no - legacy rates only

SAE needs finite-field or elliptic-curve arithmetic that does not belong in this kernel, and MFP needs BIP. Both are rejected up front with a specific log line rather than failing partway through a handshake. Mixed WPA/WPA2 networks that still broadcast under TKIP are refused for the same reason: the pairwise key would install but every broadcast frame would be dropped, which looks like a working connection that cannot get a DHCP lease.

Crypto

kernel/src/Libraries/Crypto.cpp exists because the supplicant runs in the kernel and BearSSL is a userspace library. It provides SHA-1, SHA-256, HMAC over both, PBKDF2-HMAC-SHA1, AES-128/256, RFC 3394 key wrap/unwrap and AES-CMAC. It is not a general-purpose crypto library and should not be used as one.

Testing

./tests/wifi/run.sh compiles the shipping sources for the host against a small shim and drives them from Python. It is the real Crypto.cpp, Wpa.cpp and IwxConnect.cpp, not a copy, with only the transport stubbed.

• Crypto primitives against the published vectors - FIPS-197 for AES, RFC 2202/4231 for HMAC, RFC 3394 for key wrap, RFC 4493 for CMAC, and the IEEE 802.11i Annex H.4 WPA passphrase vectors for PBKDF2.
• The supplicant against an independent authenticator using hashlib and cryptography: messages 2 and 4 carry MICs that verify under a PTK the AP derived itself, the installed TK and GTK match the AP's, a wrong passphrase produces a MIC the AP rejects, group rekeys and message-3 retransmissions are answered, and RSN negotiation picks the right suites across eight real-world information elements.
• The MLME and data path against a simulated AP that decodes every frame the driver emits: the authentication request, the association request and its elements (SSID, rates, capabilities, RSN), the handshake carried inside real 802.11 data frames, key installation arguments, and the encapsulation both ways - to-DS addressing, the protected bit, LLC/SNAP, sequence numbers, broadcast delivery, and the filtering of foreign-BSSID and null-data frames. Also the branches: open networks, retransmission and give-up when the AP is silent, authentication and association rejections, and an AP-initiated deauthentication bringing the link down.
• Firmware context ordering - the MLD command sizes and field offsets against the decoded Linux trace, and the order the teardown unwinds the contexts in, which is what the asserts above are about.

The harness clock advances on every host command (CMD_ROUND_TRIP_MS in mlme_harness.cpp) rather than standing still. That detail matters: a frozen clock makes every elapsed-time comparison in the service loop trivially true or trivially false, and hid the underflow described under "Sample the clock after the work, not before it" - the host tests passed while the adapter could not join a network at all. Anything that reads Timekeeping::GetMilliseconds() should be tested with time actually moving.

What is left needs the adapter, because it is the firmware's opinion rather than the driver's logic: whether the firmware accepts the TX command and TFD layout and actually radiates the frames, whether ADD_STA_KEY installs the keys the driver asks for, whether the RX MPDU descriptor is read correctly off real receptions, and whether association succeeds against a real AP's timing and rate expectations. None of that can be exercised in QEMU, which has no AX210-family device to emulate.