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:

```powershell
.\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](https://wiibrew.org/wiki//dev/usb/oh0#Known_Devices)
- [ASIX AX88772 datasheet, EEPROM and MDIO register layouts](https://www.framboise314.fr/wp-content/uploads/2016/08/AX88772.pdf)
- [Linux ASIX register definitions](https://github.com/torvalds/linux/blob/master/drivers/net/usb/asix.h)
- [Linux ASIX device initialization](https://github.com/torvalds/linux/blob/master/drivers/net/usb/asix_devices.c)
- [Linux ASIX frame handling](https://github.com/torvalds/linux/blob/master/drivers/net/usb/asix_common.c)
- [libslirp API](https://gitlab.freedesktop.org/slirp/libslirp/-/blob/v4.9.3/src/libslirp.h)
- [Microsoft WSAPoll supported event flags](https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll)
- [MSYS2 libslirp package](https://packages.msys2.org/package/mingw-w64-ucrt-x86_64-libslirp)