From 9d7b401c3d98d7923ce3b53d4a129e156e4c9a97 Mon Sep 17 00:00:00 2001 From: hathach Date: Wed, 19 Nov 2025 22:26:10 +0700 Subject: [PATCH 1/2] remove copilot-instructions.md, update and use AGENTS.md instead --- .github/copilot-instructions.md | 214 ----------------------------- .github/workflows/ci_set_matrix.py | 3 +- AGENTS.md | 130 +++++++++--------- 3 files changed, 67 insertions(+), 280 deletions(-) delete mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 9f9ab7e725..0000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,214 +0,0 @@ -# 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 - -### Static Analysis with PVS-Studio -- **Analyze whole project**: - ```bash - pvs-studio-analyzer analyze -f examples/cmake-build-raspberry_pi_pico/compile_commands.json -R .PVS-Studio/.pvsconfig -o pvs-report.log -j12 --dump-files --misra-cpp-version 2008 --misra-c-version 2023 --use-old-parser - ``` -- **Analyze specific source files**: - ```bash - pvs-studio-analyzer analyze -f examples/cmake-build-raspberry_pi_pico/compile_commands.json -R .PVS-Studio/.pvsconfig -S path/to/file.c -o pvs-report.log -j12 --dump-files --misra-cpp-version 2008 --misra-c-version 2023 --use-old-parser - ``` -- **Multiple specific files**: - ```bash - pvs-studio-analyzer analyze -f examples/cmake-build-raspberry_pi_pico/compile_commands.json -R .PVS-Studio/.pvsconfig -S src/file1.c -S src/file2.c -o pvs-report.log -j12 --dump-files --misra-cpp-version 2008 --misra-c-version 2023 --use-old-parser - ``` -- Requires `compile_commands.json` in the build directory (generated by CMake with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) -- Use `-f` option to specify path to `compile_commands.json` -- Use `-R .PVS-Studio/.pvsconfig` to specify rule configuration file -- Use `-j12` for parallel analysis with 12 threads -- `--dump-files` saves preprocessed files for debugging -- `--misra-c-version 2023` enables MISRA C:2023 checks -- `--misra-cpp-version 2008` enables MISRA C++:2008 checks -- `--use-old-parser` uses legacy parser for compatibility -- Analysis takes ~10-30 seconds depending on project size. Set timeout to 5+ minutes. -- View results: `plog-converter -a GA:1,2 -t errorfile pvs-report.log` or open in PVS-Studio GUI - -## 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. diff --git a/.github/workflows/ci_set_matrix.py b/.github/workflows/ci_set_matrix.py index 3789b41163..9d0e42c2e3 100755 --- a/.github/workflows/ci_set_matrix.py +++ b/.github/workflows/ci_set_matrix.py @@ -41,7 +41,8 @@ "stm32f4": ["arm-gcc", "arm-clang", "arm-iar"], "stm32f7": ["arm-gcc", "arm-clang", "arm-iar"], "stm32g0 stm32g4 stm32h5": ["arm-gcc", "arm-clang", "arm-iar"], - "stm32h7 stm32h7rs": ["arm-gcc", "arm-clang", "arm-iar"], + "stm32h7": ["arm-gcc", "arm-clang", "arm-iar"], + "stm32h7rs": ["arm-gcc", "arm-clang", "arm-iar"], "stm32l0 stm32l4": ["arm-gcc", "arm-clang", "arm-iar"], "stm32n6": ["arm-gcc"], "stm32u0 stm32u5 stm32wb": ["arm-gcc", "arm-clang", "arm-iar"], diff --git a/AGENTS.md b/AGENTS.md index 27bc60515f..d00a4b1142 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,52 +1,43 @@ -# Agent Handbook +# TinyUSB Agent Instructions -## Shared TinyUSB Ground Rules +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. + +## Shared Ground Rules - Keep TinyUSB memory-safe: avoid dynamic allocation, defer ISR work to task context, and follow C99 with two-space indentation/no tabs. - Match file organization: core stack under `src`, MCU/BSP support in `hw/{mcu,bsp}`, examples under `examples/{device,host,dual}`, docs in `docs`, tests under `test/{unit-test,fuzz,hil}`. - Use descriptive snake_case for helpers, reserve `tud_`/`tuh_` for public APIs, `TU_` for macros, and keep headers self-contained with `#if CFG_TUSB_MCU` guards where needed. - Prefer `.clang-format` for C/C++ formatting, run `pre-commit run --all-files` before submitting, and document board/HIL coverage when applicable. - Commit in imperative mood, keep changes scoped, and supply PRs with linked issues plus test/build evidence. -## Build and Test Cheatsheet -- Fetch dependencies once with `python3 tools/get_deps.py [FAMILY]`; assets land in `lib/` and `hw/mcu/`. -- CMake (preferred): `cmake -G Ninja -DBOARD= -DCMAKE_BUILD_TYPE={MinSizeRel|Debug}` inside an example `build/` dir, then `ninja` or `cmake --build .`. -- Make (alt): `make BOARD= [DEBUG=1] [LOG=2 LOGGER=rtt] all` from the example root; add `uf2`, `flash-openocd`, or `flash-jlink` targets as needed. -- Bulk builds: `python3 tools/build.py -b ` to sweep all examples; expect occasional non-critical objcopy warnings. -- Unit tests: `cd test/unit-test && ceedling test:all` (or a specific `test_`), honor Unity/CMock fixtures under `test/support`. -- Docs: `pip install -r docs/requirements.txt` then `sphinx-build -b html . _build` from `docs/`. - -## Validation Checklist -1. `pre-commit run --all-files` after edits (install with `pip install pre-commit && pre-commit install`). -2. Build at least one representative example (e.g., `examples/device/cdc_msc`) via CMake+Ninja or Make. -3. Run unit tests relevant to touched modules; add fuzz/HIL coverage when modifying parsers or protocol state machines. - -## Copilot Agent Notes (`.github/copilot-instructions.md`) -# 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 -#### 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 +## 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 @@ -55,63 +46,74 @@ 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 +## Build Options + - **Debug build**: - - CMake: `-DCMAKE_BUILD_TYPE=Debug` - - Make: `DEBUG=1` + - CMake: `-DCMAKE_BUILD_TYPE=Debug` + - Make: `DEBUG=1` - **With logging**: - - CMake: `-DLOG=2` - - Make: `LOG=2` + - CMake: `-DLOG=2` + - Make: `LOG=2` - **With RTT logger**: - - CMake: `-DLOG=2 -DLOGGER=rtt` - - Make: `LOG=2 LOGGER=rtt` + - CMake: `-DLOG=2 -DLOGGER=rtt` + - Make: `LOG=2 LOGGER=rtt` - **RootHub port selection**: - - CMake: `-DRHPORT_DEVICE=1` - - Make: `RHPORT_DEVICE=1` + - 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` + - CMake: `-DRHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` + - Make: `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` + +## Flashing and Deployment -#### Flashing and Deployment - **Flash with JLink**: - - CMake: `ninja cdc_msc-jlink` - - Make: `make BOARD=raspberry_pi_pico flash-jlink` + - 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` + - 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` + - CMake: `ninja cdc_msc-uf2` + - Make: `make BOARD=raspberry_pi_pico all uf2` - **List all targets** (CMake/Ninja): `ninja -t targets` -#### Unit Testing +## 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 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 +## 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 +## 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 -#### Static Analysis with PVS-Studio +## Static Analysis with PVS-Studio + - **Analyze whole project**: ```bash pvs-studio-analyzer analyze -f examples/cmake-build-raspberry_pi_pico/compile_commands.json -R .PVS-Studio/.pvsconfig -o pvs-report.log -j12 --dump-files --misra-cpp-version 2008 --misra-c-version 2023 --use-old-parser @@ -135,32 +137,40 @@ python3 tools/build.py -b BOARD_NAME - Analysis takes ~10-30 seconds depending on project size. Set timeout to 5+ minutes. - View results: `plog-converter -a GA:1,2 -t errorfile pvs-report.log` or open in PVS-Studio GUI -### Validation +## Validation Checklist + +### ALWAYS Run These After Making Changes -#### 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. + - 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 ``` +3. Run unit tests relevant to touched modules; add fuzz/HIL coverage when modifying parsers or protocol state machines. -#### Manual Testing Scenarios +### 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 +### 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 +## Release Instructions + +1. Bump the release version variable at the top of `tools/make_release.py`. +2. Execute `python tools/make_release.py` to refresh `src/tusb_option.h`, `repository.yml`, and `library.json`. +3. Generate release notes by running `git log ..HEAD`, then add a new entry to + `docs/info/changelog.rst` that follows the existing format (heading, date, highlights, categorized bullet lists). +4. Proceed with tagging/publishing once builds and tests succeed. -#### Repository Structure Quick Reference +## Repository Structure Quick Reference ``` ├── src/ # Core TinyUSB stack │ ├── class/ # USB device classes (CDC, HID, MSC, Audio, etc.) @@ -235,13 +245,3 @@ python3 tools/build.py -b BOARD_NAME - 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. - -## Claude Agent Notes (`CLAUDE.md`) -- Default to CMake+Ninja for builds, but align with Make workflows when users rely on legacy scripts; provide DEBUG/LOG/LOGGER knobs consistently. -- Highlight dependency helpers (`tools/get_deps.py rp2040`) and reference core locations: `src/`, `hw/`, `examples/`, `test/`. -- Run `clang-format` on all touched files to ensure consistent formatting. -- Use `TU_ASSERT` for all fallible calls to enforce runtime checks. -- Ensure header comments retain the MIT license notice. -- Add descriptive comments for non-trivial code paths to aid maintainability. -- Release flow primer: bump `tools/make_release.py` version, run the script (updates `src/tusb_option.h`, `repository.yml`, `library.json`), refresh `docs/info/changelog.rst`, then tag. -- Testing reminders: Ceedling full or targeted runs, specify board/OS context, and ensure logging of manual hardware outcomes when available. From f6a77b87f04386ea27effb7c1faf8e1a33da0fa1 Mon Sep 17 00:00:00 2001 From: hathach Date: Wed, 19 Nov 2025 22:27:47 +0700 Subject: [PATCH 2/2] Bump version to 0.20.0 --- AGENTS.md | 33 +++- docs/info/changelog.rst | 93 +++++++++++ hw/bsp/BoardPresets.json | 342 +++++++++++++++++++++++++++++++++++---- library.json | 2 +- repository.yml | 3 +- sonar-project.properties | 2 +- src/tusb_option.h | 2 +- tools/make_release.py | 17 +- 8 files changed, 452 insertions(+), 42 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d00a4b1142..a6163dd424 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,11 +164,36 @@ python3 tools/build.py -b BOARD_NAME ## Release Instructions +**DO NOT commit files automatically - only modify files and let the maintainer review before committing.** + 1. Bump the release version variable at the top of `tools/make_release.py`. -2. Execute `python tools/make_release.py` to refresh `src/tusb_option.h`, `repository.yml`, and `library.json`. -3. Generate release notes by running `git log ..HEAD`, then add a new entry to - `docs/info/changelog.rst` that follows the existing format (heading, date, highlights, categorized bullet lists). -4. Proceed with tagging/publishing once builds and tests succeed. +2. Execute `python3 tools/make_release.py` to refresh: + - `src/tusb_option.h` (version defines) + - `repository.yml` (version mapping) + - `library.json` (PlatformIO version) + - `sonar-project.properties` (SonarQube version) + - `docs/reference/boards.rst` (generated board documentation) + - `hw/bsp/BoardPresets.json` (CMake presets) +3. Generate release notes for `docs/info/changelog.rst`: + - Get commit list: `git log ..HEAD --oneline` + - **Visit GitHub PRs** for merged pull requests to understand context and gather details + - Use GitHub tools to search/read PRs: `github-mcp-server-list_pull_requests`, `github-mcp-server-pull_request_read` + - Extract key changes, API modifications, bug fixes, and new features from PR descriptions + - Add new changelog entry following the existing format: + - Version heading with equals underline (e.g., `0.20.0` followed by `======`) + - Release date in italics (e.g., `*November 19, 2024*`) + - Major sections: General, API Changes, Controller Driver (DCD & HCD), Device Stack, Host Stack, Testing + - Use bullet lists with descriptive categorization + - Reference function names, config macros, and file paths using RST inline code (double backticks) + - Include meaningful descriptions, not just commit messages +4. **Validation before commit**: + - Run unit tests: `cd test/unit-test && ceedling test:all` + - Build at least one example: `cd examples/device/cdc_msc && make BOARD=stm32f407disco all` + - Verify changed files look correct: `git diff --stat` +5. **Leave files unstaged** for maintainer to review, modify if needed, and commit with message: `Bump version to X.Y.Z` +6. **After maintainer commits**: Create annotated tag with `git tag -a vX.Y.Z -m "Release X.Y.Z"` +7. Push commit and tag: `git push origin && git push origin vX.Y.Z` +8. Create GitHub release from the tag with changelog content ## Repository Structure Quick Reference ``` diff --git a/docs/info/changelog.rst b/docs/info/changelog.rst index d6bf846ed1..3addce27b2 100644 --- a/docs/info/changelog.rst +++ b/docs/info/changelog.rst @@ -2,6 +2,99 @@ Changelog ********* +0.20.0 +====== + +*November 19, 2024* + +General +------- + +- New MCUs and Boards: + + - Add STM32U3 device support (adjusted from STM32U0) + - Add nRF54H20 support with initial board configuration + - Rename board names: pca10056→nrf52840dk, pca10059→nrf52840dongle, pca10095→nrf5340dk + - Improve CMake: Move startup and linker files from board target to executable. Enhance target warning flags and fix various build warnings + +- Code Quality and Static Analysis: + + - Add PVS-Studio static analysis to CI + - Add SonarQube scan support + - Add IAR C-Stat analysis capability + - Add ``.clang-format`` for consistent code formatting + - Fix numerous alerts and warnings found by static analysis tools + +- Documentation: + + - Improve Getting Started documentation structure and flow + - Add naming conventions and buffer handling documentation + +Controller Driver (DCD & HCD) +----------------------------- + +- DWC2 + + - Fix incorrect handling of Zero-Length Packets (ZLP) in the DWC2 driver when receiving data (OUT transfers) + - Improve EP0 multi-packet logic + - Support EP0 with max packet size = 8 + - For IN endpoint, write initial packet directly to FIFO and only use TXFE interrupt for subsequent packets + - Fix ISO with bInterval > 2 using incomplete IN interrupt handling. + - Fix compile issues when enabling both host and device + - Clear pending suspend interrupt after USB reset (enum end) + - Improve host closing endpoint and channel handling when device is unplugged + +- FSDEV (STM32) + + - Fix AT32 USB interrupt remapping in ``dcd_int_enable()`` + +- OHCI + + - Add initial LPC55 OHCI support + - Improve data cache support + +Device Stack +------------ + +- USBD Core + + - Support configurable EP0 buffer size CFG_TUD_ENDPOINT0_BUFSIZE + - Make dcd_edpt_iso_alloc/activate as default API for ISO endpoint + +- Audio + + - Add UAC1 support + - Implement RX FIFO threshold adjustment with `tud_audio_get/set_ep_in_fifo_threshold()` + +- CDC + + - Migrate to endpoint stream API + +- HID + + - Fix HID stylus descriptor + +- MIDI + + - Migrate to endpoint stream API + - Add ``tud_midi_n_packet_write_n()`` and ``tud_midi_n_packet_read_n()`` + +- MTP + + - Fix incorrect MTP xact_len calculation + +- Video + + - Add bufferless operation callback for dynamic frame generation with tud_video_prepare_payload_cb() + + +Host Stack +---------- + +- USBH Core + + - Improve transfer closing and channel management + 0.19.0 ====== diff --git a/hw/bsp/BoardPresets.json b/hw/bsp/BoardPresets.json index 044c74ee14..5df9241388 100644 --- a/hw/bsp/BoardPresets.json +++ b/hw/bsp/BoardPresets.json @@ -362,6 +362,10 @@ "name": "metro_m7_1011_sd", "inherits": "default" }, + { + "name": "metro_nrf52840", + "inherits": "default" + }, { "name": "mimxrt1010_evk", "inherits": "default" @@ -419,19 +423,43 @@ "inherits": "default" }, { - "name": "pca10056", + "name": "nrf52833dk", "inherits": "default" }, { - "name": "pca10059", + "name": "nrf52840dk", "inherits": "default" }, { - "name": "pca10095", + "name": "nrf52840dongle", "inherits": "default" }, { - "name": "pca10100", + "name": "nrf5340dk", + "inherits": "default" + }, + { + "name": "nrf54h20dk", + "inherits": "default" + }, + { + "name": "nutiny_nuc126v", + "inherits": "default" + }, + { + "name": "nutiny_sdk_nuc120", + "inherits": "default" + }, + { + "name": "nutiny_sdk_nuc121", + "inherits": "default" + }, + { + "name": "nutiny_sdk_nuc125", + "inherits": "default" + }, + { + "name": "nutiny_sdk_nuc505", "inherits": "default" }, { @@ -490,6 +518,10 @@ "name": "raspberry_pi_pico2", "inherits": "default" }, + { + "name": "raspberry_pi_pico2_riscv", + "inherits": "default" + }, { "name": "raspberry_pi_pico_w", "inherits": "default" @@ -514,6 +546,14 @@ "name": "same54_xplained", "inherits": "default" }, + { + "name": "same70_qmtech", + "inherits": "default" + }, + { + "name": "same70_xplained", + "inherits": "default" + }, { "name": "samg55_xplained", "inherits": "default" @@ -534,10 +574,18 @@ "name": "sipeed_longan_nano", "inherits": "default" }, + { + "name": "sltb009a", + "inherits": "default" + }, { "name": "sparkfun_samd21_mini_usb", "inherits": "default" }, + { + "name": "spresense", + "inherits": "default" + }, { "name": "stlinkv3mini", "inherits": "default" @@ -698,6 +746,10 @@ "name": "stm32l476disco", "inherits": "default" }, + { + "name": "stm32l496nucleo", + "inherits": "default" + }, { "name": "stm32l4p5nucleo", "inherits": "default" @@ -1336,6 +1388,11 @@ "description": "Build preset for the metro_m7_1011_sd board", "configurePreset": "metro_m7_1011_sd" }, + { + "name": "metro_nrf52840", + "description": "Build preset for the metro_nrf52840 board", + "configurePreset": "metro_nrf52840" + }, { "name": "mimxrt1010_evk", "description": "Build preset for the mimxrt1010_evk board", @@ -1407,24 +1464,54 @@ "configurePreset": "nanoch32v305" }, { - "name": "pca10056", - "description": "Build preset for the pca10056 board", - "configurePreset": "pca10056" + "name": "nrf52833dk", + "description": "Build preset for the nrf52833dk board", + "configurePreset": "nrf52833dk" + }, + { + "name": "nrf52840dk", + "description": "Build preset for the nrf52840dk board", + "configurePreset": "nrf52840dk" + }, + { + "name": "nrf52840dongle", + "description": "Build preset for the nrf52840dongle board", + "configurePreset": "nrf52840dongle" + }, + { + "name": "nrf5340dk", + "description": "Build preset for the nrf5340dk board", + "configurePreset": "nrf5340dk" + }, + { + "name": "nrf54h20dk", + "description": "Build preset for the nrf54h20dk board", + "configurePreset": "nrf54h20dk" }, { - "name": "pca10059", - "description": "Build preset for the pca10059 board", - "configurePreset": "pca10059" + "name": "nutiny_nuc126v", + "description": "Build preset for the nutiny_nuc126v board", + "configurePreset": "nutiny_nuc126v" }, { - "name": "pca10095", - "description": "Build preset for the pca10095 board", - "configurePreset": "pca10095" + "name": "nutiny_sdk_nuc120", + "description": "Build preset for the nutiny_sdk_nuc120 board", + "configurePreset": "nutiny_sdk_nuc120" }, { - "name": "pca10100", - "description": "Build preset for the pca10100 board", - "configurePreset": "pca10100" + "name": "nutiny_sdk_nuc121", + "description": "Build preset for the nutiny_sdk_nuc121 board", + "configurePreset": "nutiny_sdk_nuc121" + }, + { + "name": "nutiny_sdk_nuc125", + "description": "Build preset for the nutiny_sdk_nuc125 board", + "configurePreset": "nutiny_sdk_nuc125" + }, + { + "name": "nutiny_sdk_nuc505", + "description": "Build preset for the nutiny_sdk_nuc505 board", + "configurePreset": "nutiny_sdk_nuc505" }, { "name": "pico_sdk", @@ -1496,6 +1583,11 @@ "description": "Build preset for the raspberry_pi_pico2 board", "configurePreset": "raspberry_pi_pico2" }, + { + "name": "raspberry_pi_pico2_riscv", + "description": "Build preset for the raspberry_pi_pico2_riscv board", + "configurePreset": "raspberry_pi_pico2_riscv" + }, { "name": "raspberry_pi_pico_w", "description": "Build preset for the raspberry_pi_pico_w board", @@ -1526,6 +1618,16 @@ "description": "Build preset for the same54_xplained board", "configurePreset": "same54_xplained" }, + { + "name": "same70_qmtech", + "description": "Build preset for the same70_qmtech board", + "configurePreset": "same70_qmtech" + }, + { + "name": "same70_xplained", + "description": "Build preset for the same70_xplained board", + "configurePreset": "same70_xplained" + }, { "name": "samg55_xplained", "description": "Build preset for the samg55_xplained board", @@ -1551,11 +1653,21 @@ "description": "Build preset for the sipeed_longan_nano board", "configurePreset": "sipeed_longan_nano" }, + { + "name": "sltb009a", + "description": "Build preset for the sltb009a board", + "configurePreset": "sltb009a" + }, { "name": "sparkfun_samd21_mini_usb", "description": "Build preset for the sparkfun_samd21_mini_usb board", "configurePreset": "sparkfun_samd21_mini_usb" }, + { + "name": "spresense", + "description": "Build preset for the spresense board", + "configurePreset": "spresense" + }, { "name": "stlinkv3mini", "description": "Build preset for the stlinkv3mini board", @@ -1756,6 +1868,11 @@ "description": "Build preset for the stm32l476disco board", "configurePreset": "stm32l476disco" }, + { + "name": "stm32l496nucleo", + "description": "Build preset for the stm32l496nucleo board", + "configurePreset": "stm32l496nucleo" + }, { "name": "stm32l4p5nucleo", "description": "Build preset for the stm32l4p5nucleo board", @@ -3153,6 +3270,19 @@ } ] }, + { + "name": "metro_nrf52840", + "steps": [ + { + "type": "configure", + "name": "metro_nrf52840" + }, + { + "type": "build", + "name": "metro_nrf52840" + } + ] + }, { "name": "mimxrt1010_evk", "steps": [ @@ -3336,54 +3466,132 @@ ] }, { - "name": "pca10056", + "name": "nrf52833dk", + "steps": [ + { + "type": "configure", + "name": "nrf52833dk" + }, + { + "type": "build", + "name": "nrf52833dk" + } + ] + }, + { + "name": "nrf52840dk", + "steps": [ + { + "type": "configure", + "name": "nrf52840dk" + }, + { + "type": "build", + "name": "nrf52840dk" + } + ] + }, + { + "name": "nrf52840dongle", "steps": [ { "type": "configure", - "name": "pca10056" + "name": "nrf52840dongle" }, { "type": "build", - "name": "pca10056" + "name": "nrf52840dongle" } ] }, { - "name": "pca10059", + "name": "nrf5340dk", "steps": [ { "type": "configure", - "name": "pca10059" + "name": "nrf5340dk" }, { "type": "build", - "name": "pca10059" + "name": "nrf5340dk" } ] }, { - "name": "pca10095", + "name": "nrf54h20dk", "steps": [ { "type": "configure", - "name": "pca10095" + "name": "nrf54h20dk" }, { "type": "build", - "name": "pca10095" + "name": "nrf54h20dk" } ] }, { - "name": "pca10100", + "name": "nutiny_nuc126v", "steps": [ { "type": "configure", - "name": "pca10100" + "name": "nutiny_nuc126v" }, { "type": "build", - "name": "pca10100" + "name": "nutiny_nuc126v" + } + ] + }, + { + "name": "nutiny_sdk_nuc120", + "steps": [ + { + "type": "configure", + "name": "nutiny_sdk_nuc120" + }, + { + "type": "build", + "name": "nutiny_sdk_nuc120" + } + ] + }, + { + "name": "nutiny_sdk_nuc121", + "steps": [ + { + "type": "configure", + "name": "nutiny_sdk_nuc121" + }, + { + "type": "build", + "name": "nutiny_sdk_nuc121" + } + ] + }, + { + "name": "nutiny_sdk_nuc125", + "steps": [ + { + "type": "configure", + "name": "nutiny_sdk_nuc125" + }, + { + "type": "build", + "name": "nutiny_sdk_nuc125" + } + ] + }, + { + "name": "nutiny_sdk_nuc505", + "steps": [ + { + "type": "configure", + "name": "nutiny_sdk_nuc505" + }, + { + "type": "build", + "name": "nutiny_sdk_nuc505" } ] }, @@ -3569,6 +3777,19 @@ } ] }, + { + "name": "raspberry_pi_pico2_riscv", + "steps": [ + { + "type": "configure", + "name": "raspberry_pi_pico2_riscv" + }, + { + "type": "build", + "name": "raspberry_pi_pico2_riscv" + } + ] + }, { "name": "raspberry_pi_pico_w", "steps": [ @@ -3647,6 +3868,32 @@ } ] }, + { + "name": "same70_qmtech", + "steps": [ + { + "type": "configure", + "name": "same70_qmtech" + }, + { + "type": "build", + "name": "same70_qmtech" + } + ] + }, + { + "name": "same70_xplained", + "steps": [ + { + "type": "configure", + "name": "same70_xplained" + }, + { + "type": "build", + "name": "same70_xplained" + } + ] + }, { "name": "samg55_xplained", "steps": [ @@ -3712,6 +3959,19 @@ } ] }, + { + "name": "sltb009a", + "steps": [ + { + "type": "configure", + "name": "sltb009a" + }, + { + "type": "build", + "name": "sltb009a" + } + ] + }, { "name": "sparkfun_samd21_mini_usb", "steps": [ @@ -3725,6 +3985,19 @@ } ] }, + { + "name": "spresense", + "steps": [ + { + "type": "configure", + "name": "spresense" + }, + { + "type": "build", + "name": "spresense" + } + ] + }, { "name": "stlinkv3mini", "steps": [ @@ -4245,6 +4518,19 @@ } ] }, + { + "name": "stm32l496nucleo", + "steps": [ + { + "type": "configure", + "name": "stm32l496nucleo" + }, + { + "type": "build", + "name": "stm32l496nucleo" + } + ] + }, { "name": "stm32l4p5nucleo", "steps": [ diff --git a/library.json b/library.json index 718fd84d3d..efad438a7c 100644 --- a/library.json +++ b/library.json @@ -1,6 +1,6 @@ { "name": "TinyUSB", - "version": "0.19.0", + "version": "0.20.0", "description": "TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function.", "keywords": "usb, host, device", "repository": diff --git a/repository.yml b/repository.yml index 5c2aaa6fae..f4da056e31 100644 --- a/repository.yml +++ b/repository.yml @@ -17,5 +17,6 @@ repo.versions: "0.17.0": "0.17.0" "0.18.0": "0.18.0" "0.19.0": "0.19.0" - "0-latest": "0.19.0" + "0.20.0": "0.20.0" + "0-latest": "0.20.0" "0-dev": "0.0.0" diff --git a/sonar-project.properties b/sonar-project.properties index 5a19a234d1..c0032d6e49 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -4,7 +4,7 @@ sonar.organization=hathach # This is the name and version displayed in the SonarCloud UI. sonar.projectName=tinyusb -sonar.projectVersion=0.19.0 +sonar.projectVersion=0.20.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows. diff --git a/src/tusb_option.h b/src/tusb_option.h index eed14214d6..c8265f8985 100644 --- a/src/tusb_option.h +++ b/src/tusb_option.h @@ -31,7 +31,7 @@ // Version is release as major.minor.revision eg 1.0.0 #define TUSB_VERSION_MAJOR 0 -#define TUSB_VERSION_MINOR 19 +#define TUSB_VERSION_MINOR 20 #define TUSB_VERSION_REVISION 0 #define TUSB_VERSION_NUMBER (TUSB_VERSION_MAJOR * 10000 + TUSB_VERSION_MINOR * 100 + TUSB_VERSION_REVISION) diff --git a/tools/make_release.py b/tools/make_release.py index 0e7919f468..71c1e6f64a 100755 --- a/tools/make_release.py +++ b/tools/make_release.py @@ -1,8 +1,9 @@ #!/usr/bin/env python3 import re import gen_doc +import gen_presets -version = '0.19.0' +version = '0.20.0' print('version {}'.format(version)) ver_id = version.split('.') @@ -50,15 +51,19 @@ f_sonar_properties = 'sonar-project.properties' with open(f_sonar_properties) as f: fdata = f.read() - fdata = re.sub(r'(sonar\.projectVersion=)\d+\.\d+\.\d+', rf'\1{version}', fdata) +fdata = re.sub(r'(sonar\.projectVersion=)\d+\.\d+\.\d+', r'\g<1>{}'.format(version), fdata) with open(f_sonar_properties, 'w') as f: f.write(fdata) -################### -# docs/info/changelog.rst -################### - +# gen docs gen_doc.gen_deps_doc() +gen_doc.gen_boards_doc() +# gen presets +gen_presets.main() + +##################(ver# +# docs/info/changelog.rst +################### print("Update docs/info/changelog.rst")