mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-24 14:03:55 +01:00
e51d8285f3
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>