1.. zephyr:code-sample:: testusb-app
2   :name: USB testing application
3   :relevant-api: _usb_device_core_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   The ``usbtest`` module should claim the device:
29
30   .. code-block:: console
31
32      [21746.128743] usb 9-1: new full-speed USB device number 16 using uhci_hcd
33      [21746.303051] usb 9-1: New USB device found, idVendor=2fe3, idProduct=0009, bcdDevice= 2.03
34      [21746.303055] usb 9-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
35      [21746.303058] usb 9-1: Product: Zephyr testusb sample
36      [21746.303060] usb 9-1: Manufacturer: ZEPHYR
37      [21746.303063] usb 9-1: SerialNumber: 86FE679A598AC47A
38      [21746.306149] usbtest 9-1:1.0: matched module params, vend=0x2fe3 prod=0x0009
39      [21746.306153] usbtest 9-1:1.0: Generic USB device
40      [21746.306156] usbtest 9-1:1.0: full-speed {control} tests
41
42#. Use the ``testusb`` tool in ``linux/tools/usb`` inside Linux kernel source directory
43   to start the tests.
44
45   .. code-block:: console
46
47      $ sudo ./testusb -D /dev/bus/usb/009/016
48      /dev/bus/usb/009/016 test 0,    0.000007 secs
49      /dev/bus/usb/009/016 test 9,    4.994475 secs
50      /dev/bus/usb/009/016 test 10,   11.990054 secs
51
52#. To run all the tests the Zephyr's VID / PID should be inserted to USB
53   driver id table. The method for loading the ``usbtest`` driver for our
54   device is described here: https://lwn.net/Articles/160944/.
55
56   Since we use the "Gadget Zero" interface we specify reference device
57   ``0525:a4a0``.
58
59   .. code-block:: console
60
61      $ sudo sh -c "echo 0x2fe3 0x0009 0 0x0525 0xa4a0 > /sys/bus/usb/drivers/usbtest/new_id"
62
63#. Use the ``testusb`` tool in ``linux/tools/usb`` inside Linux kernel source directory
64   to start the tests.
65
66   .. code-block:: console
67
68      $ sudo ./testusb -v 512 -D /dev/bus/usb/009/016
69      /dev/bus/usb/009/017 test 0,    0.000008 secs
70      /dev/bus/usb/009/017 test 1,    2.000001 secs
71      /dev/bus/usb/009/017 test 2,    2.003058 secs
72      /dev/bus/usb/009/017 test 3,    1.054082 secs
73      /dev/bus/usb/009/017 test 4,    1.001010 secs
74      /dev/bus/usb/009/017 test 5,   57.962142 secs
75      /dev/bus/usb/009/017 test 6,   35.000096 secs
76      /dev/bus/usb/009/017 test 7,   30.000063 secs
77      /dev/bus/usb/009/017 test 8,   18.000159 secs
78      /dev/bus/usb/009/017 test 9,    4.984975 secs
79      /dev/bus/usb/009/017 test 10,   11.991022 secs
80      /dev/bus/usb/009/017 test 11,   17.030996 secs
81      /dev/bus/usb/009/017 test 12,   17.103034 secs
82      /dev/bus/usb/009/017 test 13,   18.022084 secs
83      /dev/bus/usb/009/017 test 14,    2.458976 secs
84      /dev/bus/usb/009/017 test 17,    2.001089 secs
85      /dev/bus/usb/009/017 test 18,    1.998975 secs
86      /dev/bus/usb/009/017 test 19,    2.010055 secs
87      /dev/bus/usb/009/017 test 20,    1.999911 secs
88      /dev/bus/usb/009/017 test 21,    2.440972 secs
89      /dev/bus/usb/009/017 test 24,   55.112078 secs
90      /dev/bus/usb/009/017 test 27,   56.911052 secs
91      /dev/bus/usb/009/017 test 28,   34.163089 secs
92      /dev/bus/usb/009/017 test 29,    3.983999 secs
93