dolphin/docs/Wii_LLE_Ethernet.md

Experimental Wii LLE Ethernet + NAT

This opt-in device keeps the original ARM IOS USB, Ethernet and IP drivers in charge. It presents an AX88772A-family USB Ethernet adapter (VID 0b95, PID 7720) on the external OHCI0 controller. Ethernet frames are passed to libslirp for user-mode NAT. The internal OHCI1 Bluetooth device is independent. No IOS socket calls are intercepted.

Windows setup

From the repository directory:

.\Setup-Wii-LLE-Network.ps1
.\Run-Wii-IOS-LLE.ps1 -Ethernet

Both scripts accept -BuildDirectory (default .starlet_msvc2). The launcher also accepts -UserDirectory; use an isolated copy of the user profile for initial tests. Its default remains .starlet_user3. Launching without -Ethernet leaves this device disabled. Alternatively set [Core] WiiLLEEthernet = True when launching without this wrapper. It requires Wii IOS LLE and does not alter normal IOS HLE networking.

The setup script downloads version-pinned, SHA-256-checked official MSYS2 UCRT64 packages into the ignored .starlet_network cache. DLLs and their licenses are placed under Binaries/Network; it does not install a driver, change PATH, configure a Windows bridge, or add firewall rules. Runtime loading uses that directory explicitly. The public libslirp 4.9.3 headers and copyright notice are included under Externals/libslirp; libslirp is loaded dynamically, not linked into Dolphin.

Configure a wired connection, with automatic IP address and DNS, in the Wii's Internet settings. The virtual subnet is 10.0.2.0/24: gateway 10.0.2.2, first DHCP lease 10.0.2.15, DNS proxy 10.0.2.3. No inbound port mappings, TFTP directory, command forwarding or loopback access to host services are enabled. This is NAT, not a LAN bridge; other LAN devices cannot initiate connections to the guest. Internet access still depends on the host's connectivity and firewall policy.

Normal network settings are saved through the existing NAND journal. The original dumps/nand.bin is never changed. Avoid accepting a system update during initial connectivity testing; a successful network connection is separate from compatibility with historical Wii servers or modern TLS endpoints.

Validation and limits

Automated tests exercise descriptors, control requests, PHY/MAC registers, USB address timing, link notifications, split Ethernet frames, OHCI DMA enumeration, EHCI companion routing and actual libslirp ARP/DHCP replies. Runtime tests skip when the optional library directory is absent; a present but unloadable library fails.

The interrupt endpoint refreshes unchanged link/PHY status after 10 emulated USB frames (the advertised full-speed interval), in addition to link-change reports. IOS synchronously polls this endpoint: replying only once per link change leaves later connectivity checks waiting indefinitely. Reports are coalesced, held while software owns MDIO, and timed by OHCI0 frames rather than host time. Regression tests cover repeated reads through OHCI DMA, pacing, MDIO ownership and savestates.

Winsock polling maps libslirp's normal/urgent reads to POLLRDNORM/POLLRDBAND. Passing POSIX-style POLLPRI to Windows WSAPoll fails the entire poll with WSAEINVAL (10022): DHCP/DNS and the TCP handshake can succeed while subsequent response reads stall. A localhost TCP regression checks data and peer-close delivery with the actual event mapping. Poll failures are logged with a bounded error count instead of silently losing host readiness notifications.

These tests do not by themselves establish Internet connectivity from retail IOS. That requires enumerating the adapter with the real IOS driver, configuring a wired connection, then observing DNS and TCP traffic in an end-to-end test.

Shop connection diagnostics (September 2026)

The wired connection test passed in the isolated test profile. The subsequent Shop connection stalled inside native IOS SSL_DOHANDSHAKE, with unchanged network frame counters. Sampling attributed most of one saturated host core to ARM JIT execution and IOS memory accesses, not the NAT worker. Native random-number requests repeatedly returned zero because AES DMA to 0x0d40f080 was incorrectly subject to the CPU's SRAM bank swap. Device DMA now uses the physical SRAM layout; CPU mapping is unchanged. Automated AES, SHA, DMA-boundary, OHCI and NAND tests cover this distinction.

On 2026-09-12, the user confirmed successful connection and navigation to the Shop's Wii Channels listing using native IOS and the virtual Ethernet adapter. The supplied capture shows 100% emulation speed and 59.96 FPS on that screen. This validates that connection path, not downloads, purchases, all servers, or constant performance in every channel. The targeted regression run passed 164 tests across 21 suites.

Separately, aligned Thumb bus accesses now call the exact bus helpers without an interpreter/dispatcher round trip. Unaligned accesses retain their architectural fallback. The targeted four-million-instruction SRAM benchmark measured a median 85.177 ms before and 54.051 ms after (about 1.58x throughput); this is not a measured whole-channel FPS improvement.

Remaining hardware limits

• USB full-speed, with 64-byte bulk packets through OHCI0. The existing EHCI skeleton does not execute high-speed queue heads. This is not a completed USB 2.0 high-speed implementation or a cycle-accurate AX88772 model.
• PHY reset/autonegotiation completes synchronously; there is no physical cable negotiation or USB link bandwidth model. Multicast hash filtering is not yet exact.
• The guest device is serialized in savestates, but restoring a state recreates NAT and closes existing host TCP/UDP flows. Ethernet must be enabled consistently when saving and restoring. This change advances Dolphin's savestate version.
• No Wi-Fi emulation, live adapter hotplug, bridged LAN broadcast discovery, or persistent external EEPROM image is provided.

IOS_USB logs show address/configuration, receive/medium setup, and unsupported AX88772 control requests. IOS_NET logs show runtime initialization and NAT errors. The first 128 IPv4 frames per direction also log IP endpoints, protocol, lengths and TCP flags/sequence numbers or UDP ports/ICMP type. Packet payloads are not logged. The -Ethernet launcher flag enables both at the normal info level, without packet payload logging. All NAT input, socket polling and callbacks run on the emulation thread; callbacks never access guest RAM directly. Polls are nonblocking and timed from the emulated ARM clock.

References

• IOS OHCI known devices
• ASIX AX88772 datasheet, EEPROM and MDIO register layouts
• Linux ASIX register definitions
• Linux ASIX device initialization
• Linux ASIX frame handling
• libslirp API
• Microsoft WSAPoll supported event flags
• MSYS2 libslirp package