Upstream Synchronization [v0.19]

.circleci/config.yml

@@ -19,21 +19,20 @@ jobs:
             echo "MATRIX_JSON=$MATRIX_JSON"
 
             BUILDSYSTEM_TOOLCHAIN=(
+              "cmake aarch64-gcc"
               "cmake arm-clang"
-              "make aarch64-gcc"
-              "make arm-gcc"
-              "make msp430-gcc"
-              "make riscv-gcc"
-              "make rx-gcc"
+              "cmake arm-gcc"
               "cmake esp-idf"
+              "cmake msp430-gcc"
+              "cmake riscv-gcc"
             )
 
             # only build IAR if not forked PR, since IAR token is not shared
             if [ -z $CIRCLE_PR_USERNAME ]; then
               BUILDSYSTEM_TOOLCHAIN+=("cmake arm-iar")
             fi
 
-            RESOURCE_LARGE='["nrf", "imxrt", "stm32f4", "stm32h7"]'
+            RESOURCE_LARGE='["nrf", "imxrt", "stm32f4", "stm32h7 stm32h7rs"]'
 
             gen_build_entry() {
               local build_system="$1"
@@ -67,7 +66,7 @@ jobs:
               FAMILY_LARGE=$(jq -n --argjson family "$FAMILY" --argjson resource "$RESOURCE_LARGE" '$family | map(select(IN($resource[])))')
               FAMILY=$(jq -n --argjson family "$FAMILY" --argjson resource "$RESOURCE_LARGE" '$family | map(select(IN($resource[]) | not))')
 
-              if [[ $toolchain == esp-idf ]]; then
+              if [[ $toolchain == esp-idf || $toolchain == arm-iar ]]; then
                 gen_build_entry "$build_system" "$toolchain" "$FAMILY" "large"
               else
                 gen_build_entry "$build_system" "$toolchain" "$FAMILY" "medium+"

.circleci/config2.yml

@@ -10,17 +10,7 @@ commands:
       - run:
           name: Set toolchain url and key
           command: |
-            TOOLCHAIN_JSON='{
-              "aarch64-gcc": "https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-elf.tar.xz",
-              "arm-clang": "https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/releases/download/release-19.1.1/LLVM-ET-Arm-19.1.1-Linux-x86_64.tar.xz",
-              "arm-gcc": "https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v13.2.1-1.1/xpack-arm-none-eabi-gcc-13.2.1-1.1-linux-x64.tar.gz",
-              "msp430-gcc": "http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSPGCC/9_2_0_0/export/msp430-gcc-9.2.0.50_linux64.tar.bz2",
-              "riscv-gcc": "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz",
-              "rx-gcc": "https://github.com/hathach/rx_device/releases/download/0.0.1/gcc-8.3.0.202411-GNURX-ELF.run",
-              "arm-iar": "https://updates.iar.com/FileStore/STANDARD/001/003/322/cxarm-9.60.3.deb"
-            }'
-            toolchain_url=$(echo $TOOLCHAIN_JSON | jq -r '.["<< parameters.toolchain >>"]')
-
+            toolchain_url=$(jq -r '."<< parameters.toolchain >>"' .github/actions/setup_toolchain/toolchain.json)
             # only cache if not a github link
             if [[ $toolchain_url != "https://github.com"* ]]; then
               echo "<< parameters.toolchain >>-$toolchain_url" > toolchain_key
@@ -121,7 +111,6 @@ commands:
                 TOOLCHAIN_OPTION="--toolchain clang"
               elif [ << parameters.toolchain >> == arm-iar ]; then
                 TOOLCHAIN_OPTION="--toolchain iar"
-                echo IAR_LMS_CLOUD_URL=$IAR_LMS_CLOUD_URL
                 iccarm --version
               elif [ << parameters.toolchain >> == arm-gcc ]; then
                 TOOLCHAIN_OPTION="--toolchain gcc"

.github/actions/setup_toolchain/action.yml

@@ -17,7 +17,7 @@ runs:
       if: inputs.toolchain == 'arm-gcc'
       uses: carlosperate/arm-none-eabi-gcc-action@v1
       with:
-        release: '13.2.Rel1'
+        release: '14.2.Rel1'
 
     - name: Pull ESP-IDF docker
       if: inputs.toolchain == 'esp-idf'
@@ -28,26 +28,17 @@ runs:
     - name: Get Toolchain URL
       if: >-
         inputs.toolchain != 'arm-gcc' &&
-        inputs.toolchain != 'arm-iar' &&
         inputs.toolchain != 'esp-idf'
       id: set-toolchain-url
       run: |
-        TOOLCHAIN_JSON='{
-          "aarch64-gcc": "https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-elf.tar.xz",
-          "arm-clang": "https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/releases/download/release-19.1.1/LLVM-ET-Arm-19.1.1-Linux-x86_64.tar.xz",
-          "msp430-gcc": "http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSPGCC/9_2_0_0/export/msp430-gcc-9.2.0.50_linux64.tar.bz2",
-          "riscv-gcc": "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz",
-          "rx-gcc": "https://github.com/hathach/rx_device/releases/download/0.0.1/gcc-8.3.0.202411-GNURX-ELF.run"
-        }'
-        TOOLCHAIN_URL=$(echo $TOOLCHAIN_JSON | jq -r '.["${{ inputs.toolchain }}"]')
+        TOOLCHAIN_URL=$(jq -r '."${{ inputs.toolchain }}"' .github/actions/setup_toolchain/toolchain.json)
         echo "toolchain_url=$TOOLCHAIN_URL"
         echo "toolchain_url=$TOOLCHAIN_URL" >> $GITHUB_OUTPUT
       shell: bash
 
     - name: Download Toolchain
       if: >-
         inputs.toolchain != 'arm-gcc' &&
-        inputs.toolchain != 'arm-iar' &&
         inputs.toolchain != 'esp-idf'
       uses: ./.github/actions/setup_toolchain/download
       with:

.github/actions/setup_toolchain/download/action.yml

@@ -23,17 +23,25 @@ runs:
       if: steps.cache-toolchain-download.outputs.cache-hit != 'true'
       run: |
         mkdir -p ~/cache/${{ inputs.toolchain }}
-        wget --progress=dot:giga ${{ inputs.toolchain_url }} -O toolchain.tar.gz
+
         if [[ ${{ inputs.toolchain }} == rx-gcc ]]; then
-          mv toolchain.tar.gz toolchain.run
+          wget --progress=dot:giga ${{ inputs.toolchain_url }} -O toolchain.run
           chmod +x toolchain.run
           ./toolchain.run -p ~/cache/${{ inputs.toolchain }}/gnurx -y
+        elif [[ ${{ inputs.toolchain }} == arm-iar ]]; then
+          wget --progress=dot:giga ${{ inputs.toolchain_url }} -O ~/cache/${{ inputs.toolchain }}/cxarm.deb
         else
+          wget --progress=dot:giga ${{ inputs.toolchain_url }} -O toolchain.tar.gz
           tar -C ~/cache/${{ inputs.toolchain }} -xaf toolchain.tar.gz
         fi
       shell: bash
 
-    - name: Set Toolchain Path
+    - name: Setup Toolchain
       run: |
-        echo >> $GITHUB_PATH `echo ~/cache/${{ inputs.toolchain }}/*/bin`
+        if [[ ${{ inputs.toolchain }} == arm-iar ]]; then
+          sudo apt-get install -y ~/cache/${{ inputs.toolchain }}/cxarm.deb
+          echo >> $GITHUB_PATH "/opt/iar/cxarm/arm/bin"
+        else
+          echo >> $GITHUB_PATH `echo ~/cache/${{ inputs.toolchain }}/*/bin`
+        fi
       shell: bash

.github/actions/setup_toolchain/toolchain.json

@@ -0,0 +1,9 @@
+{
+  "aarch64-gcc": "https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-elf.tar.xz",
+  "arm-clang": "https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/releases/download/release-19.1.1/LLVM-ET-Arm-19.1.1-Linux-x86_64.tar.xz",
+  "arm-gcc": "https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v14.2.1-1.1/xpack-arm-none-eabi-gcc-14.2.1-1.1-linux-x64.tar.gz",
+  "msp430-gcc": "http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSPGCC/9_2_0_0/export/msp430-gcc-9.2.0.50_linux64.tar.bz2",
+  "riscv-gcc": "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz",
+  "rx-gcc": "https://github.com/hathach/rx_device/releases/download/0.0.1/gcc-8.3.0.202411-GNURX-ELF.run",
+  "arm-iar": "https://netstorage.iar.com/FileStore/STANDARD/001/003/583/cxarm-9.60.4.deb"
+}

.github/copilot-instructions.md

@@ -0,0 +1,190 @@
+# TinyUSB
+TinyUSB is an open-source cross-platform USB Host/Device stack for embedded systems, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events deferred to non-ISR task functions.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Build Setup
+- Install ARM GCC toolchain: `sudo apt-get update && sudo apt-get install -y gcc-arm-none-eabi`
+- Fetch core dependencies: `python3 tools/get_deps.py` -- takes <1 second. NEVER CANCEL.
+- For specific board families: `python3 tools/get_deps.py FAMILY_NAME` (e.g., rp2040, stm32f4)
+- Dependencies are cached in `lib/` and `hw/mcu/` directories
+
+### Build Examples
+Choose ONE of these approaches:
+
+**Option 1: Individual Example with CMake (RECOMMENDED)**
+```bash
+cd examples/device/cdc_msc
+mkdir -p build && cd build
+cmake -DBOARD=raspberry_pi_pico -DCMAKE_BUILD_TYPE=MinSizeRel ..
+cmake --build . -j4
+```
+-- takes 1-2 seconds. NEVER CANCEL. Set timeout to 5+ minutes.
+
+**CMake with Ninja (Alternative)**
+```bash
+cd examples/device/cdc_msc
+mkdir build && cd build
+cmake -G Ninja -DBOARD=raspberry_pi_pico ..
+ninja
+```
+
+**Option 2: Individual Example with Make**
+```bash
+cd examples/device/cdc_msc
+make BOARD=raspberry_pi_pico all
+```
+-- takes 2-3 seconds. NEVER CANCEL. Set timeout to 5+ minutes.
+
+**Option 3: All Examples for a Board**
+```bash
+python3 tools/build.py -b BOARD_NAME
+```
+-- takes 15-20 seconds, may have some objcopy failures that are non-critical. NEVER CANCEL. Set timeout to 30+ minutes.
+
+### Build Options
+- **Debug build**:
+  - CMake: `-DCMAKE_BUILD_TYPE=Debug`
+  - Make: `DEBUG=1`
+- **With logging**:
+  - CMake: `-DLOG=2`
+  - Make: `LOG=2`
+- **With RTT logger**:
+  - CMake: `-DLOG=2 -DLOGGER=rtt`
+  - Make: `LOG=2 LOGGER=rtt`
+- **RootHub port selection**:
+  - CMake: `-DRHPORT_DEVICE=1`
+  - Make: `RHPORT_DEVICE=1`
+- **Port speed**:
+  - CMake: `-DRHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED`
+  - Make: `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED`
+
+### Flashing and Deploymen
+- **Flash with JLink**:1
+  - CMake: `ninja cdc_msc-jlink`
+  - Make: `make BOARD=raspberry_pi_pico flash-jlink`
+- **Flash with OpenOCD**:
+  - CMake: `ninja cdc_msc-openocd`
+  - Make: `make BOARD=raspberry_pi_pico flash-openocd`
+- **Generate UF2**:
+  - CMake: `ninja cdc_msc-uf2`
+  - Make: `make BOARD=raspberry_pi_pico all uf2`
+- **List all targets** (CMake/Ninja): `ninja -t targets`
+
+### Unit Testing
+- Install Ceedling: `sudo gem install ceedling`
+- Run all unit tests: `cd test/unit-test && ceedling` or `cd test/unit-test && ceedling test:all` -- takes 4 seconds. NEVER CANCEL. Set timeout to 10+ minutes.
+- Run specific test: `cd test/unit-test && ceedling test:test_fifo`
+- Tests use Unity framework with CMock for mocking
+
+### Documentation
+- Install requirements: `pip install -r docs/requirements.txt`
+- Build docs: `cd docs && sphinx-build -b html . _build` -- takes 2-3 seconds. NEVER CANCEL. Set timeout to 10+ minutes.
+
+### Code Quality and Validation
+- Format code: `clang-format -i path/to/file.c` (uses `.clang-format` config)
+- Check spelling: `pip install codespell && codespell` (uses `.codespellrc` config)
+- Pre-commit hooks validate unit tests and code quality automatically
+
+## Validation
+
+### ALWAYS Run These After Making Changes
+1. **Pre-commit validation** (RECOMMENDED): `pre-commit run --all-files`
+   - Install pre-commit: `pip install pre-commit && pre-commit install`
+   - Runs all quality checks, unit tests, spell checking, and formatting
+   - Takes 10-15 seconds. NEVER CANCEL. Set timeout to 15+ minutes.
+2. **Build validation**: Build at least one example that exercises your changes
+   ```bash
+   cd examples/device/cdc_msc
+   make BOARD=raspberry_pi_pico all
+   ```
+
+### Manual Testing Scenarios
+- **Device examples**: Cannot be fully tested without real hardware, but must build successfully
+- **Unit tests**: Exercise core stack functionality - ALL tests must pass
+- **Build system**: Must be able to build examples for multiple board families
+
+### Board Selection for Testing
+- **STM32F4**: `stm32f407disco` - no external SDK required, good for testing
+- **RP2040**: `raspberry_pi_pico` - requires Pico SDK, commonly used
+- **Other families**: Check `hw/bsp/FAMILY/boards/` for available boards
+
+## Common Tasks and Time Expectations
+
+### Repository Structure Quick Reference
+```
+├── src/                  # Core TinyUSB stack
+│   ├── class/            # USB device classes (CDC, HID, MSC, Audio, etc.)
+│   ├── portable/         # MCU-specific drivers (organized by vendor)
+│   ├── device/           # USB device stack core
+│   ├── host/             # USB host stack core
+│   └── common/           # Shared utilities (FIFO, etc.)
+├── examples/             # Example applications
+│   ├── device/           # Device examples (cdc_msc, hid_generic, etc.)
+│   ├── host/             # Host examples
+│   └── dual/             # Dual-role examples
+├── hw/bsp/               # Board Support Packages
+│   └── FAMILY/boards/    # Board-specific configurations
+├── test/unit-test/       # Unit tests using Ceedling
+├── tools/                # Build and utility scripts
+└── docs/                 # Sphinx documentation
+```
+
+### Build Time Reference
+- **Dependency fetch**: <1 second
+- **Single example build**: 1-3 seconds
+- **Unit tests**: ~4 seconds
+- **Documentation build**: ~2.5 seconds
+- **Full board examples**: 15-20 seconds
+- **Toolchain installation**: 2-5 minutes (one-time)
+
+### Key Files to Know
+- `tools/get_deps.py`: Manages dependencies for MCU families
+- `tools/build.py`: Builds multiple examples, supports make/cmake
+- `src/tusb.h`: Main TinyUSB header file
+- `src/tusb_config.h`: Configuration template
+- `examples/device/cdc_msc/`: Most commonly used example for testing
+- `test/unit-test/project.yml`: Ceedling test configuration
+
+### Debugging Build Issues
+- **Missing compiler**: Install `gcc-arm-none-eabi` package
+- **Missing dependencies**: Run `python3 tools/get_deps.py FAMILY`
+- **Board not found**: Check `hw/bsp/FAMILY/boards/` for valid board names
+- **objcopy errors**: Often non-critical in full builds, try individual example builds
+
+### Working with USB Device Classes
+- **CDC (Serial)**: `src/class/cdc/` - Virtual serial port
+- **HID**: `src/class/hid/` - Human Interface Device (keyboard, mouse, etc.)
+- **MSC**: `src/class/msc/` - Mass Storage Class (USB drive)
+- **Audio**: `src/class/audio/` - USB Audio Class
+- Each class has device (`*_device.c`) and host (`*_host.c`) implementations
+
+### MCU Family Support
+- **STM32**: Largest support (F0, F1, F2, F3, F4, F7, G0, G4, H7, L4, U5, etc.)
+- **Raspberry Pi**: RP2040, RP2350 with PIO-USB host support
+- **NXP**: iMXRT, Kinetis, LPC families
+- **Microchip**: SAM D/E/G/L families
+- Check `hw/bsp/` for complete list and `docs/reference/boards.rst` for details
+
+## Code Style Guidelines
+
+### General Coding Standards
+- Use C99 standard
+- Memory-safe: no dynamic allocation
+- Thread-safe: defer all interrupt events to non-ISR task functions
+- 2-space indentation, no tabs
+- Use snake_case for variables/functions
+- Use UPPER_CASE for macros and constants
+- Follow existing variable naming patterns in files you're modifying
+- Include proper header comments with MIT license
+- Add descriptive comments for non-obvious functions
+
+### Best Practices
+- When including headers, group in order: C stdlib, tusb common, drivers, classes
+- Always check return values from functions that can fail
+- Use TU_ASSERT() for error checking with return statements
+- Follow the existing code patterns in the files you're modifying
+
+Remember: TinyUSB is designed for embedded systems - builds are fast, tests are focused, and the codebase is optimized for resource-constrained environments.