extmod/machine: Add USB Host support. - #7

`mpy-cross` has unicode strings enabled, so when a .py is compiled to .mpy
it will store strings encoded as utf-8.  If a target does not have unicode
enabled then tests with utf-8 characters will fail.

Skip such tests (currently only one) in such situations.

Signed-off-by: Damien George <[email protected]>

These are needed by TinyUSB's synopsys/dwc2 driver, and are not available
in the current version of stm32lib used in this repository.

Signed-off-by: Damien George <[email protected]>

Co-authored-by: Angus Gratton <[email protected]>
Signed-off-by: Amirreza Hamzavi <[email protected]>

Signed-off-by: Angus Gratton <[email protected]>

These won't be accessed again until a new callback is set, but it stops the
objects being kept alive unnecessarily.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

This makes all esp32 boards have a consistent naming scheme used by the
MICROPY_HW_MCU_NAME macro, to have a hyphen after "ESP32" (if there's
anything following it).

This makes it easier to detect the SoC variant, eg "ESP32-S2", which now
only requires a single check, rather than supporting strings with and
without a hyphen.

Signed-off-by: Damien George <[email protected]>

Signed-off-by: Damien George <[email protected]>

Signed-off-by: Nicko van Someren <[email protected]>

If you call `rp2.StateMachine.init()` with `pull_thresh=32` it
will overwrite the FJOIN_TX bit in the SMx_SHIFTCTRL register.
This commit fixes that issue.

Signed-off-by: Ned Konz <[email protected]>

The RP2040 now supports running at 200 MHz, but the datasheet says
that speed requires an elevated core supply of 1.15 V.  The SDK
implements that in runtime_clocks_init, but we do not call that
function because we override it in clocks_extra.c.

Signed-off-by: David (Pololu) <[email protected]>

Signed-off-by: Jeff Epler <[email protected]>

Signed-off-by: Jeff Epler <[email protected]>

Bumps [actions/github-script](https://github.com/actions/github-script) from 8 to 9.
- [Release notes](https://github.com/actions/github-script/releases)
- [Commits](actions/github-script@v8...v9)

---
updated-dependencies:
- dependency-name: actions/github-script
  dependency-version: '9'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>

At version 5.9.0, to replace the existing copy at `lib/cmsis`.

Signed-off-by: Damien George <[email protected]>

At version v6.3.0.

Signed-off-by: Damien George <[email protected]>

This is a no-op change to the firmware because these CMSIS sources are
equivalent (verified building the default board for all 6 affected ports).

Signed-off-by: Damien George <[email protected]>

This is now replaced by the `lib/CMSIS_5` submodule, which has exactly the
same content at the 5.9.0 tag in the directory `CMSIS/Core/Include`.

Signed-off-by: Damien George <[email protected]>

Signed-off-by: Damien George <[email protected]>

Built all 14 boards, all have binary equivalent firmware.

Signed-off-by: Damien George <[email protected]>

Built all 8 PCA100xx boards, and they have binary equivalent firmware with
this change.

Signed-off-by: Damien George <[email protected]>

Built all 18 boards, all have binary equivalent firmware.

Signed-off-by: Damien George <[email protected]>

Built the 30 NUCLEO_xxx boards, all have binary equivalent firmware except
for NUCLEO_N657X0 (although it's firmware is the same size before and after
this commit).  Ran full test suite on OPENMV_N6 with CMSIS 6 to verify the
N6 and it passed.

Built mboot for NUCLEO_WB55, PYBV10, PYBD_SF2 and PYBD_SF6.  All have
binary equivalent firmware.

Signed-off-by: Damien George <[email protected]>

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Issue turned out to be something else, but I think there's still a
potential race here without this fix.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Was causing the next test to fail (maybe only when the other instance
skipped, not sure.)

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Test always fails on this chip, looks like possibly an ESP-IDF v5.5.1 bug.

Signed-off-by: Angus Gratton <[email protected]>

Feature check .py.exp files are not needed at all (and most of them are
empty).  Instead, the output of the feaure test is checked against a known
value within `run-tests.py` to see if that feature is enabled or not (and
in some cases like `byteorder.py` there are multiple valid output
values).

Signed-off-by: Damien George <[email protected]>

They are provided in a private header that is already included.

Signed-off-by: Damien George <[email protected]>

Signed-off-by: Daniël van de Giessen <[email protected]>

Signed-off-by: Daniël van de Giessen <[email protected]>

Bumps [actions/checkout](https://github.com/actions/checkout) from 6 to 7.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@v6...v7)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>

Bumps [actions/cache](https://github.com/actions/cache) from 5 to 6.
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](actions/cache@v5...v6)

---
updated-dependencies:
- dependency-name: actions/cache
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>

This commit updates the cache flushing logic for AArch32 targets.

Before these changes, when running on Linux the instruction and data
caches would be cleared only for AArch32 targets.  However, said checks
did not trigger properly when running an AArch32 binary on certain
AArch64 machines.

For example, the Unix port - when built using a 32-bits hard-float
toolchain - would work just fine on a Raspberry Pi 3B+ running a 64-bits
OS, but the very same binary all of a sudden becomes flaky when handling
generated code on a Raspberry Pi 4.

These changes aim to generalise cache flushing on Linux, enabling that
unconditionally whenever the target binary is built for either AArch32,
or for RISC-V.  Doing this for RISC-V acts both as a preventative
measure for the wide variety of RISC-V chips out there, and may also
help explaining some rare crashes seen when testing native modules on
certain MilkV-Duo RV64 boards.

If a binary targeting Linux is built with a compiler that is either not
compatible with GCC's builtins, or it does not provide
`__builtin___clear_cache` (too old or just broken), you'll have to
provide your own `MP_HAL_CLEAN_DCACHE` implementation.  See the
cacheflush(2) man page for why a generic fallback solution is not
provided.

This refactoring also made it required to provide a cache flush callback
for QEMU/SABRELITE, which has been generalised to cover all AArch32
targets.

Signed-off-by: Alessandro Gatti <[email protected]>

Use NUM_BANK0_GPIOS to size the pin IRQ array, avoiding a potential
leak using IRQs on pins > 30.

Signed-off-by: Phil Howard <[email protected]>

The RP2350 watchdog supports a 16777ms period vs the RP2040s 8388ms.

Signed-off-by: Phil Howard <[email protected]>

Move mod_network_init() before boot.py execution so that network
interfaces can be instantiated in boot.py.

Signed-off-by: Andrew Leech <[email protected]>

Replace the blocking PHY init and autonegotiation wait in
eth_mac_init() with background link polling via
eth_phy_link_status_poll(), called from the LWIP poll loop. This
allows active(True) to return immediately regardless of cable state,
and handles cable hot-plug by detecting link changes, reconfiguring
MAC speed/duplex after autonegotiation completes, and restarting DHCP
as needed.

PHY_BSR is read twice when sampling link status so the IEEE 802.3
latched-low link bit reflects the current state. If autoneg fails to
complete within 5s the MAC falls back to 10Mbps Half-Duplex and prints
a warning so the symptom is visible. On link-down in DHCP mode the
netif's DHCP-assigned IP is cleared before dhcp_stop() so that the
link-up restart path triggers a fresh DHCP exchange. Static IPs are
preserved since dhcp_supplied_address() gates the clear.

The netif is now registered once during eth_init() so status()
returns the physical link state before active(True) is called. The
active() method returns the interface enabled state rather than link
status; use status() for link/cable state.

Tested on NUCLEO_H563ZI (LAN8742A, 100Mb RMII) point-to-point with
AX88179 USB NIC, and OPENMV_N6 (RTL8211, 1000Mb RGMII). Builds clean
on NUCLEO_H563ZI, NUCLEO_F429ZI, NUCLEO_H743ZI, NUCLEO_N657X0.

Signed-off-by: Andrew Leech <[email protected]>

N6 is basically the same as H7 with respect to the FDCAN peripheral, and
it is configured to use the same buffer settings as H7.  That allows a
second CAN peripheral to work (eventually, once support is added), with one
CAN allocated 50% of buffer resources.

Signed-off-by: Kwabena W. Agyeman <[email protected]>
Signed-off-by: Damien George <[email protected]>

Signed-off-by: Kwabena W. Agyeman <[email protected]>
Signed-off-by: Damien George <[email protected]>

Changes:
- Use the same deep-tx-queue logic as the STM32H7.
- Use `time.sleep_ms()` instead of `pyb.delay()` (the latter is not
  available on all stm32 boards).

This test now passes on OPENMV_N6.

Signed-off-by: Damien George <[email protected]>

These aren't technically needed, but good to make sure they are populated.

Signed-off-by: Damien George <[email protected]>

The nrfx v3 update changed the TWI/TWIM xfer flag encoding (NOSTOP now
collides with POSTINC) and the SUSPEND/repeated-start behaviour (disable
between bursts releases the bus, breaking readfrom_mem/writeto_mem).

Signed-off-by: Andrew Leech <[email protected]>

Adds TinyUSB USB Host wrapper providing CDC/HID/MSC device management,
transfer handling, and GC integration. The implementation includes:

- mp_usbh.c: Core TinyUSB host wrapper with device enumeration,
  transfer management, and class-specific interfaces (CDC, HID, MSC)
- mp_usbh.h: Host configuration, init sequence, and device structs
- tusb_config.h: Extended configuration to support USB Host mode with
  fallback values when USB Device is disabled
- mp_usbd.h: Updated to include tusb_config.h unconditionally for
  macros used across device and host implementations

The mp_usbh_init_tuh() init sequence handles two edge cases:
- On shared-port boards (BOARD_TUH_RHPORT == TUD_OPT_RHPORT), calls
  tud_deinit() first to remove the device IRQ handler before the host
  resets the hardware.
- Pre-sets _tusb_rhport_role to TUSB_ROLE_HOST before tuh_init() to
  prevent an ISR race where a connected device triggers the host
  interrupt before the role is set, causing an infinite loop.

Updates lib/tinyusb submodule to version 0.20.0 which includes USB Host
driver improvements and bug fixes required for this implementation.

Signed-off-by: Andrew Leech <[email protected]>

Implements the Python-facing machine.USBHost() class providing USB Host
functionality for MicroPython. The implementation includes:

- machine_usb_host.c: Complete USBHost class with device enumeration
  methods (cdc_devices(), hid_devices(), msc_devices()), connection
  management, and class-specific interfaces for CDC, HID, and MSC devices
- extmod.cmake: Build system registration for machine_usb_host.c
- modmachine.c: Integration of USBHost class into machine module

The class provides high-level Python access to USB devices with methods
for device discovery, data transfer, and device-specific operations
(e.g., HID report parsing, MSC block I/O, CDC read/write).

Builds on the shared/tinyusb USB Host infrastructure added in the
previous commit.

Signed-off-by: Andrew Leech <[email protected]>

Adds USB Host support for ESP32-S3 with TinyUSB integration. The
implementation includes:

- esp32_common.cmake: Build integration for USB Host, including TinyUSB
  host stack configuration and source files
- main.c: USB Host task initialization on startup
- usb.c: ESP32-specific USB Host initialization and TinyUSB integration
- tinyusb_port/tusb_config.h: TinyUSB configuration for ESP32 USB stack
- tinyusb_port/tusb_config_host.h: USB Host specific TinyUSB configuration
  including HCD, CDC, MSC, and HID class support
- boards/ESP32_GENERIC_S3_USBHOST/: New board variant with
  USB Host enabled, configured for ESP32-S3's native USB
  peripheral on GPIO19/20

USB Host support requires ESP-IDF's TinyUSB component and is only
available on ESP32-S3 which has native USB OTG support.

Signed-off-by: Andrew Leech <[email protected]>

Adds USB Host support for STM32F4 with TinyUSB integration. The
implementation includes:

- Makefile: Build integration for USB Host support, including TinyUSB
  port files and conditional compilation
- main.c: USB Host task initialization
- stm32_it.c: Interrupt handling for TinyUSB stack
- msc_disk.c: Updates to support TinyUSB MSC
- usbd_conf.c: USB configuration support for TinyUSB
- tinyusb_port/: TinyUSB port implementation for STM32
  - tusb_config.h: TinyUSB configuration for STM32 USB stack
  - tusb_config_host.h: USB Host specific configuration
  - tusb_port.c: STM32-specific USB initialization and interrupt handlers
- boards/NUCLEO_F429ZI/: Base board updates for TinyUSB compatibility
- boards/NUCLEO_F429ZI_USBHOST/: USB Host variant using TinyUSB host
  stack on USB OTG FS peripheral (CN13)
- boards/NUCLEO_F429ZI_TINYUSB/: TinyUSB device-only variant for
  testing USB Host/Device communication between two boards

USB Host support uses STM32's USB OTG FS peripheral with TinyUSB's
Synopsys DWC2 driver. The VBUS detection is disabled in the TinyUSB
device variant to allow device operation without external VBUS supply
(when connecting two self-powered boards).

Signed-off-by: Andrew Leech <[email protected]>

Adds USB Host support for RP2040/RP2350 with TinyUSB integration:

- CMakeLists.txt: Build integration for USB Host including TinyUSB host
  stack, PIO USB support (via tinyusb_pico_pio_usb when available for
  dual-mode boards), --wrap=hcd_event_handler linker flag, and -Werror
  suppression for third-party PIO USB sources
- mpconfigport.h: Feature enables for USB Host mode
- mpconfigport_usbhost.h: USB Host specific port configuration with
  defaults for MICROPY_HW_USB_HOST and class support (CDC, MSC, HID)
- tinyusb_port/tusb_config_host.h: TinyUSB USB Host configuration
  including FIFO sizing, class driver configuration, and #ifndef guard
  on BOARD_TUH_RHPORT so boards can override
- boards/RPI_PICO2_USBHOST/: USB Host variant for Pico2 with RP2350
- boards/WAVESHARE_RP2350_USB_A/: New board configuration for Waveshare
  RP2350-USB-A which has USB-A receptacle for USB Host mode

Updates lib/pico-sdk submodule to version with RP2350 USB Host support.

Signed-off-by: Andrew Leech <[email protected]>

Adds USB Host support for the i.MX RT port via the shared TinyUSB host
infrastructure. Three board variants provided:

- MIMXRT1010_EVK_USBHOST: RT1010 with reduced TinyUSB config (max 2
  devices, no hub) due to limited memory. USB host data placed in OCRAM
  via custom linker script since DTCM is only 32KB.

- MIMXRT1060_EVK_USBHOST: RT1060 with standard host config using DTCM.

- MIMXRT1170_EVK_USBHOST: RT1170 with standard host config.

Includes linker-time assertion to catch USB host RAM section overflow
during build on memory-constrained boards.

Adds automatic UART dupterm in _boot.py when machine.USBHost is present
and machine.USBDevice is not, so single-port host boards (without USB
CDC REPL) have serial console access out of the box.

Signed-off-by: Andrew Leech <[email protected]>

Adds simultaneous USB device (RHPORT0/USB_OTG1 for CDC REPL) and host
(RHPORT1/USB_OTG2) support for MIMXRT1170-EVK. Includes tusb_config_dual.h,
dual USB PHY init, unified IRQ handlers, EHCI data placement in OCRAM,
and hcd_event_handler linker wrap.

The MIMXRT1170_EVK_USBHOST_DUAL board config inherits from the base
MIMXRT1170_EVK with USB host overrides rather than duplicating the full
config.

Signed-off-by: Andrew Leech <[email protected]>

Adds multi-instance tests for USB Host functionality, testing Host/Device
communication between two MicroPython boards. The test suite includes:

CDC (USB Serial) tests:
- cdc_basic.py: Basic CDC read/write operations between host and device
- cdc_custom_lib.py: CDC operations using usb.device library
- cdc_irq.py: CDC interrupt-driven I/O

HID (Human Interface Device) tests:
- hid_keyboard.py: HID keyboard report parsing and input
- hid_mouse.py: HID mouse report parsing and movement

MSC (Mass Storage Class) tests:
- msc_block_rw.py: Block-level read/write operations
- msc_mount_write.py: Filesystem mount and file operations

Device disconnect handling:
- disconnect_cdc.py: CDC device disconnect/reconnect handling
- disconnect_hid.py: HID device disconnect/reconnect handling
- disconnect_msc.py: MSC device disconnect/reconnect handling

Multi-interface enumeration:
- enum_multi_interface.py: Enumeration of composite USB devices

Each test includes a .py.exp file with expected output for automated
verification. Tests require two boards: one as USB Host (instance 0)
and one as USB Device (instance 1), connected via USB cable.

Signed-off-by: Andrew Leech <[email protected]>

Adds API reference documentation for machine.USBHost class at
docs/library/machine.USBHost.rst.

The documentation covers:
- USBHost class constructor and activation
- Device enumeration methods (devices(), cdc_devices(), hid_devices(),
  msc_devices())
- Class-specific interfaces:
  - CDC: read(), write(), irq() for serial communication
  - HID: read_report() for input device data
  - MSC: block I/O and filesystem mount operations
- Device lifecycle and error handling
- Example usage for each device class

Provides complete reference for USB Host functionality available on
ESP32-S3, RP2040/RP2350, and STM32F4 ports.

Signed-off-by: Andrew Leech <[email protected]>

Enable MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE for all MIMXRT boards,
add mp_usbd_runtime.c to the build, and freeze the usb-device Python
modules (CDC, HID, keyboard, mouse).

Tested on MIMXRT1170-EVK with ESP32-S3 as USB host: built-in CDC
enumeration, Python CDC bidirectional data transfer, HID keyboard
and mouse reports all verified.

Signed-off-by: Andrew Leech <[email protected]>

When CFG_TUH_RPI_PIO_USB and MICROPY_HW_USB_HOST_DP_PIN are defined,
configure PIO USB pin mapping via tuh_configure() before tuh_init().

Use the default pico-sdk alarm pool (alarm_pool_get_default()) instead
of creating a new one. The default PIO USB alarm_pool_create(2, 1)
panics because MicroPython's soft timer already claims hardware alarm 2.

Signed-off-by: Andrew Leech <[email protected]>

Reconfigure for dual-mode USB: native USB controller in device mode
(USB-C, REPL) on rhport 0, PIO USB in host mode (USB-A receptacle,
GPIO12/13) on rhport 1.

Set system clock to 120MHz (multiple of 12MHz required by PIO USB).
RP2350 default 150MHz doesn't divide evenly.

The original board config assumed native dual-controller host mode
which doesn't work as the RP2350 has only one USB controller. PIO USB
provides the second port via PIO state machines.

Tested on Waveshare RP2350-USB-A with ESP32-S3 native USB CDC device
connected to the USB-A receptacle. Host enumeration, CDC read/write
all verified.

Signed-off-by: Andrew Leech <[email protected]>

Bump micropython-lib submodule to include usb-device-cdc fix for
default timeout in CDCInterface.init().

Signed-off-by: Andrew Leech <[email protected]>

Move lib/tinyusb to a 0.21.0 base carrying the rp2 host abort/close and
tuh_next_deferred_ms accessor patches, and adapt the glue to 0.21: host
init uses tusb_init(rhport, role) (which sets the role atomically and
closes the ISR role race), and machine_usb_device.c passes the new
usbd_edpt_xfer is_isr argument. The accessor drives a one-shot soft timer
(mp_usbh.c) that pumps tuh_task at the stack's next deferred enumeration
deadline, so host-driven enumeration completes rather than only advancing
on USB events. The stm32/rp2/mimxrt builds suppress -Wunused-function on
the vendored host sources and add the ChipIdea HS host controller driver
on mimxrt. The esp32 port overlays these host sources onto the ESP-IDF
TinyUSB component, which lacks the 0.21 host API, so esp32 host is
unavailable at this revision.

Signed-off-by: Andrew Leech <[email protected]>