ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #10688 from fkjagodzinski/test_update-docs-usb 

Add a top level README file for USB tests
pull/10867/head
Anna Bridge 2019-06-19 12:21:39 +01:00 committed by GitHub
parent d8c17b5fab 0ae1be0e65
commit aa9bd486d5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 158 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
TESTS/usb_device/README.md Normal file
View File

@ -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 <<EOF
ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2013", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2012", ENV{ID_MM_DEVICE_IGNORE}="1"
EOF
sudo udevadm control --reload-rules
```
This will prevent the `ModemManager` daemon from automatically opening the
port and sending the `AT commands`, which it does for every new
`/dev/ttyACM` device registered in system.
### Mac
No setup method has been verified for this platform.
## Running tests
1. Plug both USB interfaces (*DAPLink* and *USB device*) to your host machine.
1. Run tests:
```
mbed test -t <toolchain> -m <target> -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 <toolchain> -m <target> -n tests-usb_device-* --compile
sudo mbed test -t <toolchain> -m <target> -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.
<!-- LINKS -->
[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

15
TESTS/usb_device/basic/README.md
View File

@ -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).

18
TESTS/usb_device/basic/zadig_conf/README.md
View File

@ -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*).

23
TESTS/usb_device/hid/README.md
View File

@ -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

12
TESTS/usb_device/msd/README.md
View File

@ -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
```

18
TESTS/usb_device/serial/README.md
View File

@ -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 <<EOF
ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2013", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2012", ENV{ID_MM_DEVICE_IGNORE}="1"
EOF
sudo udevadm control --reload-rules
```
This will prevent the `ModemManager` daemon from automatically opening the port
and sending the `AT commands`, which it does for every new `/dev/ttyACM` device
registered in system.
[1]: https://linux-tips.com/t/prevent-modem-manager-to-capture-usb-serial-devices/284