19037: sys/usb, pkg/tinyusb: move USB board reset from highlevel STDIO to CDC ACM r=dylad a=gschorcht
### Contribution description
The USB board reset function `usb_board_reset_coding_cb` can be used on any CDC-ACM interface, even if the CDC ACM interface is not used as high-level STDIO. Therefore, this PR provides the following changes:
- The call of the board reset function `usb_board_reset_coding_cb` from USBUS stack has been moved from the STDIO CDC ACM implementation to the CDC ACM implementation and is thus a feature of any USBUS CDC ACM interface which does not necessarily have to be used as highlevel STDIO.
- The call of the board reset function `usb_board_reset_coding_cb` from tinyUSB stack been moved from module `tinyusb_stdio_cdc_acm` to module `tinyusb_contrib` and is compiled in if the `tinyusb_class_cdc` module is used together the `tinyusb_device` module. Thus, it is now a feature of the tinyUSB CDC ACM interface, which does not necessarily have to be used as highlevel STDIO.
- The `usb_board_reset` module defines the `usb_board_reset_in_bootloader` function as a weak symbol to be used when reset in bootloader if no real implementation of this function is compiled in and the `riotboot_reset` module is not used. It only prints an error message that the reset in bootloader is not supported. This is necessary if the module `usb_board_reset` is used to be able to restart the board with an application via a USB CDC ACM interface, but the board's bootloader does not support the reset in bootloader feature.
- A test application has been added that either uses the highlevel STDIO `stdio_acm_cdc` or creates a CDC-ACM interface to enable board resets via USB. If the `usbus_dfu` module is used, it also initializes the DFU interface to be able to work together with the `riotboot_dfu` bootloader.
### Testing procedure
1. Use a board with a bootloader that supports the reset in bootloader via USB, but don't use the highlevel STDIO to check that it works with `usbus_cdc_acm`, for example:
```python
USEMODULE=stdio_uart BOARD=arduino-mkr1000 make -C tests/usb_board_reset flash
```
After reset in application with command
```python
stty -F /dev/ttyACM0 raw ispeed 600 ospeed 600 cs8 -cstopb ignpar eol 255 eof 255
```
command `dmesg` should give an output like the following with RIOT's test VID/PID:
```python
dmesg
[1745182.057403] usb 1-4.1.2: new full-speed USB device number 69 using xhci_hcd
[1745182.160386] usb 1-4.1.2: New USB device found, idVendor=1209, idProduct=7d01, bcdDevice= 1.00
[1745182.160390] usb 1-4.1.2: New USB device strings: Mfr=3, Product=2, SerialNumber=4
[1745182.160392] usb 1-4.1.2: Product: arduino-mkr1000
[1745182.160393] usb 1-4.1.2: Manufacturer: RIOT-os.org
[1745182.160395] usb 1-4.1.2: SerialNumber: 6B6C2CA5229020D8
[1745182.170982] cdc_acm 1-4.1.2:1.0: ttyACM0: USB ACM device
```
After reset in bootloader with command
```python
stty -F /dev/ttyACM0 raw ispeed 1200 ospeed 1200 cs8 -cstopb ignpar eol 255 eof 255
```
command `dmesg` should give an output like the following with vendor VID/PID:
```python
[1746220.443792] usb 1-4.1.2: new full-speed USB device number 70 using xhci_hcd
[1746220.544705] usb 1-4.1.2: New USB device found, idVendor=2341, idProduct=024e, bcdDevice= 2.00
[1746220.544708] usb 1-4.1.2: New USB device strings: Mfr=0, Product=0, SerialNumber=0
[1746220.553471] cdc_acm 1-4.1.2:1.0: ttyACM0: USB ACM device
```
2. Test the same as in 1., but this time use the highlevel STDIO to check that there is no regression and it still works with `stdio_cdc_acm`, for example:
```python
BOARD=arduino-mkr1000 make -C tests/usb_board_reset flash
```
3. Use a board that supports `riotboot_dfu` but doesn't use the highlevel STDIO and flash the `riotboot_dfu` bootloader, for example:
```python
BOARD=stm32f429i-disc1 make -C bootloaders/riotboot_dfu flash term
```
Once the bootloader is flashed, command `dfu-util --list` should give something like the following:
```python
Found DFU: [1209:7d02] ver=0100, devnum=14, cfg=1, intf=0, path="1-2", alt=1, name="RIOT-OS Slot 1", serial="6591620BCB270283"
Found DFU: [1209:7d02] ver=0100, devnum=14, cfg=1, intf=0, path="1-2", alt=0, name="RIOT-OS Slot 0", serial="6591620BCB270283"
```
If the output gives only
```python
Found Runtime: [1209:7d00] ver=0100, devnum=123, cfg=1, intf=0, path="1-2", alt=0, name="RIOT-OS bootloader", serial="6591620BCB270283"
```
an application is already running in DFU Runtime mode. Use `dfu-util -e` to restart it in bootloader DFU mode.
Then flash the test application, for example:
```python
FEATURES_REQUIRED=riotboot USEMODULE='usbus_dfu riotboot_reset' \
BOARD=stm32f429i-disc1 make -C tests/usbus_board_reset PROGRAMMER=dfu-util riotboot/flash-slot0
```
Once the test application is flashed, command `dfu-util --list` should give:
```python
Found Runtime: [1209:7d00] ver=0100, devnum=123, cfg=1, intf=0, path="1-2", alt=0, name="RIOT-OS bootloader", serial="6591620BCB270283"
```
Now, use command
```python
stty -F /dev/ttyACM1 raw ispeed 600 ospeed 600 cs8 -cstopb ignpar eol 255 eof 255
```
to restart the board in application. Command `dfu-util --list` should give again the following:
```python
Found Runtime: [1209:7d00] ver=0100, devnum=123, cfg=1, intf=0, path="1-2", alt=0, name="RIOT-OS bootloader", serial="6591620BCB270283"
```
That is, the application is running in DFU Runtime mode. Then use command
```python
stty -F /dev/ttyACM1 raw ispeed 1200 ospeed 1200 cs8 -cstopb ignpar eol 255 eof 255
```
to restart the board in bootloader DFU mode. Command `dfu-util --list` should now give the following:
```python
Found DFU: [1209:7d02] ver=0100, devnum=50, cfg=1, intf=0, path="1-2", alt=1, name="RIOT-OS Slot 1", serial="7D156425A950A8EB"
Found DFU: [1209:7d02] ver=0100, devnum=50, cfg=1, intf=0, path="1-2", alt=0, name="RIOT-OS Slot 0", serial="7D156425A950A8EB"
```
That is, the bootloader is in DFU mode and another application can be flash.
4. After a hard reset of the board under 3., try the commands `reboot` and `bootloader`.
5. To check the same for tinyUSB, use the existing tinyUSB application with a CDC ACM interface and add module `usb_board_reset`, for example:
```python
USEMODULE=usb_board_reset BOARD=stm32f429i-disc1 make -C tests/pkg_tinyusb_cdc_msc flash term
```
After flashing, it should be possible to restart the application with command:
```python
stty -F /dev/ttyACM1 raw ispeed 600 ospeed 600 cs8 -cstopb ignpar eol 255 eof 255
```
When using command
```python
stty -F /dev/ttyACM1 raw ispeed 1200 ospeed 1200 cs8 -cstopb ignpar eol 255 eof 255
```
the following error message should be shown in terminal
```python
[cdc-acm] reset in bootloader is not supported
```
### Issues/PRs references
Co-authored-by: Gunar Schorcht <gunar@schorcht.net>
There are a number of tests included in RIOT. They are located in the
tests folder. These tests
allow basic functionality to be verified as well as provide an example of
usage.
Running automated tests
Some tests can be performed automatically. The test automation scripts are
defined in the <test_application>/tests/ folder. They are written in python
and interact through the serial (typically UART) with the test application code running on a
board to do the validation. It is recommended to flash the board with the
test just before running it because some platforms cannot be reset while
testing.
Running single test
From the test application directory run:
BOARD=<board_of_your_choice> make flash test
An automated way of knowing if a test is available is to execute the
'test/available' target from the test application directory.
It executes without error if tests run by 'make test' are present.
make test/available
Running all test for particular board
If you would like execute all tests for given board, you could use dedicated
script compile_and_test_for_board.py
Running tests that require a preliminary manual configuration
Some tests need active monitoring or manual setup steps but still have some
automated scripts. The test automation scripts are defined in the
<test_application>/tests-with-config/ folder.
For running them, follow the setup or analysis documentation and use the
test-with-config target.
Running tests that require root privileges
Some tests require root privileges to launch their automated script. In this
case, the test automation scripts are defined in the
<test_application>/tests-as-root/ folder.
For running them, follow the setup or analysis documentation and use the
test-as-root target.
Cleaning intermediate files
After test execution intermediate files are not automatically deleted.
Execution of multiple tests, especially all for particular board could generate
many files. For example, after execution of all test for stm32f469i-disco board
(more than 230 tests) around 7.5 GB of intermediate files are created.
There are few methods for cleaning intermediate files.
If you would like to clean intermediate file only for particular board you should
go to main RIOT directory and execute one from these commands:
If you would like to clean intermediate files for all boards go to main RIOT
directory and use this command.
@warning This command cleans all local files, for example, pkg downloads and
locally generared docs.
make distclean
Implementing automated tests
The goal is to be able to run all tests in a sequential way for as many targets
as possible.
As some board can't be reset without a manual trigger tests should be implemented
with some kind of synchronization. This can be done in two ways:
use test_utils_interactive_sync when uart input/output does not need to be
disabled for the test. This is enabled by default.
set up the test in a loop so the test script will be able so sync with some kind
of start condition in the test.
The module for the first option is test_utils_interactive_sync and is set as a
default module in Makefile.tests_common. It can be disabled by setting in the
application makefile DISABLE_MODULE += test_utils_interactive_sync. The python
test script will adapt to it automatically.
When using the shell module, test_utils_interactive_sync will use the shell
itself to synchronize, and will not use test_utils_interactive_sync(); function
to synchronize. Some times you will want to synchronize before the start of the
script and use test_utils_interactive_sync(); function (e.g.:
tests/ps_schedstatistics). For these cases
you can disable test_utils_interactive_sync_shell module in the application
Makefile: DISABLE_MODULE += test_utils_interactive_sync_shell.
Automated Tests Guidelines
When using pexpect$ is useless for matching the end of a line, instead use
\r\n(pexpect end-of-line).
Beware of + and * at the end of patterns. These patterns will always get
a minimal match (non-greedy).(pexpect end-of-patterns)
This can be an issue when matching groups and using the matched groups to verify
some kind of behavior since * could return an empty match and + only a subset.
This is especially prevalent since printf() is buffered so the output might not
arrive in a single read to pexpect.
To avoid this make sure to match a non-ambiguous character at the end of the
pattern like \r\n, \s, \), etc..
don't:
child.expect(r'some string: (\d+)')
do:
child.expect(r'some string: (\d+)\r\n')
child.expect(r'some string: (\d+)\s')
child.expect(r'some string: (\d+) ,')
Use expect() instead of assert()
In order to make a test application functional in all cases, use expect()
instead of assert(). The former works like the latter, but will still be
compiled in if NDEBUG is defined. This is useful to keep a test application
working even when compiling with -DNDEBUG, allowing for the code-under-test to
be compiled with that flag. Otherwise, the application would force compiling
all tested code with assertions enabled.
expect() is defined in the header test_utils/expect.h.
Interaction through the uart
Tests implemented with testrunner use the cleanterm target that
provides an interaction without adding extra text output or input handling.
It can currently be expected to have unmodified line based interaction with the
board.
The expected behavior is verified with the test in tests/test_tools.
Tests cannot rely on having on all boards and terminal programs:
unbuffered input
allowing sending special characters like ctrl+c/ctrl+d
e51d8285f3