Windows ‐ WSL2 - vanilla-wiiu/vanilla GitHub Wiki

WSL2 can be configured and set up to work with Vanilla. This has the advantage of being more integrated with Windows Terminal and easier to set up with custom launch scripts. However, the set-up required is complex and is for advanced users only. We recommend you set up a virtual machine with something like Virtualbox or VMware if custom kernel compilation sounds too complex.

By default, the kernel that comes with WSL2 does not include many of the kernel modules and kernel APIs needed to enable wireless support and support the WPA2 PTK generation. This means we will need to compile our own kernel to enable these missing features.

• Update the system:

sudo apt update && sudo apt upgrade

• Install helpful packages:

sudo apt install bash-completion build-essential gcc g++ avr-libc avrdude default-jre default-jdk clang make nano xz-utils linux-tools-common linux-tools-virtual hwdata wget flex bison libssl-dev libelf-dev git dwarves bc zstd
sudo update-alternatives --install /usr/local/sbin/usbip usbip $(ls /usr/lib/linux-tools/*/usbip | tail -n1) 20

• Install your Wi-Fi card's firmware

sudo apt install linux-firmware-realtek

Since the firmware comes in a .zst compressed bundle, we need to decompress it to include it in the kernel (see note below). Luckily, the decompression process is relatively simple.

sudo zstd -d -k /lib/firmware/rtw88/rtw8822b_fw.bin.zst

• Download and prepare the kernel:

wget https://github.com/microsoft/WSL2-Linux-Kernel/archive/refs/tags/linux-msft-wsl-$(uname -r | cut -d- -f 1).tar.gz
tar -xvf linux-msft-wsl-$(uname -r | cut -d- -f 1).tar.gz
cd WSL2-Linux-Kernel-linux-msft-wsl-$(uname -r | cut -d- -f 1)
cat /proc/config.gz | gunzip > .config
make prepare modules_prepare -j$(nproc)

• Open kernel configuration:

make menuconfig -j$(nproc)

In menuconfig, there are a couple things we need to enable for Vanilla.

Under Cryptographic API, you will need the following to be enabled with y:

• AEAD (authenticated encryption with associated data) ciphers --> CCM (Counter with Cipher Block Chaining-MAC) (CONFIG_CRYPTO_CCM)
• AEAD (authenticated encryption with associated data) ciphers --> GCM (Galois/Counter Mode) and GMAC (GCM MAC) (CONFIG_CRYPTO_GCM)
• Block ciphers --> AES (Advanced Encryption Standard) (CONFIG_CRYPTO_AES)
• Hashes, digests, and MACs --> CMAC (Cipher-based MAC) (CONFIG_CRYPTO_CMAC)
• Hashes, digests, and MACs --> HMAC (Keyed-Hash MAC) (CONFIG_CRYPTO_HMAC)

Under Networking support, you will need the following to be enabled with y:

• Wireless --> cfg80211 - wireless configuraion API (CONFIG_CFG80211)
• Wireless --> Generic IEEE 802.11 Networking Stack (mac80211) (CONFIG_MAC80211)
• RF switch subsystem support (CONFIG_RFKILL)

Under Device Drivers -> USB support, you will need the following to be enabled with y or m:

• USB/IP support (CONFIG_USBIP_CORE)
• VHCI hcd (CONFIG_USBIP_VHCI_HCD)

Now we need to add the drivers to the kernel.

Under Device Drivers --> Network device support --> Wireless LAN you will need the driver for your wifi card. Enable the relevant modules for your hardware with y or m. Nearly all wireless hardware has a in-tree kernel driver, meaning that it will be here somewhere.

You will also likely need to build the kernel with the firmware included in the final image (see warning about WSL2 loading firmware above). To do this, first you need to head to Device Drivers --> Generic Driver Options --> Firmware loader and make sure Firmware loading facility (FW_LOADER) is enabled with y. Next, to actually include the firmware in the kernel, under Build named firmware blobs into the kernel binary (EXTRA_FIRMWARE), you will need to provide the path of the firmware binary. It is relative to the firmware directory, for example, if your firmware binary is

/lib/firmware/rtw88/rtw8822b_fw.bin

you would provide

rtw88/rtw8822b_fw.bin

Under Firmware blobs root directory (EXTRA_FIRMWARE_DIR) you will provide the root directory of the firmware. By default, this is /lib/firmware and you shouldn't need to change this, unless your firmware is not in one of the linux-firmware-x packages and you manually grabbed it.

make -j$(nproc)
make modules -j$(nproc)

Once compilation is finished,

sudo make modules_install
sudo make install

Copy vmlinux from your build directory to your Windows user folder. For example,

cp vmlinux /mnt/c/Users/legoisle/

Next, edit your .wslconfig or create it.

nano /mnt/c/Users/legoisle/.wslconfig

and add

[wsl2]
kernel=C:\\Users\\legoisle\\vmlinux

In a Powershell window, run

wsl --shutdown

to completely shut down WSL to let it load your freshly compiled kernel on its next boot.

In an administrator Powershell window, run

winget install usbipd

then,

usbipd list

It will show you a list of sharable USB devices. Note the busid of your Wi-Fi card, it usually looks like x-x.

Run

usbipd bind -b <busid>

to bind your Wi-Fi card to USB/IP and have it be ready to be attached to WSL2.

1. Letting Windows handle it:

In a administrator Powershell window, run

usbipd attach --wsl -b <busid>

2. Manually (May work better):

In your WSL terminal, run

sudo usbip list -r $(ip route show | grep default | awk '{print $3}') 

It will show you a list of exportable devices along with the busid. To attach your Wi-Fi adapter, run

sudo usbip attach -r $(ip route show | grep default | awk '{print $3}')  -b <busid>

Congratulations! If all went well, you should now have your USB Wi-Fi adapter show up in ip a and be usable by vanilla-pipe.