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
