1.. _usbip:
2
3USB/IP protocol support
4#######################
5
6Overview
7********
8
9New USB support includes initial support for the USB/IP protocol. It is still
10under development and is currently limited to supporting only one device
11connected to the host controller being exported.
12
13USB/IP uses TCP/IP. Both of the underlying connectivity stacks, USB and
14networking, require significant memory resources, which must be considered when
15choosing a platform.
16
17In the USB/IP protocol, a server exports the USB devices and a client imports
18them. USB/IP support in the Zephyr RTOS implements server functionality and
19exports a device connected to a host controller on a device running the Zephyr
20RTOS. A client, typically running the Linux kernel, imports this device. The
21USB/IP protocol is described in `USB/IP protocol documentation`_.
22
23To use USB/IP support, make sure the required modules are loaded on the client side.
24
25.. code-block:: console
26
27   modprobe vhci_hcd
28   modprobe usbip-core
29   modprobe usbip-host
30
31On the client side, you will also need the **usbip** user tool. It can be installed
32using your Linux distribution's package management system or built from Linux
33kernel sources.
34
35There are a few basic commands for everyday use. To list exported USB devices,
36run the following command:
37
38.. code-block:: console
39
40   $ usbip list -r 192.0.2.1
41   Exportable USB devices
42   ======================
43    - 192.0.2.1
44           1-1: NordicSemiconductor : unknown product (2fe3:0001)
45              : /sys/bus/usb/devices/usb1/1-1
46              : Miscellaneous Device / ? / Interface Association (ef/02/01)
47              :  0 - Communications / Abstract (modem) / None (02/02/00)
48              :  1 - CDC Data / Unused / unknown protocol (0a/00/00)
49
50To attach an exported device with busid 1-1:
51
52.. code-block:: console
53
54   $ sudo usbip attach -r 192.0.2.1 -b 1-1
55
56To detach an exported device on port 0:
57
58.. code-block:: console
59
60   $ sudo usbip detach -p 0
61
62USB/IP with native_sim
63**********************
64
65The preferred method to develop with USB/IP support enabled is to use
66:ref:`native_sim <native_sim>`. Use on real hardware is not really tested yet.
67USB/IP requires a network connection, see :ref:`networking_with_native_sim`
68for how to set up the interface on the client side.
69
70Building and running a sample with USB/IP requires extensive configuration,
71you can use usbip-native-sim snippet to configure host and USB/IP support.
72
73.. zephyr-app-commands::
74   :zephyr-app: samples/subsys/usb/cdc_acm
75   :board: native_sim/native/64
76   :gen-args: -DSNIPPET=usbip-native-sim -DEXTRA_DTC_OVERLAY_FILE=app.overlay
77   :goals: build
78
79.. _USB/IP protocol documentation: https://www.kernel.org/doc/html/latest/usb/usbip_protocol.html
80