From 0ae1be0e6588b07bf3a7d242937ab4a224ff2883 Mon Sep 17 00:00:00 2001 From: Filip Jagodzinski Date: Tue, 21 May 2019 17:31:16 +0200 Subject: [PATCH] Add a top level README file for USB tests Add setup instructions and aggregate all the info from README files related to USB testing. --- TESTS/usb_device/README.md | 158 ++++++++++++++++++++ TESTS/usb_device/basic/README.md | 15 -- TESTS/usb_device/basic/zadig_conf/README.md | 18 --- TESTS/usb_device/hid/README.md | 23 --- TESTS/usb_device/msd/README.md | 12 -- TESTS/usb_device/serial/README.md | 18 --- 6 files changed, 158 insertions(+), 86 deletions(-) create mode 100644 TESTS/usb_device/README.md delete mode 100644 TESTS/usb_device/basic/README.md delete mode 100644 TESTS/usb_device/basic/zadig_conf/README.md delete mode 100644 TESTS/usb_device/hid/README.md delete mode 100644 TESTS/usb_device/msd/README.md delete mode 100644 TESTS/usb_device/serial/README.md diff --git a/TESTS/usb_device/README.md b/TESTS/usb_device/README.md new file mode 100644 index 0000000000..7931b082b0 --- /dev/null +++ b/TESTS/usb_device/README.md @@ -0,0 +1,158 @@ +# Testing the Mbed OS USB device + +## Setup +Before running tests, please make sure to use a +[top-level requirements.txt][LN-requirements] file to install all the +required Python modules. + +``` +pip install -r requirements.txt +``` + +Additional, platform-specific setup is described below. +See also [Known issues](#known-issues). + +### Windows +1. Install a **generic USB driver** for two test devices. + 1. Download `Zadig` application from [the Zadig website][LN-zadig]. + 1. Unplug the Mbed device. + 1. Open `Zadig`. + 1. Select *Device -> Load Preset Device*. + 1. Open [TESTS/usb_device/basic/zadig_conf/mbed_os-usb_test_device1.cfg][LN-zadig_conf1] + 1. Choose `libusb-win32 (v1.2.6.0)` driver. + 1. Select `Install Driver` and click it. + 1. Select *Device -> Load Preset Device*. + 1. Open [TESTS/usb_device/basic/zadig_conf/mbed_os-usb_test_device2.cfg][LN-zadig_conf2] + 1. Choose `libusb-win32 (v1.2.6.0)` driver. + 1. Select `Install Driver` and click it. + 1. Close `Zadig`. + 1. Plug both USB interfaces (*DAPLink* and *USB device*). + +### Linux +1. Install the `hidapi` Python module, otherwise some USB HID test cases will + be skipped. This module is not installed during the initial setup due to + external dependencies for Linux. + + For Debian-based Linux distros, the dependencies can be installed as follows + (based on module's [README][LN-hidapi_readme]): + + ```bash + apt-get install python-dev libusb-1.0-0-dev libudev-dev + pip install --upgrade setuptools + ``` + + To install the `hidapi` module itself, please use the attached + [requirements.txt][LN-hid_requirements] file: + + ```bash + pip install -r TESTS/usb_device/hid/requirements.txt + ``` + +1. Update the `udev` rules for Mbed USB CDC device as follows + ([source][LN-udev_rules]): + + ```bash + sudo tee /etc/udev/rules.d/99-ttyacms.rules >/dev/null < -m -n tests-usb_device-* + ``` + +## Known issues + +### Insufficient user permissions on a Linux machine +Some of the tests require privileged access to the USB device. Running these +as an unprivileged user will manifest with either of the following errors: +* ``` + [HTST][INF] Device not found + ``` +* ``` + [HTST][INF] TEST ERROR: Failed with "The device has no langid". Tried 20 times. + ``` + +#### Solution +Execute tests with elevated permissions using `sudo`: +```bash +mbed test -t -m -n tests-usb_device-* --compile +sudo mbed test -t -m -n tests-usb_device-* --run -v +``` +Note only the `mbed test --run` command requires `sudo`. You can still +`mbed test --compile` as a normal user. + +#### Alternative solution +Add an `udev` rule to set the ownership of the device node +[as shown here][LN-libusb_permissions]. + +### Data toggle reset test fails on a Linux machine +The `tests-usb_device-basic` / `"endpoint test data toggle reset"` test fails +with the following error: +``` +[HTST][INF] TEST FAILED: Data toggle not reset when calling +ClearFeature(ENDPOINT_HALT) on an endpoint that has not been halted. +``` + +Implementations of the *xHCI* driver prior to version 4.17 of the Linux kernel did +not have the functionality necessary to test `"endpoint test data toggle reset"`. +Even though the data toggle is correctly reset on the device side, the host +side will not be synchronized and the test will falsely fail. + +#### Solution +Make sure that **at least one** of the following prerequisites is met: +* using the Linux kernel ***4.17* or newer**, +* using the ***eHCI*** USB driver instead of *xHCI*. + +Changing the USB driver may be as simple as updating one of the BIOS settings +on your machine. If you'd rather avoid rebooting, you can try +[using setpci command][LN-xhci_setpci]. + +#### Further reading +1. [the Linux kernel patch adding missing xHCI behavior][LN-linux_xhci_patch], +1. [LKML discussion explaining the details of this issue][LN-xhci_lkml_discussion]. + +### Mass storage tests are skipped on some targets +The `tests-usb_device-msd` test outputs the following message: +``` +[CONN][RXD] SKIP: Not enough heap memory for HeapBlockDevice creation +``` + +#### Solution +A device with at least *70 kB* of RAM is required to run this test. +The FAT32 filesystem cannot be mounted on a device smaller than 64 kB. + +The test can be easily extended to use any block device available in Mbed. + +### Isochronous endpoints are skipped in loopback tests +#### Unresolved + +### Serial tests fail intermittently on a Linux machine +#### Unresolved +You may want to connect the device directly to the host machine with no hubs on the way. + + +[LN-requirements]: ../../requirements.txt +[LN-zadig]: https://zadig.akeo.ie/ +[LN-zadig_conf1]: basic/zadig_conf/mbed_os-usb_test_device1.cfg +[LN-zadig_conf2]: basic/zadig_conf/mbed_os-usb_test_device2.cfg +[LN-hidapi_readme]: https://github.com/trezor/cython-hidapi/blob/master/README.rst#install +[LN-hid_requirements]: hid/requirements.txt +[LN-udev_rules]: https://linux-tips.com/t/prevent-modem-manager-to-capture-usb-serial-devices/284 +[LN-libusb_permissions]: https://stackoverflow.com/questions/3738173/why-does-pyusb-libusb-require-root-sudo-permissions-on-linux/8582398#8582398 +[LN-linux_xhci_patch]: https://github.com/torvalds/linux/commit/f5249461b504d35aa1a40140983b7ec415807d9e +[LN-xhci_lkml_discussion]: https://lkml.org/lkml/2016/12/15/388 +[LN-xhci_setpci]: https://linuxmusicians.com/viewtopic.php?t=16901 + diff --git a/TESTS/usb_device/basic/README.md b/TESTS/usb_device/basic/README.md deleted file mode 100644 index 88b65e33f2..0000000000 --- a/TESTS/usb_device/basic/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Testing the USB device data toggle reset with a Linux host - -When you run the `tests-usb_device-basic` test suite on a Linux machine, please make -sure that at least one of the following prerequisites are met: -* using the Linux kernel ***4.17* or newer**, -* using the ***eHCI*** USB driver instead of *xHCI*. - -Implementations of the *xHCI* driver prior to version 4.17 of the Linux kernel did -not have the functionality necessary to test `"endpoint test data toggle reset"`. -Even though the data toggle is correctly reset on the device side, the host side will -not be synchronized and the test will falsely fail. - -Further reading: -1. [the Linux kernel patch adding missing xHCI behavior](https://github.com/torvalds/linux/commit/f5249461b504d35aa1a40140983b7ec415807d9e), -1. [LKML discussion explaining the details of this issue](https://lkml.org/lkml/2016/12/15/388). \ No newline at end of file diff --git a/TESTS/usb_device/basic/zadig_conf/README.md b/TESTS/usb_device/basic/zadig_conf/README.md deleted file mode 100644 index f738d15c83..0000000000 --- a/TESTS/usb_device/basic/zadig_conf/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Generic USB driver installation on Windows machines - -In order to run the Mbed OS USB device test suite (`tests-usb_device-*`) -on Windows hosts you need to install generic USB drivers for two test devices. - -1. Download *Zadig* application from https://zadig.akeo.ie/. -1. Unplug the Mbed device. -1. Open *Zadig*. -1. Select *Device -> Load Preset Device*. -1. Open `mbed_os-usb_test_device1.cfg`. -1. Choose `libusb-win32 (v1.2.6.0)` driver. -1. Select `Install Driver` and click it. -1. Select *Device -> Load Preset Device*. -1. Open `mbed_os-usb_test_device2.cfg`. -1. Choose `libusb-win32 (v1.2.6.0)` driver. -1. Select `Install Driver` and click it. -1. Close *Zadig*. -1. Plug both device USB interfaces (*DAPLink* and *USB device*). diff --git a/TESTS/usb_device/hid/README.md b/TESTS/usb_device/hid/README.md deleted file mode 100644 index 0ea4d4c8eb..0000000000 --- a/TESTS/usb_device/hid/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Testing the USB HID device with a Linux host - -Before running `tests-usb_device-hid` test suite on a Linux machine, please -make sure to install the `hidapi` Python module first, otherwise some test -cases will be skipped. Due to external dependencies for Linux, this module -is not installed during the initial setup, to keep the process as simple -as possible. - -For Debian-based Linux distros, the dependencies can be installed as follows -(based on module's [README][1]): - -```bash -apt-get install python-dev libusb-1.0-0-dev libudev-dev -pip install --upgrade setuptools -``` -To install the `hidapi` module itself, please use the attached -`TESTS/usb_device/hid/requirements.txt` file: -```bash -pip install -r requirements.txt -``` - -[1]: https://github.com/trezor/cython-hidapi/blob/master/README.rst#install - diff --git a/TESTS/usb_device/msd/README.md b/TESTS/usb_device/msd/README.md deleted file mode 100644 index be6efed0eb..0000000000 --- a/TESTS/usb_device/msd/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# USB mass storage test user guide - -To run the tests-usb_device-msd test device with at least *70kB* of RAM is required. -Test creates 64kB `HeapBlockDevice` as block device and mounts FAT32 filesystem on it. -64kB block device is the smallest one that can mount FAT32 filesystem. - -Test can be easily extended to use any block device available in Mbed - -Test run command: -```bash -mbed test -t COMPILER -m TARGET -n tests-usb_device-msd -``` diff --git a/TESTS/usb_device/serial/README.md b/TESTS/usb_device/serial/README.md deleted file mode 100644 index f2c788eb3f..0000000000 --- a/TESTS/usb_device/serial/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# `udev` rules for Mbed USB CDC device - -Before running `tests-usb_device-serial` test suite on Debian-based Linux -distros, make sure to [update the `udev` rules][1] as follows: - -```bash -sudo tee /etc/udev/rules.d/99-ttyacms.rules >/dev/null <