RFC: Wi-Fi Simulation Driver for hostapd/wpa_supplicant Testing (hwsim)

[krish2718]

RFC: Wi-Fi Simulation Driver for hostapd/wpa_supplicant Testing (hwsim)

Summary

Three draft PRs now propose a way to test the Zephyr Wi-Fi stack (hostapd / wpa_supplicant / Wi-Fi mgmt) without physical hardware. This RFC summarises the approaches, compares them, proposes a merge strategy, and asks for community input on the open design questions — particularly around the data-path routing problem that is unique to Zephyr.

PRs under discussion:

• drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236 — drivers: wifi: add hwsim virtual Wi-Fi simulator driver (Chaitanya Tata / krish2718)
• drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 #110681 — drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 (Jukka Rissanen / jukkar)
• drivers: wifi: add emulated Wi-Fi driver  #111194 — drivers: wifi: add emulated Wi-Fi driver (Pieter De Gendt / pdgendt)

---

Background

Testing the Zephyr Wi-Fi stack today requires physical Wi-Fi hardware. Every CI run that wants to exercise the hostapd/wpa_supplicant stack, the EAPOL 4-way handshake, or even just Wi-Fi management event handling must provision a radio. This is slow, fragile, and hard to scale.

Linux solved this problem a long time ago with mac80211_hwsim: a kernel module that creates virtual radios connected by an in-kernel frame-relay bus, isolated per-process with network namespaces. All three PRs take different angles on bringing an equivalent to Zephyr.

---

The Three Approaches

Approach A — PR #111236: Pure in-process Zephyr hwsim (Chaitanya)

Creates N virtual radios inside a single Zephyr image. Each radio is a net_if with Ethernet L2 and Wi-Fi offload ops. An in-process frame-relay bus delivers frames transmitted on one radio to all other radios on the same channel, simulating a shared wireless medium.

  ┌────────────────────────────────────────────┐
  │         wpa_supplicant / hostapd           │
  │          (Zephyr, in-process)              │
  ├──────────┬──────────┬──────────────────────┤
  │  Radio 0 │  Radio 1 │  Radio N             │
  │  (STA)   │  (AP)    │  ...                 │
  ├──────────┴──────────┴──────────────────────┤
  │        In-process frame-relay bus          │
  │  same channel → deliver to all peers       │
  └────────────────────────────────────────────┘
  Runs on: native_sim, QEMU, any Zephyr target

Strengths: No host OS dependency; runs anywhere Zephyr runs; true multi-radio simulation; most portable for CI.

Key open issue: Zephyr has no network namespace support. When the relay bus delivers a frame from Radio 0 to Radio 1, both interfaces live in the same global net_if list. The return path for replies (e.g. EAPOL frames from AP back to STA) may be mis-routed by the shared routing table or silently dropped by the Ethernet L2 loopback guard. See the data-path section below.

---

Approach B — PR #110681: native_sim + host Linux nl80211 (Jukka)

Delegates the RF medium entirely to the Linux kernel. The Zephyr image runs as a native_sim process. The driver links the nl80211 host library directly into the binary and uses it to drive a mac80211_hwsim virtual radio on the host. The Zephyr wpa_supplicant is the sole SME.

  Linux Host
  ┌───────────────────────────────────────────┐
  │  mac80211_hwsim (kernel module)           │
  │    wlan0 (STA) ←──────→ wlan1 (AP)        │
  │       ↕ nl80211 (netlink)                 │
  │  ┌────────────────────────────────────┐   │
  │  │  native_sim Zephyr process         │   │
  │  │  ┌──────────────────────────────┐  │   │
  │  │  │  wifi_native_sim driver      │  │   │
  │  │  │  nl80211 host lib + event    │  │   │
  │  │  │  loop thread                 │  │   │
  │  │  ├──────────────────────────────┤  │   │
  │  │  │  Zephyr wpa_supplicant (SME) │  │   │
  │  │  ├──────────────────────────────┤  │   │
  │  │  │  AF_PACKET socket ↔ net_if   │  │   │
  │  │  └──────────────────────────────┘  │   │
  │  └────────────────────────────────────┘   │
  └───────────────────────────────────────────┘

Strengths: Uses the battle-tested mac80211_hwsim medium; namespace isolation is handled by the host OS so there is no loopback ambiguity; full EAPOL 4-way handshake works today; data-path (AF_PACKET) is clean. Already tested: scan, connect (open + WPA2-PSK), status, disconnect, and data transfer all confirmed working.

Key open issue: Linux-only (native_sim). Testing path for CI is still described as work-in-progress in the PR. Also requires the host to have mac80211_hwsim loaded, which needs kernel module support on the CI runner.

---

Approach C — PR #111194: Offload-style emulated driver (Pieter)

No RF medium at all. Scan results, connection outcomes, and disconnect events are injected at runtime through a wifi_emul test-control API. The driver is an offload-style Zephyr driver that mimics a Wi-Fi-only board.

  ┌────────────────────────────────────────┐
  │  Test / Automation Script              │
  │  wifi_emul_add_ap(ssid, rssi, ...)     │
  │  wifi_emul_set_connect_result(ok/fail) │
  └──────────────┬─────────────────────────┘
                 │ wifi_emul API
  ┌──────────────▼─────────────────────────┐
  │  wifi_emul offload driver              │
  │  - returns scripted scan results       │
  │  - simulates connect/disconnect FSM    │
  │  - no real frame exchange              │
  └──────────────┬─────────────────────────┘
                 │
  ┌──────────────▼─────────────────────────┐
  │  Zephyr Wi-Fi mgmt / net_mgmt / app    │
  └────────────────────────────────────────┘
  Runs on: any Zephyr target, QEMU, native_sim

Strengths: Extremely portable; fully deterministic; perfect for testing the application Wi-Fi event-handling layer (reconnect logic, scan throttling, error handling); zero setup overhead in CI.

Scope: Does not test hostapd / wpa_supplicant / EAPOL at all. This is an intentional design choice, not a gap.

---

The Namespace / Data-Path Problem

This is the hardest Zephyr-specific challenge and affects PR #111236 most directly. It is worth discussing explicitly.

On Linux, mac80211_hwsim creates separate netdevs (wlan0, wlan1, …). Processes in different network namespaces own one each, so the kernel routes frames naturally between them.

Zephyr has no namespace support:

• All net_if instances share a single global interface list.
• There is one routing table with no namespace scoping.
• When the in-process relay bus in PR drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236 delivers a frame from Radio 0 to Radio 1, it must call net_recv_data() on Radio 1. But the Ethernet L2 receives it in the context of a net_if that shares state with Radio 0. The L2 layer can see Radio 1's own MAC in the destination field and process it correctly — but the reply frame from Radio 1 to Radio 0 goes through the shared routing table, which has no concept of "this packet belongs to a different virtual radio"; it may loop back to Radio 1 instead of being delivered to Radio 0.

EAPOL exchange without namespaces (the problem):
Radio 0 (STA, MAC: AA:BB:CC:DD:EE:00)

Radio 1 (AP,  MAC: AA:BB:CC:DD:EE:01)
STA → EAPOL → relay bus → net_recv_data(R1, frame)  ✓

AP  → EAPOL reply → net_if_send() → routing table

→ "dst is AA:BB:CC:DD:EE:00, which net_if?"

→ may pick R1 again if routing table is ambiguous  ✗

The fix is for the relay bus to route reply frames by explicit MAC lookup across the registered radios and call net_recv_data() on the matched iface, bypassing the global routing table for inter-radio traffic. PR #111236 needs to document and validate this path explicitly — a test that exercises EAPOL across two virtual radios is the acceptance criterion.

PR #110681 sidesteps this entirely: the Linux kernel's network namespaces handle isolation, and the Zephyr side sees only one interface with one socket.

---

Proposed Merge Strategy

Given the different scopes, a two-tier approach makes more sense than picking one winner:

Tier	PR	Rationale
Merge near-term	#110681 (Jukka)	Best available driver for full hostapd/EAPOL/data-path CI today. Proven. Needs Twister test added.
Merge near-term	#111194 (Pieter)	Best tool for mgmt-plane unit tests and application-layer integration tests. Low risk, runs anywhere.
Continue + fix	#111236 (Chaitanya)	High long-term value (runs without Linux host). Must resolve the inter-VIF data-path routing issue first.

All three PRs should share a common test sample directory (samples/net/wifi/hwsim_test/) with Twister YAML covering each driver, plus a CI script for the nl80211 host setup.

---

Open Questions for the Community

1. Data-path routing (drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236): Is the proposed net_recv_data() bypass sufficient, or does Zephyr need a more formal concept of "virtual interface group" to make multi-VIF scenarios reliable? Should this be addressed as a net core change rather than a driver workaround?

2. CI infrastructure (drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 #110681): Which CI runners in the Zephyr project currently support loading kernel modules? Is mac80211_hwsim available on the GitHub Actions runners used for Twister, or would this require dedicated hardware or a custom container?

3. Scope of drivers: wifi: add emulated Wi-Fi driver  #111194: Should the wifi_emul API be able to inject EAPOL failure events (even though no real EAPOL runs) so that application-level handling of auth failures can be tested? Or does that conflate the emulation layer with the supplicant layer?

4. Long-term convergence: Once drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236's data-path issue is resolved, should it eventually replace drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 #110681 for all CI (making the stack fully host-OS-independent), or should both coexist permanently (nl80211 for deeper protocol fidelity, pure-Zephyr hwsim for portability)?

5. hostapd side: All three PRs focus on the STA role. Is there a plan / interest in also running hostapd inside the same Zephyr image (using drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236's multi-radio model) for AP-side testing?

---

Suggested Next Steps

• drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 #110681: Add a minimal Twister test (scan → WPA2-PSK connect → ping → disconnect)
• drivers: wifi: native_sim: Add Wi-Fi driver using host nl80211 #110681: Add scripts/ci/wifi_hwsim_setup.sh for the host setup steps
• drivers: wifi: add emulated Wi-Fi driver  #111194: Wrap wifi_emul as a ZTEST_SUITE fixture; add negative-path test cases
• drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236: Add a two-radio EAPOL test; document the net_recv_data() injection path; resolve loopback routing
• All: Create samples/net/wifi/hwsim_test/ with shared Twister YAML
• All: Add doc/connectivity/wifi/wifi_hwsim.rst to the Zephyr doc tree

---

Tagging @krish2718, @jukkar, @pdgendt for visibility. Input from the networking and Wi-Fi working groups very welcome.

[krish2718]

5. hostapd side: All three PRs focus on the STA role. Is there a
plan / interest in also running hostapd inside the same Zephyr image
(using drivers: wifi: add hwsim virtual Wi-Fi simulator driver #111236's multi-radio model) for AP-side testing?

Q5 (hostapd / AP role): Clarification — PR #111236 already handles this. It runs hostapd on wlan0 (AP) and wpa_supplicant on wlan1 (STA) and links them through the in-process relay bus. This means #111236 is the only PR of the three that tests all Wi-Fi roles including AP, STA, and P2P within a single Zephyr image. Q5 can be closed — the design already covers it. This actually reinforces #111236 as the right long-term target: once the inter-VIF data-path routing issue is resolved (Q1), it provides the most complete simulation coverage of any of the three approaches, with no host OS dependency.

[krish2718]

The namespace problem is solvable entirely within the hwsim driver — no Zephyr core changes needed.

The key insight is that the relay bus must never touch the routing table. Instead it maintains its own MAC→iface lookup table populated at init time, and uses net_recv_data() to inject frames directly into the target interface's RX path, bypassing the IP stack entirely:

struct hwsim_mac_entry {
    uint8_t mac[6];
    struct net_if *iface;
} mac_table[CONFIG_WIFI_HWSIM_RADIOS];

void hwsim_relay_frame(struct net_if *src, struct net_pkt *pkt)
{
    uint8_t *dst = /* L2 dst from pkt */;

    for (int i = 0; i < n_radios; i++) {
        if (mac_table[i].iface == src) continue;
        if (!same_channel(src, mac_table[i].iface)) continue;
        if (!is_broadcast(dst) && !mac_match(dst, mac_table[i].mac)) continue;

        net_recv_data(mac_table[i].iface, net_pkt_clone(pkt, K_NO_WAIT));
    }
}

This works cleanly because the interfaces are declared as offload ifaces — the Zephyr IP stack hands the full frame to the driver TX hook without doing ARP/NDP or route resolution, so the relay sees raw frames and can forward them purely at L2. EAPOL frames (which are below IP) flow through exactly the same path with no special casing.

The reply from AP→STA takes the same route: AP driver TX → relay → net_recv_data() on STA iface. The routing table is never consulted for inter-radio traffic.

[krish2718]

Update: in-process data path solved (#111236)

The data-path routing problem from the RFC is now solved entirely within the driver + two config knobs -- no Zephyr core changes. Full STA<->AP ICMP ping over the simulated medium passes in a single native_sim process (ztest test_04/test_05, 5/5 green).

The MAC->iface idea from the earlier comment was right for the relay side, but it isn't sufficient on its own: in a single image both radios share one IP stack, so each radio's address is also a local address. That trips two IP-stack guards that have to be defeated, plus a relay routing rule.

The three pieces

1. TX side -- stop local delivery short-circuiting the medium.
   net_core.c reroutes any packet whose destination is one of our own addresses back up the stack (net_ipv4_is_my_addr_raw), so an STA->AP packet never reaches the driver TX hook. This is gated by CONFIG_NET_IP_ADDR_CHECK, so the hwsim test/sample set:
   CONFIG_NET_IP_ADDR_CHECK=n
   Now the frame goes out via the route -> ARP -> driver TX -> medium.

2. RX side -- stop the anti-spoof drop.
   net_ipv4_input() drops a received frame whose source is a local address ("src addr is mine"), unless the packet is flagged loopback. Since the peer's source IP is local in this image, the driver marks every injected RX frame:
   net_pkt_set_loopback(pkt, true); /* in the hwsim RX thread, before net_recv_data() */

3. Relay -- route by L2 destination MAC.
   The medium delivers data frames (802.3) by destination MAC: unicast -> the single radio whose link address matches; broadcast/multicast -> all peers on the same frequency. Management frames (802.11) are broadcast to peers and handed to wpa_supplicant. Frame type is carried explicitly on the medium rather than guessed from the frame-control byte.

How a ping flows now

STA ping 192.168.1.1 (AP)

1. NET_IP_ADDR_CHECK=n -> not looped back internally -> route -> ARP
   ARP request (bcast) --medium--> AP (group addr -> all peers)
   ARP reply (unicast)--medium--> STA (MAC match -> STA only)
2. ICMP echo request (unicast to AP MAC) --medium--> AP
   AP RX: net_pkt_set_loopback(true) -> passes "src is mine" check
   AP delivers locally, builds echo reply -> ARP -> --medium--> STA
3. STA RX: loopback flag set -> reply accepted -> net_icmp ctx handler fires

The reply takes the same symmetric path: driver TX -> medium -> net_recv_data() on the peer iface. The routing table is never consulted for inter-radio traffic beyond the on-link ARP, and EAPOL/mgmt frames flow through the same medium with no special casing.

Notes

• Separate subnets + on-link routes (in the test) just force the ARP onto the wire rather than a same-subnet local optimization; any topology that makes the stack ARP works.
• CONFIG_NET_IP_ADDR_CHECK=n and the loopback flag are exactly the "treat peers as remote even though they share my stack" levers -- they're the in-process stand-in for the network namespaces Linux's mac80211_hwsim relies on.

[krish2718]

MoM — Zephyr Wi-Fi Telco | July 1, 2026

Attendees: Jukka, Pieter, Maochen, Hui Bai, Satish Nallamala, Robert Lubos

Decisions

Approach	Simulator	Usage
#A	hwsim	Wi-Fi-focused testing + CI
#B	native_sim	Manual testing + app-protocol testing (MQTT, HTTPS, etc.) — CI deferred due to sudo requirement
#C	—	Dropped — covered by #A + #B

---

Next Steps

• Test and merge the open PRs
• Find better names for #A and #B that reflect their intent (non-blocking)

---

Future Extensions

• Enterprise Mode — Hostapd-based AP + built-in RADIUS already working in Zephyr; extend to full Enterprise support (STA, AP, RADIUS server)
• Extend #B to additional modes: SAP / P2P
• Wi-Fi Medium Simulation — Evaluate wmediumd (ref: wifi: hostap: Evaluate the best strategy for Wi-Fi simulation based tests #84027); leaning towards it as it works with both #A (reimplemented in Zephyr) and #B, with dynamic RSSI / packet loss control