diff --git a/.github/ci/.idf_build_examples_config.toml b/.github/ci/.idf_build_examples_config.toml new file mode 100644 index 0000000000..26e47be2ea --- /dev/null +++ b/.github/ci/.idf_build_examples_config.toml @@ -0,0 +1,19 @@ +# Config file for build_idf_examples.yml workflow + +paths = [ + "examples/peripherals/usb/device", # USB Device examples + #"examples/network/sta2eth", # USB Network example +] + +manifest_files = [ + "examples/peripherals/.build-test-rules.yml", + "examples/network/.build-test-rules.yml", +] + +recursive = true +check_warnings = true +target = "all" +#enable_preview_targets = true + +# build related options +build_dir = "build_@t" diff --git a/.github/ci/override_managed_component.py b/.github/ci/override_managed_component.py new file mode 100644 index 0000000000..14eb2df2f6 --- /dev/null +++ b/.github/ci/override_managed_component.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python +# +# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD +# SPDX-License-Identifier: Apache-2.0 + +import sys +import argparse +import yaml +from pathlib import Path +from glob import glob +from idf_component_tools.manager import ManifestManager + + +def override_with_local_component(component, local_path, app): + app_path = Path(app) + + absolute_local_path = Path(local_path).absolute() + if not absolute_local_path.exists(): + print('[Error] {} path does not exist'.format(local_path)) + raise Exception + if not app_path.exists(): + print('[Error] {} path does not exist'.format(app_path)) + raise Exception + + print('[Info] Processing app {}'.format(app)) + manager = ManifestManager(app_path / 'main', 'app') + if '/' not in component: + # Prepend with default namespace + component = 'espressif/' + component + + try: + manifest_tree = yaml.safe_load(Path(manager.path).read_text()) + manifest_tree['dependencies'][component] = { + 'version': '*', + 'override_path': str(absolute_local_path) + } + with open(manager.path, 'w') as f: + yaml.dump(manifest_tree, f, allow_unicode=True, Dumper=yaml.SafeDumper) + except KeyError: + print('[Error] {} app does not depend on {}'.format(app, component)) + raise KeyError + +def override_with_local_component_all(component, local_path, apps): + # Process wildcard, e.g. "app_prefix_*" + apps_with_glob = list() + for app in apps: + apps_with_glob += glob(app) + + # Go through all collected apps + for app in apps_with_glob: + try: + override_with_local_component(component, local_path, app) + except: + print("[Error] Could not process app {}".format(app)) + return -1 + return 0 + + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('component', help='Existing component that the app depends on') + parser.add_argument('local_path', help='Path to component that will be used instead of the managed version') + parser.add_argument('apps', nargs='*', help='List of apps to process') + args = parser.parse_args() + sys.exit(override_with_local_component_all(args.component, args.local_path, args.apps)) diff --git a/.github/workflows/build_and_run_esp_usb_test_apps.yml b/.github/workflows/build_and_run_esp_usb_test_apps.yml new file mode 100644 index 0000000000..c0a85b23a4 --- /dev/null +++ b/.github/workflows/build_and_run_esp_usb_test_apps.yml @@ -0,0 +1,81 @@ +name: ESP-USB Test Apps + +on: + pull_request: + types: [opened, reopened, synchronize] + +jobs: + build: + name: Build + strategy: + matrix: + idf_ver: ["release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4", "release-v5.5", "latest"] + runs-on: ubuntu-latest + container: espressif/idf:${{ matrix.idf_ver }} + env: + ESP_TINYUSB_TEST_APPS: ./esp-usb/device/esp_tinyusb/test_apps + steps: + - uses: actions/checkout@v4 + with: + submodules: 'true' + - name: Clone esp-usb repository + run: | + git clone https://github.com/espressif/esp-usb.git + - name: Build + shell: bash + run: | + . ${IDF_PATH}/export.sh + pip install --no-cache-dir idf-component-manager>=2.1.2 idf-build-apps==2.13.1 pyyaml --upgrade + export PEDANTIC_FLAGS="-DIDF_CI_BUILD -Werror -Werror=deprecated-declarations -Werror=unused-variable -Werror=unused-but-set-variable -Werror=unused-function" + export EXTRA_CFLAGS="${PEDANTIC_FLAGS} -Wstrict-prototypes" + export EXTRA_CXXFLAGS="${PEDANTIC_FLAGS}" + python .github/ci/override_managed_component.py tinyusb . ${{ env.ESP_TINYUSB_TEST_APPS }}/*/ + cd esp-usb + idf-build-apps find --path ./device/esp_tinyusb/test_apps/ + idf-build-apps build --path ./device/esp_tinyusb/test_apps/ + - uses: actions/upload-artifact@v4 + with: + name: usb_test_app_bin_${{ matrix.idf_ver }} + path: | + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/bootloader/bootloader.bin + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/partition_table/partition-table.bin + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/test_app_*.bin + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/test_app_*.elf + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/flasher_args.json + ${{env.ESP_TINYUSB_TEST_APPS}}/**/build_*/config/sdkconfig.json + if-no-files-found: error + + # run-target: + # name: Run + # if: ${{ github.repository_owner == 'espressif' }} + # needs: build + # strategy: + # matrix: + # idf_ver: ["release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4", "release-v5.5", "latest"] + # idf_target: ["esp32s2"] + # runner_tag: ["usb_device"] + # runs-on: [self-hosted, linux, docker, "${{ matrix.idf_target }}", "${{ matrix.runner_tag }}"] + # container: + # image: python:3.11-bookworm + # options: --privileged --device-cgroup-rule="c 188:* rmw" --device-cgroup-rule="c 166:* rmw" + # env: + # ESP_TINYUSB_TEST_APPS: ./esp-usb/device/esp_tinyusb/test_apps + # steps: + # - uses: actions/checkout@v4 + # - name: Clone esp-usb repository + # run: | + # git clone https://github.com/espressif/esp-usb.git + # - name: ⚙️ Install System tools + # run: | + # apt update + # apt install -y usbutils + # - name: Install Python packages + # env: + # PIP_EXTRA_INDEX_URL: "https://dl.espressif.com/pypi/" + # run: pip install --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf pyserial pyusb + # - uses: actions/download-artifact@v4 + # with: + # name: usb_test_app_bin_${{ matrix.idf_ver }} + # path: ${{env.ESP_TINYUSB_TEST_APPS}} + # - name: Run USB Test App on target + # run: pytest ${{env.ESP_TINYUSB_TEST_APPS}} --embedded-services esp,idf --target=${{ matrix.idf_target }} -m ${{ matrix.runner_tag }} --build-dir=build_${{ matrix.idf_target }} diff --git a/.github/workflows/build_and_run_idf_examples.yml b/.github/workflows/build_and_run_idf_examples.yml new file mode 100644 index 0000000000..2d1792fe78 --- /dev/null +++ b/.github/workflows/build_and_run_idf_examples.yml @@ -0,0 +1,80 @@ +name: ESP-IDF USB Device examples + +on: + pull_request: + types: [opened, reopened, synchronize] + +jobs: + build: + strategy: + matrix: + idf_ver: ["release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4", "release-v5.5", "latest"] + fail-fast: false + runs-on: ubuntu-latest + container: espressif/idf:${{ matrix.idf_ver }} + env: + CONFIG_PATH: ${{ github.workspace }}/.github/ci/.idf_build_examples_config.toml + steps: + - uses: actions/checkout@v4 + - name: Install Python dependencies + shell: bash + run: | + . ${IDF_PATH}/export.sh + pip install --no-cache-dir idf-component-manager>=2.1.2 idf-build-apps==2.13.1 pyyaml --upgrade + - name: Build USB Device examples + shell: bash + run: | + . ${IDF_PATH}/export.sh + python .github/ci/override_managed_component.py tinyusb . ${IDF_PATH}/examples/peripherals/usb/device/tusb_* + python .github/ci/override_managed_component.py tinyusb . ${IDF_PATH}/examples/network/sta2eth + cd ${IDF_PATH} + idf-build-apps find --config-file ${CONFIG_PATH} + idf-build-apps build --config-file ${CONFIG_PATH} + - uses: actions/upload-artifact@v4 + with: + # We upload only the USB Device example binaries to run them on the target + name: usb_device_tusb_apps_bin_${{ matrix.idf_ver }} + path: | + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/bootloader/bootloader.bin + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/partition_table/partition-table.bin + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/tusb_*.bin + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/tusb_*.elf + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/flasher_args.json + /opt/esp/idf/examples/peripherals/usb/device/tusb_*/build_*/config/sdkconfig.json + if-no-files-found: error + run-target: + name: Run USB Device examples + if: ${{ github.repository_owner == 'espressif' }} + needs: build + strategy: + fail-fast: false + matrix: + idf_ver: ["release-v5.3", "release-v5.4", "release-v5.5" , "latest"] + idf_target: ["esp32s2"] + runner_tag: ["usb_device"] + runs-on: [self-hosted, linux, docker, "${{ matrix.idf_target }}", "${{ matrix.runner_tag }}"] + container: + image: espressif/idf:${{ matrix.idf_ver }} + options: --privileged --device-cgroup-rule="c 188:* rmw" --device-cgroup-rule="c 166:* rmw" + steps: + - name: ⚙️ Install System tools + run: | + apt update + apt install net-tools + - name: ⚙️ Install Python packages + env: + PIP_EXTRA_INDEX_URL: "https://dl.espressif.com/pypi/" + run: | + cd ${IDF_PATH} + . ./export.sh + pip install --no-cache-dir --only-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-jtag pytest-embedded-idf pyserial pyusb python-gitlab minio idf-build-apps idf_ci pytest_ignore_test_results pytest-timeout netifaces + - uses: actions/download-artifact@v4 + with: + name: usb_device_tusb_apps_bin_${{ matrix.idf_ver }} + path: /opt/esp/idf/examples/peripherals/usb/device + - name: Run USB Test App on target + run: | + cd ${IDF_PATH} + . ./export.sh + export EXAMPLES_PATH="${IDF_PATH}/examples/peripherals/usb/device" + pytest ${EXAMPLES_PATH} --target ${{ matrix.idf_target }} -m ${{ matrix.runner_tag }} --ignore-result-cases=*ncm_example diff --git a/.github/workflows/build_iot_examples.yml b/.github/workflows/build_iot_examples.yml new file mode 100644 index 0000000000..0c650c7aac --- /dev/null +++ b/.github/workflows/build_iot_examples.yml @@ -0,0 +1,33 @@ +name: ESP IoT Solution - USB Device Examples + +on: + pull_request: + types: [opened, reopened, synchronize] + +jobs: + build: + strategy: + matrix: + idf_ver: ["release-v5.3", "release-v5.4", "release-v5.5", "latest"] + name: ["usb_uart_bridge"] + runs-on: ubuntu-latest + container: espressif/idf:${{ matrix.idf_ver }} + env: + ESP_IOT_PATH: esp-iot-solution + MANIFEST_PATH: esp-iot-solution/examples/.build-rules.yml + EXAMPLE_PATH: esp-iot-solution/examples/usb/device/${{ matrix.name }} + steps: + - uses: actions/checkout@v4 + with: + submodules: 'true' + - name: Clone esp-iot-solution repository + run: | + git clone https://github.com/espressif/esp-iot-solution.git + - name: Build + shell: bash + run: | + . ${IDF_PATH}/export.sh + pip install --no-cache-dir idf-component-manager>=2.1.2 idf-build-apps==2.13.1 pyyaml --upgrade + python .github/ci/override_managed_component.py tinyusb . ${{ env.EXAMPLE_PATH }}/ + idf-build-apps find --paths ${{ env.EXAMPLE_PATH }} --manifest-file ${{ env.MANIFEST_PATH }} --manifest-rootpath ${{ env.ESP_IOT_PATH }} + idf-build-apps build --paths ${{ env.EXAMPLE_PATH }} --manifest-file ${{ env.MANIFEST_PATH }} --manifest-rootpath ${{ env.ESP_IOT_PATH }} diff --git a/.github/workflows/upload_component.yml b/.github/workflows/upload_component.yml new file mode 100644 index 0000000000..3fe1a03dc0 --- /dev/null +++ b/.github/workflows/upload_component.yml @@ -0,0 +1,21 @@ +name: Push TinyUSB to Espressif Component Service + +# If the commit is tagged, it will be uploaded. Other scenario silently fail. +on: + push: + tags: + - v* + +jobs: + upload_components: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Upload components to component service + uses: espressif/upload-components-ci-action@v2 + with: + components: "tinyusb: ." + version: ${{ github.ref_name }} + namespace: "espressif" + api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }} diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000000..9ac96367fc --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,80 @@ +idf_build_get_property(target IDF_TARGET) + +if(${target} STREQUAL "esp32s3") + set(tusb_mcu "OPT_MCU_ESP32S3") + set(tusb_family "esp32sx") +elseif(${target} STREQUAL "esp32s2") + set(tusb_mcu "OPT_MCU_ESP32S2") + set(tusb_family "esp32sx") +elseif(${target} STREQUAL "esp32p4") + set(tusb_mcu "OPT_MCU_ESP32P4") + set(tusb_family "esp32px") +elseif(${target} STREQUAL "esp32h4") + set(tusb_mcu "OPT_MCU_ESP32H4") + set(tusb_family "esp32sx") +endif() + +set(compile_options + "-DCFG_TUSB_MCU=${tusb_mcu}" + ) + +idf_component_get_property(freertos_include freertos ORIG_INCLUDE_PATH) + +set(includes_private + "src/" + "src/device" + "lib/networking" # For RNDIS definitions + ) + +set(includes_public + "src/" + # The FreeRTOS API include convention in tinyusb is different from esp-idf + "${freertos_include}" + ) + +set(srcs + "src/class/cdc/cdc_device.c" + "src/class/hid/hid_device.c" + "src/class/midi/midi_device.c" + "src/class/msc/msc_device.c" + "src/class/vendor/vendor_device.c" + "src/class/audio/audio_device.c" + "src/class/video/video_device.c" + "src/class/bth/bth_device.c" + "src/class/usbtmc/usbtmc_device.c" + # NET class + "src/class/net/ecm_rndis_device.c" + "lib/networking/rndis_reports.c" + "src/class/net/ncm_device.c" + # DFU + "src/class/dfu/dfu_device.c" + "src/class/dfu/dfu_rt_device.c" + # Common, device-mode related + "src/portable/synopsys/dwc2/dcd_dwc2.c" + "src/portable/synopsys/dwc2/dwc2_common.c" + "src/common/tusb_fifo.c" + "src/device/usbd_control.c" + "src/device/usbd.c" + "src/tusb.c" + ) + +set(requirements_private + esp_netif # required by rndis_reports.c: #include "netif/ethernet.h" + ) + +if(${target} STREQUAL "esp32p4") + list(APPEND requirements_private + esp_mm # required by dcd_dwc2.c: #include "esp_cache.h" + ) +endif() + +idf_component_register(SRCS ${srcs} + INCLUDE_DIRS ${includes_public} + PRIV_INCLUDE_DIRS ${includes_private} + PRIV_REQUIRES ${requirements_private} + ) + +target_compile_options(${COMPONENT_LIB} PUBLIC ${compile_options}) + +# when no builtin class driver is enabled, an uint8_t data compared with `BUILTIN_DRIVER_COUNT` will always be false +set_source_files_properties("src/device/usbd.c" PROPERTIES COMPILE_FLAGS "-Wno-type-limits") diff --git a/README.md b/README.md new file mode 100644 index 0000000000..8e88c4d92d --- /dev/null +++ b/README.md @@ -0,0 +1,71 @@ +# Espressif TinyUSB component + +[![Component Registry](https://components.espressif.com/components/espressif/tinyusb/badge.svg)](https://components.espressif.com/components/espressif/tinyusb) +![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) +[![ESP-IDF USB Device examples](https://github.com/espressif/tinyusb/actions/workflows/build_and_run_idf_examples.yml/badge.svg?branch=release%2Fv0.19)](https://github.com/espressif/tinyusb/actions/workflows/build_and_run_idf_examples.yml) + +## Overview + +This repository is Espressif’s maintained fork of [TinyUSB](https://github.com/hathach/tinyusb), integrated with the ESP-IDF build system. It exists to provide ESP users with timely TinyUSB updates, as upstream releases occur too infrequently to match Espressif’s hardware cadence. All fixes and features developed in this repository are submitted upstream to maintain long-term alignment with the official TinyUSB project and minimize divergence between the two codebases. + +Only Device part of TinyUSB stack is supported. For Host mode, please refer to [espressif/usb](https://components.espressif.com/components/espressif/usb) component. + +#### Versioning and branching + +TinyUSB has not yet reached its first stable release (v1.0.0), so breaking changes may still occur in any version. In practice, the API remains relatively stable, and when incompatible changes arise, we aim to preserve backward compatibility where feasible. + +For each upstream release tag (e.g., `0.18.0`), a corresponding branch is created (e.g., `release/v0.18`). Ongoing development continues on this branch, occasionally synchronized with upstream’s `master` branch. Espressif release versions follow a revision-based suffix scheme: for example, `0.18.0~2` represents an intermediate commit derived from the upstream 0.18.0 release. + +#### Examples + +USB Device examples based on TinyUSB are present in [esp-idf](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/device). + +## How to use + +There are two options of using TinyUSB component with Espressif's SoCs: + +### 1. Use component via [esp_tinyusb](https://components.espressif.com/components/espressif/esp_tinyusb) + +[Espressif TinyUSB additions](https://github.com/espressif/esp-usb/tree/master/device/esp_tinyusb) (esp_tinyusb) provide several preconfigured features to use benefits of TinyUSB stack faster. + +To use [Espressif TinyUSB additions](https://github.com/espressif/esp-usb/tree/master/device/esp_tinyusb), add ``idf_component.yml`` to your main component with the following content:: + +```yaml +## IDF Component Manager Manifest File +dependencies: + esp_tinyusb: "^2.0.0" # Automatically update minor releases +``` + +Or simply run: +```sh +idf.py add-dependency "esp_tinyusb^2.0.0" +``` + +Then, the Espressif TinyUSB component will be added automatically during resolving dependencies by the component manager. + +### 2. Using standalone TinyUSB + +Use this option for custom TinyUSB applications. +In this case you will have to provide configuration header file ``tusb_config.h``. More information about TinyUSB configuration can be found [in official TinyUSB documentation](https://docs.tinyusb.org/en/latest/reference/getting_started.html). + +You will also have to tell TinyUSB where to find the configuration file. This can be achieved by adding following CMake snippet to your main component's ``CMakeLists.txt``: + +```cmake +idf_component_get_property(tusb_lib espressif__tinyusb COMPONENT_LIB) +target_include_directories(${tusb_lib} PRIVATE path_to_your_tusb_config) +``` + +Again, you can add this component to your project by adding ``idf_component.yml`` file: + +```yaml +## IDF Component Manager Manifest File +dependencies: + tinyusb: "~0.19.0" # TinyUSB does not guarantee backward compatibility +``` + +Or simply run: +```sh +idf.py add-dependency "tinyusb~0.19.0" +``` + +README from the upstream TinyUSB can be found in [hathach/tinyusb/README](https://github.com/hathach/tinyusb/blob/master/README.rst). diff --git a/idf_component.yml b/idf_component.yml new file mode 100644 index 0000000000..0ebcb65f01 --- /dev/null +++ b/idf_component.yml @@ -0,0 +1,22 @@ +description: TinyUSB ported to Espressif's SoCs +url: https://docs.tinyusb.org/en/latest/ +documentation: "https://docs.tinyusb.org/en/latest/" +repository: "https://github.com/espressif/tinyusb.git" +issues: "https://github.com/hathach/tinyusb/issues" +dependencies: + idf: '>=5.0' # IDF 4.x contains TinyUSB as submodule +files: + exclude: + - "docs/**/*" + - "tools/**/*" + - "lib/embedded-cli/**/*" + - "lib/fatfs/**/*" + - "lib/SEGGER_RTT/**/*" +targets: + - esp32s2 + - esp32s3 + - esp32p4 + - esp32h4 +tags: + - usb + - usb_device diff --git a/sbom.yml b/sbom.yml new file mode 100644 index 0000000000..91867531ab --- /dev/null +++ b/sbom.yml @@ -0,0 +1,2 @@ +supplier: 'Organization: Espressif Systems (Shanghai) CO LTD' +originator: 'Person: Ha Thach ' diff --git a/src/tusb.h b/src/tusb.h index 6a469eef44..f3d371674a 100644 --- a/src/tusb.h +++ b/src/tusb.h @@ -137,6 +137,12 @@ //--------------------------------------------------------------------+ // User API //--------------------------------------------------------------------+ + +// Following macros are defined to be backward compatible +// tinyusb 0.17.x and 0.18.x +#define tusb_rhport_teardown(rhport) tusb_deinit(rhport) +#define tusb_teardown() tusb_deinit(0) + #if CFG_TUH_ENABLED || CFG_TUD_ENABLED // Internal helper for backward compatible with tusb_init(void)