WSL support

WSL

Tip

These instructions have changed since version 4.0.0; you no longer have to install any client-side tooling.

The command usbipd list lists all the USB devices connected to Windows. From an administrator command prompt on Windows, run this command.

> usbipd list
BUSID  DEVICE                                      STATE
1-7    USB Input Device                            Not shared
4-4    STMicroelectronics STLink dongle, STMic...  Not shared
5-2    Surface Ethernet Adapter                    Not shared

The command usbipd bind shares a device, allowing it to be attached to WSL. This requires administrator privileges. Select the bus ID of the device you would like to use in WSL and run this command.

> usbipd bind --busid 4-4

Verify that the device is shared.

> usbipd list
BUSID  DEVICE                                      STATE
1-7    USB Input Device                            Not shared
4-4    STMicroelectronics STLink dongle, STMic...  Shared
5-2    Surface Ethernet Adapter                    Not shared

Note that sharing a device is persistent; it survives reboots. You will have to do it only once, per device.

Close the administrator command prompt; further commands do not require special privileges.

Open a normal command prompt on Windows. Additionally, ensure a WSL command prompt is open; this will keep the WSL 2 lightweight VM active.

The command usbipd attach --wsl attaches a USB device to WSL. As long as the device is attached to WSL, it cannot be used by Windows. Once attached to WSL, you can use the device in any WSL 2 distribution. From the Windows command prompt run this command.

> usbipd attach --wsl --busid 4-4

Verify that the device is attached.

> usbipd list
BUSID  DEVICE                                      STATE
1-7    USB Input Device                            Not shared
4-4    STMicroelectronics STLink dongle, STMic...  Attached
5-2    Surface Ethernet Adapter                    Not shared

From within WSL, run lsusb to list the attached USB devices. You should see the device you just attached and be able to interact with it using normal Linux tools.

$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0483:374b STMicroelectronics ST-LINK/V2.1
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

The command usbipd detach detaches a device from WSL. Once detached, the device can be used by Windows again. The device will also be detached when it is unplugged or when WSL is restarted.

> usbipd detach --busid 4-4

> usbipd list
BUSID  DEVICE                                      STATE
1-7    USB Input Device                            Not shared
4-4    STMicroelectronics STLink dongle, STMic...  Shared
5-2    Surface Ethernet Adapter                    Not shared

Use the --help option to learn more about these commands.

udev

Depending on your application, you may need to configure udev rules to allow non-root users to access the device. Rules to enable a device must be in place before attaching the device. As a common example, for using embedded devices with openocd, copy share/openocd/contrib60-openocd.rules to the /etc/udev/rules.d folder.

After updating your rules run sudo udevadm control --reload. If you get an error like "Failed to send reload request: No such file or directory", run sudo service udev restart.

Building your own WSL 2 kernel with additional drivers

Note

Recent versions of Windows running WSL kernel 5.10.60.1 or later already include support for common scenarios like USB-to-serial adapters and flashing embedded development boards. Only if you require special drivers will you need to build your own kernel for WSL 2.

Update WSL:

wsl --update

List your distributions.

wsl --list --verbose

Verify that your target distribution is version 2; see WSL documentation for instructions on how to set the WSL version.

Export current distribution to be able to fall back if something goes wrong.

wsl --export <current-distro> <temporary-path>\wsl2-usbip.tar

Import new distribution with current distribution as base.

wsl --import wsl2-usbip <install-path> <temporary-path>\wsl2-usbip.tar

Run new distribution.

wsl --distribution wsl2-usbip --user <user>

Update resources (assuming apt, you may need to use yum or another package manager).

sudo apt update
sudo apt upgrade

Install prerequisites.

sudo apt install build-essential flex bison libssl-dev libelf-dev libncurses-dev autoconf libudev-dev libtool

Note

Depending on the drivers you will select below, additional packages may be required.

Clone kernel that matches WSL version. To find the version you can run.

uname -r

The kernel can be found at: https://github.com/microsoft/WSL2-Linux-Kernel

Clone the kernel repo, then checkout the branch/tag that matches your kernel version; run uname -r to find the kernel version.

git clone https://github.com/microsoft/WSL2-Linux-Kernel.git
cd WSL2-Linux-Kernel
git checkout linux-msft-wsl-5.10.43.3

Copy current configuration file.

cp /proc/config.gz config.gz
gunzip config.gz
mv config .config

You may need to set CONFIG_USB=y in .config prior to running menuconfig to get all options enabled for selection.

Run menuconfig to select kernel features to add.

sudo make menuconfig

These are the necessary additional features in menuconfig.
Device Drivers -> USB Support
Device Drivers -> USB Support -> USB announce new devices
Device Drivers -> USB Support -> USB Modem (CDC ACM) support
Device Drivers -> USB Support -> USB/IP
Device Drivers -> USB Support -> USB/IP -> VHCI HCD
Device Drivers -> USB Support -> USB/IP -> Debug messages for USB/IP
Device Drivers -> USB Serial Converter Support
Device Drivers -> USB Serial Converter Support -> USB FTDI Single port Serial Driver

Note

These instructions have changed.
Debug messages have a huge negative performance impact on bulk transfers. Enabling debug messages is no longer recommended.

In the following command the number '8' is the number of cores to use; run getconf _NPROCESSORS_ONLN to find the number of cores.

sudo make -j 8 && sudo make modules_install -j 8 && sudo make install -j 8

From the root of the repo, copy the image.

cp arch/x86/boot/bzImage /mnt/c/Users/<user>/usbip-bzImage

Create a .wslconfig file on /mnt/c/Users/<user>/ and add a reference to the created image with the following.

[wsl2]
kernel=c:\\users\\<user>\\usbip-bzImage

Your WSL distro is now ready to use!