1.. zephyr:code-sample:: testusb-app
2 :name: USB device testing application
3 :relevant-api: usbd_api
4
5 Test USB device drivers using a loopback function.
6
7This sample implements a loopback function that can be used
8to test USB device drivers and the device stack connected to a Linux host
9and has a similar interface to "Gadget Zero" of the Linux kernel.
10The userspace tool ``testusb`` is needed to start the tests.
11
12Building and flashing
13*********************
14
15Follow the general procedure for building and flashing Zephyr device.
16
17Testing
18*******
19
20To run USB tests:
21
22#. Load the ``usbtest`` Linux kernel module on the Linux Host.
23
24 .. code-block:: console
25
26 $ sudo modprobe usbtest vendor=0x2fe3 product=0x0009
27
28 By checking the kernel diagnostic messages, you should see that the ``usbtest``
29 module has claimed the device:
30
31 .. code-block:: console
32
33 [21746.128743] usb 9-1: new full-speed USB device number 16 using uhci_hcd
34 [21746.303051] usb 9-1: New USB device found, idVendor=2fe3, idProduct=0009, bcdDevice= 2.03
35 [21746.303055] usb 9-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
36 [21746.303058] usb 9-1: Product: Zephyr testusb sample
37 [21746.303060] usb 9-1: Manufacturer: ZEPHYR
38 [21746.303063] usb 9-1: SerialNumber: 86FE679A598AC47A
39 [21746.306149] usbtest 9-1:1.0: matched module params, vend=0x2fe3 prod=0x0009
40 [21746.306153] usbtest 9-1:1.0: Generic USB device
41 [21746.306156] usbtest 9-1:1.0: full-speed {control} tests
42
43 .. note::
44 The kernel diagnostic messages can be displayed using a command such as
45 ``journalctl -k -n 20`` or ``dmesg`` (these commands may need to be
46 executed as root - e.g., ``sudo dmesg``).
47
48 The first line of the diagnostic messages above contains two important
49 pieces of information that will be needed later on:
50
51 * The USB bus number: ``9`` in ``usb 9-1: [...]``
52
53 * The device under testing (DUT)'s USB device number: ``16`` in ``USB device number 16``
54
55#. Use the ``testusb`` tool in ``linux/tools/usb`` inside Linux kernel source directory
56 to start the tests.
57
58 .. code-block:: console
59
60 $ sudo ./testusb -D /dev/bus/usb/009/016
61 /dev/bus/usb/009/016 test 0, 0.000007 secs
62 /dev/bus/usb/009/016 test 9, 4.994475 secs
63 /dev/bus/usb/009/016 test 10, 11.990054 secs
64
65 .. note::
66 In this command, replace ``009`` and ``016`` with the USB bus number and
67 DUT's device number, respectively, as found in the debugging messages on
68 your host. Do not forget to pad with zeros.
69
70#. The Linux ``usbtest`` driver does not support this Zephyr sample's VID/PID
71 so we cannot run all the tests by default. To run all the tests, we can use
72 the feature described in the `"Dynamic USB device IDs" LWN.net article`_ to
73 write one of the supported VID/PID pair to the ``new_id`` sysfs attribute
74 of our device. Since the sample implements an interface similar to the
75 "Gadget Zero" interface, we specify reference device ``0525:a4a0``.
76
77 .. code-block:: console
78
79 $ sudo sh -c "echo 0x2fe3 0x0009 0 0x0525 0xa4a0 > /sys/bus/usb/drivers/usbtest/new_id"
80
81 .. note::
82 This step can be performed right after loading the ``usbtest`` module instead.
83 Otherwise, you may have to disconnect and reconnect the DUT in order for the
84 Gadget Zero interface to become enabled.
85
86 Once this step has been performed, the kernel diagnostic messages upon connecting
87 the DUT should be similar to the following:
88
89 .. code-block::
90
91 [100458.667241] usb 3-5.3.1: new full-speed USB device number 38 using xhci_hcd
92 [100458.761743] usb 3-5.3.1: New USB device found, idVendor=2fe3, idProduct=0009, bcdDevice= 4.02
93 [100458.761750] usb 3-5.3.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
94 [100458.761753] usb 3-5.3.1: Product: Zephyr testusb sample
95 [100458.761755] usb 3-5.3.1: Manufacturer: Zephyr Project
96 [100458.761757] usb 3-5.3.1: SerialNumber: 2034354E32365007003C001C
97 [100458.773785] usbtest 3-5.3.1:1.0: Linux gadget zero
98 [100458.773791] usbtest 3-5.3.1:1.0: full-speed {control in/out bulk-in bulk-out} tests (+alt)
99 [100458.773858] usbtest 3-5.3.1:1.1: Linux gadget zero
100 [100458.773859] usbtest 3-5.3.1:1.1: full-speed {control in/out int-in int-out} tests (+alt)
101 [100458.773914] usbtest 3-5.3.1:1.2: Linux gadget zero
102 [100458.773916] usbtest 3-5.3.1:1.2: full-speed {control in/out iso-in iso-out} tests (+alt)
103
104#. Use the ``testusb`` tool in ``linux/tools/usb`` inside Linux kernel source directory
105 to start the tests.
106
107 .. code-block:: console
108
109 $ sudo ./testusb -v 512 -D /dev/bus/usb/009/016
110 /dev/bus/usb/009/017 test 0, 0.000008 secs
111 /dev/bus/usb/009/017 test 1, 2.000001 secs
112 /dev/bus/usb/009/017 test 2, 2.003058 secs
113 /dev/bus/usb/009/017 test 3, 1.054082 secs
114 /dev/bus/usb/009/017 test 4, 1.001010 secs
115 /dev/bus/usb/009/017 test 5, 57.962142 secs
116 /dev/bus/usb/009/017 test 6, 35.000096 secs
117 /dev/bus/usb/009/017 test 7, 30.000063 secs
118 /dev/bus/usb/009/017 test 8, 18.000159 secs
119 /dev/bus/usb/009/017 test 9, 4.984975 secs
120 /dev/bus/usb/009/017 test 10, 11.991022 secs
121 /dev/bus/usb/009/017 test 11, 17.030996 secs
122 /dev/bus/usb/009/017 test 12, 17.103034 secs
123 /dev/bus/usb/009/017 test 13, 18.022084 secs
124 /dev/bus/usb/009/017 test 14, 2.458976 secs
125 /dev/bus/usb/009/017 test 17, 2.001089 secs
126 /dev/bus/usb/009/017 test 18, 1.998975 secs
127 /dev/bus/usb/009/017 test 19, 2.010055 secs
128 /dev/bus/usb/009/017 test 20, 1.999911 secs
129 /dev/bus/usb/009/017 test 21, 2.440972 secs
130 /dev/bus/usb/009/017 test 24, 55.112078 secs
131 /dev/bus/usb/009/017 test 27, 56.911052 secs
132 /dev/bus/usb/009/017 test 28, 34.163089 secs
133 /dev/bus/usb/009/017 test 29, 3.983999 secs
134
135.. _"Dynamic USB device IDs" LWN.net article:
136 https://lwn.net/Articles/160944/
137
