From f4a1e3c6b842d6b05e9e1b76e0229ade7de7c78a Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 14:37:10 -0400 Subject: [PATCH 01/10] M5c: vendor Ryan Gilmore's sp1-usb-audio at 74f3c44 The whole repository, unmodified (blobs checked against upstream), in third_party/sp1-usb-audio/upstream/, with a README beside it recording the commit, what each part is for in Wakes, and how to update. Nothing is compiled yet. Its regulator host test passes at 128- and 256-frame blocks and fails at Wakes' 96, so uacring needs retuning before use. NOTICE and LICENSES/README.md gain its Apache-2.0 entry; its own NOTICE (Nordic for the driver, chattock for the audio bring-up) is carried with it. Co-Authored-By: Claude Opus 5.5 --- LICENSES/README.md | 2 +- NOTICE | 11 + third_party/sp1-usb-audio/README.md | 47 + third_party/sp1-usb-audio/upstream/.gitignore | 3 + third_party/sp1-usb-audio/upstream/LICENSE | 202 ++ .../upstream/LICENSES/sp1-tape-looper-MIT.txt | 21 + third_party/sp1-usb-audio/upstream/NOTICE | 20 + third_party/sp1-usb-audio/upstream/README.md | 63 + .../upstream/docs/HOW-IT-WORKS.md | 66 + .../sp1-usb-audio/upstream/docs/LESSONS.md | 54 + .../upstream/docs/ON-THE-SP-1.md | 108 + .../upstream/docs/STOCK-OR-FAST-PATH.md | 111 + .../upstream/extras/nrf52840dk/CMakeLists.txt | 30 + .../upstream/extras/nrf52840dk/Kconfig | 9 + .../upstream/extras/nrf52840dk/README.md | 44 + .../upstream/extras/nrf52840dk/app.overlay | 45 + .../upstream/extras/nrf52840dk/isofast.conf | 6 + .../upstream/extras/nrf52840dk/prj.conf | 16 + .../upstream/extras/nrf52840dk/src/main.c | 74 + .../module/nrf-usbd-isofast/CMakeLists.txt | 11 + .../upstream/module/nrf-usbd-isofast/Kconfig | 20 + .../module/nrf-usbd-isofast/README.md | 69 + .../patches/udc_nrf-iso-in-fast.patch | 153 ++ .../patches/udc_nrf.c.upstream | 1903 ++++++++++++++++ .../module/nrf-usbd-isofast/src/udc_nrf.c | 2003 +++++++++++++++++ .../src/udc_nrf_iso_in_fast.h | 73 + .../module/nrf-usbd-isofast/tools/check.sh | 18 + .../sp1-usb-audio/upstream/sp1/README.md | 98 + .../upstream/sp1/fw/CMakeLists.txt | 29 + .../sp1-usb-audio/upstream/sp1/fw/Kconfig | 6 + .../sp1-usb-audio/upstream/sp1/fw/app.overlay | 149 ++ .../upstream/sp1/fw/isofast.conf | 5 + .../sp1-usb-audio/upstream/sp1/fw/prj.conf | 32 + .../sp1-usb-audio/upstream/sp1/fw/src/audio.c | 388 ++++ .../sp1-usb-audio/upstream/sp1/fw/src/audio.h | 34 + .../upstream/sp1/fw/src/gesture.c | 111 + .../upstream/sp1/fw/src/gesture.h | 94 + .../sp1-usb-audio/upstream/sp1/fw/src/main.c | 76 + .../sp1-usb-audio/upstream/sp1/fw/src/power.c | 239 ++ .../sp1-usb-audio/upstream/sp1/fw/src/power.h | 16 + .../sp1-usb-audio/upstream/sp1/fw/src/wdt.c | 36 + .../sp1-usb-audio/upstream/sp1/fw/src/wdt.h | 27 + .../sp1-usb-audio/upstream/sp1/fw/txq2.conf | 4 + .../sp1-usb-audio/upstream/sp1/prep.sh | 144 ++ .../sp1-usb-audio/upstream/test/run.sh | 12 + .../upstream/test/test_uacring.c | 183 ++ .../upstream/usb-audio/README.md | 18 + .../upstream/usb-audio/uacring.c | 208 ++ .../upstream/usb-audio/uacring.h | 93 + .../upstream/usb-audio/usb_audio.c | 175 ++ .../upstream/usb-audio/usb_audio.h | 20 + 51 files changed, 7378 insertions(+), 1 deletion(-) create mode 100644 third_party/sp1-usb-audio/README.md create mode 100644 third_party/sp1-usb-audio/upstream/.gitignore create mode 100644 third_party/sp1-usb-audio/upstream/LICENSE create mode 100644 third_party/sp1-usb-audio/upstream/LICENSES/sp1-tape-looper-MIT.txt create mode 100644 third_party/sp1-usb-audio/upstream/NOTICE create mode 100644 third_party/sp1-usb-audio/upstream/README.md create mode 100644 third_party/sp1-usb-audio/upstream/docs/HOW-IT-WORKS.md create mode 100644 third_party/sp1-usb-audio/upstream/docs/LESSONS.md create mode 100644 third_party/sp1-usb-audio/upstream/docs/ON-THE-SP-1.md create mode 100644 third_party/sp1-usb-audio/upstream/docs/STOCK-OR-FAST-PATH.md create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/CMakeLists.txt create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/Kconfig create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/README.md create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/app.overlay create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/isofast.conf create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/prj.conf create mode 100644 third_party/sp1-usb-audio/upstream/extras/nrf52840dk/src/main.c create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/CMakeLists.txt create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/Kconfig create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/README.md create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf-iso-in-fast.patch create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf.c.upstream create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf.c create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf_iso_in_fast.h create mode 100644 third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/tools/check.sh create mode 100644 third_party/sp1-usb-audio/upstream/sp1/README.md create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/CMakeLists.txt create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/Kconfig create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/app.overlay create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/isofast.conf create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/prj.conf create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.c create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.h create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.c create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.h create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/main.c create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/power.c create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/power.h create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.c create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.h create mode 100644 third_party/sp1-usb-audio/upstream/sp1/fw/txq2.conf create mode 100644 third_party/sp1-usb-audio/upstream/sp1/prep.sh create mode 100644 third_party/sp1-usb-audio/upstream/test/run.sh create mode 100644 third_party/sp1-usb-audio/upstream/test/test_uacring.c create mode 100644 third_party/sp1-usb-audio/upstream/usb-audio/README.md create mode 100644 third_party/sp1-usb-audio/upstream/usb-audio/uacring.c create mode 100644 third_party/sp1-usb-audio/upstream/usb-audio/uacring.h create mode 100644 third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.c create mode 100644 third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.h diff --git a/LICENSES/README.md b/LICENSES/README.md index a32a641..270d11e 100644 --- a/LICENSES/README.md +++ b/LICENSES/README.md @@ -12,7 +12,7 @@ what was changed. | `MIT-sp1-tape-looper.txt` | chattock | the board definition, power-off and watchdog sequence, and codec bring-up adapted from chattock/sp1-tape-looper | | `MIT-SP-1-dev.txt` | Tim Knapen | the SP-1 pin map and hardware documentation from timknapen/SP-1-dev | | `MIT-sp1-midi.txt` | Eric Lewis | the original `stem_player` Zephyr board that the board definition descends from | -| `Apache-2.0.txt` | the Zephyr Project contributors | `boards/teenageengineering/stem_player/Kconfig.defconfig`, `Kconfig.stem_player` and `stem_player_defconfig` (inherited from Zephyr's board template), `zephyr-patches/`, `firmware/src/sp1_usbd.c` (derived from Zephyr's USB sample helper), and the Zephyr RTOS compiled into every firmware image | +| `Apache-2.0.txt` | the Zephyr Project contributors; Ryan Gilmore | `third_party/sp1-usb-audio/` (USB audio out; it also carries its own `LICENSE` and `NOTICE`), `boards/teenageengineering/stem_player/Kconfig.defconfig`, `Kconfig.stem_player` and `stem_player_defconfig` (inherited from Zephyr's board template), `zephyr-patches/`, `firmware/src/sp1_usbd.c` (derived from Zephyr's USB sample helper), and the Zephyr RTOS compiled into every firmware image | A built firmware image also contains other Zephyr modules (CMSIS, Nordic's `hal_nordic`) under their own licences. Release archives will carry a generated bill of materials listing them. diff --git a/NOTICE b/NOTICE index 87f80dd..2838c00 100644 --- a/NOTICE +++ b/NOTICE @@ -107,6 +107,17 @@ USB-MIDI 1.0 device class (M5a) — vendored unmodified in third_party/feldd/ instead of feldd's clock router and MIDI-thru. Commit and file list: third_party/feldd/README.md. +USB audio out (M5c) — vendored unmodified in third_party/sp1-usb-audio/upstream/ + ryanmgilmore/sp1-usb-audio — Copyright (c) 2026 Ryan Gilmore — Apache-2.0 + https://github.com/ryanmgilmore/sp1-usb-audio + Licence text: LICENSES/Apache-2.0.txt (and upstream/LICENSE). + The whole repository at one commit; its own NOTICE + (third_party/sp1-usb-audio/upstream/NOTICE) is carried forward with it: it + credits Nordic Semiconductor ASA (Apache-2.0) for the modified driver in + module/nrf-usbd-isofast/, and chattock/sp1-tape-looper (MIT) for the SP-1 + audio bring-up in sp1/fw/src/audio.c. Not yet compiled into Wakes. Commit + and what each part is for: third_party/sp1-usb-audio/README.md. + Zephyr RTOS — Apache-2.0 — https://github.com/zephyrproject-rtos/zephyr Licence text: LICENSES/Apache-2.0.txt boards/teenageengineering/stem_player/Kconfig.defconfig, Kconfig.stem_player diff --git a/third_party/sp1-usb-audio/README.md b/third_party/sp1-usb-audio/README.md new file mode 100644 index 0000000..5897713 --- /dev/null +++ b/third_party/sp1-usb-audio/README.md @@ -0,0 +1,47 @@ +# Vendored: Ryan Gilmore's sp1-usb-audio (M5c, USB audio out) + +**Upstream, unmodified.** Everything under `upstream/` is the whole repository at the commit +below, byte for byte (`git archive`; the blobs were checked against upstream's). Do not edit it. +When Wakes needs a change to one of these files, it goes in a patch applied at build time to a +copy, as for `third_party/feldd/`. + +| | repository | commit | +|---|---|---| +| `upstream/` | https://github.com/ryanmgilmore/sp1-usb-audio | `74f3c4401676c06488d309a2cecd250eaedf0ef8` | + +Copyright (c) 2026 Ryan Gilmore. Apache-2.0 — `upstream/LICENSE`. `upstream/NOTICE` is carried +forward as Apache-2.0 asks: it credits Nordic Semiconductor for the driver in +`upstream/module/nrf-usbd-isofast/` and chattock (MIT) for the SP-1 audio bring-up in +`upstream/sp1/fw/src/audio.c`. + +Nothing here is compiled yet. M5c is "USB audio out": the SP-1's output, sent to the host. Nothing +in Wakes receives audio from the host. + +## What is here, and what Wakes uses it for + +| path | what it is | for Wakes | +|---|---|---| +| `usb-audio/uacring.{c,h}` | the ring buffer and the packet regulator: 47, 48 or 49 frames per 1 ms packet, following the drift between the SP-1's 3.072 MHz audio clock and the host's USB frames | **to be built.** Tuned upstream for 128- and 256-frame producer blocks; Wakes renders 96 (2 ms), so its constants need retuning (its host test fails at 96 as it stands) | +| `usb-audio/usb_audio.{c,h}` | glue between Zephyr's UAC2 class, the ring and the fast path, incl. stop on VBUS removed / bus reset and re-prime on resume | reference for M5c's glue; which class Wakes uses is still open (UAC1 or UAC2) | +| `test/test_uacring.c`, `test/run.sh` | host tests for the regulator | to be run by `tools/host-tests`, at 96 | +| `module/nrf-usbd-isofast/` | the ISO IN fast path: a patch against nRF Connect SDK's `udc_nrf.c` (`sdk-zephyr` `fd9204a0`), with that base kept as `patches/udc_nrf.c.upstream` | already ported to Zephyr 4.3.1 in `zephyr-patches/udc_nrf-fast-paths.patch` (`CONFIG_UDC_NRF_ISO_IN_FAST`, off). `udc_nrf.c.upstream` is the base for checking that port against 4.3.1's driver | +| `docs/` | how it works, stock driver vs fast path (measured on an SP-1), lessons from the bench | reference | +| `sp1/`, `extras/nrf52840dk/` | Ryan's complete SP-1 test firmware (a tone to speaker and USB) and a dev-board version | reference only; never built here | + +Where Wakes deliberately differs from upstream (M5-PLAN, section E): + +- **USB audio follows VOL.** Upstream sends at a fixed −6 dB, independent of the volume. +- **The fast path is the only path.** Upstream treats it as optional; stock Zephyr costs ~18 % of + the CPU, which Wakes does not have. + +## Updating + +From a clone of upstream: + +```sh +git -C archive | tar -x -C third_party/sp1-usb-audio/upstream +``` + +after emptying `upstream/`. Then read the upstream diff since the commit above (in particular +`module/nrf-usbd-isofast/patches/` against `zephyr-patches/udc_nrf-fast-paths.patch`), rebuild, +run the host tests, update the commit above, and test on hardware. diff --git a/third_party/sp1-usb-audio/upstream/.gitignore b/third_party/sp1-usb-audio/upstream/.gitignore new file mode 100644 index 0000000..805f251 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/.gitignore @@ -0,0 +1,3 @@ +# Build output: sp1/prep.sh builds into sp1/.build/ by default; west into build/. +.build/ +build/ diff --git a/third_party/sp1-usb-audio/upstream/LICENSE b/third_party/sp1-usb-audio/upstream/LICENSE new file mode 100644 index 0000000..8f71f43 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/LICENSE @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright {yyyy} {name of copyright owner} + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/third_party/sp1-usb-audio/upstream/LICENSES/sp1-tape-looper-MIT.txt b/third_party/sp1-usb-audio/upstream/LICENSES/sp1-tape-looper-MIT.txt new file mode 100644 index 0000000..07ad803 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/LICENSES/sp1-tape-looper-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 chattock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third_party/sp1-usb-audio/upstream/NOTICE b/third_party/sp1-usb-audio/upstream/NOTICE new file mode 100644 index 0000000..8fcb155 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/NOTICE @@ -0,0 +1,20 @@ +sp1-usb-audio + +module/nrf-usbd-isofast/src/udc_nrf.c is Nordic Semiconductor ASA's nRF USBD +device-controller driver from Zephyr (drivers/usb/udc/udc_nrf.c), as carried by +nRF Connect SDK's Zephyr (sdk-zephyr, commit fd9204a0), Copyright (c) 2021 +Nordic Semiconductor ASA, Apache-2.0. It has been MODIFIED: the changes are +exactly module/nrf-usbd-isofast/patches/udc_nrf-iso-in-fast.patch against the +unmodified copy in module/nrf-usbd-isofast/patches/udc_nrf.c.upstream. + +sp1/fw/src/audio.c ports the SP-1 audio bring-up (TAS2505 and CS42L42 +configuration, clock topology, init order, audio thread) from +chattock/sp1-tape-looper, firmware/src/main.c, at commit 2565e79, +Copyright (c) 2026 chattock, MIT License. The licence text is in +LICENSES/sp1-tape-looper-MIT.txt. The CS42L42 register sequence is Tim +Knapen's (github.com/timknapen/SP-1-dev/wiki/I2C). + +sp1/prep.sh builds against two projects it fetches at build time and does not +include here: marisko's sp1 board definition (github.com/softmodded/marisko) +and feldd's hardware files (github.com/bnjreece/feldd-sp1-firmware, MIT, +Copyright (c) 2026 Benjamin Reece). Their licences govern those files. diff --git a/third_party/sp1-usb-audio/upstream/README.md b/third_party/sp1-usb-audio/upstream/README.md new file mode 100644 index 0000000..dfbac29 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/README.md @@ -0,0 +1,63 @@ +# sp1-usb-audio + +USB audio out for the Teenage Engineering SP-1: 48 kHz, 16-bit stereo from the +SP-1 to a computer, as a class-compliant USB audio input. No driver on the host. + +This is for people writing their own firmware for the SP-1 on Zephyr. It +explains how USB audio out works, gives you the code that does it, and records +what went wrong along the way so you don't have to find it again. The code comes +from an SP-1 firmware that has shipped USB audio in its default build since +September 2026. + +## Start here + +[`sp1/`](sp1/README.md) is a complete SP-1 firmware: it plays a 1 kHz tone +through the speaker, at the master volume on Vol+/Vol-, and to the computer over +USB at a fixed level. It has everything an SP-1 firmware needs besides the audio: +power on and off, the watchdog, the charge gauge. Build it, flash it, and record +the tone on your computer — then copy the parts you need into your own firmware. +[`docs/ON-THE-SP-1.md`](docs/ON-THE-SP-1.md) walks through it. + +## The short version + +- **Stock Zephyr already does USB audio.** Its UAC2 class (`zephyr,uac2`) on the + nRF52840's stock USB driver is all this needs. Nothing here has to be patched to + get sound out. +- **What you do have to write** is the part that sizes packets: 47, 48 or 49 + frames per 1 ms, to follow the drift between the audio clock and the host's. + [`docs/HOW-IT-WORKS.md`](docs/HOW-IT-WORKS.md). +- **The patched driver is optional.** It cuts the USB stack's CPU cost from ~18% + to ~0, which matters only for firmware short of CPU. Which to use, and what + each costs: [`docs/STOCK-OR-FAST-PATH.md`](docs/STOCK-OR-FAST-PATH.md). + +## What is here + +| | | +|---|---| +| [`sp1/`](sp1/README.md) | **the SP-1 firmware**: tone to speaker and USB, with power, watchdog and LEDs | +| [`usb-audio/`](usb-audio/README.md) | the USB audio code itself, shared by both firmwares: the glue and the packet regulator | +| [`module/nrf-usbd-isofast/`](module/nrf-usbd-isofast/README.md) | the optional fast-path driver for Zephyr's nRF USB driver | +| [`docs/ON-THE-SP-1.md`](docs/ON-THE-SP-1.md) | a walkthrough of the SP-1 firmware: clocking, the USB node, where the calls go | +| [`docs/STOCK-OR-FAST-PATH.md`](docs/STOCK-OR-FAST-PATH.md) | which driver to use, measured, with the trade-offs of each | +| [`docs/HOW-IT-WORKS.md`](docs/HOW-IT-WORKS.md) | the pieces and where each comes from | +| [`docs/LESSONS.md`](docs/LESSONS.md) | what went wrong on the way, and the fixes | +| [`test/`](test/run.sh) | host tests for the regulator (any C compiler) | +| [`extras/nrf52840dk/`](extras/nrf52840dk/README.md) | the same USB side on a Nordic dev board, with no SP-1 code around it — the smallest version to read | + +## Where it has been tested + +- **On an SP-1, with macOS:** the regulator, the glue and the fast-path driver, + as part of a full firmware. Streams clean under full synth load; stops cleanly + when the cable is pulled. +- **Not tried:** Windows, Linux, and resuming from a host that suspends without + closing the stream. +- **The SP-1 firmware in `sp1/` has run on an SP-1** with both the stock driver + and the fast path: power, tone, volume, headphones, a clean USB recording and + power-off all checked on each. Not yet tried there: unplugging mid-stream. +- **The dev-board version** has been built with both drivers, not run. + +## Licence + +Apache-2.0 ([`LICENSE`](LICENSE)), as Zephyr. The driver in +`module/nrf-usbd-isofast/` is Nordic Semiconductor's, modified; see +[`NOTICE`](NOTICE). diff --git a/third_party/sp1-usb-audio/upstream/docs/HOW-IT-WORKS.md b/third_party/sp1-usb-audio/upstream/docs/HOW-IT-WORKS.md new file mode 100644 index 0000000..a6b0606 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/docs/HOW-IT-WORKS.md @@ -0,0 +1,66 @@ +# How USB audio out works on the SP-1 + +## The pieces, and where each comes from + +| Piece | What it does | From | Licence | +|---|---|---|---| +| UAC2 class | makes the device a USB audio device: descriptors, alternate settings, the ISO IN endpoint | Zephyr, `device_next` stack (`subsys/usb/device_next/class/usbd_uac2.c`), configured by devicetree ([`sp1/fw/app.overlay`](../sp1/fw/app.overlay)) | Apache-2.0 | +| nRF USB driver | moves packets over the nRF52840's USB hardware | Zephyr, `drivers/usb/udc/udc_nrf.c`, written by Nordic | Apache-2.0 | +| ring + regulator | holds rendered audio; sizes each 1 ms packet 47/48/49 frames | this repo, [`usb-audio/uacring.c`](../usb-audio/uacring.c) | Apache-2.0 | +| glue | connects the class's callbacks to the ring | [`usb-audio/usb_audio.c`](../usb-audio/usb_audio.c) | Apache-2.0 | +| fast path (optional) | sends each packet from the driver's interrupt | [`module/nrf-usbd-isofast/`](../module/nrf-usbd-isofast/README.md) | Apache-2.0 | + +## The stream + +- One UAC2 function: a clock source fixed at 48 kHz, an input terminal + ("synthesizer"), a USB streaming output terminal, and one audio-streaming + interface with 2-byte subslots, 16-bit. The host sees an audio INPUT. +- No ISO OUT and no feedback endpoint. So there is no way for the device to tell + the host its real rate — the device adjusts packet sizes instead + ("asynchronous" by packet size). +- The host opens the stream by selecting the interface's alternate setting 1; + the class calls `terminal_update_cb`, which starts the ring priming. + +## Why packets are 47, 48 or 49 frames + +There are two clocks. On the SP-1 a 3.072 MHz oscillator paces the audio; the +computer paces USB frames, one per millisecond. They never agree exactly, so +sending exactly 48 frames every millisecond would slowly overfill or drain the +ring. Instead the device watches how full the ring is and now and then sends one +frame more or less. + +- The ring's average fill is tracked with ~1 s smoothing. Outside a dead band + around the target it sends one 47- or 49-frame packet, at most one per 50 + packets: 20 frames a second, ~417 ppm, about twice the worst crystal. +- Target fill with 128-frame producer blocks: 416 frames, ~8.7 ms. +- It steers on the **claimed** position — where the audio thread took its I2S + slot — not on when rendering finished, so a heavy chord does not look like + clock drift. See [`LESSONS.md`](LESSONS.md), "the chord-start click". + +## Each 1 ms frame, stock path + +1. The driver's start-of-frame interrupt posts an event (`CONFIG_UDC_ENABLE_SOF=y` + is required for the nRF driver to schedule any ISO IN). +2. The class calls `sof_cb`, which pops a packet into a slab buffer and calls + `usbd_uac2_send()`. +3. The driver sends it; the class returns the buffer through `buf_release_cb`. + +That is four thread wake-ups per millisecond, ~18% of the SP-1's 64 MHz CPU. For +most firmware that is fine. + +## Each 1 ms frame, with the fast path + +1. At start-of-frame the patched driver's interrupt calls your fill callback, + which pops the packet straight into a driver-owned buffer. +2. The same interrupt starts the DMA. +3. When it finishes, the driver just releases the DMA channel. + +No buffer to allocate, no send call, no event, no thread wake-up. The glue can +also tell the driver to stop posting SOF events, since nothing else needs them. + +## Stopping and restarting + +- The class reports a stream stopping only when the host selects alternate + setting 0. A pulled cable or a bus reset never does, so the glue also stops + the stream on `USBD_MSG_VBUS_REMOVED` and `USBD_MSG_RESET`. +- On `USBD_MSG_RESUME` it re-primes, because the ring filled while the host slept. diff --git a/third_party/sp1-usb-audio/upstream/docs/LESSONS.md b/third_party/sp1-usb-audio/upstream/docs/LESSONS.md new file mode 100644 index 0000000..b0bb716 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/docs/LESSONS.md @@ -0,0 +1,54 @@ +# Lessons from the bench + +## The chord-start click was the packet sizer, not the driver + +- Symptom: a click in the recording as chords started. +- Cause: the regulator read a render-timing step (a heavy chord makes each block + finish later) as clock drift, and sent ~150 ms of 47-frame packets. To the host + the clock briefly ran 2% slow, and macOS's correction was audible. +- Fix: ~1 s smoothing, a dead band, at most one correction per 50 packets, and + steering on the claimed position instead of the push. +- Lesson: the regulator must only ever see clock drift. Anything that moves + the fill for another reason has to be kept out of what it measures. + +## A pulled cable does not stop the stream + +- The UAC2 class only hears alternate setting 0. With the cable out the stream + stayed "on", every block counted as an overflow, and the unit stayed on battery. +- Fix: stop on VBUS removed and on bus reset. Confirmed on hardware: the stream + stops ~27 ms after the cable, no reset, restarts clean. + +## Resume needs a re-prime + +- Nothing drains while the host sleeps; a stream resumed on a full ring runs ~40 + ms late and drifts back for minutes. +- Status: the re-prime is written but **not exercised** — macOS closes the stream + before it sleeps, so this path never ran on the bench. + +## Latency comes from the audio path, not USB + +- The USB ring adds ~8.7 ms (416 frames). The big win was elsewhere: a 2-block + I2S queue and 128-sample blocks. +- The fast path does not reduce latency: the packet goes out on the next frame + either way. + +## Level + +- USB audio goes out at its own fixed level (-6 dB by default), separate from + the master volume. The volume buttons reach only the speaker and headphones. +- Why: a recording's level should not depend on where the volume happened to be + set. +- -6 dB is close to the edge, not safe: the heaviest chord tested there peaked at + 33398 of 32767 and clipped one sample. The level trims from 0 to -18 dB over + SysEx, so a firmware for louder material can sit lower. + +## Not tried + +- Windows. An output-only stream has no feedback endpoint, so it avoids the one + Windows quirk Zephyr documents for asynchronous streams (its UAC2 driver + expects a 4-byte explicit-feedback endpoint, against the USB spec; see Zephyr's + `samples/subsys/usb/uac2_explicit_feedback`). Untested all the same. +- Linux. +- Host audio INTO the SP-1 (playback). With the only isochronous IN endpoint + used by the capture stream, it would need implicit feedback, which Zephyr's + `uac2_implicit_feedback` sample notes Windows' UAC2 driver does not support. diff --git a/third_party/sp1-usb-audio/upstream/docs/ON-THE-SP-1.md b/third_party/sp1-usb-audio/upstream/docs/ON-THE-SP-1.md new file mode 100644 index 0000000..46dd4c8 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/docs/ON-THE-SP-1.md @@ -0,0 +1,108 @@ +# Adding USB audio out to an SP-1 firmware + +This page walks through what USB audio needs on an SP-1, pointing at where each +piece lives in [`../sp1/`](../sp1/README.md), the complete example firmware. If +you are adding USB audio to a firmware you already have, these are the parts to +copy. If you are starting from nothing, start from `sp1/` itself: it already has +the watchdog, power-off and LEDs an SP-1 firmware needs. Everything below was +worked out in an SP-1 firmware that ships USB audio in its default build. + +## 1. The clock: the codec is the master, not the nRF + +On the SP-1 a 3.072 MHz oscillator (enabled on P0.13) drives the I2S bit clock. +The CS42L42 headphone codec divides it by 64 to make an exact 48 kHz frame clock, +and **the nRF52840's I2S and the TAS2505 speaker amp are both slaves.** The board +definition most SP-1 projects build against has the nRF as I2S master, and that +crackles on the speaker and gives noise on the headphones. + +So the I2S bit and frame clock pins become **inputs** (the `_S` pin selections): + +```dts +&i2s0_default { + group1 { + psels = , + , + ; + }; +}; +``` + +and the I2S is configured as a slave on both clocks: + +```c +.options = I2S_OPT_FRAME_CLK_SLAVE | I2S_OPT_BIT_CLK_SLAVE, +.word_size = 16, .channels = 2, .frame_clk_freq = 48000, +``` + +This is also why USB audio needs the packet regulator at all: the audio runs on +the SP-1's oscillator, USB frames run on the computer's clock, and nothing ties +the two together. + +Bring-up order, as proven on hardware: release the codec (P0.15) and amp (P0.9) +resets, wait 20 ms, enable the oscillator, wait 5 ms, then start I2S and the +TAS2505 before initialising the CS42L42. The CS42L42 register sequence is Tim +Knapen's ([SP-1-dev wiki, I2C](https://github.com/timknapen/SP-1-dev/wiki/I2C)); +the clocking and bring-up order come from +[chattock/sp1-tape-looper](https://github.com/chattock/sp1-tape-looper) (MIT). + +## 2. The USB device node + +The common `sp1` board definition has no USB device node. Add one in your app's +overlay; the UAC2 function then goes alongside it unchanged. Both are in +[`sp1/fw/app.overlay`](../sp1/fw/app.overlay): + +```dts +zephyr_udc0: &usbd { + compatible = "nordic,nrf-usbd"; + status = "okay"; +}; +``` + +## 3. Where the two calls go + +Copy the four files in [`usb-audio/`](../usb-audio/README.md) into your app, add +the USB lines from [`sp1/fw/prj.conf`](../sp1/fw/prj.conf), and — as +[`sp1/fw/src/main.c`](../sp1/fw/src/main.c) and +[`sp1/fw/src/audio.c`](../sp1/fw/src/audio.c) do: + +- at startup, call `usb_audio_init()` **before** `usbd_enable()`, and pass + `usb_audio_usbd_msg` to `sample_usbd_init_device()` (or call it from your own + USB message callback); +- in the audio thread, each time it takes a block for I2S, **before rendering**: + `usb_audio_claim(frames)`; +- after rendering that block: `usb_audio_push(lr, frames)` with interleaved + 16-bit left/right frames. + +The claim is what keeps a heavy render from being mistaken for clock drift +([`LESSONS.md`](LESSONS.md)). The regulator's settings are tuned for 128- or +256-frame blocks (`AUDIO_BLK_FRAMES`, default 128). + +## 4. The audio thread's priority + +Keep the audio thread **preemptible**, at `K_PRIO_PREEMPT(0)`. Zephyr's USB +threads are cooperative at priority 8 and outrank it, so USB work can land in the +middle of a render; the I2S queue absorbs that. Making the audio thread +cooperative stopped the interruptions, but under near-full load it then starved +the main thread and the USB threads until the watchdog reset the unit. A +preemptible audio thread fails as one late block instead. + +## 5. Level + +Push the USB copy at its own fixed level, not through the master volume, so a +recording never follows the volume buttons. The SP-1 firmware this comes from +renders once and writes two outputs: the speaker/headphone mix at the master +volume, and the USB stream at -6 dB by default, adjustable over SysEx. + +## 6. Alongside USB-MIDI and a serial console + +UAC2 fits beside USB-MIDI and a CDC serial console on the nRF52840: together +they use 3 of 7 IN endpoints, 2 of 7 OUT, and the one isochronous IN. The +nRF driver splits its isochronous buffer in half, 511 bytes a side, and a packet +is at most 196 bytes. The audio side adds under ~2 KB of RAM. + +## 7. CPU + +With the stock driver, streaming costs ~18% of the SP-1's 64 MHz CPU. If your +firmware has that to spare, stop here. If it does not, the optional +[fast-path driver](../module/nrf-usbd-isofast/README.md) takes it to ~0 — +[`STOCK-OR-FAST-PATH.md`](STOCK-OR-FAST-PATH.md) weighs the two. diff --git a/third_party/sp1-usb-audio/upstream/docs/STOCK-OR-FAST-PATH.md b/third_party/sp1-usb-audio/upstream/docs/STOCK-OR-FAST-PATH.md new file mode 100644 index 0000000..87ec70a --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/docs/STOCK-OR-FAST-PATH.md @@ -0,0 +1,111 @@ +# Stock driver or fast path? + +Both send the same audio. They differ in what it costs your firmware to send it, +and what you take on to get that cost down. **Start with stock.** Switch only if +you have measured that you need the CPU back. + +## The short answer + +| Your firmware... | Use | +|---|---| +| has CPU to spare while streaming | **stock** | +| sends no USB audio (MIDI, serial, HID only) | **stock** — the fast path does nothing for these | +| also receives audio from the host, or has a feedback endpoint | **stock**, or expect a much smaller gain | +| produces its audio in a thread and needs locks or heavy work to hand over a packet | **stock** | +| is short of CPU while streaming, and can hand over each packet in a few µs without locks | **fast path** | + +## What each one does, every millisecond + +**Stock.** The USB interrupt posts an event; Zephyr's `usbd` thread wakes and +asks your code for a packet; the driver's own thread wakes to start the transfer, +wakes again when it finishes, and hands the buffer back to `usbd`, which wakes a +second time to release it. Four thread wake-ups per packet, a thousand packets a +second. + +**Fast path.** The USB interrupt calls your fill function, which copies the next +packet into a driver buffer, and the same interrupt starts the transfer. No +threads wake at all. + +## Measured on an SP-1 + +64 MHz Cortex-M4, 48 kHz 16-bit stereo to macOS, the same synth firmware both ways: + +| | Stock | Fast path | +|---|---|---| +| USB threads' share of the CPU, four voices playing | ~18% (`usbd` 11%, driver thread 7%) | ~0 | +| Time to render one audio block, four voices | ~3486 µs | 2923 µs — the same as with no stream open | +| Six voices plus the stream, repeated chords | the unit reset | 4139–4456 µs of a 5333 µs budget, no reset | +| Dropped or late packets | none, until overloaded | none | +| Latency | a packet leaves on the next USB frame | the same | + +In that firmware the difference was five voices or six. That is the whole case +for the fast path: **it buys back CPU, nothing else.** + +## Stock: positives and negatives + +**Positives** +- **Nothing to maintain.** It is Zephyr's driver; every Zephyr and nRF Connect + SDK release brings its fixes, and it is tested by far more people than this repo. +- **Portable.** The same code works on any chip Zephyr's UAC2 class supports. +- **Forgiving.** Your packet code runs in a thread. It can take a lock, wait + briefly, or do real work, and a mistake shows up as an ordinary thread bug you + can debug. +- **Plays well with others.** It does not care whether other classes need + start-of-frame events or whether you also receive audio. + +**Negatives** +- **CPU.** ~18% of a 64 MHz nRF52840 while the stream is open, whether or not + anything is playing. +- **Scheduling pressure.** Those wake-ups land in the middle of your audio work. + Zephyr's USB threads outrank a normal audio thread, so a render that was + already close to its deadline can be pushed past it. + +## Fast path: positives and negatives + +**Positives** +- **The CPU comes back.** The USB audio cost goes to roughly zero. +- **Robust under load.** The packet is written by the interrupt itself, so a busy + audio thread cannot make it late. +- **Opt-in and contained.** About 100 added lines, all behind the callback being + registered. Built with no callback, the driver behaves exactly as stock. + +**Negatives** +- **You carry a copy of a Zephyr driver.** It is one file forked at one version + (nRF Connect SDK v3.3.0's Zephyr). Fixes Nordic makes after that do not reach + you until someone rebases the patch by hand. +- **It is tied to that version.** Upstream Zephyr v4.3.1's copy of the file + differs by ~330 lines, including the timing logic the fast path relies on. The + patch *applies* there, which is misleading: on another Zephyr it needs review + and testing, not just applying. +- **Your fill function runs in an interrupt,** a thousand times a second. It must + be short, never block, and take no locks — copy from a ring buffer and return. + Anything slower delays every other interrupt too: I2S, timers, the radio. +- **Bugs are harder to see.** A mistake in interrupt-level code does not show up + as a thread you can inspect. +- **Most of the gain assumes nothing else needs start-of-frame events.** The + biggest saving is skipping the `usbd` wake-up every frame. If you also receive + audio from the host, or use a feedback endpoint, that wake-up has to stay. +- **Send direction only, nRF52840 only.** It does nothing for audio coming *into* + the device, and the API is specific to Nordic's nRF52840 USB driver. +- **Less tested.** Proven on one SP-1 with macOS. Not yet tried on Windows or + Linux, or across a host suspend with the stream open. + +## How to decide on your own firmware + +1. Build with stock and open the stream. +2. Turn on Zephyr's per-thread CPU accounting (`CONFIG_THREAD_RUNTIME_STATS=y`, + `CONFIG_SCHED_THREAD_USAGE_ALL=y`, and on nRF52 + `CONFIG_THREAD_RUNTIME_STATS_USE_TIMING_FUNCTIONS=y`, since the default 32 kHz + clock is too coarse for USB work). +3. Play your heaviest material and read the `usbd` and `udc_nrfx` threads' share. +4. If your audio still keeps up, you are done. If it does not, and those two + threads are what tips it over, try the fast path. It is one config switch in + either direction. + +## If the fast path reaches Zephyr + +The plan is to offer the fast path to Zephyr as an opt-in setting. If it is +accepted, most of its negatives go away: you would build stock Zephyr, each +release would carry a version written for its own driver, and Nordic's fixes and +Zephyr's testing would cover it. The interrupt-context rules would still apply, +and whether you need it would still depend on your CPU budget. diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/CMakeLists.txt b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/CMakeLists.txt new file mode 100644 index 0000000..12f4105 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/CMakeLists.txt @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: Apache-2.0 +cmake_minimum_required(VERSION 3.20.0) +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +project(sp1_usb_audio_sample) + +# This sample has no watchdog feed, no power-off and no LEDs. Flashed on an +# SP-1 it would reset every 5 s (the bootloader's watchdog) with no way to turn +# the unit off. See README.md, "Running on an SP-1". +if(BOARD STREQUAL "sp1") + message(FATAL_ERROR "sample: not for the sp1 board as it stands -- the SP-1 firmware is ../../sp1/") +endif() + +# sample_usbd: Zephyr's device_next helper that builds the USB device from the +# classes enabled in devicetree and Kconfig. +include(${ZEPHYR_BASE}/samples/subsys/usb/common/common.cmake) + +# The shared USB audio code: the glue and the packet regulator. +set(USB_AUDIO ${CMAKE_CURRENT_SOURCE_DIR}/../../usb-audio) +target_sources(app PRIVATE src/main.c ${USB_AUDIO}/usb_audio.c ${USB_AUDIO}/uacring.c) +target_include_directories(app PRIVATE ${USB_AUDIO}) + +# The ring is single-producer single-consumer across a thread and the USB +# stack (or, with the fast path, the USBD interrupt): full barriers on target. +set_source_files_properties(${USB_AUDIO}/uacring.c PROPERTIES + COMPILE_DEFINITIONS "UACRING_BARRIER=barrier_dmem_fence_full" + COMPILE_OPTIONS "-include;zephyr/sys/barrier.h") + +# Optional: the ISO IN fast path, in place of Zephyr's nRF USBD driver. +# Build with -DEXTRA_CONF_FILE=isofast.conf. +include(${CMAKE_CURRENT_SOURCE_DIR}/../../module/nrf-usbd-isofast/CMakeLists.txt) diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/Kconfig b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/Kconfig new file mode 100644 index 0000000..78b3a7d --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/Kconfig @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: Apache-2.0 + +# CONFIG_SAMPLE_USBD_VID/PID/PRODUCT/..., consumed by sample_usbd_init.c. +source "samples/subsys/usb/common/Kconfig.sample_usbd" + +# CONFIG_UDC_NRF_ISOFAST: the optional fast-path driver. +rsource "../../module/nrf-usbd-isofast/Kconfig" + +source "Kconfig.zephyr" diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/README.md b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/README.md new file mode 100644 index 0000000..5298272 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/README.md @@ -0,0 +1,44 @@ +# extras/nrf52840dk — the USB side alone, on a Nordic dev board + +**For an SP-1, use [`../../sp1/`](../../sp1/README.md).** This is the same USB +audio code with nothing SP-1-specific around it — no codec, power or LEDs — so it +is the shortest thing to read, and it runs on hardware you may already have. The +device appears on the host as a 48 kHz stereo audio input playing a 1 kHz sine at +-12 dBFS. It builds for any nRF52840 board with +Zephyr's USB device controller enabled. Built for `nrf52840dk/nrf52840`, both +driver paths, no warnings; not yet run on hardware. + +## Build + +Zephyr with the `device_next` USB stack (developed against nRF Connect SDK +v3.3.0's Zephyr, 4.3.99): + +```sh +west build -b nrf52840dk/nrf52840 extras/nrf52840dk +# with the optional fast-path driver: +west build -b nrf52840dk/nrf52840 extras/nrf52840dk -- -DEXTRA_CONF_FILE=isofast.conf +``` + +On nRF Connect SDK, `west build` uses sysbuild by default and the image lands in +`build/nrf52840dk/zephyr/`; `--no-sysbuild` puts it in `build/zephyr/`. + +Build from this repo's layout: it takes the shared code from `../../usb-audio` +and the module from `../../module/nrf-usbd-isofast`. + +## Check it + +Plug the board's nRF USB port into a computer. It appears as an audio input +called "UAC2 tone sample": on macOS in Audio MIDI Setup, on Linux in +`arecord -l`. Record from it in any audio app and you should hear a steady 1 kHz +tone. + +## Not for an SP-1 + +**Do not flash this onto an SP-1.** The build refuses the `sp1` board on +purpose: it has no watchdog feed, so the SP-1's bootloader watchdog would reset +it every 5 s, and no power-off, so the unit could not easily get back to its +bootloader. [`../../sp1/`](../../sp1/README.md) is the SP-1 version, with both. + +## Replace before shipping + +The USB VID/PID are Zephyr's test IDs (`0x2fe3`/`0x0001`). Use your own. diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/app.overlay b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/app.overlay new file mode 100644 index 0000000..3bc48b0 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/app.overlay @@ -0,0 +1,45 @@ +/* SPDX-License-Identifier: Apache-2.0 + * + * One UAC2 function: a 48 kHz, 16-bit stereo capture stream to the host -- + * the device appears as an audio INPUT on the computer. No ISO OUT and no + * feedback endpoint, so nothing but the capture stream needs SOF events. + */ +#include + +/ { + uac2_synth: usb_audio2 { + compatible = "zephyr,uac2"; + status = "okay"; + full-speed; + audio-function = ; + + uac2_synth_clock: clock { + compatible = "zephyr,uac2-clock-source"; + clock-type = "internal-fixed"; + frequency-control = "read-only"; + sampling-frequencies = <48000>; + }; + + uac2_synth_in: synthesizer { + compatible = "zephyr,uac2-input-terminal"; + clock-source = <&uac2_synth_clock>; + terminal-type = ; + front-left; + front-right; + }; + + uac2_usb_out: usb_out { + compatible = "zephyr,uac2-output-terminal"; + data-source = <&uac2_synth_in>; + clock-source = <&uac2_synth_clock>; + terminal-type = ; + }; + + uac2_capture: capture { + compatible = "zephyr,uac2-audio-streaming"; + linked-terminal = <&uac2_usb_out>; + subslot-size = <2>; + bit-resolution = <16>; + }; + }; +}; diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/isofast.conf b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/isofast.conf new file mode 100644 index 0000000..ccf8da0 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/isofast.conf @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: Apache-2.0 +# Optional: replace Zephyr's nRF USBD driver with nrf-usbd-isofast's copy, +# whose ISO IN fast path sends each packet from the SOF interrupt with no thread +# wake-up. ../../module/nrf-usbd-isofast/README.md says when this is worth it. +CONFIG_UDC_NRF=n +CONFIG_UDC_NRF_ISOFAST=y diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/prj.conf b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/prj.conf new file mode 100644 index 0000000..1ba3ec3 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/prj.conf @@ -0,0 +1,16 @@ +# SPDX-License-Identifier: Apache-2.0 + +# Zephyr's newer USB device stack and its UAC2 (USB Audio Class 2) function. +CONFIG_USB_DEVICE_STACK_NEXT=y +CONFIG_USBD_AUDIO2_CLASS=y +# The nRF USBD driver enables its start-of-frame interrupt only with this set. +# The class forwards each SOF to uac2_ops.sof_cb, which sends one packet. +CONFIG_UDC_ENABLE_SOF=y + +# Zephyr's test VID/PID. Use your own for anything you distribute. +CONFIG_SAMPLE_USBD_PRODUCT="UAC2 tone sample" +CONFIG_SAMPLE_USBD_MAX_POWER=50 + +CONFIG_HWINFO=y +CONFIG_PRINTK=y +CONFIG_LOG=n diff --git a/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/src/main.c b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/src/main.c new file mode 100644 index 0000000..73d4037 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/extras/nrf52840dk/src/main.c @@ -0,0 +1,74 @@ +/* SPDX-License-Identifier: Apache-2.0 + * + * UAC2 tone sample: a 1 kHz sine at -12 dBFS, 48 kHz stereo, to the host as a + * USB audio input. + * + * The producer stands in for a real audio path. On an SP-1 the audio thread is + * paced by the I2S codec's clock, one block at a time; here a thread is paced by + * the system timer and renders however many frames the timer says are due. + * Either way the audio runs on a clock that is not the host's USB frame clock, + * which is exactly the drift the packet regulator (uacring.c) absorbs. + */ +#include +#include + +#include +#include +#include +#include + +#include "usb_audio.h" + +#define RATE 48000u +#define TONE_PERIOD 48u /* 1 kHz at 48 kHz: a whole cycle in 48 frames */ +#define MAX_CHUNK 256u +#define TICK_MS 2 + +static int16_t sine[TONE_PERIOD]; +static int16_t chunk[MAX_CHUNK * 2u]; + +int main(void) +{ + for (uint32_t i = 0; i < TONE_PERIOD; i++) { + /* -12 dBFS: a quarter of full scale. */ + sine[i] = (int16_t)(8192.0f * sinf(2.0f * 3.14159265f * (float)i / TONE_PERIOD)); + } + + usb_audio_init(); + struct usbd_context *ctx = sample_usbd_init_device(usb_audio_usbd_msg); + + if (ctx == NULL || usbd_enable(ctx) != 0) { + printk("usb init failed\n"); + return 0; + } + + const uint64_t hz = (uint64_t)sys_clock_hw_cycles_per_sec(); + const uint64_t start = k_cycle_get_64(); + uint64_t produced = 0; + uint32_t phase = 0; + + for (;;) { + k_msleep(TICK_MS); + + /* Frames due by the system clock, so the rate is exactly 48 kHz on + * that clock however the sleeps round. */ + uint64_t due = (k_cycle_get_64() - start) * RATE / hz; + + while (produced < due) { + uint32_t n = (uint32_t)MIN(due - produced, (uint64_t)MAX_CHUNK); + + /* Tell the regulator what is coming BEFORE rendering it, so a + * slow render never looks like clock drift. On an SP-1 this is + * where the audio thread takes its I2S slot. */ + usb_audio_claim(n); + for (uint32_t i = 0; i < n; i++) { + chunk[i * 2u] = sine[phase]; + chunk[i * 2u + 1u] = sine[phase]; + phase = (phase + 1u) % TONE_PERIOD; + } + usb_audio_push(chunk, n); + produced += n; + } + } + return 0; +} diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/CMakeLists.txt b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/CMakeLists.txt new file mode 100644 index 0000000..63de096 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/CMakeLists.txt @@ -0,0 +1,11 @@ +# Out-of-tree build of the patched nRF USBD driver. Include from an application +# CMakeLists.txt after find_package(Zephyr): +# include(/nrf-usbd-isofast/CMakeLists.txt) +# The driver needs Zephyr's private UDC and nrf_usbd_common headers. +if(CONFIG_UDC_NRF_ISOFAST) + target_sources(app PRIVATE ${CMAKE_CURRENT_LIST_DIR}/src/udc_nrf.c) + target_include_directories(app PRIVATE + ${CMAKE_CURRENT_LIST_DIR}/src + ${ZEPHYR_BASE}/drivers/usb/udc + ${ZEPHYR_BASE}/drivers/usb/common/nrf_usbd_common) +endif() diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/Kconfig b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/Kconfig new file mode 100644 index 0000000..13e972e --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/Kconfig @@ -0,0 +1,20 @@ +# nRF USBD driver with the ISO IN fast path, built out of tree in place of +# Zephyr's drivers/usb/udc/udc_nrf.c. Set CONFIG_UDC_NRF=n and this =y. + +config UDC_NRF_ISOFAST + bool "nRF USBD driver with ISO IN fast path (out-of-tree copy of udc_nrf.c)" + depends on DT_HAS_NORDIC_NRF_USBD_ENABLED + depends on !UDC_NRF + select NRF_USBD_COMMON + select NRFX_POWER + select EVENTS + help + The same driver as Zephyr's UDC_NRF plus udc_nrf_iso_in_fast_set(): + isochronous IN packets produced and DMA'd in the USBD interrupt at SOF, + with no thread wake-up per frame. See nrf-usbd-isofast/README.md. + +# Zephyr defines this only inside `if UDC_NRF`, which is off here. +config UDC_NRF_THREAD_STACK_SIZE + int "nRF UDC driver internal thread stack size" + default 512 + depends on UDC_NRF_ISOFAST diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/README.md b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/README.md new file mode 100644 index 0000000..fdd8a94 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/README.md @@ -0,0 +1,69 @@ +# nrf-usbd-isofast — an ISO IN fast path for Zephyr's nRF52840 USB driver + +A copy of Zephyr's `drivers/usb/udc/udc_nrf.c` plus one patch of about 100 lines. +**Optional:** stock Zephyr sends USB audio fine. Use this only if you need the +CPU back. + +## What it changes + +- An opt-in call, `udc_nrf_iso_in_fast_set(fill, ctx, suppress_sof)` + ([`src/udc_nrf_iso_in_fast.h`](src/udc_nrf_iso_in_fast.h)). +- At each start-of-frame, while the ISO IN endpoint is enabled, the driver's + interrupt calls `fill` for the next packet and starts its DMA in the same + interrupt, through the driver's existing DMA scheduler. +- No net_buf, no event, no thread wake-up for ISO IN. Optionally no SOF event to + the stack either, when no class needs one. +- Unchanged: enumeration, descriptors, alternate settings, every other endpoint, + and the driver's behaviour when no callback is registered. + +## Measured on an SP-1 (64 MHz Cortex-M4, 48 kHz 16-bit stereo, macOS) + +| | Zephyr's driver | With the fast path | +|---|---|---| +| USB threads' share of the CPU, stream open | usbd 11% + udc_nrfx 7% | 0 + 0 | +| Six synth voices + stream, repeated chords | resets | no reset | +| Stream integrity | clean until overload | clean | + +## When stock is better + +The full comparison, with measurements and the trade-offs of each, is +[`../../docs/STOCK-OR-FAST-PATH.md`](../../docs/STOCK-OR-FAST-PATH.md). In short: + +1. There is no ISO IN audio. MIDI, CDC and HID gain nothing. +2. CPU is not scarce. +3. The packet cannot come cheaply and safely from an interrupt: `fill` runs at + USBD interrupt priority every 1 ms and must be short, lock-free, non-blocking. +4. Another class needs SOF (ISO OUT, a feedback endpoint): most of the gain is + suppressing the per-frame SOF wake-up. +5. You are on a different Zephyr. This is one file at one base; see below. + +It does **not** lower latency. + +## Base, and why it matters + +- Forked from nRF Connect SDK's Zephyr (`sdk-zephyr`) at `fd9204a0` + (NCS v3.3.0, Zephyr 4.3.99). The unmodified file is + [`patches/udc_nrf.c.upstream`](patches/udc_nrf.c.upstream). +- [`tools/check.sh`](tools/check.sh) proves `src/udc_nrf.c` equals that file plus + [`patches/udc_nrf-iso-in-fast.patch`](patches/udc_nrf-iso-in-fast.patch). +- **Upstream Zephyr v4.3.1's copy differs by ~330 lines**, including how it + handles a DMA transfer still running at start-of-frame, which the fast path + depends on. The patch applies there cleanly, and that is misleading: on another + base it needs review and hardware testing, not just applying. + +## Using it + +1. `CONFIG_UDC_NRF=n`, `CONFIG_UDC_NRF_ISOFAST=y`, `CONFIG_UDC_ENABLE_SOF=y`. +2. `rsource` this directory's [`Kconfig`](Kconfig) from your app's Kconfig and + `include()` its [`CMakeLists.txt`](CMakeLists.txt) from your app's. +3. Register once, before enabling USB. Do not also enqueue on the ISO IN endpoint + through the UDC API. [`../../usb-audio/usb_audio.c`](../../usb-audio/usb_audio.c) + shows both paths. + +## Upstream + +The plan is to offer this to Zephyr as an opt-in, Kconfig-gated API. Merged +there, the copy here goes away: you build stock Zephyr and register the callback. +The open question for Zephyr's USB maintainers is whether they want an +nRF-specific call like this one, or a generic hook in the USB device controller +API that other chips could implement too. diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf-iso-in-fast.patch b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf-iso-in-fast.patch new file mode 100644 index 0000000..d1c1198 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf-iso-in-fast.patch @@ -0,0 +1,153 @@ +--- a/drivers/usb/udc/udc_nrf.c ++++ b/drivers/usb/udc/udc_nrf.c +@@ -19,6 +19,7 @@ + #include + #include + #include "udc_common.h" ++#include "udc_nrf_iso_in_fast.h" + + #include + LOG_MODULE_REGISTER(udc_nrf, CONFIG_UDC_DRIVER_LOG_LEVEL); +@@ -194,6 +195,23 @@ + /* Bounce buffer for sending data from FLASH */ + static uint32_t m_tx_buffer[NRFX_CEIL_DIV(NRF_USBD_COMMON_FEEDER_BUFFER_SIZE, sizeof(uint32_t))]; + ++/* ISO IN fast path (udc_nrf_iso_in_fast.h). When registered, ev_sof_handler() ++ * asks the application for the next ISO IN packet and usbd_dmareq_process() ++ * DMAs it from iso_fast_buf at the end of the same interrupt, so no thread is ++ * woken per frame. Two buffers: a DMA may still be running across SOF (see ++ * ev_sof_handler), and the next packet must not be written under it. ++ */ ++static udc_nrf_iso_in_fill_t iso_fast_fill; ++static void *iso_fast_user_data; ++static bool iso_fast_suppress_sof; ++static uint32_t iso_fast_buf[2][UDC_NRF_ISO_IN_FAST_MAX / sizeof(uint32_t)]; ++static uint8_t iso_fast_next; ++static uint8_t *iso_fast_ptr; ++static uint16_t iso_fast_len; ++/* True from DMA start until DMA end of a fast-path packet. */ ++static bool iso_fast_dma; ++static struct udc_nrf_iso_in_fast_stats iso_fast_stats; ++ + /* Early declaration. Documentation above definition. */ + static void usbd_dmareq_process(void); + static inline void usbd_int_rise(void); +@@ -408,7 +426,10 @@ + m_dma_odd ^= usbd_ep_amount_get(ep) & 1; + usbd_dma_pending_clear(); + +- if ((m_ep_dma_waiting & BIT(ep2bit(ep))) == 0) { ++ if (ep == NRF_USBD_COMMON_EPIN8 && iso_fast_dma) { ++ /* ISO IN fast path: no net_buf to complete, and no thread to wake */ ++ iso_fast_dma = false; ++ } else if ((m_ep_dma_waiting & BIT(ep2bit(ep))) == 0) { + if (NRF_USBD_COMMON_EP_IS_OUT(ep) || (ep == NRF_USBD_COMMON_EPIN8)) { + /* Send event to the user - for an ISO IN or any OUT endpoint, + * the whole transfer is finished in this moment +@@ -436,6 +457,44 @@ + dma_ep = NRF_USBD_COMMON_EPIN1; + + k_sem_give(&dma_available); ++} ++ ++/* ISO IN fast path at SOF: take this frame's packet from the application and ++ * request its DMA, which usbd_dmareq_process() starts at the end of this same ++ * interrupt. Returns true if the fast path is active. ++ */ ++static bool iso_fast_sof(void) ++{ ++ const udc_nrf_iso_in_fill_t fill = iso_fast_fill; ++ const uint32_t bit = BIT(ep2bit(NRF_USBD_COMMON_EPIN8)); ++ uint8_t *buf; ++ uint16_t len; ++ ++ if (fill == NULL || !(NRF_USBD->EPINEN & BIT(NRF_USBD_COMMON_EP_NUM(NRF_USBD_COMMON_EPIN8)))) { ++ return false; ++ } ++ ++ if (m_ep_dma_waiting & bit) { ++ /* Last frame's packet never got the DMA (another endpoint held it ++ * across the whole frame): it is stale, send this frame's instead. ++ */ ++ iso_fast_stats.replaced++; ++ } ++ ++ buf = (uint8_t *)iso_fast_buf[iso_fast_next]; ++ len = fill(buf, UDC_NRF_ISO_IN_FAST_MAX, iso_fast_user_data); ++ if (len == 0) { ++ m_ep_dma_waiting &= ~bit; ++ iso_fast_stats.empty++; ++ return true; ++ } ++ ++ iso_fast_ptr = buf; ++ iso_fast_len = MIN(len, UDC_NRF_ISO_IN_FAST_MAX); ++ iso_fast_next ^= 1; ++ m_ep_dma_waiting |= bit; ++ ++ return true; + } + + static void ev_sof_handler(void) +@@ -460,6 +519,10 @@ + + m_ep_armed &= ~USBD_EPISO_BIT_MASK; + ++ if (iso_fast_sof() && iso_fast_suppress_sof) { ++ return; ++ } ++ + udc_submit_sof_event(udc_nrf_dev); + } + +@@ -611,6 +674,18 @@ + } + + nrf_usbd_common_ep_t ep = bit2ep(pos); ++ ++ if (ep == NRF_USBD_COMMON_EPIN8 && iso_fast_fill != NULL) { ++ /* ISO IN fast path: the packet is in iso_fast_buf, not a net_buf */ ++ m_ep_dma_waiting &= ~BIT(pos); ++ usbd_dma_pending_set(); ++ m_ep_ready &= ~BIT(pos); ++ iso_fast_dma = true; ++ iso_fast_stats.packets++; ++ dma_ep = ep; ++ usbd_ep_dma_start(ep, (uint32_t)iso_fast_ptr, iso_fast_len); ++ return; ++ } + + ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); + buf = udc_buf_peek(ep_cfg); +@@ -1547,6 +1622,31 @@ + } + } + ++void udc_nrf_iso_in_fast_set(udc_nrf_iso_in_fill_t fill, void *user_data, bool suppress_sof) ++{ ++ unsigned int key = irq_lock(); ++ ++ iso_fast_user_data = user_data; ++ iso_fast_suppress_sof = suppress_sof; ++ iso_fast_fill = fill; ++ if (fill == NULL) { ++ /* A packet requested but not yet DMA'd is dropped; one in flight ++ * completes normally (iso_fast_dma). ++ */ ++ m_ep_dma_waiting &= ~BIT(ep2bit(NRF_USBD_COMMON_EPIN8)); ++ } ++ ++ irq_unlock(key); ++} ++ ++void udc_nrf_iso_in_fast_stats_get(struct udc_nrf_iso_in_fast_stats *stats) ++{ ++ unsigned int key = irq_lock(); ++ ++ *stats = iso_fast_stats; ++ irq_unlock(key); ++} ++ + static int udc_nrf_ep_enqueue(const struct device *dev, + struct udc_ep_config *cfg, + struct net_buf *buf) diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf.c.upstream b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf.c.upstream new file mode 100644 index 0000000..da0e527 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/udc_nrf.c.upstream @@ -0,0 +1,1903 @@ +/* + * Copyright (c) 2021 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#include +#include +#include + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include "udc_common.h" + +#include +LOG_MODULE_REGISTER(udc_nrf, CONFIG_UDC_DRIVER_LOG_LEVEL); + +/* + * There is no real advantage to change control endpoint size + * but we can use it for testing UDC driver API and higher layers. + */ +#define UDC_NRF_MPS0 UDC_MPS0_64 +#define UDC_NRF_EP0_SIZE 64 + +enum udc_nrf_event_type { + /* Trigger next transfer (buffer enqueued) */ + UDC_NRF_EVT_XFER, + /* Transfer finished */ + UDC_NRF_EVT_EP_FINISHED, + /* SETUP data received */ + UDC_NRF_EVT_SETUP, + /* USB bus suspended */ + UDC_NRF_EVT_SUSPEND, + /* USB bus resumed */ + UDC_NRF_EVT_RESUME, + /* Remote Wakeup initiated */ + UDC_NRF_EVT_WUREQ, + /* Endpoint dequeue requested */ + UDC_NRF_EVT_DEQUEUE, +}; + +/* Main events the driver thread waits for */ +static K_EVENT_DEFINE(drv_evt); +/* Transfer triggers */ +static atomic_t xfer_new; +/* Finished transactions */ +static atomic_t xfer_finished; + +static K_KERNEL_STACK_DEFINE(drv_stack, CONFIG_UDC_NRF_THREAD_STACK_SIZE); +static struct k_thread drv_stack_data; + +/* USB device controller access from devicetree */ +#define DT_DRV_COMPAT nordic_nrf_usbd + +#define CFG_EPIN_CNT DT_INST_PROP(0, num_in_endpoints) +#define CFG_EPOUT_CNT DT_INST_PROP(0, num_out_endpoints) +#define CFG_EP_ISOIN_CNT DT_INST_PROP(0, num_isoin_endpoints) +#define CFG_EP_ISOOUT_CNT DT_INST_PROP(0, num_isoout_endpoints) + +static struct udc_ep_config ep_cfg_out[CFG_EPOUT_CNT + CFG_EP_ISOOUT_CNT + 1]; +static struct udc_ep_config ep_cfg_in[CFG_EPIN_CNT + CFG_EP_ISOIN_CNT + 1]; +static bool udc_nrf_ctrl_data_in_finished; +static bool udc_nrf_setup_set_addr, udc_nrf_fake_setup; +static uint8_t udc_nrf_address; +const static struct device *udc_nrf_dev; + +#define NRF_USBD_COMMON_EPIN_CNT 9 +#define NRF_USBD_COMMON_EPOUT_CNT 9 +#define NRF_USBD_COMMON_EP_NUM(ep) (ep & 0xF) +#define NRF_USBD_COMMON_EP_IS_IN(ep) ((ep & 0x80) == 0x80) +#define NRF_USBD_COMMON_EP_IS_OUT(ep) ((ep & 0x80) == 0) +#define NRF_USBD_COMMON_EP_IS_ISO(ep) ((ep & 0xF) >= 8) + +#ifndef NRF_USBD_COMMON_ISO_DEBUG +/* Also generate information about ISOCHRONOUS events and transfers. + * Turn this off if no ISOCHRONOUS transfers are going to be debugged and this + * option generates a lot of useless messages. + */ +#define NRF_USBD_COMMON_ISO_DEBUG 1 +#endif + +#ifndef NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 +/* Anomaly 211 - Device remains in SUSPEND too long when host resumes + * a bus activity (sending SOF packets) without a RESUME condition. + */ +#define NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 0 +#endif + +/* Assert endpoint is valid */ +#define NRF_USBD_COMMON_ASSERT_EP_VALID(ep) __ASSERT_NO_MSG( \ + ((NRF_USBD_COMMON_EP_IS_IN(ep) && \ + (NRF_USBD_COMMON_EP_NUM(ep) < NRF_USBD_COMMON_EPIN_CNT)) || \ + (NRF_USBD_COMMON_EP_IS_OUT(ep) && \ + (NRF_USBD_COMMON_EP_NUM(ep) < NRF_USBD_COMMON_EPOUT_CNT)))); + +/* Lowest IN endpoint bit position */ +#define NRF_USBD_COMMON_EPIN_BITPOS_0 0 + +/* Lowest OUT endpoint bit position */ +#define NRF_USBD_COMMON_EPOUT_BITPOS_0 16 + +/* Input endpoint bits mask */ +#define NRF_USBD_COMMON_EPIN_BIT_MASK (0xFFFFU << NRF_USBD_COMMON_EPIN_BITPOS_0) + +/* Output endpoint bits mask */ +#define NRF_USBD_COMMON_EPOUT_BIT_MASK (0xFFFFU << NRF_USBD_COMMON_EPOUT_BITPOS_0) + +/* Isochronous endpoint bit mask */ +#define USBD_EPISO_BIT_MASK \ + ((1U << NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT8)) | \ + (1U << NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN8))) + +/* Convert endpoint number to bit position */ +#define NRF_USBD_COMMON_EP_BITPOS(ep) ((NRF_USBD_COMMON_EP_IS_IN(ep) \ + ? NRF_USBD_COMMON_EPIN_BITPOS_0 : NRF_USBD_COMMON_EPOUT_BITPOS_0) \ + + NRF_USBD_COMMON_EP_NUM(ep)) + +/* Check it the bit positions values match defined DATAEPSTATUS bit positions */ +BUILD_ASSERT( + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN1) == USBD_EPDATASTATUS_EPIN1_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN2) == USBD_EPDATASTATUS_EPIN2_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN3) == USBD_EPDATASTATUS_EPIN3_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN4) == USBD_EPDATASTATUS_EPIN4_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN5) == USBD_EPDATASTATUS_EPIN5_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN6) == USBD_EPDATASTATUS_EPIN6_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN7) == USBD_EPDATASTATUS_EPIN7_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT1) == USBD_EPDATASTATUS_EPOUT1_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT2) == USBD_EPDATASTATUS_EPOUT2_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT3) == USBD_EPDATASTATUS_EPOUT3_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT4) == USBD_EPDATASTATUS_EPOUT4_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT5) == USBD_EPDATASTATUS_EPOUT5_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT6) == USBD_EPDATASTATUS_EPOUT6_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT7) == USBD_EPDATASTATUS_EPOUT7_Pos), + "NRF_USBD_COMMON bit positions do not match hardware" +); + +/* True if USB bus is suspended, updated in interrupt handler */ +static volatile bool m_bus_suspend; + +/* Data Stage direction used to map EP0DATADONE to actual endpoint */ +static uint8_t m_ep0_data_dir; + +/* Set bit indicates that endpoint is ready for DMA transfer. + * + * OUT endpoint is ready when DATA packet has been ACKed by device. + * IN endpoint is ready when IN endpoint buffer has no pending data. + * + * When endpoint is ready it responds with NAK to any further traffic. + */ +static uint32_t m_ep_ready; + +/* Set bit indicates that endpoint is waiting for DMA transfer, i.e. there is + * USB stack buffer queued for the transfer. + */ +static uint32_t m_ep_dma_waiting; + +/* Set bit indicates that endpoint is armed. + * + * OUT endpoint armed means that valid DATA packet from host will be ACKed. + * IN endpoint armed means that device will respond with DATA packet. + */ +static uint32_t m_ep_armed; + +/* Set bit indicates that endpoint is requested to be dequeued. */ +static uint32_t m_ep_dequeue; + +static K_CONDVAR_DEFINE(ep_dequeued); + +/* Semaphore to guard EasyDMA access. + * In USBD there is only one DMA channel working in background, and new transfer + * cannot be started when there is ongoing transfer on any other channel. + */ +static K_SEM_DEFINE(dma_available, 1, 1); + +/* Endpoint on which DMA was started. */ +static nrf_usbd_common_ep_t dma_ep; + +/* Tracks whether total bytes transferred by DMA is even or odd. */ +static uint8_t m_dma_odd; + +/* First time enabling after reset. Used in nRF52 errata 223. */ +static bool m_first_enable = true; + +#define NRF_USBD_COMMON_FEEDER_BUFFER_SIZE NRF_USBD_COMMON_EPSIZE + +/* Bounce buffer for sending data from FLASH */ +static uint32_t m_tx_buffer[NRFX_CEIL_DIV(NRF_USBD_COMMON_FEEDER_BUFFER_SIZE, sizeof(uint32_t))]; + +/* Early declaration. Documentation above definition. */ +static void usbd_dmareq_process(void); +static inline void usbd_int_rise(void); +static void nrf_usbd_common_stop(void); +static void nrf_usbd_legacy_transfer_out_drop(nrf_usbd_common_ep_t ep); +static size_t nrf_usbd_legacy_epout_size_get(nrf_usbd_common_ep_t ep); +static bool nrf_usbd_legacy_suspend_check(void); + +/* Get EasyDMA end event address for given endpoint */ +static volatile uint32_t *usbd_ep_to_endevent(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return &NRF_USBD->EVENTS_ENDEPIN[ep_num]; + } else { + return &NRF_USBD->EVENTS_ENDEPOUT[ep_num]; + } + } + + return ep_in ? &NRF_USBD->EVENTS_ENDISOIN : &NRF_USBD->EVENTS_ENDISOOUT; +} + +/* Return number of bytes last transferred by EasyDMA on given endpoint */ +static uint32_t usbd_ep_amount_get(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return NRF_USBD->EPIN[ep_num].AMOUNT; + } else { + return NRF_USBD->EPOUT[ep_num].AMOUNT; + } + } + + return ep_in ? NRF_USBD->ISOIN.AMOUNT : NRF_USBD->ISOOUT.AMOUNT; +} + +/* Start EasyDMA on given endpoint */ +static void usbd_ep_dma_start(nrf_usbd_common_ep_t ep, uint32_t addr, size_t len) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + NRF_USBD->EPIN[ep_num].PTR = addr; + NRF_USBD->EPIN[ep_num].MAXCNT = len; + NRF_USBD->TASKS_STARTEPIN[ep_num] = 1; + } else { + NRF_USBD->EPOUT[ep_num].PTR = addr; + NRF_USBD->EPOUT[ep_num].MAXCNT = len; + NRF_USBD->TASKS_STARTEPOUT[ep_num] = 1; + } + } else if (ep_in) { + NRF_USBD->ISOIN.PTR = addr; + NRF_USBD->ISOIN.MAXCNT = len; + NRF_USBD->TASKS_STARTISOIN = 1; + } else { + NRF_USBD->ISOOUT.PTR = addr; + NRF_USBD->ISOOUT.MAXCNT = len; + NRF_USBD->TASKS_STARTISOOUT = 1; + } +} + +/* Convert endpoint number to bit position matching EPDATASTATUS register. + * Control and isochronous endpoints occupy unused EPDATASTATUS bits. + */ +static inline uint8_t ep2bit(nrf_usbd_common_ep_t ep) +{ + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + return NRF_USBD_COMMON_EP_BITPOS(ep); +} + +static inline nrf_usbd_common_ep_t bit2ep(uint8_t bitpos) +{ + BUILD_ASSERT(NRF_USBD_COMMON_EPOUT_BITPOS_0 > NRF_USBD_COMMON_EPIN_BITPOS_0, + "OUT endpoint bits should be higher than IN endpoint bits"); + return (nrf_usbd_common_ep_t)((bitpos >= NRF_USBD_COMMON_EPOUT_BITPOS_0) + ? NRF_USBD_COMMON_EPOUT(bitpos - NRF_USBD_COMMON_EPOUT_BITPOS_0) + : NRF_USBD_COMMON_EPIN(bitpos)); +} + +/* Prepare DMA for transfer */ +static inline void usbd_dma_pending_set(void) +{ + if (nrf_usbd_common_errata_199()) { + *((volatile uint32_t *)0x40027C1C) = 0x00000082; + } +} + +/* DMA transfer finished */ +static inline void usbd_dma_pending_clear(void) +{ + if (nrf_usbd_common_errata_199()) { + *((volatile uint32_t *)0x40027C1C) = 0x00000000; + } +} + +static void disarm_endpoint(uint8_t ep) +{ + if (ep == USB_CONTROL_EP_OUT || ep == USB_CONTROL_EP_IN) { + /* EP0 cannot be disarmed. This is not a problem because SETUP + * token automatically disarms EP0 IN and EP0 OUT. + */ + return; + } + + if (NRF_USBD_COMMON_EP_IS_ISO(ep)) { + /* Isochronous endpoints cannot be disarmed */ + return; + } + + if (!(m_ep_armed & BIT(ep2bit(ep)))) { + /* Endpoint is not armed, nothing to do */ + return; + } + + m_ep_armed &= ~BIT(ep2bit(ep)); + + /* Disarm the endpoint if there is any data buffered. For OUT endpoints + * disarming means that the endpoint won't ACK (will NAK) DATA packet. + */ + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x800)) = 0x7B6 + + 2 * (USB_EP_GET_IDX(ep) - 1) + USB_EP_DIR_IS_OUT(ep) * 0x10; + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x804)) |= BIT(1); +} + +static inline void usbd_ep_abort(nrf_usbd_common_ep_t ep) +{ + unsigned int irq_lock_key = irq_lock(); + + disarm_endpoint(ep); + + /* Do not process any data until endpoint is enqueued again */ + m_ep_dma_waiting &= ~BIT(ep2bit(ep)); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep)) { + if (NRF_USBD_COMMON_EP_IS_OUT(ep)) { + m_ep_ready &= ~BIT(ep2bit(ep)); + } else { + m_ep_ready |= BIT(ep2bit(ep)); + } + } + + /* Disarming endpoint is inherently a race between the driver and host. + * Clear EPDATASTATUS to prevent interrupt handler from processing the + * data if disarming lost the race (i.e. host finished first). + */ + NRF_USBD->EPDATASTATUS = BIT(ep2bit(ep)); + + irq_unlock(irq_lock_key); +} + +static void nrf_usbd_legacy_ep_abort(nrf_usbd_common_ep_t ep) +{ + /* Only abort if there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + usbd_ep_abort(ep); + k_sem_give(&dma_available); + + /* This function was holding DMA semaphore and could potentially prevent + * next DMA from executing. Fire IRQ handler to check if any DMA needs + * to be started. + */ + usbd_int_rise(); +} + +static void usbd_ep_abort_all(void) +{ + uint32_t ep_waiting = m_ep_dma_waiting | (m_ep_ready & NRF_USBD_COMMON_EPOUT_BIT_MASK); + + while (ep_waiting != 0) { + uint8_t bitpos = NRF_CTZ(ep_waiting); + + if (!NRF_USBD_COMMON_EP_IS_ISO(bit2ep(bitpos))) { + usbd_ep_abort(bit2ep(bitpos)); + } + ep_waiting &= ~(1U << bitpos); + } + + m_ep_ready = (((1U << NRF_USBD_COMMON_EPIN_CNT) - 1U) << NRF_USBD_COMMON_EPIN_BITPOS_0); +} + +/* Rise USBD interrupt to trigger interrupt handler */ +static inline void usbd_int_rise(void) +{ + NVIC_SetPendingIRQ(USBD_IRQn); +} + +static void ev_usbreset_handler(void) +{ + m_bus_suspend = false; + + LOG_INF("Reset"); + udc_submit_event(udc_nrf_dev, UDC_EVT_RESET, 0); +} + +static void nrf_usbd_dma_finished(nrf_usbd_common_ep_t ep) +{ + /* DMA finished, track if total bytes transferred is even or odd */ + m_dma_odd ^= usbd_ep_amount_get(ep) & 1; + usbd_dma_pending_clear(); + + if ((m_ep_dma_waiting & BIT(ep2bit(ep))) == 0) { + if (NRF_USBD_COMMON_EP_IS_OUT(ep) || (ep == NRF_USBD_COMMON_EPIN8)) { + /* Send event to the user - for an ISO IN or any OUT endpoint, + * the whole transfer is finished in this moment + */ + atomic_set_bit(&xfer_finished, ep2bit(ep)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_EP_FINISHED)); + } + } else if (ep == NRF_USBD_COMMON_EPOUT0) { + /* Allow receiving next OUT Data Stage chunk */ + NRF_USBD->TASKS_EP0RCVOUT = 1; + } + + if (NRF_USBD_COMMON_EP_IS_IN(ep) || + (ep >= NRF_USBD_COMMON_EPOUT1 && ep <= NRF_USBD_COMMON_EPOUT7)) { + m_ep_armed |= BIT(ep2bit(ep)); + } + + /* Set default dma_ep value that has no special meaning, so we do not + * need to have separate dma_ep_valid flag (in the hot interrupt path). + * This is necessary to avoid false positives in ev_sof_handler() and + * on EVENTS_EP0SETUP check when dma_available is held in thread context + * (e.g. when thread wants to call usbd_ep_abort()), i.e. when thread + * prevents DMA operation. + */ + dma_ep = NRF_USBD_COMMON_EPIN1; + + k_sem_give(&dma_available); +} + +static void ev_sof_handler(void) +{ + /* Process isochronous endpoints */ + uint32_t iso_ready_mask = (1U << ep2bit(NRF_USBD_COMMON_EPIN8)); + + /* SIZE.ISOOUT is 0 only when no packet was received at all */ + if (NRF_USBD->SIZE.ISOOUT) { + iso_ready_mask |= (1U << ep2bit(NRF_USBD_COMMON_EPOUT8)); + } + + if (k_sem_count_get(&dma_available) == 0) { + /* DMA may have been active across SOF which means that endpoint + * data may be corrupted (if DMA was to isochronous endpoint). + * Do not mark the endpoint as ready if this is the case. + */ + iso_ready_mask &= ~BIT(ep2bit(dma_ep)); + } + + m_ep_ready |= iso_ready_mask; + + m_ep_armed &= ~USBD_EPISO_BIT_MASK; + + udc_submit_sof_event(udc_nrf_dev); +} + +static void usbd_in_packet_sent(uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); + struct net_buf *buf = udc_buf_peek(ep_cfg); + + net_buf_pull(buf, usbd_ep_amount_get(ep)); + + if (buf->len) { + /* More packets will be sent, nothing to do here */ + } else if (udc_ep_buf_has_zlp(buf)) { + /* Actual payload sent, only ZLP left */ + udc_ep_buf_clear_zlp(buf); + } else { + LOG_DBG("USBD event: EndpointData: In finished"); + /* No more data to be send - transmission finished */ + atomic_set_bit(&xfer_finished, ep2bit(ep)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_EP_FINISHED)); + } +} + +static void ev_setup_handler(void) +{ + LOG_DBG("USBD event: Setup (rt:%.2x r:%.2x v:%.4x i:%.4x l:%u )", + NRF_USBD->BMREQUESTTYPE, NRF_USBD->BREQUEST, + NRF_USBD->WVALUEL | (NRF_USBD->WVALUEH << 8), + NRF_USBD->WINDEXL | (NRF_USBD->WINDEXH << 8), + NRF_USBD->WLENGTHL | (NRF_USBD->WLENGTHH << 8)); + + m_ep_dma_waiting &= ~((1U << ep2bit(NRF_USBD_COMMON_EPOUT0)) | + (1U << ep2bit(NRF_USBD_COMMON_EPIN0))); + m_ep_ready &= ~(1U << ep2bit(NRF_USBD_COMMON_EPOUT0)); + m_ep_ready |= 1U << ep2bit(NRF_USBD_COMMON_EPIN0); + + m_ep_armed &= ~(BIT(ep2bit(USB_CONTROL_EP_OUT)) | + BIT(ep2bit(USB_CONTROL_EP_IN))); + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SETUP)); +} + +static void ev_usbevent_handler(void) +{ + uint32_t event = NRF_USBD->EVENTCAUSE; + + /* Clear handled events */ + NRF_USBD->EVENTCAUSE = event; + + if (event & USBD_EVENTCAUSE_ISOOUTCRC_Msk) { + LOG_DBG("USBD event: ISOOUTCRC"); + /* Currently no support */ + } + if (event & USBD_EVENTCAUSE_SUSPEND_Msk) { + LOG_DBG("USBD event: SUSPEND"); + m_bus_suspend = true; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SUSPEND)); + } + if (event & USBD_EVENTCAUSE_RESUME_Msk) { + LOG_DBG("USBD event: RESUME"); + m_bus_suspend = false; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_RESUME)); + } + if (event & USBD_EVENTCAUSE_USBWUALLOWED_Msk) { + LOG_DBG("USBD event: WUREQ (%s)", m_bus_suspend ? "In Suspend" : "Active"); + if (m_bus_suspend) { + __ASSERT_NO_MSG(!nrf_usbd_legacy_suspend_check()); + m_bus_suspend = false; + + NRF_USBD->DPDMVALUE = USBD_DPDMVALUE_STATE_Resume + << USBD_DPDMVALUE_STATE_Pos; + NRF_USBD->TASKS_DPDMDRIVE = 1; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_WUREQ)); + } + } +} + +static void ev_epdata_handler(uint32_t dataepstatus) +{ + if (dataepstatus) { + LOG_DBG("USBD event: EndpointEPStatus: %x", dataepstatus); + + /* Mark endpoints ready for next DMA access */ + m_ep_ready |= dataepstatus & ~USBD_EPISO_BIT_MASK; + + /* IN endpoints are no longer armed after host read the data. + * OUT endpoints are no longer armed before DMA reads the data. + */ + m_ep_armed &= ~(dataepstatus & ~USBD_EPISO_BIT_MASK); + + /* Peripheral automatically enables endpoint for data reception + * after OUT endpoint DMA transfer. This makes the device ACK + * the OUT DATA even if the stack did not enqueue any buffer. + * + * This behaviour most likely cannot be avoided and therefore + * there's nothing more to do for OUT endpoints. + */ + dataepstatus &= NRF_USBD_COMMON_EPIN_BIT_MASK; + } + + /* Prepare next packet on IN endpoints */ + while (dataepstatus) { + uint8_t bitpos = NRF_CTZ(dataepstatus); + + dataepstatus &= ~BIT(bitpos); + + usbd_in_packet_sent(bit2ep(bitpos)); + } +} + +/* Select endpoint for next DMA transfer. + * + * Passed value has at least one bit set. Each bit set indicates which endpoints + * can have data transferred between peripheral and USB stack buffer. + * + * Return bit position indicating which endpoint to transfer. + */ +static uint8_t usbd_dma_scheduler_algorithm(uint32_t req) +{ + /* Only prioritized scheduling mode is supported. */ + return NRF_CTZ(req); +} + +/* Process next DMA request, called at the end of interrupt handler */ +static void usbd_dmareq_process(void) +{ + uint32_t req = m_ep_dma_waiting & m_ep_ready; + struct net_buf *buf; + struct udc_ep_config *ep_cfg; + uint8_t *payload_buf; + size_t payload_len; + bool last_packet; + uint8_t pos; + + if (req == 0 || nrf_usbd_legacy_suspend_check() || + k_sem_take(&dma_available, K_NO_WAIT) != 0) { + /* DMA cannot be started */ + return; + } + + if (NRFX_USBD_CONFIG_DMASCHEDULER_ISO_BOOST && + ((req & USBD_EPISO_BIT_MASK) != 0)) { + pos = usbd_dma_scheduler_algorithm(req & USBD_EPISO_BIT_MASK); + } else { + pos = usbd_dma_scheduler_algorithm(req); + } + + nrf_usbd_common_ep_t ep = bit2ep(pos); + + ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); + buf = udc_buf_peek(ep_cfg); + + __ASSERT_NO_MSG(buf); + + if (NRF_USBD_COMMON_EP_IS_IN(ep)) { + /* Device -> Host */ + payload_buf = buf->data; + + if (buf->len > udc_mps_ep_size(ep_cfg)) { + payload_len = udc_mps_ep_size(ep_cfg); + last_packet = false; + } else { + payload_len = buf->len; + last_packet = !udc_ep_buf_has_zlp(buf); + } + + if (!nrfx_is_in_ram(payload_buf)) { + __ASSERT_NO_MSG(payload_len <= NRF_USBD_COMMON_FEEDER_BUFFER_SIZE); + memcpy(m_tx_buffer, payload_buf, payload_len); + payload_buf = (uint8_t *)m_tx_buffer; + } + } else { + /* Host -> Device */ + const size_t received = nrf_usbd_legacy_epout_size_get(ep); + + payload_buf = net_buf_tail(buf); + payload_len = net_buf_tailroom(buf); + + __ASSERT_NO_MSG(nrfx_is_in_ram(payload_buf)); + + if (received > payload_len) { + LOG_ERR("buffer too small: r: %u, l: %u", received, payload_len); + } else { + payload_len = received; + } + + /* DMA will copy the received data, update the buffer here so received + * does not have to be stored (can be done because there is no cache). + */ + net_buf_add(buf, payload_len); + + last_packet = (udc_mps_ep_size(ep_cfg) != received) || + (net_buf_tailroom(buf) == 0); + } + + if (last_packet) { + m_ep_dma_waiting &= ~BIT(pos); + } + + usbd_dma_pending_set(); + m_ep_ready &= ~BIT(pos); + if (NRF_USBD_COMMON_ISO_DEBUG || (!NRF_USBD_COMMON_EP_IS_ISO(ep))) { + LOG_DBG("USB DMA process: Starting transfer on EP: %x, size: %u", + ep, payload_len); + } + + /* Start transfer to the endpoint buffer */ + dma_ep = ep; + usbd_ep_dma_start(ep, (uint32_t)payload_buf, payload_len); +} + +static inline void usbd_errata_171_begin(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_171_end(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x00000000; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x00000000; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_187_211_begin(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006ED14)) = 0x00000003; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006ED14)) = 0x00000003; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_187_211_end(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006ED14)) = 0x00000000; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006ED14)) = 0x00000000; + } + + irq_unlock(irq_lock_key); +} + +static void nrf_usbd_peripheral_enable(void) +{ + if (nrf_usbd_common_errata_187()) { + usbd_errata_187_211_begin(); + } + + if (nrf_usbd_common_errata_171()) { + usbd_errata_171_begin(); + } + + /* Enable the peripheral */ + NRF_USBD->ENABLE = 1; + + /* Waiting for peripheral to enable, this should take a few us */ + while ((NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_READY_Msk) == 0) { + } + NRF_USBD->EVENTCAUSE = USBD_EVENTCAUSE_READY_Msk; + + if (nrf_usbd_common_errata_171()) { + usbd_errata_171_end(); + } + + if (nrf_usbd_common_errata_187()) { + usbd_errata_187_211_end(); + } +} + +static void nrf_usbd_irq_handler(void) +{ + volatile uint32_t *dma_endevent; + uint32_t epdatastatus = 0; + + /* Always check and clear SOF but call handler only if SOF interrupt + * is actually enabled. + */ + if (NRF_USBD->EVENTS_SOF) { + NRF_USBD->EVENTS_SOF = 0; + if (NRF_USBD->INTENSET & USBD_INTEN_SOF_Msk) { + ev_sof_handler(); + } + } + + /* Clear EPDATA event and only then get and clear EPDATASTATUS to make + * sure we don't miss any event. + */ + if (NRF_USBD->EVENTS_EPDATA) { + NRF_USBD->EVENTS_EPDATA = 0; + epdatastatus = NRF_USBD->EPDATASTATUS; + NRF_USBD->EPDATASTATUS = epdatastatus; + } + + /* Use common variable to store EP0DATADONE processing needed flag */ + if (NRF_USBD->EVENTS_EP0DATADONE) { + NRF_USBD->EVENTS_EP0DATADONE = 0; + epdatastatus |= BIT(ep2bit(m_ep0_data_dir)); + } + + /* Check DMA end event only for last enabled DMA channel. Other channels + * cannot be active and there's no harm in rechecking the event multiple + * times (it is not a problem to check it even if DMA is not active). + * + * It is important to check DMA and handle DMA finished event before + * handling acknowledged data transfer bits (epdatastatus) to avoid + * a race condition between interrupt handler and host IN token. + */ + dma_endevent = usbd_ep_to_endevent(dma_ep); + if (*dma_endevent) { + *dma_endevent = 0; + nrf_usbd_dma_finished(dma_ep); + } + + /* Process acknowledged transfers so we can prepare next DMA (if any) */ + ev_epdata_handler(epdatastatus); + + if (NRF_USBD->EVENTS_USBRESET) { + NRF_USBD->EVENTS_USBRESET = 0; + ev_usbreset_handler(); + } + + if (NRF_USBD->EVENTS_USBEVENT) { + NRF_USBD->EVENTS_USBEVENT = 0; + ev_usbevent_handler(); + } + + /* Handle SETUP only if there is no active DMA on EP0 */ + if (unlikely(NRF_USBD->EVENTS_EP0SETUP) && + (k_sem_count_get(&dma_available) || + (dma_ep != NRF_USBD_COMMON_EPIN0 && dma_ep != NRF_USBD_COMMON_EPOUT0))) { + NRF_USBD->EVENTS_EP0SETUP = 0; + ev_setup_handler(); + } + + usbd_dmareq_process(); +} + +static void nrf_usbd_legacy_enable(void) +{ + /* Prepare for READY event receiving */ + NRF_USBD->EVENTCAUSE = USBD_EVENTCAUSE_READY_Msk; + + nrf_usbd_peripheral_enable(); + + if (nrf_usbd_common_errata_223() && m_first_enable) { + NRF_USBD->ENABLE = 0; + + nrf_usbd_peripheral_enable(); + + m_first_enable = false; + } + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_187() || nrf_usbd_common_errata_211()) { +#else + if (nrf_usbd_common_errata_187()) { +#endif + usbd_errata_187_211_begin(); + } + + if (nrf_usbd_common_errata_166()) { + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x800)) = 0x7E3; + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x804)) = 0x40; + __ISB(); + __DSB(); + } + + NRF_USBD->ISOSPLIT = USBD_ISOSPLIT_SPLIT_HalfIN << USBD_ISOSPLIT_SPLIT_Pos; + + if (IS_ENABLED(CONFIG_NRF_USBD_ISO_IN_ZLP)) { + NRF_USBD->ISOINCONFIG = USBD_ISOINCONFIG_RESPONSE_ZeroData + << USBD_ISOINCONFIG_RESPONSE_Pos; + } else { + NRF_USBD->ISOINCONFIG = USBD_ISOINCONFIG_RESPONSE_NoResp + << USBD_ISOINCONFIG_RESPONSE_Pos; + } + + m_ep_ready = (((1U << NRF_USBD_COMMON_EPIN_CNT) - 1U) << NRF_USBD_COMMON_EPIN_BITPOS_0); + m_ep_dma_waiting = 0; + m_ep_armed = 0; + m_dma_odd = 0; + __ASSERT_NO_MSG(k_sem_count_get(&dma_available) == 1); + usbd_dma_pending_clear(); + m_ep0_data_dir = USB_CONTROL_EP_OUT; + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_187() && !nrf_usbd_common_errata_211()) { +#else + if (nrf_usbd_common_errata_187()) { +#endif + usbd_errata_187_211_end(); + } +} + +static void nrf_usbd_legacy_disable(void) +{ + /* Make sure DMA is not active */ + k_sem_take(&dma_available, K_FOREVER); + + /* Stop just in case */ + nrf_usbd_common_stop(); + + /* Disable all parts */ + if (m_dma_odd) { + /* Prevent invalid bus request after next USBD enable by ensuring + * that total number of bytes transferred by DMA is even. + */ + NRF_USBD->EVENTS_ENDEPIN[0] = 0; + usbd_ep_dma_start(NRF_USBD_COMMON_EPIN0, (uint32_t)&m_dma_odd, 1); + while (!NRF_USBD->EVENTS_ENDEPIN[0]) { + } + NRF_USBD->EVENTS_ENDEPIN[0] = 0; + m_dma_odd = 0; + } + NRF_USBD->ENABLE = 0; + usbd_dma_pending_clear(); + k_sem_give(&dma_available); + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_211()) { + usbd_errata_187_211_end(); + } +#endif +} + +static void nrf_usbd_legacy_start(bool enable_sof) +{ + m_bus_suspend = false; + + uint32_t int_mask = USBD_INTEN_USBRESET_Msk | USBD_INTEN_ENDEPIN0_Msk | + USBD_INTEN_ENDEPIN1_Msk | USBD_INTEN_ENDEPIN2_Msk | + USBD_INTEN_ENDEPIN3_Msk | USBD_INTEN_ENDEPIN4_Msk | + USBD_INTEN_ENDEPIN5_Msk | USBD_INTEN_ENDEPIN6_Msk | + USBD_INTEN_ENDEPIN7_Msk | USBD_INTEN_EP0DATADONE_Msk | + USBD_INTEN_ENDISOIN_Msk | USBD_INTEN_ENDEPOUT0_Msk | + USBD_INTEN_ENDEPOUT1_Msk | USBD_INTEN_ENDEPOUT2_Msk | + USBD_INTEN_ENDEPOUT3_Msk | USBD_INTEN_ENDEPOUT4_Msk | + USBD_INTEN_ENDEPOUT5_Msk | USBD_INTEN_ENDEPOUT6_Msk | + USBD_INTEN_ENDEPOUT7_Msk | USBD_INTEN_ENDISOOUT_Msk | + USBD_INTEN_USBEVENT_Msk | USBD_INTEN_EP0SETUP_Msk | + USBD_INTEN_EPDATA_Msk; + + if (enable_sof) { + int_mask |= USBD_INTEN_SOF_Msk; + } + + /* Enable all required interrupts */ + NRF_USBD->INTEN = int_mask; + + /* Enable interrupt globally */ + irq_enable(USBD_IRQn); + + /* Enable pullups */ + NRF_USBD->USBPULLUP = 1; +} + +static void nrf_usbd_common_stop(void) +{ + /* Clear interrupt */ + NVIC_ClearPendingIRQ(USBD_IRQn); + + if (irq_is_enabled(USBD_IRQn)) { + /* Abort transfers */ + usbd_ep_abort_all(); + + /* Disable pullups */ + NRF_USBD->USBPULLUP = 0; + + /* Disable interrupt globally */ + irq_disable(USBD_IRQn); + + /* Disable all interrupts */ + NRF_USBD->INTEN = 0; + } +} + +static bool nrf_usbd_legacy_suspend(void) +{ + bool suspended = false; + unsigned int irq_lock_key; + + /* DMA doesn't work in Low Power mode, ensure there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + irq_lock_key = irq_lock(); + + if (m_bus_suspend) { + if (!(NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_RESUME_Msk)) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_LowPower + << USBD_LOWPOWER_LOWPOWER_Pos; + (void)NRF_USBD->LOWPOWER; + if (NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_RESUME_Msk) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_ForceNormal + << USBD_LOWPOWER_LOWPOWER_Pos; + } else { + suspended = true; + } + } + } + + irq_unlock(irq_lock_key); + k_sem_give(&dma_available); + + return suspended; +} + +static bool nrf_usbd_legacy_wakeup_req(void) +{ + bool started = false; + unsigned int irq_lock_key = irq_lock(); + + if (m_bus_suspend && nrf_usbd_legacy_suspend_check()) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_ForceNormal + << USBD_LOWPOWER_LOWPOWER_Pos; + started = true; + + if (nrf_usbd_common_errata_171()) { + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + } + } + } + + irq_unlock(irq_lock_key); + + return started; +} + +static bool nrf_usbd_legacy_suspend_check(void) +{ + return NRF_USBD->LOWPOWER != + (USBD_LOWPOWER_LOWPOWER_ForceNormal << USBD_LOWPOWER_LOWPOWER_Pos); +} + +static bool nrf_usbd_legacy_ep_enable_check(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + return (ep_in ? NRF_USBD->EPINEN : NRF_USBD->EPOUTEN) & BIT(ep_num); +} + +static void nrf_usbd_legacy_ep_enable(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + if (nrf_usbd_legacy_ep_enable_check(ep)) { + return; + } + + if (ep_in) { + NRF_USBD->EPINEN |= BIT(ep_num); + } else { + NRF_USBD->EPOUTEN |= BIT(ep_num); + } +} + +static void nrf_usbd_legacy_ep_disable(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + /* Only disable endpoint if there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + usbd_ep_abort(ep); + if (ep_in) { + NRF_USBD->EPINEN &= ~BIT(ep_num); + } else { + NRF_USBD->EPOUTEN &= ~BIT(ep_num); + } + k_sem_give(&dma_available); + + /* This function was holding DMA semaphore and could potentially prevent + * next DMA from executing. Fire IRQ handler to check if any DMA needs + * to be started. + */ + usbd_int_rise(); +} + +static void nrf_usbd_start_transfer(uint8_t ep) +{ + const uint8_t ep_bitpos = ep2bit(ep); + unsigned int irq_lock_key = irq_lock(); + + if (ep >= NRF_USBD_COMMON_EPOUT1 && ep <= NRF_USBD_COMMON_EPOUT7) { + if (!(m_ep_armed & BIT(ep_bitpos)) && + !(m_ep_ready & BIT(ep_bitpos))) { + /* Allow receiving DATA packet on OUT endpoint */ + NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)] = 0; + m_ep_armed |= BIT(ep_bitpos); + } + } else if (ep == NRF_USBD_COMMON_EPIN8) { + /* ISO IN endpoint can be already armed if application is double + * buffering ISO IN data. When the endpoint is already armed it + * must not be ready for next DMA transfer (until SOF). + */ + __ASSERT(!(m_ep_armed & BIT(ep_bitpos)) || + !(m_ep_ready & BIT(ep_bitpos)), + "ISO IN must not be armed and ready"); + } else if (NRF_USBD_COMMON_EP_IS_IN(ep)) { + /* IN endpoint must not have data armed */ + __ASSERT(!(m_ep_armed & BIT(ep_bitpos)), + "ep 0x%02x already armed", ep); + } + + __ASSERT(!(m_ep_dma_waiting & BIT(ep_bitpos)), + "ep 0x%02x already waiting", ep); + + m_ep_dma_waiting |= BIT(ep_bitpos); + usbd_int_rise(); + + irq_unlock(irq_lock_key); +} + +static size_t nrf_usbd_legacy_epout_size_get(nrf_usbd_common_ep_t ep) +{ + if (NRF_USBD_COMMON_EP_IS_ISO(ep)) { + size_t size = NRF_USBD->SIZE.ISOOUT; + + if ((size & USBD_SIZE_ISOOUT_ZERO_Msk) == + (USBD_SIZE_ISOOUT_ZERO_ZeroData << USBD_SIZE_ISOOUT_ZERO_Pos)) { + size = 0; + } + return size; + } + + return NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)]; +} + +static void nrf_usbd_legacy_ep_stall(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + LOG_DBG("USB: EP %x stalled.", ep); + NRF_USBD->EPSTALL = (USBD_EPSTALL_STALL_Stall << USBD_EPSTALL_STALL_Pos) | ep; +} + +static bool nrf_usbd_legacy_ep_stall_check(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return NRF_USBD->HALTED.EPIN[ep_num]; + } else { + return NRF_USBD->HALTED.EPOUT[ep_num]; + } + } + + return false; +} + +static void nrf_usbd_legacy_ep_stall_clear(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + if (NRF_USBD_COMMON_EP_IS_OUT(ep) && nrf_usbd_legacy_ep_stall_check(ep)) { + nrf_usbd_legacy_transfer_out_drop(ep); + } + NRF_USBD->EPSTALL = (USBD_EPSTALL_STALL_UnStall << USBD_EPSTALL_STALL_Pos) | ep; +} + +static void nrf_usbd_legacy_ep_dtoggle_clear(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + NRF_USBD->DTOGGLE = ep | (USBD_DTOGGLE_VALUE_Nop << USBD_DTOGGLE_VALUE_Pos); + NRF_USBD->DTOGGLE = ep | (USBD_DTOGGLE_VALUE_Data0 << USBD_DTOGGLE_VALUE_Pos); +} + +static void nrf_usbd_legacy_transfer_out_drop(nrf_usbd_common_ep_t ep) +{ + unsigned int irq_lock_key = irq_lock(); + + __ASSERT_NO_MSG(NRF_USBD_COMMON_EP_IS_OUT(ep)); + + m_ep_ready &= ~(1U << ep2bit(ep)); + if (!NRF_USBD_COMMON_EP_IS_ISO(ep)) { + NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)] = 0; + } + + irq_unlock(irq_lock_key); +} + +struct udc_nrf_config { + clock_control_subsys_t clock; + nrfx_power_config_t pwr; + nrfx_power_usbevt_config_t evt; +}; + +static struct onoff_manager *hfxo_mgr; +static struct onoff_client hfxo_cli; + +static void udc_event_xfer_in_next(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(dev, ep); + struct net_buf *buf; + + if (udc_ep_is_busy(ep_cfg)) { + return; + } + + buf = udc_buf_peek(ep_cfg); + if (buf == NULL) { + return; + } + + if (ep == USB_CONTROL_EP_IN) { + const struct udc_buf_info *bi = udc_get_buf_info(buf); + + if (bi->data) { + m_ep0_data_dir = USB_CONTROL_EP_IN; + } + + if (bi->status) { + if (!udc_nrf_setup_set_addr) { + /* Allow status stage */ + NRF_USBD->TASKS_EP0STATUS = 1; + } + + /* Controller automatically performs status IN + * stage and SW cannot know when it is done. + */ + buf = udc_buf_get(ep_cfg); + udc_submit_ep_event(dev, buf, 0); + return; + } + } + + nrf_usbd_start_transfer(ep); + udc_ep_set_busy(ep_cfg, true); +} + +static void udc_event_xfer_in(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg; + struct net_buf *buf; + + ep_cfg = udc_get_ep_cfg(dev, ep); + + buf = udc_buf_get(ep_cfg); + if (buf == NULL) { + LOG_ERR("ep 0x%02x queue is empty", ep); + __ASSERT_NO_MSG(false); + return; + } + + udc_ep_set_busy(ep_cfg, false); + udc_submit_ep_event(dev, buf, 0); + + if (ep == USB_CONTROL_EP_IN) { + __ASSERT(udc_get_buf_info(buf)->data, "EP0IN buf is not data"); + + udc_nrf_ctrl_data_in_finished = true; + + /* STALL any further IN tokens, allow status stage */ + NRF_USBD->TASKS_EP0STATUS = 1; + + /* Software won't know when status stage finishes, if we have + * status OUT pending, just complete it. + */ + ep_cfg = udc_get_ep_cfg(dev, USB_CONTROL_EP_OUT); + buf = udc_buf_get(ep_cfg); + if (buf != NULL) { + __ASSERT(udc_get_buf_info(buf)->status, "EP0OUT buf is not status"); + udc_submit_ep_event(dev, buf, 0); + } + } +} + +static void udc_event_xfer_out_next(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(dev, ep); + struct net_buf *buf; + + if (udc_ep_is_busy(ep_cfg)) { + return; + } + + buf = udc_buf_peek(ep_cfg); + if (buf != NULL) { + if (ep == USB_CONTROL_EP_OUT) { + struct udc_buf_info *bi = udc_get_buf_info(buf); + + if (bi->setup) { + /* SETUP can be received without any action */ + return; + } + + if (bi->data) { + m_ep0_data_dir = USB_CONTROL_EP_OUT; + + /* Allow receiving first OUT Data Stage packet */ + NRF_USBD->TASKS_EP0RCVOUT = 1; + } + + if (bi->status) { + if (udc_nrf_ctrl_data_in_finished) { + udc_submit_ep_event(dev, buf, 0); + } + + return; + } + } + + nrf_usbd_start_transfer(ep); + udc_ep_set_busy(ep_cfg, true); + } else { + LOG_DBG("ep 0x%02x waiting, queue is empty", ep); + } +} + +static void udc_event_xfer_out(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg; + struct net_buf *buf; + + ep_cfg = udc_get_ep_cfg(dev, ep); + buf = udc_buf_get(ep_cfg); + if (buf == NULL) { + LOG_ERR("ep 0x%02x ok, queue is empty", ep); + return; + } + + udc_ep_set_busy(ep_cfg, false); + udc_submit_ep_event(dev, buf, 0); +} + +static int udc_event_xfer_setup(const struct device *dev) +{ + struct usb_setup_packet setup; + + udc_nrf_ctrl_data_in_finished = false; + + setup.bmRequestType = NRF_USBD->BMREQUESTTYPE; + setup.bRequest = NRF_USBD->BREQUEST; + setup.wValue = NRF_USBD->WVALUEL | (NRF_USBD->WVALUEH << 8); + setup.wIndex = NRF_USBD->WINDEXL | (NRF_USBD->WINDEXH << 8); + setup.wLength = NRF_USBD->WLENGTHL | (NRF_USBD->WLENGTHH << 8); + + /* USBD peripheral automatically handles Set Address in slightly + * different manner than the USB stack. + * + * USBD peripheral doesn't care about wLength, but the peripheral + * switches to new address only after status stage. The device won't + * automatically accept Data Stage packets. + * + * However, in the case the host: + * * sends SETUP Set Address with non-zero wLength + * * does not send corresponding OUT DATA packets (to match wLength) + * or sends the packets but disregards NAK + * or sends the packets that device ACKs + * * sends IN token (either incorrectly proceeds to status stage, or + * manages to send IN before SW sets STALL) + * then the USBD peripheral will accept the address and USB stack won't. + * This will lead to state mismatch between the stack and peripheral. + * + * In cases where the USB stack would like to STALL the request there is + * a race condition between host issuing Set Address status stage (IN + * token) and SW setting STALL bit. If host wins the race, the device + * ACKs status stage and use new address. If device wins the race, the + * device STALLs status stage and address remains unchanged. + */ + udc_nrf_setup_set_addr = + setup.bmRequestType == 0 && + setup.bRequest == USB_SREQ_SET_ADDRESS; + if (udc_nrf_setup_set_addr) { + if (setup.wLength) { + /* Currently USB stack only STALLs OUT Data Stage when + * buffer allocation fails. To prevent the device from + * ACKing the Data Stage, simply ignore the request + * completely. + * + * If host incorrectly proceeds to status stage there + * will be address mismatch (unless the new address is + * equal to current device address). If host does not + * issue IN token then the mismatch will be avoided. + */ + return 0; + } + + /* nRF52/nRF53 USBD doesn't care about wValue bits 8..15 and + * wIndex value but USB device stack does. + * + * Just clear the bits so stack will handle the request in the + * same way as USBD peripheral does, avoiding the mismatch. + */ + setup.wValue &= 0x7F; + setup.wIndex = 0; + } + + if (!udc_nrf_setup_set_addr && udc_nrf_address != NRF_USBD->USBADDR) { + /* Address mismatch detected. Fake Set Address handling to + * correct the situation, then repeat handling. + */ + udc_nrf_fake_setup = true; + udc_nrf_setup_set_addr = true; + + setup.bmRequestType = 0; + setup.bRequest = USB_SREQ_SET_ADDRESS; + setup.wValue = NRF_USBD->USBADDR; + setup.wIndex = 0; + setup.wLength = 0; + } else { + udc_nrf_fake_setup = false; + } + + udc_setup_received(dev, &setup); + + return 0; +} + +static void udc_handle_ep_dequeue(const struct device *dev, + struct udc_ep_config *cfg) +{ + nrf_usbd_legacy_ep_abort(cfg->addr); + + udc_ep_cancel_queued(dev, cfg); + + udc_ep_set_busy(cfg, false); +} + +static void udc_nrf_thread_handler(const struct device *dev) +{ + uint32_t evt; + + /* Wait for at least one event */ + k_event_wait(&drv_evt, UINT32_MAX, false, K_FOREVER); + + /* Process all events that are set */ + evt = k_event_clear(&drv_evt, UINT32_MAX); + + if (evt & BIT(UDC_NRF_EVT_SUSPEND)) { + LOG_INF("SUSPEND state detected"); + nrf_usbd_legacy_suspend(); + udc_set_suspended(dev, true); + udc_submit_event(dev, UDC_EVT_SUSPEND, 0); + } + + if (evt & BIT(UDC_NRF_EVT_RESUME)) { + LOG_INF("RESUMING from suspend"); + udc_set_suspended(dev, false); + udc_submit_event(dev, UDC_EVT_RESUME, 0); + } + + if (evt & BIT(UDC_NRF_EVT_WUREQ)) { + LOG_INF("Remote wakeup initiated"); + udc_set_suspended(dev, false); + udc_submit_event(dev, UDC_EVT_RESUME, 0); + } + + if (evt & BIT(UDC_NRF_EVT_EP_FINISHED)) { + uint32_t eps = atomic_clear(&xfer_finished); + + while (eps) { + uint8_t bitpos = NRF_CTZ(eps); + nrf_usbd_common_ep_t ep = bit2ep(bitpos); + + eps &= ~BIT(bitpos); + + if (USB_EP_DIR_IS_IN(ep)) { + udc_event_xfer_in(dev, ep); + udc_event_xfer_in_next(dev, ep); + } else { + udc_event_xfer_out(dev, ep); + udc_event_xfer_out_next(dev, ep); + } + } + } + + if (evt & BIT(UDC_NRF_EVT_XFER)) { + uint32_t eps = atomic_clear(&xfer_new); + + while (eps) { + uint8_t bitpos = NRF_CTZ(eps); + nrf_usbd_common_ep_t ep = bit2ep(bitpos); + + eps &= ~BIT(bitpos); + + if (USB_EP_DIR_IS_IN(ep)) { + udc_event_xfer_in_next(dev, ep); + } else { + udc_event_xfer_out_next(dev, ep); + } + } + } + + if (evt & BIT(UDC_NRF_EVT_SETUP)) { + udc_event_xfer_setup(dev); + } + + if (evt & BIT(UDC_NRF_EVT_DEQUEUE)) { + udc_lock_internal(dev, K_FOREVER); + + while (m_ep_dequeue) { + struct udc_ep_config *ep_cfg; + uint8_t bitpos = NRF_CTZ(m_ep_dequeue); + + ep_cfg = udc_get_ep_cfg(dev, bit2ep(bitpos)); + udc_handle_ep_dequeue(dev, ep_cfg); + + /* If transfer actually finished before dequeue, then + * xfer_finished bit may be set. Just clear it. + */ + atomic_clear_bit(&xfer_finished, bitpos); + + m_ep_dequeue &= ~BIT(bitpos); + } + + /* Notify requestors that requested endpoints are dequeued */ + k_condvar_broadcast(&ep_dequeued); + + udc_unlock_internal(dev); + } +} + +static void udc_nrf_thread(void *p1, void *p2, void *p3) +{ + ARG_UNUSED(p2); + ARG_UNUSED(p3); + + const struct device *dev = p1; + + while (true) { + udc_nrf_thread_handler(dev); + } +} + +static void udc_nrf_power_handler(nrfx_power_usb_evt_t pwr_evt) +{ + switch (pwr_evt) { + case NRFX_POWER_USB_EVT_DETECTED: + LOG_DBG("POWER event detected"); + udc_submit_event(udc_nrf_dev, UDC_EVT_VBUS_READY, 0); + break; + case NRFX_POWER_USB_EVT_READY: + LOG_DBG("POWER event ready"); + nrf_usbd_legacy_start(IS_ENABLED(CONFIG_UDC_ENABLE_SOF)); + break; + case NRFX_POWER_USB_EVT_REMOVED: + LOG_DBG("POWER event removed"); + udc_submit_event(udc_nrf_dev, UDC_EVT_VBUS_REMOVED, 0); + break; + default: + LOG_ERR("Unknown power event %d", pwr_evt); + } +} + +static int udc_nrf_ep_enqueue(const struct device *dev, + struct udc_ep_config *cfg, + struct net_buf *buf) +{ + udc_buf_put(cfg, buf); + + atomic_set_bit(&xfer_new, ep2bit(cfg->addr)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_XFER)); + + return 0; +} + +static int udc_nrf_ep_dequeue(const struct device *dev, + struct udc_ep_config *cfg) +{ + struct udc_data *data = dev->data; + + /* Signal that we want to dequeue, variable is protected by UDC mutex */ + m_ep_dequeue |= BIT(ep2bit(cfg->addr)); + + /* Avoid context switch immediately after posting event */ + k_sched_lock(); + + /* Inform nRF UDC driver that there are endpoints to be dequeued */ + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_DEQUEUE)); + + /* Wait for endpoints to be dequeued, UDC mutex was acquired via + * api->lock() called in udc_ep_dequeue(). + */ + k_condvar_wait(&ep_dequeued, &data->mutex, K_FOREVER); + + k_sched_unlock(); + + return 0; +} + +static int udc_nrf_ep_enable(const struct device *dev, + struct udc_ep_config *cfg) +{ + uint16_t mps; + + __ASSERT_NO_MSG(cfg); + mps = (udc_mps_ep_size(cfg) == 0) ? cfg->caps.mps : udc_mps_ep_size(cfg); + nrf_usbd_legacy_ep_enable(cfg->addr); + if (!NRF_USBD_EPISO_CHECK(cfg->addr)) { + /* ISO transactions for full-speed device do not support + * toggle sequencing and should only send DATA0 PID. + */ + nrf_usbd_legacy_ep_dtoggle_clear(cfg->addr); + nrf_usbd_legacy_ep_stall_clear(cfg->addr); + } + + LOG_DBG("Enable ep 0x%02x", cfg->addr); + + return 0; +} + +static int udc_nrf_ep_disable(const struct device *dev, + struct udc_ep_config *cfg) +{ + __ASSERT_NO_MSG(cfg); + nrf_usbd_legacy_ep_disable(cfg->addr); + LOG_DBG("Disable ep 0x%02x", cfg->addr); + + return 0; +} + +static int udc_nrf_ep_set_halt(const struct device *dev, + struct udc_ep_config *cfg) +{ + LOG_DBG("Halt ep 0x%02x", cfg->addr); + + if (cfg->addr == USB_CONTROL_EP_OUT || + cfg->addr == USB_CONTROL_EP_IN) { + NRF_USBD->TASKS_EP0STALL = 1; + } else { + nrf_usbd_legacy_ep_stall(cfg->addr); + } + + return 0; +} + +static int udc_nrf_ep_clear_halt(const struct device *dev, + struct udc_ep_config *cfg) +{ + LOG_DBG("Clear halt ep 0x%02x", cfg->addr); + + nrf_usbd_legacy_ep_dtoggle_clear(cfg->addr); + nrf_usbd_legacy_ep_stall_clear(cfg->addr); + + return 0; +} + +static int udc_nrf_set_address(const struct device *dev, const uint8_t addr) +{ + /* + * If the status stage already finished (which depends entirely on when + * the host sends IN token) then NRF_USBD->USBADDR will have the same + * address, otherwise it won't (unless new address is unchanged). + * + * Store the address so the driver can detect address mismatches + * between USB stack and USBD peripheral. The mismatches can occur if: + * * SW has high enough latency in SETUP handling, or + * * Host did not issue Status Stage after Set Address request + * + * The SETUP handling latency is a problem because the Set Address is + * automatically handled by device. Because whole Set Address handling + * can finish in less than 21 us, the latency required (with perfect + * timing) to hit the issue is relatively short (2 ms Set Address + * recovery interval + negligible Set Address handling time). If host + * sends new SETUP before SW had a chance to read the Set Address one, + * the Set Address one will be overwritten without a trace. + */ + udc_nrf_address = addr; + + if (udc_nrf_fake_setup) { + /* Finished handling lost Set Address, now handle the pending + * SETUP transfer. + */ + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SETUP)); + } + + return 0; +} + +static int udc_nrf_host_wakeup(const struct device *dev) +{ + bool res = nrf_usbd_legacy_wakeup_req(); + + LOG_DBG("Host wakeup request"); + if (!res) { + return -EAGAIN; + } + + return 0; +} + +static int udc_nrf_enable(const struct device *dev) +{ + unsigned int key; + int ret; + + if (udc_ep_enable_internal(dev, USB_CONTROL_EP_OUT, + USB_EP_TYPE_CONTROL, UDC_NRF_EP0_SIZE, 0)) { + LOG_ERR("Failed to enable control endpoint"); + return -EIO; + } + + if (udc_ep_enable_internal(dev, USB_CONTROL_EP_IN, + USB_EP_TYPE_CONTROL, UDC_NRF_EP0_SIZE, 0)) { + LOG_ERR("Failed to enable control endpoint"); + return -EIO; + } + + sys_notify_init_spinwait(&hfxo_cli.notify); + ret = onoff_request(hfxo_mgr, &hfxo_cli); + if (ret < 0) { + LOG_ERR("Failed to start HFXO %d", ret); + return ret; + } + + /* Disable interrupts until USBD is enabled */ + key = irq_lock(); + nrf_usbd_legacy_enable(); + irq_unlock(key); + + return 0; +} + +static int udc_nrf_disable(const struct device *dev) +{ + int ret; + + nrf_usbd_legacy_disable(); + + if (udc_ep_disable_internal(dev, USB_CONTROL_EP_OUT)) { + LOG_ERR("Failed to disable control endpoint"); + return -EIO; + } + + if (udc_ep_disable_internal(dev, USB_CONTROL_EP_IN)) { + LOG_ERR("Failed to disable control endpoint"); + return -EIO; + } + + ret = onoff_cancel_or_release(hfxo_mgr, &hfxo_cli); + if (ret < 0) { + LOG_ERR("Failed to stop HFXO %d", ret); + return ret; + } + + return 0; +} + +static int udc_nrf_init(const struct device *dev) +{ + const struct udc_nrf_config *cfg = dev->config; + + hfxo_mgr = z_nrf_clock_control_get_onoff(cfg->clock); + +#ifdef CONFIG_HAS_HW_NRF_USBREG + /* Use CLOCK/POWER priority for compatibility with other series where + * USB events are handled by CLOCK interrupt handler. + */ + IRQ_CONNECT(USBREGULATOR_IRQn, + DT_IRQ(DT_INST(0, nordic_nrf_clock), priority), + nrfx_isr, nrfx_usbreg_irq_handler, 0); +#endif + + IRQ_CONNECT(DT_INST_IRQN(0), DT_INST_IRQ(0, priority), + nrfx_isr, nrf_usbd_irq_handler, 0); + + (void)nrfx_power_init(&cfg->pwr); + nrfx_power_usbevt_init(&cfg->evt); + + nrfx_power_usbevt_enable(); + LOG_INF("Initialized"); + + return 0; +} + +static int udc_nrf_shutdown(const struct device *dev) +{ + LOG_INF("shutdown"); + + nrfx_power_usbevt_disable(); + nrfx_power_usbevt_uninit(); + + return 0; +} + +static int udc_nrf_driver_init(const struct device *dev) +{ + struct udc_data *data = dev->data; + int err; + + LOG_INF("Preinit"); + udc_nrf_dev = dev; + k_mutex_init(&data->mutex); + k_thread_create(&drv_stack_data, drv_stack, + K_KERNEL_STACK_SIZEOF(drv_stack), + udc_nrf_thread, + (void *)dev, NULL, NULL, + K_PRIO_COOP(8), 0, K_NO_WAIT); + + k_thread_name_set(&drv_stack_data, "udc_nrfx"); + + for (int i = 0; i < ARRAY_SIZE(ep_cfg_out); i++) { + ep_cfg_out[i].caps.out = 1; + if (i == 0) { + ep_cfg_out[i].caps.control = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else if (i < (CFG_EPOUT_CNT + 1)) { + ep_cfg_out[i].caps.bulk = 1; + ep_cfg_out[i].caps.interrupt = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else { + ep_cfg_out[i].caps.iso = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_ISOSIZE / 2; + } + + ep_cfg_out[i].addr = USB_EP_DIR_OUT | i; + err = udc_register_ep(dev, &ep_cfg_out[i]); + if (err != 0) { + LOG_ERR("Failed to register endpoint"); + return err; + } + } + + for (int i = 0; i < ARRAY_SIZE(ep_cfg_in); i++) { + ep_cfg_in[i].caps.in = 1; + if (i == 0) { + ep_cfg_in[i].caps.control = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else if (i < (CFG_EPIN_CNT + 1)) { + ep_cfg_in[i].caps.bulk = 1; + ep_cfg_in[i].caps.interrupt = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else { + ep_cfg_in[i].caps.iso = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_ISOSIZE / 2; + } + + ep_cfg_in[i].addr = USB_EP_DIR_IN | i; + err = udc_register_ep(dev, &ep_cfg_in[i]); + if (err != 0) { + LOG_ERR("Failed to register endpoint"); + return err; + } + } + + data->caps.rwup = true; + data->caps.mps0 = UDC_NRF_MPS0; + data->caps.can_detect_vbus = true; + + return 0; +} + +static void udc_nrf_lock(const struct device *dev) +{ + udc_lock_internal(dev, K_FOREVER); +} + +static void udc_nrf_unlock(const struct device *dev) +{ + udc_unlock_internal(dev); +} + +static const struct udc_nrf_config udc_nrf_cfg = { + .clock = COND_CODE_1(NRF_CLOCK_HAS_HFCLK192M, + (CLOCK_CONTROL_NRF_SUBSYS_HF192M), + (CLOCK_CONTROL_NRF_SUBSYS_HF)), + .pwr = { + .dcdcen = (DT_PROP(DT_INST(0, nordic_nrf5x_regulator), regulator_initial_mode) + == NRF5X_REG_MODE_DCDC), +#if NRFX_POWER_SUPPORTS_DCDCEN_VDDH + .dcdcenhv = COND_CODE_1(CONFIG_SOC_SERIES_NRF52, + (DT_NODE_HAS_STATUS_OKAY(DT_INST(0, nordic_nrf52x_regulator_hv))), + (DT_NODE_HAS_STATUS_OKAY(DT_INST(0, nordic_nrf53x_regulator_hv)))), +#endif + }, + + .evt = { + .handler = udc_nrf_power_handler + }, +}; + +static struct udc_data udc_nrf_data = { + .mutex = Z_MUTEX_INITIALIZER(udc_nrf_data.mutex), + .priv = NULL, +}; + +static const struct udc_api udc_nrf_api = { + .lock = udc_nrf_lock, + .unlock = udc_nrf_unlock, + .init = udc_nrf_init, + .enable = udc_nrf_enable, + .disable = udc_nrf_disable, + .shutdown = udc_nrf_shutdown, + .set_address = udc_nrf_set_address, + .host_wakeup = udc_nrf_host_wakeup, + .ep_try_config = NULL, + .ep_enable = udc_nrf_ep_enable, + .ep_disable = udc_nrf_ep_disable, + .ep_set_halt = udc_nrf_ep_set_halt, + .ep_clear_halt = udc_nrf_ep_clear_halt, + .ep_enqueue = udc_nrf_ep_enqueue, + .ep_dequeue = udc_nrf_ep_dequeue, +}; + +DEVICE_DT_INST_DEFINE(0, udc_nrf_driver_init, NULL, + &udc_nrf_data, &udc_nrf_cfg, + POST_KERNEL, CONFIG_KERNEL_INIT_PRIORITY_DEVICE, + &udc_nrf_api); diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf.c b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf.c new file mode 100644 index 0000000..fb40395 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf.c @@ -0,0 +1,2003 @@ +/* + * Copyright (c) 2021 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#include +#include +#include + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include "udc_common.h" +#include "udc_nrf_iso_in_fast.h" + +#include +LOG_MODULE_REGISTER(udc_nrf, CONFIG_UDC_DRIVER_LOG_LEVEL); + +/* + * There is no real advantage to change control endpoint size + * but we can use it for testing UDC driver API and higher layers. + */ +#define UDC_NRF_MPS0 UDC_MPS0_64 +#define UDC_NRF_EP0_SIZE 64 + +enum udc_nrf_event_type { + /* Trigger next transfer (buffer enqueued) */ + UDC_NRF_EVT_XFER, + /* Transfer finished */ + UDC_NRF_EVT_EP_FINISHED, + /* SETUP data received */ + UDC_NRF_EVT_SETUP, + /* USB bus suspended */ + UDC_NRF_EVT_SUSPEND, + /* USB bus resumed */ + UDC_NRF_EVT_RESUME, + /* Remote Wakeup initiated */ + UDC_NRF_EVT_WUREQ, + /* Endpoint dequeue requested */ + UDC_NRF_EVT_DEQUEUE, +}; + +/* Main events the driver thread waits for */ +static K_EVENT_DEFINE(drv_evt); +/* Transfer triggers */ +static atomic_t xfer_new; +/* Finished transactions */ +static atomic_t xfer_finished; + +static K_KERNEL_STACK_DEFINE(drv_stack, CONFIG_UDC_NRF_THREAD_STACK_SIZE); +static struct k_thread drv_stack_data; + +/* USB device controller access from devicetree */ +#define DT_DRV_COMPAT nordic_nrf_usbd + +#define CFG_EPIN_CNT DT_INST_PROP(0, num_in_endpoints) +#define CFG_EPOUT_CNT DT_INST_PROP(0, num_out_endpoints) +#define CFG_EP_ISOIN_CNT DT_INST_PROP(0, num_isoin_endpoints) +#define CFG_EP_ISOOUT_CNT DT_INST_PROP(0, num_isoout_endpoints) + +static struct udc_ep_config ep_cfg_out[CFG_EPOUT_CNT + CFG_EP_ISOOUT_CNT + 1]; +static struct udc_ep_config ep_cfg_in[CFG_EPIN_CNT + CFG_EP_ISOIN_CNT + 1]; +static bool udc_nrf_ctrl_data_in_finished; +static bool udc_nrf_setup_set_addr, udc_nrf_fake_setup; +static uint8_t udc_nrf_address; +const static struct device *udc_nrf_dev; + +#define NRF_USBD_COMMON_EPIN_CNT 9 +#define NRF_USBD_COMMON_EPOUT_CNT 9 +#define NRF_USBD_COMMON_EP_NUM(ep) (ep & 0xF) +#define NRF_USBD_COMMON_EP_IS_IN(ep) ((ep & 0x80) == 0x80) +#define NRF_USBD_COMMON_EP_IS_OUT(ep) ((ep & 0x80) == 0) +#define NRF_USBD_COMMON_EP_IS_ISO(ep) ((ep & 0xF) >= 8) + +#ifndef NRF_USBD_COMMON_ISO_DEBUG +/* Also generate information about ISOCHRONOUS events and transfers. + * Turn this off if no ISOCHRONOUS transfers are going to be debugged and this + * option generates a lot of useless messages. + */ +#define NRF_USBD_COMMON_ISO_DEBUG 1 +#endif + +#ifndef NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 +/* Anomaly 211 - Device remains in SUSPEND too long when host resumes + * a bus activity (sending SOF packets) without a RESUME condition. + */ +#define NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 0 +#endif + +/* Assert endpoint is valid */ +#define NRF_USBD_COMMON_ASSERT_EP_VALID(ep) __ASSERT_NO_MSG( \ + ((NRF_USBD_COMMON_EP_IS_IN(ep) && \ + (NRF_USBD_COMMON_EP_NUM(ep) < NRF_USBD_COMMON_EPIN_CNT)) || \ + (NRF_USBD_COMMON_EP_IS_OUT(ep) && \ + (NRF_USBD_COMMON_EP_NUM(ep) < NRF_USBD_COMMON_EPOUT_CNT)))); + +/* Lowest IN endpoint bit position */ +#define NRF_USBD_COMMON_EPIN_BITPOS_0 0 + +/* Lowest OUT endpoint bit position */ +#define NRF_USBD_COMMON_EPOUT_BITPOS_0 16 + +/* Input endpoint bits mask */ +#define NRF_USBD_COMMON_EPIN_BIT_MASK (0xFFFFU << NRF_USBD_COMMON_EPIN_BITPOS_0) + +/* Output endpoint bits mask */ +#define NRF_USBD_COMMON_EPOUT_BIT_MASK (0xFFFFU << NRF_USBD_COMMON_EPOUT_BITPOS_0) + +/* Isochronous endpoint bit mask */ +#define USBD_EPISO_BIT_MASK \ + ((1U << NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT8)) | \ + (1U << NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN8))) + +/* Convert endpoint number to bit position */ +#define NRF_USBD_COMMON_EP_BITPOS(ep) ((NRF_USBD_COMMON_EP_IS_IN(ep) \ + ? NRF_USBD_COMMON_EPIN_BITPOS_0 : NRF_USBD_COMMON_EPOUT_BITPOS_0) \ + + NRF_USBD_COMMON_EP_NUM(ep)) + +/* Check it the bit positions values match defined DATAEPSTATUS bit positions */ +BUILD_ASSERT( + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN1) == USBD_EPDATASTATUS_EPIN1_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN2) == USBD_EPDATASTATUS_EPIN2_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN3) == USBD_EPDATASTATUS_EPIN3_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN4) == USBD_EPDATASTATUS_EPIN4_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN5) == USBD_EPDATASTATUS_EPIN5_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN6) == USBD_EPDATASTATUS_EPIN6_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPIN7) == USBD_EPDATASTATUS_EPIN7_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT1) == USBD_EPDATASTATUS_EPOUT1_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT2) == USBD_EPDATASTATUS_EPOUT2_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT3) == USBD_EPDATASTATUS_EPOUT3_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT4) == USBD_EPDATASTATUS_EPOUT4_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT5) == USBD_EPDATASTATUS_EPOUT5_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT6) == USBD_EPDATASTATUS_EPOUT6_Pos) && + (NRF_USBD_COMMON_EP_BITPOS(NRF_USBD_COMMON_EPOUT7) == USBD_EPDATASTATUS_EPOUT7_Pos), + "NRF_USBD_COMMON bit positions do not match hardware" +); + +/* True if USB bus is suspended, updated in interrupt handler */ +static volatile bool m_bus_suspend; + +/* Data Stage direction used to map EP0DATADONE to actual endpoint */ +static uint8_t m_ep0_data_dir; + +/* Set bit indicates that endpoint is ready for DMA transfer. + * + * OUT endpoint is ready when DATA packet has been ACKed by device. + * IN endpoint is ready when IN endpoint buffer has no pending data. + * + * When endpoint is ready it responds with NAK to any further traffic. + */ +static uint32_t m_ep_ready; + +/* Set bit indicates that endpoint is waiting for DMA transfer, i.e. there is + * USB stack buffer queued for the transfer. + */ +static uint32_t m_ep_dma_waiting; + +/* Set bit indicates that endpoint is armed. + * + * OUT endpoint armed means that valid DATA packet from host will be ACKed. + * IN endpoint armed means that device will respond with DATA packet. + */ +static uint32_t m_ep_armed; + +/* Set bit indicates that endpoint is requested to be dequeued. */ +static uint32_t m_ep_dequeue; + +static K_CONDVAR_DEFINE(ep_dequeued); + +/* Semaphore to guard EasyDMA access. + * In USBD there is only one DMA channel working in background, and new transfer + * cannot be started when there is ongoing transfer on any other channel. + */ +static K_SEM_DEFINE(dma_available, 1, 1); + +/* Endpoint on which DMA was started. */ +static nrf_usbd_common_ep_t dma_ep; + +/* Tracks whether total bytes transferred by DMA is even or odd. */ +static uint8_t m_dma_odd; + +/* First time enabling after reset. Used in nRF52 errata 223. */ +static bool m_first_enable = true; + +#define NRF_USBD_COMMON_FEEDER_BUFFER_SIZE NRF_USBD_COMMON_EPSIZE + +/* Bounce buffer for sending data from FLASH */ +static uint32_t m_tx_buffer[NRFX_CEIL_DIV(NRF_USBD_COMMON_FEEDER_BUFFER_SIZE, sizeof(uint32_t))]; + +/* ISO IN fast path (udc_nrf_iso_in_fast.h). When registered, ev_sof_handler() + * asks the application for the next ISO IN packet and usbd_dmareq_process() + * DMAs it from iso_fast_buf at the end of the same interrupt, so no thread is + * woken per frame. Two buffers: a DMA may still be running across SOF (see + * ev_sof_handler), and the next packet must not be written under it. + */ +static udc_nrf_iso_in_fill_t iso_fast_fill; +static void *iso_fast_user_data; +static bool iso_fast_suppress_sof; +static uint32_t iso_fast_buf[2][UDC_NRF_ISO_IN_FAST_MAX / sizeof(uint32_t)]; +static uint8_t iso_fast_next; +static uint8_t *iso_fast_ptr; +static uint16_t iso_fast_len; +/* True from DMA start until DMA end of a fast-path packet. */ +static bool iso_fast_dma; +static struct udc_nrf_iso_in_fast_stats iso_fast_stats; + +/* Early declaration. Documentation above definition. */ +static void usbd_dmareq_process(void); +static inline void usbd_int_rise(void); +static void nrf_usbd_common_stop(void); +static void nrf_usbd_legacy_transfer_out_drop(nrf_usbd_common_ep_t ep); +static size_t nrf_usbd_legacy_epout_size_get(nrf_usbd_common_ep_t ep); +static bool nrf_usbd_legacy_suspend_check(void); + +/* Get EasyDMA end event address for given endpoint */ +static volatile uint32_t *usbd_ep_to_endevent(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return &NRF_USBD->EVENTS_ENDEPIN[ep_num]; + } else { + return &NRF_USBD->EVENTS_ENDEPOUT[ep_num]; + } + } + + return ep_in ? &NRF_USBD->EVENTS_ENDISOIN : &NRF_USBD->EVENTS_ENDISOOUT; +} + +/* Return number of bytes last transferred by EasyDMA on given endpoint */ +static uint32_t usbd_ep_amount_get(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return NRF_USBD->EPIN[ep_num].AMOUNT; + } else { + return NRF_USBD->EPOUT[ep_num].AMOUNT; + } + } + + return ep_in ? NRF_USBD->ISOIN.AMOUNT : NRF_USBD->ISOOUT.AMOUNT; +} + +/* Start EasyDMA on given endpoint */ +static void usbd_ep_dma_start(nrf_usbd_common_ep_t ep, uint32_t addr, size_t len) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + NRF_USBD->EPIN[ep_num].PTR = addr; + NRF_USBD->EPIN[ep_num].MAXCNT = len; + NRF_USBD->TASKS_STARTEPIN[ep_num] = 1; + } else { + NRF_USBD->EPOUT[ep_num].PTR = addr; + NRF_USBD->EPOUT[ep_num].MAXCNT = len; + NRF_USBD->TASKS_STARTEPOUT[ep_num] = 1; + } + } else if (ep_in) { + NRF_USBD->ISOIN.PTR = addr; + NRF_USBD->ISOIN.MAXCNT = len; + NRF_USBD->TASKS_STARTISOIN = 1; + } else { + NRF_USBD->ISOOUT.PTR = addr; + NRF_USBD->ISOOUT.MAXCNT = len; + NRF_USBD->TASKS_STARTISOOUT = 1; + } +} + +/* Convert endpoint number to bit position matching EPDATASTATUS register. + * Control and isochronous endpoints occupy unused EPDATASTATUS bits. + */ +static inline uint8_t ep2bit(nrf_usbd_common_ep_t ep) +{ + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + return NRF_USBD_COMMON_EP_BITPOS(ep); +} + +static inline nrf_usbd_common_ep_t bit2ep(uint8_t bitpos) +{ + BUILD_ASSERT(NRF_USBD_COMMON_EPOUT_BITPOS_0 > NRF_USBD_COMMON_EPIN_BITPOS_0, + "OUT endpoint bits should be higher than IN endpoint bits"); + return (nrf_usbd_common_ep_t)((bitpos >= NRF_USBD_COMMON_EPOUT_BITPOS_0) + ? NRF_USBD_COMMON_EPOUT(bitpos - NRF_USBD_COMMON_EPOUT_BITPOS_0) + : NRF_USBD_COMMON_EPIN(bitpos)); +} + +/* Prepare DMA for transfer */ +static inline void usbd_dma_pending_set(void) +{ + if (nrf_usbd_common_errata_199()) { + *((volatile uint32_t *)0x40027C1C) = 0x00000082; + } +} + +/* DMA transfer finished */ +static inline void usbd_dma_pending_clear(void) +{ + if (nrf_usbd_common_errata_199()) { + *((volatile uint32_t *)0x40027C1C) = 0x00000000; + } +} + +static void disarm_endpoint(uint8_t ep) +{ + if (ep == USB_CONTROL_EP_OUT || ep == USB_CONTROL_EP_IN) { + /* EP0 cannot be disarmed. This is not a problem because SETUP + * token automatically disarms EP0 IN and EP0 OUT. + */ + return; + } + + if (NRF_USBD_COMMON_EP_IS_ISO(ep)) { + /* Isochronous endpoints cannot be disarmed */ + return; + } + + if (!(m_ep_armed & BIT(ep2bit(ep)))) { + /* Endpoint is not armed, nothing to do */ + return; + } + + m_ep_armed &= ~BIT(ep2bit(ep)); + + /* Disarm the endpoint if there is any data buffered. For OUT endpoints + * disarming means that the endpoint won't ACK (will NAK) DATA packet. + */ + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x800)) = 0x7B6 + + 2 * (USB_EP_GET_IDX(ep) - 1) + USB_EP_DIR_IS_OUT(ep) * 0x10; + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x804)) |= BIT(1); +} + +static inline void usbd_ep_abort(nrf_usbd_common_ep_t ep) +{ + unsigned int irq_lock_key = irq_lock(); + + disarm_endpoint(ep); + + /* Do not process any data until endpoint is enqueued again */ + m_ep_dma_waiting &= ~BIT(ep2bit(ep)); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep)) { + if (NRF_USBD_COMMON_EP_IS_OUT(ep)) { + m_ep_ready &= ~BIT(ep2bit(ep)); + } else { + m_ep_ready |= BIT(ep2bit(ep)); + } + } + + /* Disarming endpoint is inherently a race between the driver and host. + * Clear EPDATASTATUS to prevent interrupt handler from processing the + * data if disarming lost the race (i.e. host finished first). + */ + NRF_USBD->EPDATASTATUS = BIT(ep2bit(ep)); + + irq_unlock(irq_lock_key); +} + +static void nrf_usbd_legacy_ep_abort(nrf_usbd_common_ep_t ep) +{ + /* Only abort if there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + usbd_ep_abort(ep); + k_sem_give(&dma_available); + + /* This function was holding DMA semaphore and could potentially prevent + * next DMA from executing. Fire IRQ handler to check if any DMA needs + * to be started. + */ + usbd_int_rise(); +} + +static void usbd_ep_abort_all(void) +{ + uint32_t ep_waiting = m_ep_dma_waiting | (m_ep_ready & NRF_USBD_COMMON_EPOUT_BIT_MASK); + + while (ep_waiting != 0) { + uint8_t bitpos = NRF_CTZ(ep_waiting); + + if (!NRF_USBD_COMMON_EP_IS_ISO(bit2ep(bitpos))) { + usbd_ep_abort(bit2ep(bitpos)); + } + ep_waiting &= ~(1U << bitpos); + } + + m_ep_ready = (((1U << NRF_USBD_COMMON_EPIN_CNT) - 1U) << NRF_USBD_COMMON_EPIN_BITPOS_0); +} + +/* Rise USBD interrupt to trigger interrupt handler */ +static inline void usbd_int_rise(void) +{ + NVIC_SetPendingIRQ(USBD_IRQn); +} + +static void ev_usbreset_handler(void) +{ + m_bus_suspend = false; + + LOG_INF("Reset"); + udc_submit_event(udc_nrf_dev, UDC_EVT_RESET, 0); +} + +static void nrf_usbd_dma_finished(nrf_usbd_common_ep_t ep) +{ + /* DMA finished, track if total bytes transferred is even or odd */ + m_dma_odd ^= usbd_ep_amount_get(ep) & 1; + usbd_dma_pending_clear(); + + if (ep == NRF_USBD_COMMON_EPIN8 && iso_fast_dma) { + /* ISO IN fast path: no net_buf to complete, and no thread to wake */ + iso_fast_dma = false; + } else if ((m_ep_dma_waiting & BIT(ep2bit(ep))) == 0) { + if (NRF_USBD_COMMON_EP_IS_OUT(ep) || (ep == NRF_USBD_COMMON_EPIN8)) { + /* Send event to the user - for an ISO IN or any OUT endpoint, + * the whole transfer is finished in this moment + */ + atomic_set_bit(&xfer_finished, ep2bit(ep)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_EP_FINISHED)); + } + } else if (ep == NRF_USBD_COMMON_EPOUT0) { + /* Allow receiving next OUT Data Stage chunk */ + NRF_USBD->TASKS_EP0RCVOUT = 1; + } + + if (NRF_USBD_COMMON_EP_IS_IN(ep) || + (ep >= NRF_USBD_COMMON_EPOUT1 && ep <= NRF_USBD_COMMON_EPOUT7)) { + m_ep_armed |= BIT(ep2bit(ep)); + } + + /* Set default dma_ep value that has no special meaning, so we do not + * need to have separate dma_ep_valid flag (in the hot interrupt path). + * This is necessary to avoid false positives in ev_sof_handler() and + * on EVENTS_EP0SETUP check when dma_available is held in thread context + * (e.g. when thread wants to call usbd_ep_abort()), i.e. when thread + * prevents DMA operation. + */ + dma_ep = NRF_USBD_COMMON_EPIN1; + + k_sem_give(&dma_available); +} + +/* ISO IN fast path at SOF: take this frame's packet from the application and + * request its DMA, which usbd_dmareq_process() starts at the end of this same + * interrupt. Returns true if the fast path is active. + */ +static bool iso_fast_sof(void) +{ + const udc_nrf_iso_in_fill_t fill = iso_fast_fill; + const uint32_t bit = BIT(ep2bit(NRF_USBD_COMMON_EPIN8)); + uint8_t *buf; + uint16_t len; + + if (fill == NULL || !(NRF_USBD->EPINEN & BIT(NRF_USBD_COMMON_EP_NUM(NRF_USBD_COMMON_EPIN8)))) { + return false; + } + + if (m_ep_dma_waiting & bit) { + /* Last frame's packet never got the DMA (another endpoint held it + * across the whole frame): it is stale, send this frame's instead. + */ + iso_fast_stats.replaced++; + } + + buf = (uint8_t *)iso_fast_buf[iso_fast_next]; + len = fill(buf, UDC_NRF_ISO_IN_FAST_MAX, iso_fast_user_data); + if (len == 0) { + m_ep_dma_waiting &= ~bit; + iso_fast_stats.empty++; + return true; + } + + iso_fast_ptr = buf; + iso_fast_len = MIN(len, UDC_NRF_ISO_IN_FAST_MAX); + iso_fast_next ^= 1; + m_ep_dma_waiting |= bit; + + return true; +} + +static void ev_sof_handler(void) +{ + /* Process isochronous endpoints */ + uint32_t iso_ready_mask = (1U << ep2bit(NRF_USBD_COMMON_EPIN8)); + + /* SIZE.ISOOUT is 0 only when no packet was received at all */ + if (NRF_USBD->SIZE.ISOOUT) { + iso_ready_mask |= (1U << ep2bit(NRF_USBD_COMMON_EPOUT8)); + } + + if (k_sem_count_get(&dma_available) == 0) { + /* DMA may have been active across SOF which means that endpoint + * data may be corrupted (if DMA was to isochronous endpoint). + * Do not mark the endpoint as ready if this is the case. + */ + iso_ready_mask &= ~BIT(ep2bit(dma_ep)); + } + + m_ep_ready |= iso_ready_mask; + + m_ep_armed &= ~USBD_EPISO_BIT_MASK; + + if (iso_fast_sof() && iso_fast_suppress_sof) { + return; + } + + udc_submit_sof_event(udc_nrf_dev); +} + +static void usbd_in_packet_sent(uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); + struct net_buf *buf = udc_buf_peek(ep_cfg); + + net_buf_pull(buf, usbd_ep_amount_get(ep)); + + if (buf->len) { + /* More packets will be sent, nothing to do here */ + } else if (udc_ep_buf_has_zlp(buf)) { + /* Actual payload sent, only ZLP left */ + udc_ep_buf_clear_zlp(buf); + } else { + LOG_DBG("USBD event: EndpointData: In finished"); + /* No more data to be send - transmission finished */ + atomic_set_bit(&xfer_finished, ep2bit(ep)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_EP_FINISHED)); + } +} + +static void ev_setup_handler(void) +{ + LOG_DBG("USBD event: Setup (rt:%.2x r:%.2x v:%.4x i:%.4x l:%u )", + NRF_USBD->BMREQUESTTYPE, NRF_USBD->BREQUEST, + NRF_USBD->WVALUEL | (NRF_USBD->WVALUEH << 8), + NRF_USBD->WINDEXL | (NRF_USBD->WINDEXH << 8), + NRF_USBD->WLENGTHL | (NRF_USBD->WLENGTHH << 8)); + + m_ep_dma_waiting &= ~((1U << ep2bit(NRF_USBD_COMMON_EPOUT0)) | + (1U << ep2bit(NRF_USBD_COMMON_EPIN0))); + m_ep_ready &= ~(1U << ep2bit(NRF_USBD_COMMON_EPOUT0)); + m_ep_ready |= 1U << ep2bit(NRF_USBD_COMMON_EPIN0); + + m_ep_armed &= ~(BIT(ep2bit(USB_CONTROL_EP_OUT)) | + BIT(ep2bit(USB_CONTROL_EP_IN))); + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SETUP)); +} + +static void ev_usbevent_handler(void) +{ + uint32_t event = NRF_USBD->EVENTCAUSE; + + /* Clear handled events */ + NRF_USBD->EVENTCAUSE = event; + + if (event & USBD_EVENTCAUSE_ISOOUTCRC_Msk) { + LOG_DBG("USBD event: ISOOUTCRC"); + /* Currently no support */ + } + if (event & USBD_EVENTCAUSE_SUSPEND_Msk) { + LOG_DBG("USBD event: SUSPEND"); + m_bus_suspend = true; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SUSPEND)); + } + if (event & USBD_EVENTCAUSE_RESUME_Msk) { + LOG_DBG("USBD event: RESUME"); + m_bus_suspend = false; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_RESUME)); + } + if (event & USBD_EVENTCAUSE_USBWUALLOWED_Msk) { + LOG_DBG("USBD event: WUREQ (%s)", m_bus_suspend ? "In Suspend" : "Active"); + if (m_bus_suspend) { + __ASSERT_NO_MSG(!nrf_usbd_legacy_suspend_check()); + m_bus_suspend = false; + + NRF_USBD->DPDMVALUE = USBD_DPDMVALUE_STATE_Resume + << USBD_DPDMVALUE_STATE_Pos; + NRF_USBD->TASKS_DPDMDRIVE = 1; + + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_WUREQ)); + } + } +} + +static void ev_epdata_handler(uint32_t dataepstatus) +{ + if (dataepstatus) { + LOG_DBG("USBD event: EndpointEPStatus: %x", dataepstatus); + + /* Mark endpoints ready for next DMA access */ + m_ep_ready |= dataepstatus & ~USBD_EPISO_BIT_MASK; + + /* IN endpoints are no longer armed after host read the data. + * OUT endpoints are no longer armed before DMA reads the data. + */ + m_ep_armed &= ~(dataepstatus & ~USBD_EPISO_BIT_MASK); + + /* Peripheral automatically enables endpoint for data reception + * after OUT endpoint DMA transfer. This makes the device ACK + * the OUT DATA even if the stack did not enqueue any buffer. + * + * This behaviour most likely cannot be avoided and therefore + * there's nothing more to do for OUT endpoints. + */ + dataepstatus &= NRF_USBD_COMMON_EPIN_BIT_MASK; + } + + /* Prepare next packet on IN endpoints */ + while (dataepstatus) { + uint8_t bitpos = NRF_CTZ(dataepstatus); + + dataepstatus &= ~BIT(bitpos); + + usbd_in_packet_sent(bit2ep(bitpos)); + } +} + +/* Select endpoint for next DMA transfer. + * + * Passed value has at least one bit set. Each bit set indicates which endpoints + * can have data transferred between peripheral and USB stack buffer. + * + * Return bit position indicating which endpoint to transfer. + */ +static uint8_t usbd_dma_scheduler_algorithm(uint32_t req) +{ + /* Only prioritized scheduling mode is supported. */ + return NRF_CTZ(req); +} + +/* Process next DMA request, called at the end of interrupt handler */ +static void usbd_dmareq_process(void) +{ + uint32_t req = m_ep_dma_waiting & m_ep_ready; + struct net_buf *buf; + struct udc_ep_config *ep_cfg; + uint8_t *payload_buf; + size_t payload_len; + bool last_packet; + uint8_t pos; + + if (req == 0 || nrf_usbd_legacy_suspend_check() || + k_sem_take(&dma_available, K_NO_WAIT) != 0) { + /* DMA cannot be started */ + return; + } + + if (NRFX_USBD_CONFIG_DMASCHEDULER_ISO_BOOST && + ((req & USBD_EPISO_BIT_MASK) != 0)) { + pos = usbd_dma_scheduler_algorithm(req & USBD_EPISO_BIT_MASK); + } else { + pos = usbd_dma_scheduler_algorithm(req); + } + + nrf_usbd_common_ep_t ep = bit2ep(pos); + + if (ep == NRF_USBD_COMMON_EPIN8 && iso_fast_fill != NULL) { + /* ISO IN fast path: the packet is in iso_fast_buf, not a net_buf */ + m_ep_dma_waiting &= ~BIT(pos); + usbd_dma_pending_set(); + m_ep_ready &= ~BIT(pos); + iso_fast_dma = true; + iso_fast_stats.packets++; + dma_ep = ep; + usbd_ep_dma_start(ep, (uint32_t)iso_fast_ptr, iso_fast_len); + return; + } + + ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); + buf = udc_buf_peek(ep_cfg); + + __ASSERT_NO_MSG(buf); + + if (NRF_USBD_COMMON_EP_IS_IN(ep)) { + /* Device -> Host */ + payload_buf = buf->data; + + if (buf->len > udc_mps_ep_size(ep_cfg)) { + payload_len = udc_mps_ep_size(ep_cfg); + last_packet = false; + } else { + payload_len = buf->len; + last_packet = !udc_ep_buf_has_zlp(buf); + } + + if (!nrfx_is_in_ram(payload_buf)) { + __ASSERT_NO_MSG(payload_len <= NRF_USBD_COMMON_FEEDER_BUFFER_SIZE); + memcpy(m_tx_buffer, payload_buf, payload_len); + payload_buf = (uint8_t *)m_tx_buffer; + } + } else { + /* Host -> Device */ + const size_t received = nrf_usbd_legacy_epout_size_get(ep); + + payload_buf = net_buf_tail(buf); + payload_len = net_buf_tailroom(buf); + + __ASSERT_NO_MSG(nrfx_is_in_ram(payload_buf)); + + if (received > payload_len) { + LOG_ERR("buffer too small: r: %u, l: %u", received, payload_len); + } else { + payload_len = received; + } + + /* DMA will copy the received data, update the buffer here so received + * does not have to be stored (can be done because there is no cache). + */ + net_buf_add(buf, payload_len); + + last_packet = (udc_mps_ep_size(ep_cfg) != received) || + (net_buf_tailroom(buf) == 0); + } + + if (last_packet) { + m_ep_dma_waiting &= ~BIT(pos); + } + + usbd_dma_pending_set(); + m_ep_ready &= ~BIT(pos); + if (NRF_USBD_COMMON_ISO_DEBUG || (!NRF_USBD_COMMON_EP_IS_ISO(ep))) { + LOG_DBG("USB DMA process: Starting transfer on EP: %x, size: %u", + ep, payload_len); + } + + /* Start transfer to the endpoint buffer */ + dma_ep = ep; + usbd_ep_dma_start(ep, (uint32_t)payload_buf, payload_len); +} + +static inline void usbd_errata_171_begin(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_171_end(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x00000000; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x00000000; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_187_211_begin(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006ED14)) = 0x00000003; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006ED14)) = 0x00000003; + } + + irq_unlock(irq_lock_key); +} + +static inline void usbd_errata_187_211_end(void) +{ + unsigned int irq_lock_key = irq_lock(); + + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006ED14)) = 0x00000000; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006ED14)) = 0x00000000; + } + + irq_unlock(irq_lock_key); +} + +static void nrf_usbd_peripheral_enable(void) +{ + if (nrf_usbd_common_errata_187()) { + usbd_errata_187_211_begin(); + } + + if (nrf_usbd_common_errata_171()) { + usbd_errata_171_begin(); + } + + /* Enable the peripheral */ + NRF_USBD->ENABLE = 1; + + /* Waiting for peripheral to enable, this should take a few us */ + while ((NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_READY_Msk) == 0) { + } + NRF_USBD->EVENTCAUSE = USBD_EVENTCAUSE_READY_Msk; + + if (nrf_usbd_common_errata_171()) { + usbd_errata_171_end(); + } + + if (nrf_usbd_common_errata_187()) { + usbd_errata_187_211_end(); + } +} + +static void nrf_usbd_irq_handler(void) +{ + volatile uint32_t *dma_endevent; + uint32_t epdatastatus = 0; + + /* Always check and clear SOF but call handler only if SOF interrupt + * is actually enabled. + */ + if (NRF_USBD->EVENTS_SOF) { + NRF_USBD->EVENTS_SOF = 0; + if (NRF_USBD->INTENSET & USBD_INTEN_SOF_Msk) { + ev_sof_handler(); + } + } + + /* Clear EPDATA event and only then get and clear EPDATASTATUS to make + * sure we don't miss any event. + */ + if (NRF_USBD->EVENTS_EPDATA) { + NRF_USBD->EVENTS_EPDATA = 0; + epdatastatus = NRF_USBD->EPDATASTATUS; + NRF_USBD->EPDATASTATUS = epdatastatus; + } + + /* Use common variable to store EP0DATADONE processing needed flag */ + if (NRF_USBD->EVENTS_EP0DATADONE) { + NRF_USBD->EVENTS_EP0DATADONE = 0; + epdatastatus |= BIT(ep2bit(m_ep0_data_dir)); + } + + /* Check DMA end event only for last enabled DMA channel. Other channels + * cannot be active and there's no harm in rechecking the event multiple + * times (it is not a problem to check it even if DMA is not active). + * + * It is important to check DMA and handle DMA finished event before + * handling acknowledged data transfer bits (epdatastatus) to avoid + * a race condition between interrupt handler and host IN token. + */ + dma_endevent = usbd_ep_to_endevent(dma_ep); + if (*dma_endevent) { + *dma_endevent = 0; + nrf_usbd_dma_finished(dma_ep); + } + + /* Process acknowledged transfers so we can prepare next DMA (if any) */ + ev_epdata_handler(epdatastatus); + + if (NRF_USBD->EVENTS_USBRESET) { + NRF_USBD->EVENTS_USBRESET = 0; + ev_usbreset_handler(); + } + + if (NRF_USBD->EVENTS_USBEVENT) { + NRF_USBD->EVENTS_USBEVENT = 0; + ev_usbevent_handler(); + } + + /* Handle SETUP only if there is no active DMA on EP0 */ + if (unlikely(NRF_USBD->EVENTS_EP0SETUP) && + (k_sem_count_get(&dma_available) || + (dma_ep != NRF_USBD_COMMON_EPIN0 && dma_ep != NRF_USBD_COMMON_EPOUT0))) { + NRF_USBD->EVENTS_EP0SETUP = 0; + ev_setup_handler(); + } + + usbd_dmareq_process(); +} + +static void nrf_usbd_legacy_enable(void) +{ + /* Prepare for READY event receiving */ + NRF_USBD->EVENTCAUSE = USBD_EVENTCAUSE_READY_Msk; + + nrf_usbd_peripheral_enable(); + + if (nrf_usbd_common_errata_223() && m_first_enable) { + NRF_USBD->ENABLE = 0; + + nrf_usbd_peripheral_enable(); + + m_first_enable = false; + } + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_187() || nrf_usbd_common_errata_211()) { +#else + if (nrf_usbd_common_errata_187()) { +#endif + usbd_errata_187_211_begin(); + } + + if (nrf_usbd_common_errata_166()) { + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x800)) = 0x7E3; + *((volatile uint32_t *)((uint32_t)(NRF_USBD) + 0x804)) = 0x40; + __ISB(); + __DSB(); + } + + NRF_USBD->ISOSPLIT = USBD_ISOSPLIT_SPLIT_HalfIN << USBD_ISOSPLIT_SPLIT_Pos; + + if (IS_ENABLED(CONFIG_NRF_USBD_ISO_IN_ZLP)) { + NRF_USBD->ISOINCONFIG = USBD_ISOINCONFIG_RESPONSE_ZeroData + << USBD_ISOINCONFIG_RESPONSE_Pos; + } else { + NRF_USBD->ISOINCONFIG = USBD_ISOINCONFIG_RESPONSE_NoResp + << USBD_ISOINCONFIG_RESPONSE_Pos; + } + + m_ep_ready = (((1U << NRF_USBD_COMMON_EPIN_CNT) - 1U) << NRF_USBD_COMMON_EPIN_BITPOS_0); + m_ep_dma_waiting = 0; + m_ep_armed = 0; + m_dma_odd = 0; + __ASSERT_NO_MSG(k_sem_count_get(&dma_available) == 1); + usbd_dma_pending_clear(); + m_ep0_data_dir = USB_CONTROL_EP_OUT; + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_187() && !nrf_usbd_common_errata_211()) { +#else + if (nrf_usbd_common_errata_187()) { +#endif + usbd_errata_187_211_end(); + } +} + +static void nrf_usbd_legacy_disable(void) +{ + /* Make sure DMA is not active */ + k_sem_take(&dma_available, K_FOREVER); + + /* Stop just in case */ + nrf_usbd_common_stop(); + + /* Disable all parts */ + if (m_dma_odd) { + /* Prevent invalid bus request after next USBD enable by ensuring + * that total number of bytes transferred by DMA is even. + */ + NRF_USBD->EVENTS_ENDEPIN[0] = 0; + usbd_ep_dma_start(NRF_USBD_COMMON_EPIN0, (uint32_t)&m_dma_odd, 1); + while (!NRF_USBD->EVENTS_ENDEPIN[0]) { + } + NRF_USBD->EVENTS_ENDEPIN[0] = 0; + m_dma_odd = 0; + } + NRF_USBD->ENABLE = 0; + usbd_dma_pending_clear(); + k_sem_give(&dma_available); + +#if NRF_USBD_COMMON_USE_WORKAROUND_FOR_ANOMALY_211 + if (nrf_usbd_common_errata_211()) { + usbd_errata_187_211_end(); + } +#endif +} + +static void nrf_usbd_legacy_start(bool enable_sof) +{ + m_bus_suspend = false; + + uint32_t int_mask = USBD_INTEN_USBRESET_Msk | USBD_INTEN_ENDEPIN0_Msk | + USBD_INTEN_ENDEPIN1_Msk | USBD_INTEN_ENDEPIN2_Msk | + USBD_INTEN_ENDEPIN3_Msk | USBD_INTEN_ENDEPIN4_Msk | + USBD_INTEN_ENDEPIN5_Msk | USBD_INTEN_ENDEPIN6_Msk | + USBD_INTEN_ENDEPIN7_Msk | USBD_INTEN_EP0DATADONE_Msk | + USBD_INTEN_ENDISOIN_Msk | USBD_INTEN_ENDEPOUT0_Msk | + USBD_INTEN_ENDEPOUT1_Msk | USBD_INTEN_ENDEPOUT2_Msk | + USBD_INTEN_ENDEPOUT3_Msk | USBD_INTEN_ENDEPOUT4_Msk | + USBD_INTEN_ENDEPOUT5_Msk | USBD_INTEN_ENDEPOUT6_Msk | + USBD_INTEN_ENDEPOUT7_Msk | USBD_INTEN_ENDISOOUT_Msk | + USBD_INTEN_USBEVENT_Msk | USBD_INTEN_EP0SETUP_Msk | + USBD_INTEN_EPDATA_Msk; + + if (enable_sof) { + int_mask |= USBD_INTEN_SOF_Msk; + } + + /* Enable all required interrupts */ + NRF_USBD->INTEN = int_mask; + + /* Enable interrupt globally */ + irq_enable(USBD_IRQn); + + /* Enable pullups */ + NRF_USBD->USBPULLUP = 1; +} + +static void nrf_usbd_common_stop(void) +{ + /* Clear interrupt */ + NVIC_ClearPendingIRQ(USBD_IRQn); + + if (irq_is_enabled(USBD_IRQn)) { + /* Abort transfers */ + usbd_ep_abort_all(); + + /* Disable pullups */ + NRF_USBD->USBPULLUP = 0; + + /* Disable interrupt globally */ + irq_disable(USBD_IRQn); + + /* Disable all interrupts */ + NRF_USBD->INTEN = 0; + } +} + +static bool nrf_usbd_legacy_suspend(void) +{ + bool suspended = false; + unsigned int irq_lock_key; + + /* DMA doesn't work in Low Power mode, ensure there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + irq_lock_key = irq_lock(); + + if (m_bus_suspend) { + if (!(NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_RESUME_Msk)) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_LowPower + << USBD_LOWPOWER_LOWPOWER_Pos; + (void)NRF_USBD->LOWPOWER; + if (NRF_USBD->EVENTCAUSE & USBD_EVENTCAUSE_RESUME_Msk) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_ForceNormal + << USBD_LOWPOWER_LOWPOWER_Pos; + } else { + suspended = true; + } + } + } + + irq_unlock(irq_lock_key); + k_sem_give(&dma_available); + + return suspended; +} + +static bool nrf_usbd_legacy_wakeup_req(void) +{ + bool started = false; + unsigned int irq_lock_key = irq_lock(); + + if (m_bus_suspend && nrf_usbd_legacy_suspend_check()) { + NRF_USBD->LOWPOWER = USBD_LOWPOWER_LOWPOWER_ForceNormal + << USBD_LOWPOWER_LOWPOWER_Pos; + started = true; + + if (nrf_usbd_common_errata_171()) { + if (*((volatile uint32_t *)(0x4006EC00)) == 0x00000000) { + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + *((volatile uint32_t *)(0x4006EC00)) = 0x00009375; + } else { + *((volatile uint32_t *)(0x4006EC14)) = 0x000000C0; + } + } + } + + irq_unlock(irq_lock_key); + + return started; +} + +static bool nrf_usbd_legacy_suspend_check(void) +{ + return NRF_USBD->LOWPOWER != + (USBD_LOWPOWER_LOWPOWER_ForceNormal << USBD_LOWPOWER_LOWPOWER_Pos); +} + +static bool nrf_usbd_legacy_ep_enable_check(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + NRF_USBD_COMMON_ASSERT_EP_VALID(ep); + + return (ep_in ? NRF_USBD->EPINEN : NRF_USBD->EPOUTEN) & BIT(ep_num); +} + +static void nrf_usbd_legacy_ep_enable(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + if (nrf_usbd_legacy_ep_enable_check(ep)) { + return; + } + + if (ep_in) { + NRF_USBD->EPINEN |= BIT(ep_num); + } else { + NRF_USBD->EPOUTEN |= BIT(ep_num); + } +} + +static void nrf_usbd_legacy_ep_disable(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + /* Only disable endpoint if there is no active DMA */ + k_sem_take(&dma_available, K_FOREVER); + usbd_ep_abort(ep); + if (ep_in) { + NRF_USBD->EPINEN &= ~BIT(ep_num); + } else { + NRF_USBD->EPOUTEN &= ~BIT(ep_num); + } + k_sem_give(&dma_available); + + /* This function was holding DMA semaphore and could potentially prevent + * next DMA from executing. Fire IRQ handler to check if any DMA needs + * to be started. + */ + usbd_int_rise(); +} + +static void nrf_usbd_start_transfer(uint8_t ep) +{ + const uint8_t ep_bitpos = ep2bit(ep); + unsigned int irq_lock_key = irq_lock(); + + if (ep >= NRF_USBD_COMMON_EPOUT1 && ep <= NRF_USBD_COMMON_EPOUT7) { + if (!(m_ep_armed & BIT(ep_bitpos)) && + !(m_ep_ready & BIT(ep_bitpos))) { + /* Allow receiving DATA packet on OUT endpoint */ + NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)] = 0; + m_ep_armed |= BIT(ep_bitpos); + } + } else if (ep == NRF_USBD_COMMON_EPIN8) { + /* ISO IN endpoint can be already armed if application is double + * buffering ISO IN data. When the endpoint is already armed it + * must not be ready for next DMA transfer (until SOF). + */ + __ASSERT(!(m_ep_armed & BIT(ep_bitpos)) || + !(m_ep_ready & BIT(ep_bitpos)), + "ISO IN must not be armed and ready"); + } else if (NRF_USBD_COMMON_EP_IS_IN(ep)) { + /* IN endpoint must not have data armed */ + __ASSERT(!(m_ep_armed & BIT(ep_bitpos)), + "ep 0x%02x already armed", ep); + } + + __ASSERT(!(m_ep_dma_waiting & BIT(ep_bitpos)), + "ep 0x%02x already waiting", ep); + + m_ep_dma_waiting |= BIT(ep_bitpos); + usbd_int_rise(); + + irq_unlock(irq_lock_key); +} + +static size_t nrf_usbd_legacy_epout_size_get(nrf_usbd_common_ep_t ep) +{ + if (NRF_USBD_COMMON_EP_IS_ISO(ep)) { + size_t size = NRF_USBD->SIZE.ISOOUT; + + if ((size & USBD_SIZE_ISOOUT_ZERO_Msk) == + (USBD_SIZE_ISOOUT_ZERO_ZeroData << USBD_SIZE_ISOOUT_ZERO_Pos)) { + size = 0; + } + return size; + } + + return NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)]; +} + +static void nrf_usbd_legacy_ep_stall(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + LOG_DBG("USB: EP %x stalled.", ep); + NRF_USBD->EPSTALL = (USBD_EPSTALL_STALL_Stall << USBD_EPSTALL_STALL_Pos) | ep; +} + +static bool nrf_usbd_legacy_ep_stall_check(nrf_usbd_common_ep_t ep) +{ + int ep_in = NRF_USBD_COMMON_EP_IS_IN(ep); + int ep_num = NRF_USBD_COMMON_EP_NUM(ep); + + if (!NRF_USBD_COMMON_EP_IS_ISO(ep_num)) { + if (ep_in) { + return NRF_USBD->HALTED.EPIN[ep_num]; + } else { + return NRF_USBD->HALTED.EPOUT[ep_num]; + } + } + + return false; +} + +static void nrf_usbd_legacy_ep_stall_clear(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + if (NRF_USBD_COMMON_EP_IS_OUT(ep) && nrf_usbd_legacy_ep_stall_check(ep)) { + nrf_usbd_legacy_transfer_out_drop(ep); + } + NRF_USBD->EPSTALL = (USBD_EPSTALL_STALL_UnStall << USBD_EPSTALL_STALL_Pos) | ep; +} + +static void nrf_usbd_legacy_ep_dtoggle_clear(nrf_usbd_common_ep_t ep) +{ + __ASSERT_NO_MSG(!NRF_USBD_COMMON_EP_IS_ISO(ep)); + + NRF_USBD->DTOGGLE = ep | (USBD_DTOGGLE_VALUE_Nop << USBD_DTOGGLE_VALUE_Pos); + NRF_USBD->DTOGGLE = ep | (USBD_DTOGGLE_VALUE_Data0 << USBD_DTOGGLE_VALUE_Pos); +} + +static void nrf_usbd_legacy_transfer_out_drop(nrf_usbd_common_ep_t ep) +{ + unsigned int irq_lock_key = irq_lock(); + + __ASSERT_NO_MSG(NRF_USBD_COMMON_EP_IS_OUT(ep)); + + m_ep_ready &= ~(1U << ep2bit(ep)); + if (!NRF_USBD_COMMON_EP_IS_ISO(ep)) { + NRF_USBD->SIZE.EPOUT[NRF_USBD_COMMON_EP_NUM(ep)] = 0; + } + + irq_unlock(irq_lock_key); +} + +struct udc_nrf_config { + clock_control_subsys_t clock; + nrfx_power_config_t pwr; + nrfx_power_usbevt_config_t evt; +}; + +static struct onoff_manager *hfxo_mgr; +static struct onoff_client hfxo_cli; + +static void udc_event_xfer_in_next(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(dev, ep); + struct net_buf *buf; + + if (udc_ep_is_busy(ep_cfg)) { + return; + } + + buf = udc_buf_peek(ep_cfg); + if (buf == NULL) { + return; + } + + if (ep == USB_CONTROL_EP_IN) { + const struct udc_buf_info *bi = udc_get_buf_info(buf); + + if (bi->data) { + m_ep0_data_dir = USB_CONTROL_EP_IN; + } + + if (bi->status) { + if (!udc_nrf_setup_set_addr) { + /* Allow status stage */ + NRF_USBD->TASKS_EP0STATUS = 1; + } + + /* Controller automatically performs status IN + * stage and SW cannot know when it is done. + */ + buf = udc_buf_get(ep_cfg); + udc_submit_ep_event(dev, buf, 0); + return; + } + } + + nrf_usbd_start_transfer(ep); + udc_ep_set_busy(ep_cfg, true); +} + +static void udc_event_xfer_in(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg; + struct net_buf *buf; + + ep_cfg = udc_get_ep_cfg(dev, ep); + + buf = udc_buf_get(ep_cfg); + if (buf == NULL) { + LOG_ERR("ep 0x%02x queue is empty", ep); + __ASSERT_NO_MSG(false); + return; + } + + udc_ep_set_busy(ep_cfg, false); + udc_submit_ep_event(dev, buf, 0); + + if (ep == USB_CONTROL_EP_IN) { + __ASSERT(udc_get_buf_info(buf)->data, "EP0IN buf is not data"); + + udc_nrf_ctrl_data_in_finished = true; + + /* STALL any further IN tokens, allow status stage */ + NRF_USBD->TASKS_EP0STATUS = 1; + + /* Software won't know when status stage finishes, if we have + * status OUT pending, just complete it. + */ + ep_cfg = udc_get_ep_cfg(dev, USB_CONTROL_EP_OUT); + buf = udc_buf_get(ep_cfg); + if (buf != NULL) { + __ASSERT(udc_get_buf_info(buf)->status, "EP0OUT buf is not status"); + udc_submit_ep_event(dev, buf, 0); + } + } +} + +static void udc_event_xfer_out_next(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg = udc_get_ep_cfg(dev, ep); + struct net_buf *buf; + + if (udc_ep_is_busy(ep_cfg)) { + return; + } + + buf = udc_buf_peek(ep_cfg); + if (buf != NULL) { + if (ep == USB_CONTROL_EP_OUT) { + struct udc_buf_info *bi = udc_get_buf_info(buf); + + if (bi->setup) { + /* SETUP can be received without any action */ + return; + } + + if (bi->data) { + m_ep0_data_dir = USB_CONTROL_EP_OUT; + + /* Allow receiving first OUT Data Stage packet */ + NRF_USBD->TASKS_EP0RCVOUT = 1; + } + + if (bi->status) { + if (udc_nrf_ctrl_data_in_finished) { + udc_submit_ep_event(dev, buf, 0); + } + + return; + } + } + + nrf_usbd_start_transfer(ep); + udc_ep_set_busy(ep_cfg, true); + } else { + LOG_DBG("ep 0x%02x waiting, queue is empty", ep); + } +} + +static void udc_event_xfer_out(const struct device *dev, const uint8_t ep) +{ + struct udc_ep_config *ep_cfg; + struct net_buf *buf; + + ep_cfg = udc_get_ep_cfg(dev, ep); + buf = udc_buf_get(ep_cfg); + if (buf == NULL) { + LOG_ERR("ep 0x%02x ok, queue is empty", ep); + return; + } + + udc_ep_set_busy(ep_cfg, false); + udc_submit_ep_event(dev, buf, 0); +} + +static int udc_event_xfer_setup(const struct device *dev) +{ + struct usb_setup_packet setup; + + udc_nrf_ctrl_data_in_finished = false; + + setup.bmRequestType = NRF_USBD->BMREQUESTTYPE; + setup.bRequest = NRF_USBD->BREQUEST; + setup.wValue = NRF_USBD->WVALUEL | (NRF_USBD->WVALUEH << 8); + setup.wIndex = NRF_USBD->WINDEXL | (NRF_USBD->WINDEXH << 8); + setup.wLength = NRF_USBD->WLENGTHL | (NRF_USBD->WLENGTHH << 8); + + /* USBD peripheral automatically handles Set Address in slightly + * different manner than the USB stack. + * + * USBD peripheral doesn't care about wLength, but the peripheral + * switches to new address only after status stage. The device won't + * automatically accept Data Stage packets. + * + * However, in the case the host: + * * sends SETUP Set Address with non-zero wLength + * * does not send corresponding OUT DATA packets (to match wLength) + * or sends the packets but disregards NAK + * or sends the packets that device ACKs + * * sends IN token (either incorrectly proceeds to status stage, or + * manages to send IN before SW sets STALL) + * then the USBD peripheral will accept the address and USB stack won't. + * This will lead to state mismatch between the stack and peripheral. + * + * In cases where the USB stack would like to STALL the request there is + * a race condition between host issuing Set Address status stage (IN + * token) and SW setting STALL bit. If host wins the race, the device + * ACKs status stage and use new address. If device wins the race, the + * device STALLs status stage and address remains unchanged. + */ + udc_nrf_setup_set_addr = + setup.bmRequestType == 0 && + setup.bRequest == USB_SREQ_SET_ADDRESS; + if (udc_nrf_setup_set_addr) { + if (setup.wLength) { + /* Currently USB stack only STALLs OUT Data Stage when + * buffer allocation fails. To prevent the device from + * ACKing the Data Stage, simply ignore the request + * completely. + * + * If host incorrectly proceeds to status stage there + * will be address mismatch (unless the new address is + * equal to current device address). If host does not + * issue IN token then the mismatch will be avoided. + */ + return 0; + } + + /* nRF52/nRF53 USBD doesn't care about wValue bits 8..15 and + * wIndex value but USB device stack does. + * + * Just clear the bits so stack will handle the request in the + * same way as USBD peripheral does, avoiding the mismatch. + */ + setup.wValue &= 0x7F; + setup.wIndex = 0; + } + + if (!udc_nrf_setup_set_addr && udc_nrf_address != NRF_USBD->USBADDR) { + /* Address mismatch detected. Fake Set Address handling to + * correct the situation, then repeat handling. + */ + udc_nrf_fake_setup = true; + udc_nrf_setup_set_addr = true; + + setup.bmRequestType = 0; + setup.bRequest = USB_SREQ_SET_ADDRESS; + setup.wValue = NRF_USBD->USBADDR; + setup.wIndex = 0; + setup.wLength = 0; + } else { + udc_nrf_fake_setup = false; + } + + udc_setup_received(dev, &setup); + + return 0; +} + +static void udc_handle_ep_dequeue(const struct device *dev, + struct udc_ep_config *cfg) +{ + nrf_usbd_legacy_ep_abort(cfg->addr); + + udc_ep_cancel_queued(dev, cfg); + + udc_ep_set_busy(cfg, false); +} + +static void udc_nrf_thread_handler(const struct device *dev) +{ + uint32_t evt; + + /* Wait for at least one event */ + k_event_wait(&drv_evt, UINT32_MAX, false, K_FOREVER); + + /* Process all events that are set */ + evt = k_event_clear(&drv_evt, UINT32_MAX); + + if (evt & BIT(UDC_NRF_EVT_SUSPEND)) { + LOG_INF("SUSPEND state detected"); + nrf_usbd_legacy_suspend(); + udc_set_suspended(dev, true); + udc_submit_event(dev, UDC_EVT_SUSPEND, 0); + } + + if (evt & BIT(UDC_NRF_EVT_RESUME)) { + LOG_INF("RESUMING from suspend"); + udc_set_suspended(dev, false); + udc_submit_event(dev, UDC_EVT_RESUME, 0); + } + + if (evt & BIT(UDC_NRF_EVT_WUREQ)) { + LOG_INF("Remote wakeup initiated"); + udc_set_suspended(dev, false); + udc_submit_event(dev, UDC_EVT_RESUME, 0); + } + + if (evt & BIT(UDC_NRF_EVT_EP_FINISHED)) { + uint32_t eps = atomic_clear(&xfer_finished); + + while (eps) { + uint8_t bitpos = NRF_CTZ(eps); + nrf_usbd_common_ep_t ep = bit2ep(bitpos); + + eps &= ~BIT(bitpos); + + if (USB_EP_DIR_IS_IN(ep)) { + udc_event_xfer_in(dev, ep); + udc_event_xfer_in_next(dev, ep); + } else { + udc_event_xfer_out(dev, ep); + udc_event_xfer_out_next(dev, ep); + } + } + } + + if (evt & BIT(UDC_NRF_EVT_XFER)) { + uint32_t eps = atomic_clear(&xfer_new); + + while (eps) { + uint8_t bitpos = NRF_CTZ(eps); + nrf_usbd_common_ep_t ep = bit2ep(bitpos); + + eps &= ~BIT(bitpos); + + if (USB_EP_DIR_IS_IN(ep)) { + udc_event_xfer_in_next(dev, ep); + } else { + udc_event_xfer_out_next(dev, ep); + } + } + } + + if (evt & BIT(UDC_NRF_EVT_SETUP)) { + udc_event_xfer_setup(dev); + } + + if (evt & BIT(UDC_NRF_EVT_DEQUEUE)) { + udc_lock_internal(dev, K_FOREVER); + + while (m_ep_dequeue) { + struct udc_ep_config *ep_cfg; + uint8_t bitpos = NRF_CTZ(m_ep_dequeue); + + ep_cfg = udc_get_ep_cfg(dev, bit2ep(bitpos)); + udc_handle_ep_dequeue(dev, ep_cfg); + + /* If transfer actually finished before dequeue, then + * xfer_finished bit may be set. Just clear it. + */ + atomic_clear_bit(&xfer_finished, bitpos); + + m_ep_dequeue &= ~BIT(bitpos); + } + + /* Notify requestors that requested endpoints are dequeued */ + k_condvar_broadcast(&ep_dequeued); + + udc_unlock_internal(dev); + } +} + +static void udc_nrf_thread(void *p1, void *p2, void *p3) +{ + ARG_UNUSED(p2); + ARG_UNUSED(p3); + + const struct device *dev = p1; + + while (true) { + udc_nrf_thread_handler(dev); + } +} + +static void udc_nrf_power_handler(nrfx_power_usb_evt_t pwr_evt) +{ + switch (pwr_evt) { + case NRFX_POWER_USB_EVT_DETECTED: + LOG_DBG("POWER event detected"); + udc_submit_event(udc_nrf_dev, UDC_EVT_VBUS_READY, 0); + break; + case NRFX_POWER_USB_EVT_READY: + LOG_DBG("POWER event ready"); + nrf_usbd_legacy_start(IS_ENABLED(CONFIG_UDC_ENABLE_SOF)); + break; + case NRFX_POWER_USB_EVT_REMOVED: + LOG_DBG("POWER event removed"); + udc_submit_event(udc_nrf_dev, UDC_EVT_VBUS_REMOVED, 0); + break; + default: + LOG_ERR("Unknown power event %d", pwr_evt); + } +} + +void udc_nrf_iso_in_fast_set(udc_nrf_iso_in_fill_t fill, void *user_data, bool suppress_sof) +{ + unsigned int key = irq_lock(); + + iso_fast_user_data = user_data; + iso_fast_suppress_sof = suppress_sof; + iso_fast_fill = fill; + if (fill == NULL) { + /* A packet requested but not yet DMA'd is dropped; one in flight + * completes normally (iso_fast_dma). + */ + m_ep_dma_waiting &= ~BIT(ep2bit(NRF_USBD_COMMON_EPIN8)); + } + + irq_unlock(key); +} + +void udc_nrf_iso_in_fast_stats_get(struct udc_nrf_iso_in_fast_stats *stats) +{ + unsigned int key = irq_lock(); + + *stats = iso_fast_stats; + irq_unlock(key); +} + +static int udc_nrf_ep_enqueue(const struct device *dev, + struct udc_ep_config *cfg, + struct net_buf *buf) +{ + udc_buf_put(cfg, buf); + + atomic_set_bit(&xfer_new, ep2bit(cfg->addr)); + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_XFER)); + + return 0; +} + +static int udc_nrf_ep_dequeue(const struct device *dev, + struct udc_ep_config *cfg) +{ + struct udc_data *data = dev->data; + + /* Signal that we want to dequeue, variable is protected by UDC mutex */ + m_ep_dequeue |= BIT(ep2bit(cfg->addr)); + + /* Avoid context switch immediately after posting event */ + k_sched_lock(); + + /* Inform nRF UDC driver that there are endpoints to be dequeued */ + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_DEQUEUE)); + + /* Wait for endpoints to be dequeued, UDC mutex was acquired via + * api->lock() called in udc_ep_dequeue(). + */ + k_condvar_wait(&ep_dequeued, &data->mutex, K_FOREVER); + + k_sched_unlock(); + + return 0; +} + +static int udc_nrf_ep_enable(const struct device *dev, + struct udc_ep_config *cfg) +{ + uint16_t mps; + + __ASSERT_NO_MSG(cfg); + mps = (udc_mps_ep_size(cfg) == 0) ? cfg->caps.mps : udc_mps_ep_size(cfg); + nrf_usbd_legacy_ep_enable(cfg->addr); + if (!NRF_USBD_EPISO_CHECK(cfg->addr)) { + /* ISO transactions for full-speed device do not support + * toggle sequencing and should only send DATA0 PID. + */ + nrf_usbd_legacy_ep_dtoggle_clear(cfg->addr); + nrf_usbd_legacy_ep_stall_clear(cfg->addr); + } + + LOG_DBG("Enable ep 0x%02x", cfg->addr); + + return 0; +} + +static int udc_nrf_ep_disable(const struct device *dev, + struct udc_ep_config *cfg) +{ + __ASSERT_NO_MSG(cfg); + nrf_usbd_legacy_ep_disable(cfg->addr); + LOG_DBG("Disable ep 0x%02x", cfg->addr); + + return 0; +} + +static int udc_nrf_ep_set_halt(const struct device *dev, + struct udc_ep_config *cfg) +{ + LOG_DBG("Halt ep 0x%02x", cfg->addr); + + if (cfg->addr == USB_CONTROL_EP_OUT || + cfg->addr == USB_CONTROL_EP_IN) { + NRF_USBD->TASKS_EP0STALL = 1; + } else { + nrf_usbd_legacy_ep_stall(cfg->addr); + } + + return 0; +} + +static int udc_nrf_ep_clear_halt(const struct device *dev, + struct udc_ep_config *cfg) +{ + LOG_DBG("Clear halt ep 0x%02x", cfg->addr); + + nrf_usbd_legacy_ep_dtoggle_clear(cfg->addr); + nrf_usbd_legacy_ep_stall_clear(cfg->addr); + + return 0; +} + +static int udc_nrf_set_address(const struct device *dev, const uint8_t addr) +{ + /* + * If the status stage already finished (which depends entirely on when + * the host sends IN token) then NRF_USBD->USBADDR will have the same + * address, otherwise it won't (unless new address is unchanged). + * + * Store the address so the driver can detect address mismatches + * between USB stack and USBD peripheral. The mismatches can occur if: + * * SW has high enough latency in SETUP handling, or + * * Host did not issue Status Stage after Set Address request + * + * The SETUP handling latency is a problem because the Set Address is + * automatically handled by device. Because whole Set Address handling + * can finish in less than 21 us, the latency required (with perfect + * timing) to hit the issue is relatively short (2 ms Set Address + * recovery interval + negligible Set Address handling time). If host + * sends new SETUP before SW had a chance to read the Set Address one, + * the Set Address one will be overwritten without a trace. + */ + udc_nrf_address = addr; + + if (udc_nrf_fake_setup) { + /* Finished handling lost Set Address, now handle the pending + * SETUP transfer. + */ + k_event_post(&drv_evt, BIT(UDC_NRF_EVT_SETUP)); + } + + return 0; +} + +static int udc_nrf_host_wakeup(const struct device *dev) +{ + bool res = nrf_usbd_legacy_wakeup_req(); + + LOG_DBG("Host wakeup request"); + if (!res) { + return -EAGAIN; + } + + return 0; +} + +static int udc_nrf_enable(const struct device *dev) +{ + unsigned int key; + int ret; + + if (udc_ep_enable_internal(dev, USB_CONTROL_EP_OUT, + USB_EP_TYPE_CONTROL, UDC_NRF_EP0_SIZE, 0)) { + LOG_ERR("Failed to enable control endpoint"); + return -EIO; + } + + if (udc_ep_enable_internal(dev, USB_CONTROL_EP_IN, + USB_EP_TYPE_CONTROL, UDC_NRF_EP0_SIZE, 0)) { + LOG_ERR("Failed to enable control endpoint"); + return -EIO; + } + + sys_notify_init_spinwait(&hfxo_cli.notify); + ret = onoff_request(hfxo_mgr, &hfxo_cli); + if (ret < 0) { + LOG_ERR("Failed to start HFXO %d", ret); + return ret; + } + + /* Disable interrupts until USBD is enabled */ + key = irq_lock(); + nrf_usbd_legacy_enable(); + irq_unlock(key); + + return 0; +} + +static int udc_nrf_disable(const struct device *dev) +{ + int ret; + + nrf_usbd_legacy_disable(); + + if (udc_ep_disable_internal(dev, USB_CONTROL_EP_OUT)) { + LOG_ERR("Failed to disable control endpoint"); + return -EIO; + } + + if (udc_ep_disable_internal(dev, USB_CONTROL_EP_IN)) { + LOG_ERR("Failed to disable control endpoint"); + return -EIO; + } + + ret = onoff_cancel_or_release(hfxo_mgr, &hfxo_cli); + if (ret < 0) { + LOG_ERR("Failed to stop HFXO %d", ret); + return ret; + } + + return 0; +} + +static int udc_nrf_init(const struct device *dev) +{ + const struct udc_nrf_config *cfg = dev->config; + + hfxo_mgr = z_nrf_clock_control_get_onoff(cfg->clock); + +#ifdef CONFIG_HAS_HW_NRF_USBREG + /* Use CLOCK/POWER priority for compatibility with other series where + * USB events are handled by CLOCK interrupt handler. + */ + IRQ_CONNECT(USBREGULATOR_IRQn, + DT_IRQ(DT_INST(0, nordic_nrf_clock), priority), + nrfx_isr, nrfx_usbreg_irq_handler, 0); +#endif + + IRQ_CONNECT(DT_INST_IRQN(0), DT_INST_IRQ(0, priority), + nrfx_isr, nrf_usbd_irq_handler, 0); + + (void)nrfx_power_init(&cfg->pwr); + nrfx_power_usbevt_init(&cfg->evt); + + nrfx_power_usbevt_enable(); + LOG_INF("Initialized"); + + return 0; +} + +static int udc_nrf_shutdown(const struct device *dev) +{ + LOG_INF("shutdown"); + + nrfx_power_usbevt_disable(); + nrfx_power_usbevt_uninit(); + + return 0; +} + +static int udc_nrf_driver_init(const struct device *dev) +{ + struct udc_data *data = dev->data; + int err; + + LOG_INF("Preinit"); + udc_nrf_dev = dev; + k_mutex_init(&data->mutex); + k_thread_create(&drv_stack_data, drv_stack, + K_KERNEL_STACK_SIZEOF(drv_stack), + udc_nrf_thread, + (void *)dev, NULL, NULL, + K_PRIO_COOP(8), 0, K_NO_WAIT); + + k_thread_name_set(&drv_stack_data, "udc_nrfx"); + + for (int i = 0; i < ARRAY_SIZE(ep_cfg_out); i++) { + ep_cfg_out[i].caps.out = 1; + if (i == 0) { + ep_cfg_out[i].caps.control = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else if (i < (CFG_EPOUT_CNT + 1)) { + ep_cfg_out[i].caps.bulk = 1; + ep_cfg_out[i].caps.interrupt = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else { + ep_cfg_out[i].caps.iso = 1; + ep_cfg_out[i].caps.mps = NRF_USBD_COMMON_ISOSIZE / 2; + } + + ep_cfg_out[i].addr = USB_EP_DIR_OUT | i; + err = udc_register_ep(dev, &ep_cfg_out[i]); + if (err != 0) { + LOG_ERR("Failed to register endpoint"); + return err; + } + } + + for (int i = 0; i < ARRAY_SIZE(ep_cfg_in); i++) { + ep_cfg_in[i].caps.in = 1; + if (i == 0) { + ep_cfg_in[i].caps.control = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else if (i < (CFG_EPIN_CNT + 1)) { + ep_cfg_in[i].caps.bulk = 1; + ep_cfg_in[i].caps.interrupt = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_EPSIZE; + } else { + ep_cfg_in[i].caps.iso = 1; + ep_cfg_in[i].caps.mps = NRF_USBD_COMMON_ISOSIZE / 2; + } + + ep_cfg_in[i].addr = USB_EP_DIR_IN | i; + err = udc_register_ep(dev, &ep_cfg_in[i]); + if (err != 0) { + LOG_ERR("Failed to register endpoint"); + return err; + } + } + + data->caps.rwup = true; + data->caps.mps0 = UDC_NRF_MPS0; + data->caps.can_detect_vbus = true; + + return 0; +} + +static void udc_nrf_lock(const struct device *dev) +{ + udc_lock_internal(dev, K_FOREVER); +} + +static void udc_nrf_unlock(const struct device *dev) +{ + udc_unlock_internal(dev); +} + +static const struct udc_nrf_config udc_nrf_cfg = { + .clock = COND_CODE_1(NRF_CLOCK_HAS_HFCLK192M, + (CLOCK_CONTROL_NRF_SUBSYS_HF192M), + (CLOCK_CONTROL_NRF_SUBSYS_HF)), + .pwr = { + .dcdcen = (DT_PROP(DT_INST(0, nordic_nrf5x_regulator), regulator_initial_mode) + == NRF5X_REG_MODE_DCDC), +#if NRFX_POWER_SUPPORTS_DCDCEN_VDDH + .dcdcenhv = COND_CODE_1(CONFIG_SOC_SERIES_NRF52, + (DT_NODE_HAS_STATUS_OKAY(DT_INST(0, nordic_nrf52x_regulator_hv))), + (DT_NODE_HAS_STATUS_OKAY(DT_INST(0, nordic_nrf53x_regulator_hv)))), +#endif + }, + + .evt = { + .handler = udc_nrf_power_handler + }, +}; + +static struct udc_data udc_nrf_data = { + .mutex = Z_MUTEX_INITIALIZER(udc_nrf_data.mutex), + .priv = NULL, +}; + +static const struct udc_api udc_nrf_api = { + .lock = udc_nrf_lock, + .unlock = udc_nrf_unlock, + .init = udc_nrf_init, + .enable = udc_nrf_enable, + .disable = udc_nrf_disable, + .shutdown = udc_nrf_shutdown, + .set_address = udc_nrf_set_address, + .host_wakeup = udc_nrf_host_wakeup, + .ep_try_config = NULL, + .ep_enable = udc_nrf_ep_enable, + .ep_disable = udc_nrf_ep_disable, + .ep_set_halt = udc_nrf_ep_set_halt, + .ep_clear_halt = udc_nrf_ep_clear_halt, + .ep_enqueue = udc_nrf_ep_enqueue, + .ep_dequeue = udc_nrf_ep_dequeue, +}; + +DEVICE_DT_INST_DEFINE(0, udc_nrf_driver_init, NULL, + &udc_nrf_data, &udc_nrf_cfg, + POST_KERNEL, CONFIG_KERNEL_INIT_PRIORITY_DEVICE, + &udc_nrf_api); diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf_iso_in_fast.h b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf_iso_in_fast.h new file mode 100644 index 0000000..f96ad05 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/src/udc_nrf_iso_in_fast.h @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * @file + * @brief nRF USBD isochronous IN fast path. + * + * Streaming isochronous IN through the UDC API costs, every 1 ms frame: a SOF + * event to the usbd thread, an enqueue to the driver thread, a DMA-finished + * event back to the driver thread, and a completion to the usbd thread -- four + * thread wake-ups to move one packet. On an nRF52840 streaming 48 kHz stereo + * 16-bit audio that measured ~18% of the 64 MHz CPU. + * + * With the fast path registered, the driver asks the application for the next + * packet directly in the USBD interrupt at SOF, and DMAs it from its own buffer + * in the same interrupt. No net_buf, no event, no thread wake-up. + * + * The class driver (e.g. UAC2) still owns the endpoint: enumeration, alternate + * setting and enable/disable are unchanged, and the fast path only runs while + * the ISO IN endpoint is enabled. While it is registered, do not enqueue buffers + * on the ISO IN endpoint through the UDC API; they would not be sent. + */ + +#ifndef UDC_NRF_ISO_IN_FAST_H_ +#define UDC_NRF_ISO_IN_FAST_H_ + +#include +#include + +/** Largest packet the fast path sends: the ISO IN half of the ISO buffer. */ +#define UDC_NRF_ISO_IN_FAST_MAX 512 + +/** + * @brief Produce the next ISO IN packet. + * + * Called from the USBD interrupt at every SOF while the fast path is registered + * and the ISO IN endpoint is enabled. Must not block, and should be short: it + * runs at interrupt priority, once a millisecond. + * + * @param buf Write the packet here. Word aligned, in RAM. + * @param max Capacity of @p buf in bytes. + * @param user_data As given to udc_nrf_iso_in_fast_set(). + * + * @return Bytes to send this frame, at most @p max. 0 sends nothing: the host + * then gets no data (or a zero-length packet with NRF_USBD_ISO_IN_ZLP). + */ +typedef uint16_t (*udc_nrf_iso_in_fill_t)(uint8_t *buf, uint16_t max, void *user_data); + +/** + * @brief Register or remove the ISO IN fast path. + * + * @param fill Packet producer, or NULL to return to the UDC API path. + * @param user_data Passed to @p fill. + * @param suppress_sof Also stop posting UDC_EVT_SOF to the stack while the fast + * path is active, saving the usbd thread wake-up every + * frame. Only valid when no class needs SOF events -- for + * example no ISO OUT or feedback endpoint in UAC2. + */ +void udc_nrf_iso_in_fast_set(udc_nrf_iso_in_fill_t fill, void *user_data, bool suppress_sof); + +/** Counters, for diagnostics. */ +struct udc_nrf_iso_in_fast_stats { + uint32_t packets; /**< packets DMA'd to the ISO IN buffer */ + uint32_t replaced; /**< packets filled but not DMA'd before the next SOF */ + uint32_t empty; /**< frames where @ref udc_nrf_iso_in_fill_t returned 0 */ +}; + +void udc_nrf_iso_in_fast_stats_get(struct udc_nrf_iso_in_fast_stats *stats); + +#endif /* UDC_NRF_ISO_IN_FAST_H_ */ diff --git a/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/tools/check.sh b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/tools/check.sh new file mode 100644 index 0000000..326d754 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/tools/check.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# The patch IS the change: src/udc_nrf.c must equal the pristine upstream copy +# with patches/udc_nrf-iso-in-fast.patch applied. Regenerate the patch with +# tools/check.sh --regen +set -euo pipefail +D="$(cd "$(dirname "$0")/.." && pwd)" +UP="$D/patches/udc_nrf.c.upstream" +PATCH="$D/patches/udc_nrf-iso-in-fast.patch" +if [ "${1:-}" = "--regen" ]; then + (cd "$D" && diff -u --label a/drivers/usb/udc/udc_nrf.c --label b/drivers/usb/udc/udc_nrf.c \ + patches/udc_nrf.c.upstream src/udc_nrf.c > "$PATCH") || true + echo "regenerated $PATCH" +fi +T=$(mktemp -d); trap 'rm -rf "$T"' EXIT +cp "$UP" "$T/udc_nrf.c" +patch -s "$T/udc_nrf.c" "$PATCH" +cmp -s "$T/udc_nrf.c" "$D/src/udc_nrf.c" || { echo "!! src/udc_nrf.c differs from upstream + patch"; exit 1; } +echo "nrf-usbd-isofast: src/udc_nrf.c == upstream + patch" diff --git a/third_party/sp1-usb-audio/upstream/sp1/README.md b/third_party/sp1-usb-audio/upstream/sp1/README.md new file mode 100644 index 0000000..cce9639 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/README.md @@ -0,0 +1,98 @@ +# SP-1 USB audio example + +This is a standalone Zephyr firmware for the Teenage Engineering SP-1. It plays +a continuous 1 kHz sine wave at −12 dBFS through the speaker or headphones and +exposes the same tone to a computer as a 48 kHz, 16-bit stereo UAC2 input. The +speaker/headphone copy follows the SP-1 master volume; the USB copy stays at a +fixed −6 dB gain. + +The example includes the complete SP-1 power baseline rather than only the USB +audio path. **It has run on an SP-1** (both USB drivers, macOS, September +2026): power on and off, the tone on the speaker, Vol+/Vol- including held +repeat, headphones muting the speaker, a clean fixed-level USB recording, and the +bootloader still reachable afterwards were all checked. Not yet tried: unplugging +USB mid-stream. Keep a known-good image to +flash back all the same. + +## Controls and indicators + +- Hold **•• for 1.5 seconds** to power on. Track LED 1 lights during the hold, + followed by two Track 1→4 sweeps. Only recovery from a watchdog reset skips + the hold. Releasing early on battery returns immediately to `SYSTEM_OFF`. +- Hold **•• for 5 seconds** to power off. A ••+button combination never counts + toward that hold. Power-off mutes and resets the codecs, stops the audio + oscillator, darkens every LED, parks the outputs, and arms •• as the wake pin. +- **Vol+ and Vol−** control only the speaker/headphone output. A press changes + one of 16 perceptual steps; holding repeats after 500 ms and then every 110 ms. + The firmware boots at the quiet 45/256 setting, so press Vol+ for more level. +- Plugging in headphones mutes the speaker. Removing them restores it after the + same debounced jack detection used by the source firmware. +- The bottom side LED is the running indicator. While holding **••+Track 1**, + the side row shows the battery charge gauge instead. While off on USB, whole + quarters are solid and the next quarter blinks; all four are solid when full. + +The audio thread uses 128-frame blocks, a two-block I2S transmit queue, and +preemptible priority 0. The CS42L42 is frame master; the nRF52840 and TAS2505 are +slaves to its 48 kHz clock. The watchdog starvation guard yields if the main +loop has not fed the watchdog for 1.5 seconds. + +## Build + +The build needs `west`, `ZEPHYR_BASE`, and a Zephyr SDK selected with +`ZEPHYR_TOOLCHAIN_VARIANT=zephyr` and `ZEPHYR_SDK_INSTALL_DIR`. It was developed +against the Zephyr in nRF Connect SDK v3.3.0 (`sdk-zephyr` commit `fd9204a0`) and +Zephyr SDK 0.17.0. + +The `CONFIG_PM` Kconfig warning comes from the upstream `sp1` board's defconfig, +does not apply to the nRF52840, and is harmless. + +`prep.sh` stages, but does not commit, two pinned dependencies: + +- the `sp1` board from [softmodded/marisko](https://github.com/softmodded/marisko) + at `b787d90`; +- the unmodified `led`, `controls`, `buttons`, and `sp1_board` hardware files + from [bnjreece/feldd-sp1-firmware](https://github.com/bnjreece/feldd-sp1-firmware) + at `b70a3a2`. + +Set `SP1_BOARD_ROOT` and `FELDD_DIR` to existing checkouts at exactly those +commits. If either is unset, the script clones the pinned dependency into its +build cache. The staging directory must be outside every Git working tree; set +`SP1_BUILD_ROOT` if the default location is unsuitable. + +```sh +export ZEPHYR_TOOLCHAIN_VARIANT=zephyr +export ZEPHYR_SDK_INSTALL_DIR=/path/to/zephyr-sdk-0.17.0 +export ZEPHYR_BASE=/path/to/zephyr + +./sp1/prep.sh +SP1_ISOFAST=1 ./sp1/prep.sh +``` + +The first command builds with Zephyr's stock nRF USB driver. The second replaces +it with the optional `nrf-usbd-isofast` driver. `prep.sh` emits a flashable bare +application `.bin` and audits the vector address, watchdog, power path, audio +path, UAC2 symbols, I2S queue, and selected USB driver after linking. The USB +descriptor uses Zephyr's test VID/PID (`0x2fe3`/`0x0001`); use your own for any +distributed product. + +There is deliberately no CDC console. The power baseline does not need one, and +omitting it keeps this example focused on UAC2. + +## Flash with the stock bootloader + +1. Power the SP-1 off. +2. Hold Track 1 and Track 4, plug in USB-C, and keep holding until Track LED 1 + lights solid. Release the buttons. The power button is not part of this + combination. +3. In Chrome or Edge, open [Solderless](https://solderless.engineering), choose + its firmware utility, connect to the SP-1 bootloader, and upload the generated + `.bin`. Alternatively, use the `softmodded/rome` CLI: + + ```sh + rome flash -p /dev/your-serial-device path/to/sp1_usb_audio.bin + ``` + +After flashing, hold •• for 1.5 seconds to start the example. To return to the +bootloader later, hold •• for 5 seconds to power off, then repeat the Track 1+4 +procedure. Do not flash this untested example onto a unit that cannot be +recovered through its stock bootloader or SWD. diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/CMakeLists.txt b/third_party/sp1-usb-audio/upstream/sp1/fw/CMakeLists.txt new file mode 100644 index 0000000..61137b1 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/CMakeLists.txt @@ -0,0 +1,29 @@ +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20.0) +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +project(sp1_usb_audio_example) + +include(${ZEPHYR_BASE}/samples/subsys/usb/common/common.cmake) + +foreach(f src/usb_audio.c src/usb_audio.h src/uacring.c src/uacring.h + src/led.c src/led.h src/controls.c src/controls.h + src/buttons.c src/buttons.h src/sp1_board.h) + if(NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${f}) + message(FATAL_ERROR "${f} missing: build with sp1/prep.sh, which stages it") + endif() +endforeach() + +target_sources(app PRIVATE + src/main.c src/audio.c src/power.c src/gesture.c src/wdt.c + src/usb_audio.c src/uacring.c + src/led.c src/controls.c src/buttons.c) + +set_source_files_properties(src/uacring.c PROPERTIES + COMPILE_DEFINITIONS "UACRING_BARRIER=barrier_dmem_fence_full" + COMPILE_OPTIONS "-include;zephyr/sys/barrier.h") + +include(${CMAKE_CURRENT_SOURCE_DIR}/isofast/CMakeLists.txt) + +target_include_directories(app PRIVATE src) diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/Kconfig b/third_party/sp1-usb-audio/upstream/sp1/fw/Kconfig new file mode 100644 index 0000000..fa9bcdd --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/Kconfig @@ -0,0 +1,6 @@ +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 + +source "samples/subsys/usb/common/Kconfig.sample_usbd" +rsource "isofast/Kconfig" +source "Kconfig.zephyr" diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/app.overlay b/third_party/sp1-usb-audio/upstream/sp1/fw/app.overlay new file mode 100644 index 0000000..383d5ae --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/app.overlay @@ -0,0 +1,149 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include +#include +#include +#include +#include + +/ { + zephyr,user { + midi_ring_gpios = <&gpio0 23 GPIO_ACTIVE_LOW>; + io-channels = <&adc 0>, <&adc 1>, <&adc 2>, <&adc 3>, <&adc 4>, <&adc 5>, <&adc 6>; + }; + + /* led.c's fixed order: Track 1..4, then side LED 1..4. */ + feldd_leds: feldd-leds { + compatible = "pwm-leds"; + fled_t1: fled_t1 { pwms = <&pwm2 0 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_t2: fled_t2 { pwms = <&pwm2 1 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_t3: fled_t3 { pwms = <&pwm2 2 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_t4: fled_t4 { pwms = <&pwm2 3 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_p1: fled_p1 { pwms = <&pwm3 0 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_p2: fled_p2 { pwms = <&pwm3 1 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_p3: fled_p3 { pwms = <&pwm3 2 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + fled_p4: fled_p4 { pwms = <&pwm3 3 PWM_USEC(1024) PWM_POLARITY_NORMAL>; }; + }; + + uac2_synth: usb_audio2 { + compatible = "zephyr,uac2"; + status = "okay"; + full-speed; + audio-function = ; + + uac2_synth_clock: clock { + compatible = "zephyr,uac2-clock-source"; + clock-type = "internal-fixed"; + frequency-control = "read-only"; + sampling-frequencies = <48000>; + }; + + uac2_synth_in: synthesizer { + compatible = "zephyr,uac2-input-terminal"; + clock-source = <&uac2_synth_clock>; + terminal-type = ; + front-left; + front-right; + }; + + uac2_usb_out: usb_out { + compatible = "zephyr,uac2-output-terminal"; + data-source = <&uac2_synth_in>; + clock-source = <&uac2_synth_clock>; + terminal-type = ; + }; + + uac2_capture: capture { + compatible = "zephyr,uac2-audio-streaming"; + linked-terminal = <&uac2_usb_out>; + subslot-size = <2>; + bit-resolution = <16>; + }; + }; +}; + +&pwm2 { + status = "okay"; + pinctrl-0 = <&pwm2_default>; + pinctrl-1 = <&pwm2_sleep>; + pinctrl-names = "default", "sleep"; +}; + +&pwm3 { + status = "okay"; + pinctrl-0 = <&pwm3_default>; + pinctrl-1 = <&pwm3_sleep>; + pinctrl-names = "default", "sleep"; +}; + +&adc { + status = "okay"; + #address-cells = <1>; + #size-cells = <0>; + channel@0 { reg = <0>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@1 { reg = <1>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@2 { reg = <2>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@3 { reg = <3>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@4 { reg = <4>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@5 { reg = <5>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; + channel@6 { reg = <6>; zephyr,gain = "ADC_GAIN_1_6"; zephyr,reference = "ADC_REF_INTERNAL"; + zephyr,acquisition-time = ; + zephyr,input-positive = ; zephyr,resolution = <12>; }; +}; + +&i2s0_default { + group1 { + psels = , + , + ; + }; +}; + +&i2c0 { + clock-frequency = ; +}; + +&pinctrl { + pwm2_default: pwm2_default { + group1 { psels = , , + , ; }; + }; + pwm2_sleep: pwm2_sleep { + group1 { psels = , , + , ; + low-power-enable; }; + }; + pwm3_default: pwm3_default { + group1 { psels = , , + , ; }; + }; + pwm3_sleep: pwm3_sleep { + group1 { psels = , , + , ; + low-power-enable; }; + }; +}; + +zephyr_udc0: &usbd { + compatible = "nordic,nrf-usbd"; + status = "okay"; +}; + +&uart0 { + status = "disabled"; +}; diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/isofast.conf b/third_party/sp1-usb-audio/upstream/sp1/fw/isofast.conf new file mode 100644 index 0000000..05dfd40 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/isofast.conf @@ -0,0 +1,5 @@ +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 + +CONFIG_UDC_NRF=n +CONFIG_UDC_NRF_ISOFAST=y diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/prj.conf b/third_party/sp1-usb-audio/upstream/sp1/fw/prj.conf new file mode 100644 index 0000000..0816cf3 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/prj.conf @@ -0,0 +1,32 @@ +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 + +CONFIG_MAIN_THREAD_PRIORITY=7 +CONFIG_MAIN_STACK_SIZE=2048 + +CONFIG_FPU=y +CONFIG_GPIO=y +CONFIG_I2C=y +CONFIG_I2S=y +CONFIG_I2S_NRFX=y +CONFIG_PWM=y +CONFIG_ADC=y + +CONFIG_USB_DEVICE_STACK_NEXT=y +CONFIG_USBD_AUDIO2_CLASS=y +CONFIG_UDC_ENABLE_SOF=y + +# Zephyr's test VID/PID. Use your own for anything you distribute. +CONFIG_SAMPLE_USBD_VID=0x2fe3 +CONFIG_SAMPLE_USBD_PID=0x0001 +CONFIG_SAMPLE_USBD_PRODUCT="SP-1 USB audio example" +CONFIG_SAMPLE_USBD_MAX_POWER=50 + +CONFIG_HWINFO=y +CONFIG_PRINTK=y +CONFIG_LOG=n + +CONFIG_REBOOT=y +CONFIG_STACK_SENTINEL=y +CONFIG_HW_STACK_PROTECTION=n +CONFIG_CLOCK_CONTROL_NRF_K32SRC_SYNTH=y diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.c b/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.c new file mode 100644 index 0000000..1958c89 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.c @@ -0,0 +1,388 @@ +/* SP-1 audio bring-up. + * + * Ported from chattock/sp1-tape-looper, firmware/src/main.c (MIT), at 2565e79: + * tas2505_configure(), hp_codec_init() on its HP_TIM_TEST path, audio_thread() + * and audio_init(). Register values and the init ORDER are unchanged; that is + * the part proven on hardware. The CS42L42 sequence is Tim Knapen's + * (github.com/timknapen/SP-1-dev/wiki/I2C). + * + * Copyright (c) chattock, sp1-tape-looper contributors. MIT License. + * + * Clock topology: the 3.072 MHz oscillator (enabled on P0.13) drives SCLK; the + * CS42L42 is frame master and divides it by 64 to an exact 48 kHz LRCK; the + * nRF I2S and the TAS2505 are both slaves. + */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "audio.h" +#include "usb_audio.h" +#include "wdt.h" + +#include +#include +#include +#include +#include +#include +#include + +#define CS42_RST_PORT NRF_P0 +#define CS42_RST_PIN 15u +#define TAS_RST_PORT NRF_P0 +#define TAS_RST_PIN 9u /* an NFC pin: the board's uicr reclaims it as GPIO */ +#define OSC_EN_PORT NRF_P0 +#define OSC_EN_PIN 13u +#define CS42L42_ADDR 0x48u +#define TAS2505_ADDR 0x18u +#define BLK_BYTES (AUDIO_BLK_FRAMES * 2 * (int)sizeof(int16_t)) + +/* nrfx TX queue (2), two EasyDMA buffers, the block being filled, plus slack. */ +K_MEM_SLAB_DEFINE_STATIC(tx_slab, BLK_BYTES, 8, 4); + +static const struct device *const i2c_bus = DEVICE_DT_GET(DT_NODELABEL(i2c0)); +static const struct device *const i2s_dev = DEVICE_DT_GET(DT_NODELABEL(i2s0)); + +static volatile uint16_t vol_target = 45; /* main thread writes, audio thread reads */ +static audio_render_fn render_cb; +static bool cs42_up; +static bool i2s_started; +static int8_t hp_in = -1; + +static void gpio_drive_high(NRF_GPIO_Type *port, uint32_t pin) +{ + port->OUTSET = 1u << pin; + port->PIN_CNF[pin] = + (GPIO_PIN_CNF_DIR_Output << GPIO_PIN_CNF_DIR_Pos) | + (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos) | + (GPIO_PIN_CNF_INPUT_Connect << GPIO_PIN_CNF_INPUT_Pos); + port->OUTSET = 1u << pin; +} + +static void gpio_drive_low(NRF_GPIO_Type *port, uint32_t pin) +{ + port->OUTCLR = 1u << pin; +} + +/* BOOT CLICK, 2026-09-16. The speaker used to click as it came up: the DAC was + * unmuted on page 0 BEFORE any analog block existed, class-D gain was set to + * +18 dB and attenuation to 0 dB BEFORE the driver powered up, and every analog + * enable was a back-to-back I2C write with nothing allowed to settle. The amp + * was being switched on into a live path -- amp before preamp. + * + * Fixed by muting across the bring-up and unmuting last, plus two settling + * delays. NOT a volume problem: master volume is applied digitally -- a boot + * volume ramp would change nothing. This diverges from the looper's init order + * deliberately (Ryan, 2026-09-16). */ +/* ---- TAS2505 speaker amp (TI SLAU472C §5.1). PLL locked to BCLK: + * 3.072 MHz x J32 = 98.304 MHz / (NDAC2 x MDAC8 x DOSR128) = 48000 Hz. ---- */ +static int tas_wr(uint8_t reg, uint8_t val) +{ + return i2c_reg_write_byte(i2c_bus, TAS2505_ADDR, reg, val); +} + +static bool tas2505_configure(void) +{ + int rc = 0; + + rc |= tas_wr(0x00, 0x00); + rc |= tas_wr(0x01, 0x01); /* software reset */ + k_msleep(5); + + rc |= tas_wr(0x00, 0x01); + rc |= tas_wr(0x02, 0x00); /* LDO 1.8 V, level shifters up */ + + rc |= tas_wr(0x00, 0x00); + rc |= tas_wr(0x04, 0x07); /* PLL_CLKIN = BCLK, CODEC_CLKIN = PLL */ + rc |= tas_wr(0x05, 0x91); /* PLL on, P=1, R=1 */ + rc |= tas_wr(0x06, 0x20); /* J = 32 */ + rc |= tas_wr(0x07, 0x00); /* D = 0 */ + rc |= tas_wr(0x08, 0x00); + k_msleep(15); /* PLL lock */ + rc |= tas_wr(0x0B, 0x82); /* NDAC = 2 */ + rc |= tas_wr(0x0C, 0x88); /* MDAC = 8 */ + rc |= tas_wr(0x0D, 0x00); + rc |= tas_wr(0x0E, 0x80); /* DOSR = 128 */ + rc |= tas_wr(0x1B, 0x00); /* I2S, 16-bit, slave */ + rc |= tas_wr(0x1C, 0x00); + rc |= tas_wr(0x3C, 0x02); /* PRB_P2, mono */ + rc |= tas_wr(0x3F, 0x90); /* DAC up, left -> left, soft-step */ + rc |= tas_wr(0x41, 0x00); /* digital gain 0 dB */ + /* The DAC stays MUTED here -- its power-on-reset state -- through the whole + * analog bring-up below. The unmute moved to the end of this function; see + * the boot-click note above. */ + + rc |= tas_wr(0x00, 0x01); + rc |= tas_wr(0x01, 0x10); /* analog reference on */ + rc |= tas_wr(0x0A, 0x00); /* common mode 0.9 V */ + /* Let the common-mode node charge before anything drives a load. These were + * back-to-back I2C writes, which is the click. */ + k_msleep(20); + rc |= tas_wr(0x0C, 0x04); /* DAC -> output mixer */ + rc |= tas_wr(0x16, 0x00); + rc |= tas_wr(0x18, 0x00); + rc |= tas_wr(0x09, 0x20); /* HP driver up */ + rc |= tas_wr(0x10, 0x00); + rc |= tas_wr(0x2E, 0x00); /* speaker attenuation 0 dB */ + rc |= tas_wr(0x30, 0x30); /* class-D gain +18 dB */ + rc |= tas_wr(0x2D, 0x02); /* speaker driver up */ + /* And let the driver settle before the DAC is allowed to feed it. */ + k_msleep(20); + + rc |= tas_wr(0x00, 0x00); + /* Unmute LAST, into an already-settled analog path, and let the DAC's own + * soft-step (0x3F bit 4, set above) do the ramp. */ + rc |= tas_wr(0x40, 0x04); /* unmute */ + k_msleep(10); + return rc == 0; +} + +/* ---- CS42L42 headphones: paged register protocol ---- */ +static bool tpw(uint16_t reg, uint8_t val) +{ + uint8_t p[2] = { 0x00, (uint8_t)(reg >> 8) }; + uint8_t b[2] = { (uint8_t)reg, val }; + if (i2c_write(i2c_bus, p, 2, CS42L42_ADDR) != 0) return false; + return i2c_write(i2c_bus, b, 2, CS42L42_ADDR) == 0; +} + +static bool tpr(uint16_t reg, uint8_t *val) +{ + uint8_t p[2] = { 0x00, (uint8_t)(reg >> 8) }; + uint8_t o = (uint8_t)reg; + if (i2c_write(i2c_bus, p, 2, CS42L42_ADDR) != 0) return false; + return i2c_write_read(i2c_bus, CS42L42_ADDR, &o, 1, val, 1) == 0; +} + +static void hp_codec_init(void) +{ + uint8_t id[3] = { 0 }, pll; + + gpio_drive_low(CS42_RST_PORT, CS42_RST_PIN); /* without it the codec NAKs */ + k_msleep(5); + gpio_drive_high(CS42_RST_PORT, CS42_RST_PIN); + k_msleep(10); + + (void)tpr(0x1001, &id[0]); + (void)tpr(0x1002, &id[1]); + (void)tpr(0x1003, &id[2]); + if (id[0] != 0x42) return; + (void)tpw(0x1508, 0x10); /* PLL Control 3 */ + (void)tpw(0x1504, 0x80); /* PLL Division Fractional Byte 2 */ + (void)tpw(0x1505, 0x3E); /* PLL Division Integer */ + (void)tpw(0x150A, 0x7D); /* PLL Calibration Ratio */ + (void)tpw(0x1009, 0x00); /* MCLK Control */ + (void)tpw(0x1201, 0x01); /* MCLK Source Select */ + (void)tpw(0x120A, 0x01); /* Input ASRC Clock Select */ + (void)tpw(0x120B, 0x01); /* Output ASRC Clock Select */ + (void)tpw(0x1501, 0x01); /* PLL start */ + (void)tpw(0x1107, 0x01); /* Oscillator Switch: SCLK */ + for (int t = 0; t < 10; t++) { + k_msleep(1); + if (tpr(0x1109, &pll) && pll == 0x02) break; + } + (void)tpw(0x1007, 0x13); /* Serial Port SRC Control */ + (void)tpw(0x1203, 0x1F); /* FSYNC Pulse Width Lower (64-SCLK frame) */ + (void)tpw(0x1205, 0x3F); /* FSYNC Period Lower */ + (void)tpw(0x1207, 0x34); /* ASP Clock Config: MASTER */ + (void)tpw(0x1208, 0x1A); /* ASP Frame Configuration */ + (void)tpw(0x2A02, 0x02); /* Channel 1 */ + (void)tpw(0x2A05, 0x42); /* Channel 2 */ + (void)tpw(0x2601, 0x4C); /* SRC Input Sample Rate */ + (void)tpw(0x2609, 0x4C); /* SRC Output Sample Rate */ + (void)tpw(0x2A01, 0x0C); /* ASP Receive Enable */ + (void)tpw(0x240E, 0x01); /* Equalizer Input Mute Control */ + (void)tpw(0x2301, 0x00); /* Mixer A 0 dB */ + (void)tpw(0x2303, 0x00); /* Mixer B 0 dB */ + (void)tpw(0x1101, 0x96); /* power up */ + k_msleep(10); + (void)tpw(0x1121, 0x41); /* Headset switch control */ + (void)tpw(0x1B74, 0x03); /* Misc detect control */ + (void)tpw(0x1129, 0x01); /* Headset clamp disable */ + (void)tpw(0x2001, 0x0D); /* HP mute all */ + (void)tpw(0x1F06, 0x84); /* DAC Control 2 */ + (void)tpw(0x2301, 0x00); + (void)tpw(0x2303, 0x00); + (void)tpw(0x1B73, 0xC2); /* Tip Sense Control */ + (void)tpw(0x1B75, 0x9F); /* Mic detect control 1 */ + (void)tpw(0x2001, 0x01); /* unmute headphones */ + cs42_up = true; +} + +/* ---- speaker on/off: TAS2505 page 1, reg 0x2D (0x02 driver up, 0x00 off) ---- */ +static void tas_set_speaker(bool on) +{ + (void)tas_wr(0x00, 0x01); + (void)tas_wr(0x2D, on ? 0x02 : 0x00); + (void)tas_wr(0x00, 0x00); +} + +/* Headphones in the jack: CS42L42 DET_STATUS1 (page 0x1B, reg 0x77) bit 7, per + * Tim Knapen's wiki and the looper. 1 plugged, 0 not, -1 read failed. */ +static int hp_detect(void) +{ + uint8_t v; + if (!tpr(0x1B77, &v)) return -1; + return (v >> 7) & 1; +} + +void audio_set_volume_q8(uint16_t q8) +{ + vol_target = q8 > 256 ? 256 : q8; +} + +uint16_t audio_volume_q8(void) +{ + return vol_target; +} + +void audio_hp_poll(void) +{ + static int div, cand = -1, cnt; + if (!cs42_up || ++div < 4) return; + div = 0; + int c = hp_detect(); + if (c < 0) return; /* a failed read holds */ + if (c != cand) { + cand = c; + cnt = 1; + return; + } + if (++cnt >= 3 && c != hp_in) { + hp_in = (int8_t)c; + tas_set_speaker(!c); + } +} + +/* ---- power-down: the looper's power_off() order ---- */ +void audio_shutdown(void) +{ + /* SYSTEM_OFF stops only the nRF. Left powered, the amp and codec drain the + * battery for days and can murmur with no clock. Mute both output stages + * first so they discharge quietly, then reset them. */ + (void)tpw(0x2001, 0x0D); /* CS42L42 HP: mute all */ + (void)tas_wr(0x00, 0x01); + (void)tas_wr(0x30, 0x00); /* TAS2505 class-D driver: mute */ + k_msleep(30); + (void)tas_wr(0x00, 0x00); + (void)tas_wr(0x01, 0x01); /* TAS2505 software reset */ + gpio_drive_low(CS42_RST_PORT, CS42_RST_PIN); + gpio_drive_low(OSC_EN_PORT, OSC_EN_PIN); /* it draws through SYSTEM_OFF */ +} + +/* ---- the I2S thread ---- */ +static K_THREAD_STACK_DEFINE(audio_stack, 1536); +static struct k_thread audio_tcb; + +/* Blocks written before the I2S start: exactly the driver's TX queue, which is + * also what sets output latency (a new block plays after the ones queued). */ +#define AUDIO_PRIME CONFIG_I2S_NRFX_TX_BLOCK_COUNT + +static void prime(int n, k_timeout_t wait) +{ + for (int i = 0; i < n; i++) { + void *blk; + if (k_mem_slab_alloc(&tx_slab, &blk, wait) != 0) break; + memset(blk, 0, BLK_BYTES); + if (i2s_write(i2s_dev, blk, BLK_BYTES) != 0) k_mem_slab_free(&tx_slab, blk); + } +} + +static void audio_thread(void *a, void *b, void *c) +{ + ARG_UNUSED(a); + ARG_UNUSED(b); + ARG_UNUSED(c); + + struct i2s_config cfg = { + .word_size = 16, /* 16 MSBs of each 32-SCLK half-frame */ + .channels = 2, + .format = I2S_FMT_DATA_FORMAT_I2S, + .options = I2S_OPT_FRAME_CLK_SLAVE | I2S_OPT_BIT_CLK_SLAVE, + .frame_clk_freq = AUDIO_SR, + .mem_slab = &tx_slab, + .block_size = BLK_BYTES, + .timeout = 2000, + }; + + if (!device_is_ready(i2s_dev) || i2s_configure(i2s_dev, I2S_DIR_TX, &cfg) != 0) return; + prime(AUDIO_PRIME, K_FOREVER); + (void)i2s_trigger(i2s_dev, I2S_DIR_TX, I2S_TRIGGER_START); + i2s_started = true; + + int wfail = 0; + for (;;) { + /* STARVATION GUARD (2026-09-24). Main feeds the watchdog; this thread + * outranks it. When a render needs the whole CPU, main gets nothing and + * the watchdog resets the unit. If main has not fed it for 1.5 s, step + * aside for 20 ms: main finishes its pass and feeds it. The I2S queue runs + * dry -- a dropout, which the wfail path below recovers -- instead of a + * reset. Idle otherwise: main feeds every few ms. A truly hung main still + * stops feeding, so the watchdog still catches it. */ + if (wdt_ms_since_feed() > 1500u) k_msleep(20); + + void *blk; + if (k_mem_slab_alloc(&tx_slab, &blk, K_FOREVER) != 0) continue; + /* The slot's time is the audio clock's; the push after the render is + * late by the render. The USB regulator steers on this claim. */ + usb_audio_claim(AUDIO_BLK_FRAMES); + render_cb(blk, AUDIO_BLK_FRAMES); + /* The USB copy was pushed by render_cb itself (main.c): a second output + * at its own level, not this block. */ + if (i2s_write(i2s_dev, blk, BLK_BYTES) != 0) { + k_mem_slab_free(&tx_slab, blk); + /* A stopped stream fails every write forever: drop, re-prime, restart. */ + if (++wfail >= 8) { + wfail = 0; + (void)i2s_trigger(i2s_dev, I2S_DIR_TX, I2S_TRIGGER_DROP); + prime(AUDIO_PRIME, K_NO_WAIT); + (void)i2s_trigger(i2s_dev, I2S_DIR_TX, I2S_TRIGGER_START); + } + continue; + } + wfail = 0; + } +} + +void audio_start(audio_render_fn render) +{ + render_cb = render; + + /* The looper's order: resets, osc + I2S + TAS2505, then the CS42L42. */ + gpio_drive_high(CS42_RST_PORT, CS42_RST_PIN); + gpio_drive_high(TAS_RST_PORT, TAS_RST_PIN); + k_msleep(20); + gpio_drive_high(OSC_EN_PORT, OSC_EN_PIN); + k_msleep(5); + + /* PREEMPTIBLE, on purpose. Zephyr's USB threads (usbd, the nRF driver's) are + * K_PRIO_COOP(8) and outrank it, so USB work can land mid-render. Made + * K_PRIO_COOP(7) to stop that, a render that needs the whole CPU then starved + * main and the USB threads for 5 s and the WATCHDOG RESET the unit. Under + * overload a preemptible audio thread fails as a late block -- a glitch -- + * instead. */ + k_thread_create(&audio_tcb, audio_stack, K_THREAD_STACK_SIZEOF(audio_stack), + audio_thread, NULL, NULL, NULL, K_PRIO_PREEMPT(0), 0, K_NO_WAIT); + k_thread_name_set(&audio_tcb, "audio"); + + for (int i = 0; i < 100 && !i2s_started; i++) k_msleep(2); + (void)tas2505_configure(); + hp_codec_init(); + + /* Auto-mute boot state, the looper's: a majority of 5 reads, 8 ms apart. */ + if (cs42_up) { + int votes = 0, reads = 0; + for (int i = 0; i < 5; i++) { + int c = hp_detect(); + if (c >= 0) { + reads++; + votes += c; + } + k_msleep(8); + } + hp_in = (reads > 0 && votes * 2 > reads) ? 1 : 0; + tas_set_speaker(!hp_in); + } +} diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.h b/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.h new file mode 100644 index 0000000..341c4e4 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/audio.h @@ -0,0 +1,34 @@ +/* SP-1 audio output: CS42L42 headphones + TAS2505 speaker, 48 kHz 16-bit stereo. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#pragma once + +#include + +#define AUDIO_SR 48000 +/* 128 = 2.67 ms at 48 kHz: a new block plays after the ones queued, so latency + * scales with block length. */ +#define AUDIO_BLK_FRAMES 128 /* 2.67 ms at 48 kHz */ + +/* Fill `frames` interleaved stereo frames. Runs on the audio thread, + * PREEMPT(0): no blocking, no I2C, no printk. */ +typedef void (*audio_render_fn)(int16_t *lr, uint32_t frames); + +void audio_start(audio_render_fn render); +/* Mute and reset both output chips, stop the oscillator. Before SYSTEM_OFF + * only; main thread (it uses I2C). */ +void audio_shutdown(void); + +/* Master volume, Q8 (256 = unity). Main thread; the audio thread ramps to it + * across one block, as the looper does, so a step never clicks. */ +void audio_set_volume_q8(uint16_t q8); +/* Read the target volume for the audio thread's per-block ramp. */ +uint16_t audio_volume_q8(void); + +/* Headphone auto-mute of the speaker, the looper's: CS42L42 jack detect polled + * every 4th call (~40 ms at the 10 ms tick), switching only after 3 equal reads; + * a failed read holds. Main thread only -- the audio thread does no I2C. */ +void audio_hp_poll(void); diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.c b/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.c new file mode 100644 index 0000000..cc54401 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.c @@ -0,0 +1,111 @@ +/* gesture.c — see gesture.h. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "gesture.h" + +void gesture_init(struct gesture_state *s) +{ + s->func_ticks = 0; + s->func_armed = false; +} + +bool gesture_step(struct gesture_state *s, bool func_low) +{ + /* A •• already down at boot (the wake press, or a hold through a reset) + * must not start a power-off: feldd's func_armed rule. */ + if (!s->func_armed) { + if (!func_low) s->func_armed = true; + s->func_ticks = 0; + return false; + } + if (!func_low) { + s->func_ticks = 0; + return false; + } + return ++s->func_ticks >= GESTURE_OFF_TICKS; +} + +void gesture_cancel(struct gesture_state *s) +{ + s->func_ticks = 0; +} + +void wake_init(struct wake_state *s) +{ + s->held_ms = 0; +} + +enum wake wake_step(struct wake_state *s, bool func_low, bool usb_present) +{ + if (func_low) { + s->held_ms += WAKE_TICK_MS; + return s->held_ms >= WAKE_HOLD_MS ? WAKE_BOOT : WAKE_WAIT; + } + s->held_ms = 0; + return usb_present ? WAKE_WAIT : WAKE_OFF; +} + +int battery_pct(int raw) +{ + if (raw < 0) return -1; + int pct = (raw - BATT_RAW_EMPTY) * 100 / (BATT_RAW_FULL - BATT_RAW_EMPTY); + if (pct < 0) pct = 0; + if (pct > 100) pct = 100; + return pct; +} + +unsigned charge_gauge_bits(int pct, bool charging, unsigned tick) +{ + if (!charging) return 0xFu; + int n_full = pct < 0 ? 0 : pct / 25; + if (n_full > 4) n_full = 4; + unsigned bits = (1u << n_full) - 1u; + if (n_full < 4 && ((tick / GAUGE_BLINK_TICKS) & 1u)) bits |= 1u << n_full; + return bits; +} + +static const uint16_t vol_table[VOL_STEPS + 1] = { + 0, 2, 3, 4, 6, 8, 11, 16, 23, 32, 45, 64, 90, 128, 181, 256, +}; + +void vol_init(struct vol_state *s) +{ + s->idx = VOL_DEFAULT_IDX; + s->dir = 0; + s->held_ms = s->last_ms = 0; +} + +bool vol_step(struct vol_state *s, int dir, uint32_t now_ms) +{ + bool step = false; + if (dir == 0) { + s->dir = 0; + return false; + } + if (dir != s->dir) { /* a new press: step now */ + s->dir = dir; + s->held_ms = s->last_ms = now_ms; + step = true; + } else if (now_ms - s->held_ms >= VOL_REPEAT_MS && + now_ms - s->last_ms >= VOL_EVERY_MS) { + s->last_ms = now_ms; /* held: repeat */ + step = true; + } + if (!step) return false; + int n = s->idx + dir; + if (n < 0) n = 0; + if (n > VOL_STEPS) n = VOL_STEPS; + if (n == s->idx) return false; + s->idx = n; + return true; +} + +uint16_t vol_q8(int idx) +{ + if (idx < 0) idx = 0; + if (idx > VOL_STEPS) idx = VOL_STEPS; + return vol_table[idx]; +} diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.h b/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.h new file mode 100644 index 0000000..81ef833 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/gesture.h @@ -0,0 +1,94 @@ +/* gesture.h — •• held -> power off. + * + * A •• press wakes through SYSTEM_OFF, and Track 1+4 held from off enters DFU. + * Without a power-off, a firmware that feeds the watchdog can only be left by + * draining the battery or by SWD. There is deliberately no in-firmware DFU + * combo (Ryan, 2026-09-14): power off, then use the bootloader. + * + * Pure logic; power.c does the I/O. The hold is feldd's (~5 s, main.c), + * rescaled from its ~8 ms tick to this firmware's 10 ms. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#pragma once + +#include +#include + +#define GESTURE_TICK_MS 10 +#define GESTURE_OFF_TICKS 500 /* 5 s */ + +struct gesture_state { + int func_ticks; + bool func_armed; /* •• must read released once before a hold counts */ +}; + +void gesture_init(struct gesture_state *s); + +/* One tick. func_low: the •• pin reads pressed. True: power off now. */ +bool gesture_step(struct gesture_state *s, bool func_low); + +/* A •• combo press (•• + a button) is consumed and must not count toward the + * power-off, as feldd's combo_dispatch resets its hold. Call every tick the + * combo is held, before gesture_step: feldd resets only on the press edge, so a + * long ••+T1 battery peek there would still power off at 5 s. */ +void gesture_cancel(struct gesture_state *s); + +/* ---- power-on hold ---- + * The SP-1 wakes on ANY •• press, and USB plug-in and the post-flash reset + * reach the app too. A bump must not boot the firmware and drain the battery, + * so every boot except a watchdog recovery waits for a 1.5 s •• hold first. On + * battery, a release before then goes straight back to off; on USB it waits, + * as feldd parks after a plug-in. The looper's M18 fix. */ +#define WAKE_TICK_MS 20 +#define WAKE_HOLD_MS 1500 + +enum wake { WAKE_WAIT, WAKE_BOOT, WAKE_OFF }; + +struct wake_state { + int held_ms; +}; + +void wake_init(struct wake_state *s); + +/* One WAKE_TICK_MS tick of the boot gate. */ +enum wake wake_step(struct wake_state *s, bool func_low, bool usb_present); + +/* ---- charge gauge, shown on the side row while waiting on USB ---- + * feldd's battery_pct() and charge_gauge() (main.c). Its calibration is marked + * PROVISIONAL there: fitted against the stock curve, divider assumed ~1/2. */ +#define BATT_RAW_EMPTY 1962 +#define BATT_RAW_FULL 2378 +#define GAUGE_BLINK_TICKS 24 /* feldd: 12 ticks of 40 ms; here 24 of 20 ms */ +#define GAUGE_SAMPLE_TICKS 100 /* feldd re-reads ~every 2 s */ + +/* 0..100 from a raw AIN4 read, or -1 if the read failed. */ +int battery_pct(int raw); + +/* Bit i = side LED i+1. Charging: whole quarters solid, the next one blinking. + * Not charging (charge complete): all four solid. */ +unsigned charge_gauge_bits(int pct, bool charging, unsigned tick); + +/* ---- master volume, on Vol+ / Vol- ---- + * The looper's (sp1-tape-looper main.c): a 16-step perceptual table, ~3 dB a + * step, Q8 (256 = unity), booting at index 10 = 45 -- its proven-clean speaker + * level; the TAS2505's small speaker distorts well below full scale. A press + * steps once; holding repeats after 500 ms, then every 110 ms. Not saved. */ +#define VOL_STEPS 15 +#define VOL_DEFAULT_IDX 10 +#define VOL_REPEAT_MS 500 +#define VOL_EVERY_MS 110 + +struct vol_state { + int idx; + int dir; /* the direction held last tick: -1, 0, +1 */ + uint32_t held_ms; /* when that hold began */ + uint32_t last_ms; /* when it last stepped */ +}; + +void vol_init(struct vol_state *s); +/* One tick. dir: +1 Vol+ held, -1 Vol- held, 0 neither. True if idx changed. */ +bool vol_step(struct vol_state *s, int dir, uint32_t now_ms); +uint16_t vol_q8(int idx); diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/main.c b/third_party/sp1-usb-audio/upstream/sp1/fw/src/main.c new file mode 100644 index 0000000..04004c5 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/main.c @@ -0,0 +1,76 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "audio.h" +#include "gesture.h" +#include "power.h" +#include "usb_audio.h" +#include "wdt.h" + +#include +#include +#include +#include + +#define TONE_PERIOD 48u +#define USB_GAIN_Q8 128 + +static int16_t sine[TONE_PERIOD]; + +static void render(int16_t *lr, uint32_t frames) +{ + static int16_t usb[AUDIO_BLK_FRAMES * 2]; + static uint32_t phase; + static int32_t vol_prev = 45; + const int32_t vol_target = audio_volume_q8(); + const int32_t vol_gd = vol_target - vol_prev; + + if (frames > AUDIO_BLK_FRAMES) frames = AUDIO_BLK_FRAMES; + for (uint32_t i = 0; i < frames; i++) { + const int32_t s = sine[phase]; + phase = (phase + 1u) % TONE_PERIOD; + + /* The ramp spreads each volume step across one block so a Vol press does + * not click. */ + const int32_t g = vol_prev + vol_gd * (int32_t)(i + 1u) / + (int32_t)frames; + const int16_t speaker = (int16_t)((s * g) >> 8); + const int16_t host = (int16_t)((s * USB_GAIN_Q8) >> 8); + lr[i * 2u] = speaker; + lr[i * 2u + 1u] = speaker; + usb[i * 2u] = host; + usb[i * 2u + 1u] = host; + } + vol_prev = vol_target; + usb_audio_push(usb, frames); +} + +int main(void) +{ + /* The stock bootloader's roughly 5 s watchdog is already counting. */ + wdt_ensure_started(); + feed_wdt(); + power_boot(); + + for (uint32_t i = 0; i < TONE_PERIOD; i++) { + /* -12 dBFS before either output gain. */ + sine[i] = (int16_t)(8192.0f * + sinf(2.0f * 3.14159265f * (float)i / (float)TONE_PERIOD)); + } + + feed_wdt(); + usb_audio_init(); + struct usbd_context *ctx = sample_usbd_init_device(usb_audio_usbd_msg); + if (ctx != NULL) (void)usbd_enable(ctx); + feed_wdt(); + audio_start(render); + + for (;;) { + feed_wdt(); + power_poll(); + k_msleep(GESTURE_TICK_MS); + } + return 0; +} diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.c b/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.c new file mode 100644 index 0000000..e7026e6 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.c @@ -0,0 +1,239 @@ +/* power.c — see power.h. + * + * Ported from feldd (firmware/app/src/main.c): charger_init(), the charge- + * standby gate with its press feedback and charge gauge, boot_signature(), + * enter_bootloader()'s park-and-SYSTEM_OFF, the side-row rest LED, track press + * feedback and the ••+T1 battery peek. The LED, ADC and button drivers are + * feldd's own files, staged by prep.sh. Every LED behaviour here is feldd's; + * the one deviation is gesture_cancel()'s per-tick reset (gesture.h). */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "power.h" + +#include "audio.h" +#include "buttons.h" +#include "controls.h" +#include "gesture.h" +#include "led.h" +#include "sp1_board.h" +#include "wdt.h" + +#include +#include +#include + +#define PIN_TRS_RING NRF_GPIO_PIN_MAP(0, 23) /* PNP base: HIGH = current source off */ +#define ADC_BATTERY 6 /* controls.c channel order */ +#define BOOT_SIG_SWEEPS 2 /* feldd v0.6.2-beta */ +#define LED_SIDE1 4 /* led.c: 4..7 = side LED1..4 */ + +static struct gesture_state gs; +static struct vol_state vs; +static bool vol_up_held, vol_dn_held; + +FUNC_NORETURN static void system_off(void); + +/* ---- LED writes: only on change, lit before dark ---- + * + * power_poll used to rewrite all eight LEDs every 10 ms tick. Two costs, both + * avoided here: + * - LIT BEFORE DARK. Zephyr's nRF PWM driver stops a PWM instance the moment + * all its channels are dark, then busy-waits up to a period (1.024 ms) to + * restart it (pwm_nrfx.c). A single LED stepping along a row -- press + * feedback moving between Tracks -- would hit that on every step if the + * old LED went dark first. Both rows are one PWM instance each + * (app.overlay: PWM2 Track, PWM3 side). + * - ONLY ON CHANGE. A write that changes nothing still ends in a PWM sequence + * playback. The cache is power_poll's alone: power_boot() forgets it, since + * the boot and gate paths drive LEDs directly. */ +static int8_t led_cache[LED_COUNT]; + +static void led_cache_forget(void) +{ + for (int i = 0; i < LED_COUNT; i++) led_cache[i] = -1; +} + +static void led_put(int i, bool on) +{ + if (led_cache[i] == (int8_t)on) return; + led_idx(i, on); + led_cache[i] = (int8_t)on; +} + +static void row_put(int base, unsigned bits) +{ + for (int i = 0; i < 4; i++) if ((bits >> i) & 1u) led_put(base + i, true); + for (int i = 0; i < 4; i++) if (!((bits >> i) & 1u)) led_put(base + i, false); +} + +static void side_row(unsigned bits) +{ + row_put(LED_SIDE1, bits); +} + +/* feldd's boot_signature(): two Track 1->4 sweeps at full brightness. */ +static void boot_signature(void) +{ + led_set_brightness(LED_BRIGHTNESS_FULL); + for (int i = 0; i < 4; i++) led_idx(i, false); + for (int pass = 0; pass < BOOT_SIG_SWEEPS; pass++) { + for (int i = 0; i < 4; i++) { + feed_wdt(); + led_idx(i, true); + k_msleep(80); + led_idx(i, false); + } + } + led_set_brightness(LED_BRIGHTNESS_DEFAULT); +} + +/* The power-on hold (gesture.h), with feldd's gate feedback: Track LED 1 while + * •• is held; the charge gauge on the side row while released on USB, the ADC + * and BTN_COM rail brought up only then, never on battery. */ +static void power_on_gate(void) +{ + struct wake_state w; + wake_init(&w); + bool adc_up = false; + int batt_raw = -1; + + led_set_brightness(LED_BRIGHTNESS_FULL); + for (unsigned tick = 0;; tick++) { + feed_wdt(); + bool held = nrf_gpio_pin_read(SP1_FUNC_BTN) == 0; + bool usb = nrf_gpio_pin_read(SP1_CHG_NPGOOD) == 0; + switch (wake_step(&w, held, usb)) { + case WAKE_BOOT: + side_row(0); + led_idx(0, false); + led_set_brightness(LED_BRIGHTNESS_DEFAULT); + return; /* the •• still held is ignored by gesture_step */ + case WAKE_OFF: + system_off(); /* nothing is running yet to shut down */ + case WAKE_WAIT: + break; + } + led_idx(0, held); + if (!held && usb) { + if (!adc_up) { + (void)controls_init(); + batt_raw = controls_read_raw(ADC_BATTERY); + adc_up = true; + } else if (tick % GAUGE_SAMPLE_TICKS == 0) { + batt_raw = controls_read_raw(ADC_BATTERY); + } + side_row(charge_gauge_bits(battery_pct(batt_raw), + nrf_gpio_pin_read(SP1_CHG_NCHG) == 0, tick)); + } + k_msleep(WAKE_TICK_MS); + } +} + +void power_boot(void) +{ + /* Why we booted -- read BEFORE clearing. A stale reset reason or DFU flag + * can make the bootloader misfire after a watchdog reset. */ + uint32_t reas = NRF_POWER->RESETREAS; + led_cache_forget(); /* nothing is known to be lit yet */ + NRF_POWER->RESETREAS = 0xFFFFFFFFu; + NRF_POWER->GPREGRET = 0; + + (void)led_init(); + /* Without this the battery never charges, even on USB, and a flat cell + * brown-out-thrashes the boot. */ + nrf_gpio_pin_clear(SP1_CHG_NCE); + nrf_gpio_cfg_output(SP1_CHG_NCE); + nrf_gpio_pin_clear(SP1_CHG_NCE); + nrf_gpio_cfg_input(SP1_CHG_NCHG, NRF_GPIO_PIN_PULLUP); + nrf_gpio_cfg_input(SP1_CHG_NPGOOD, NRF_GPIO_PIN_PULLUP); + + nrf_gpio_cfg_input(SP1_FUNC_BTN, NRF_GPIO_PIN_PULLUP); + gesture_init(&gs); + vol_init(&vs); + audio_set_volume_q8(vol_q8(vs.idx)); + + /* A watchdog recovery was mid-session: resume without the hold. */ + if (!(reas & POWER_RESETREAS_DOG_Msk)) power_on_gate(); + + boot_signature(); + (void)controls_init(); /* power the ladder rail, set up the SAADC */ + (void)buttons_init(); + led_idx(LED_SIDE1, true); /* lit through boot; power_poll takes over from here */ + led_cache_forget(); /* the paths above wrote LEDs directly */ +} + +FUNC_NORETURN static void power_off(void) +{ + audio_shutdown(); + system_off(); +} + +/* feldd's enter_bootloader(): park every output, wait for the •• release, arm + * sense-low on it, clear RESETREAS, SYSTEM_OFF. */ +FUNC_NORETURN static void system_off(void) +{ + /* SYSTEM_OFF retains driven levels: a lit LED would stay lit and drain the + * cell (feldd's 0.7.0-beta "LEDs never turn off" report). */ + for (int i = 0; i < LED_COUNT; i++) led_idx(i, false); + nrf_gpio_cfg_output(SP1_BTN_COM); + nrf_gpio_pin_clear(SP1_BTN_COM); + nrf_gpio_pin_set(PIN_TRS_RING); + nrf_gpio_cfg_output(PIN_TRS_RING); + + /* Arming sense-low on a pin still held low wakes the chip the instant + * SYSTEM_OFF latches, and the power-off silently fails. */ + while (nrf_gpio_pin_read(SP1_FUNC_BTN) == 0) { + feed_wdt(); + k_msleep(20); + } + k_msleep(60); + nrf_gpio_cfg_sense_input(SP1_FUNC_BTN, NRF_GPIO_PIN_PULLUP, + NRF_GPIO_PIN_SENSE_LOW); + NRF_POWER->RESETREAS = 0xFFFFFFFFu; + __DSB(); + NRF_POWER->SYSTEMOFF = 1u; + __DSB(); + for (;;) { } +} + +void power_poll(void) +{ + static unsigned tick; + tick++; + + /* The ladder debounce, as feldd's control loop runs it. Vol+/- are consumed + * here; the committed track state drives the LEDs below. */ + struct button_event evt[BTN_COUNT * 2]; + int nev = buttons_scan(evt, ARRAY_SIZE(evt)); + /* Vol+ (5) and Vol- (6): the looper's master volume (gesture.h). */ + for (int i = 0; i < nev; i++) { + if (evt[i].idx == 5) vol_up_held = evt[i].pressed; + if (evt[i].idx == 6) vol_dn_held = evt[i].pressed; + } + + int vdir = vol_up_held == vol_dn_held ? 0 : (vol_up_held ? 1 : -1); + if (vol_step(&vs, vdir, k_uptime_get_32())) audio_set_volume_q8(vol_q8(vs.idx)); + audio_hp_poll(); + + bool func_down = nrf_gpio_pin_read(SP1_FUNC_BTN) == 0; + int trk = buttons_track_committed(); /* -1 none, 0 Play, 1..4 Track */ + if (func_down && trk >= 0) gesture_cancel(&gs); + if (gesture_step(&gs, func_down)) power_off(); + + /* feldd's track row: the ••+T1 battery peek keeps it dark; otherwise light + * only the held Track's own LED. */ + bool batt_peek = func_down && trk == 1; + unsigned track_bits = !batt_peek && trk >= 1 && trk <= 4 ? 1u << (trk - 1) : 0; + row_put(0, track_bits); + /* The side row: feldd's charge gauge during the ••+T1 peek, then feldd's + * rest dot. tick / 2 keeps the gauge's ~0.5 s blink at this loop's 10 ms tick. */ + if (batt_peek) { + side_row(charge_gauge_bits(battery_pct(controls_read_raw(ADC_BATTERY)), + nrf_gpio_pin_read(SP1_CHG_NCHG) == 0, tick / 2)); + } else { + side_row(1u); /* feldd's running/rest LED at default brightness */ + } +} diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.h b/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.h new file mode 100644 index 0000000..5290c73 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/power.h @@ -0,0 +1,16 @@ +/* power.h — boot hygiene, the battery charger, and the •• power-off. + * See gesture.h for why power-off is not optional. Main thread only. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#pragma once + +/* First thing in main(), after the watchdog: clear RESETREAS and GPREGRET, + * enable charging, configure the •• pin, then hold the boot until •• has been + * held 1.5 s (gesture.h). Returns only to boot; a bump on battery never returns. */ +void power_boot(void); + +/* Every GESTURE_TICK_MS. Does not return once a power-off starts. */ +void power_poll(void); diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.c b/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.c new file mode 100644 index 0000000..7b21a5a --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.c @@ -0,0 +1,36 @@ +/* wdt.c — see wdt.h. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "wdt.h" + +#include +#include + +static volatile uint32_t last_feed_ms; + +void wdt_ensure_started(void) +{ + /* If the bootloader ever hands over a STOPPED WDT, feeding is a silent + * no-op and there is no hang backstop at all; start one. */ + if (NRF_WDT->RUNSTATUS & WDT_RUNSTATUS_RUNSTATUS_Msk) return; + NRF_WDT->CONFIG = (WDT_CONFIG_SLEEP_Run << WDT_CONFIG_SLEEP_Pos); + NRF_WDT->CRV = 8u * 32768u - 1u; /* ~8 s at 32.768 kHz */ + NRF_WDT->RREN = WDT_RREN_RR0_Msk; + NRF_WDT->TASKS_START = 1u; +} + +void feed_wdt(void) +{ + /* Writing a channel that is not enabled is harmless, and which ones the + * bootloader enabled is not ours to know. */ + for (int ch = 0; ch < 8; ch++) NRF_WDT->RR[ch] = WDT_RR_RR_Reload; + last_feed_ms = k_uptime_get_32(); +} + +uint32_t wdt_ms_since_feed(void) +{ + return k_uptime_get_32() - last_feed_ms; +} diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.h b/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.h new file mode 100644 index 0000000..e9df1e3 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/src/wdt.h @@ -0,0 +1,27 @@ +/* wdt.h — the hardware watchdog the TE bootloader leaves running. + * + * The bootloader starts WDT0 (~5 s) before jumping to the app, and a running + * nRF52840 WDT cannot be stopped or reconfigured. An app that never reloads it + * resets every 5 s. + * + * Both functions are feldd's (main.c), which is hardware-proven; the looper + * feeds the same way. */ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#pragma once + +#include + +/* Start WDT0 at ~8 s only if nothing already did; a running one is left as the + * bootloader configured it. Call first thing in main(). */ +void wdt_ensure_started(void); + +/* Reload every channel. Main thread: once per loop pass. */ +void feed_wdt(void); + +/* Milliseconds since the last feed_wdt(). Any thread: the audio thread reads it + * to notice main being starved (audio.c, the starvation guard). */ +uint32_t wdt_ms_since_feed(void); diff --git a/third_party/sp1-usb-audio/upstream/sp1/fw/txq2.conf b/third_party/sp1-usb-audio/upstream/sp1/fw/txq2.conf new file mode 100644 index 0000000..f0da501 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/fw/txq2.conf @@ -0,0 +1,4 @@ +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 + +CONFIG_I2S_NRFX_TX_BLOCK_COUNT=2 diff --git a/third_party/sp1-usb-audio/upstream/sp1/prep.sh b/third_party/sp1-usb-audio/upstream/sp1/prep.sh new file mode 100644 index 0000000..3f84967 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/sp1/prep.sh @@ -0,0 +1,144 @@ +#!/usr/bin/env bash +# Copyright (c) 2026 Ryan Gilmore +# SPDX-License-Identifier: Apache-2.0 +# +# Stage the SP-1 example with pinned external hardware sources, then build it. +set -euo pipefail + +SELF="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +WORK="${SP1_BUILD_ROOT:-$SELF/.build}" +CACHE="$WORK/cache" +VARIANT=stock +[ "${SP1_ISOFAST:-0}" = 0 ] || [ "${SP1_ISOFAST:-0}" = 1 ] || { + echo "!! SP1_ISOFAST must be 0 or 1" >&2; exit 1; } +[ "${SP1_ISOFAST:-0}" = 0 ] || VARIANT=isofast +STAGE="$WORK/stage-$VARIANT" +BUILD="$WORK/build-$VARIANT" +OUT="$WORK/sp1_usb_audio${VARIANT/isofast/-isofast}.bin" +[ "$VARIANT" = stock ] && OUT="$WORK/sp1_usb_audio.bin" + +MARISKO_COMMIT=b787d906c96db3f03b11860ec20f0b53441c266d +FELDD_COMMIT=b70a3a274b8d5c4b99d6ed1edb9f265d4588d967 +MARISKO_URL=https://github.com/softmodded/marisko.git +FELDD_URL=https://github.com/bnjreece/feldd-sp1-firmware.git + +[ -n "${ZEPHYR_BASE:-}" ] && [ -d "$ZEPHYR_BASE" ] || { + echo "!! ZEPHYR_BASE must name a Zephyr source tree" >&2; exit 1; } +[ "${ZEPHYR_TOOLCHAIN_VARIANT:-}" = zephyr ] || { + echo "!! set ZEPHYR_TOOLCHAIN_VARIANT=zephyr" >&2; exit 1; } +[ -n "${ZEPHYR_SDK_INSTALL_DIR:-}" ] && [ -d "$ZEPHYR_SDK_INSTALL_DIR" ] || { + echo "!! ZEPHYR_SDK_INSTALL_DIR must name a Zephyr SDK" >&2; exit 1; } +command -v west >/dev/null || { echo "!! west is not on PATH" >&2; exit 1; } + +mkdir -p "$CACHE" + +checkout_or_clone() +{ + local env_path="$1" cache_name="$2" url="$3" commit="$4" path + if [ -n "$env_path" ]; then + path="$env_path" + else + path="$CACHE/$cache_name" + if [ ! -d "$path/.git" ]; then + git clone "$url" "$path" + git -C "$path" checkout --detach "$commit" + fi + fi + [ -d "$path/.git" ] || { echo "!! not a git checkout: $path" >&2; exit 1; } + local head + head="$(git -C "$path" rev-parse HEAD)" + [ "$head" = "$commit" ] || { + echo "!! $path is at $head; required pinned commit is $commit" >&2; exit 1; } + printf '%s\n' "$path" +} + +BOARD_ROOT="$(checkout_or_clone "${SP1_BOARD_ROOT:-}" marisko "$MARISKO_URL" "$MARISKO_COMMIT")" +FELDD="$(checkout_or_clone "${FELDD_DIR:-}" feldd-sp1-firmware "$FELDD_URL" "$FELDD_COMMIT")" + +USBA="$SELF/../usb-audio" +MODULE="$SELF/../module/nrf-usbd-isofast" +for f in usb_audio.c usb_audio.h uacring.c uacring.h; do + [ -f "$USBA/$f" ] || { + echo "!! $USBA/$f is missing; run prep.sh from the assembled public tree" >&2; exit 1; } +done +for f in CMakeLists.txt Kconfig src/udc_nrf.c src/udc_nrf_iso_in_fast.h; do + [ -f "$MODULE/$f" ] || { + echo "!! $MODULE/$f is missing; run prep.sh from the assembled public tree" >&2; exit 1; } +done + +rm -rf "$STAGE" +mkdir -p "$STAGE" +rsync -a --exclude .git "$SELF/fw/" "$STAGE/" + +# External sources must never be copied into a git working tree. +if git -C "$STAGE" rev-parse --git-dir >/dev/null 2>&1; then + echo "!! $STAGE is inside a git working tree; set SP1_BUILD_ROOT outside it" >&2 + exit 1 +fi + +FELDD_SRC="$FELDD/firmware/app/src" +for f in led.c led.h controls.c controls.h buttons.c buttons.h sp1_board.h; do + [ -f "$FELDD_SRC/$f" ] || { echo "!! feldd source missing: $FELDD_SRC/$f" >&2; exit 1; } + [ ! -e "$STAGE/src/$f" ] || { + echo "!! fw/src/$f exists; feldd files must only be staged" >&2; exit 1; } + cp "$FELDD_SRC/$f" "$STAGE/src/$f" +done +for f in usb_audio.c usb_audio.h uacring.c uacring.h; do + [ ! -e "$STAGE/src/$f" ] || { + echo "!! fw/src/$f exists; the shared usb-audio files must only be staged" >&2; exit 1; } + cp "$USBA/$f" "$STAGE/src/$f" +done +mkdir -p "$STAGE/isofast" +cp -R "$MODULE/src" "$MODULE/CMakeLists.txt" "$MODULE/Kconfig" "$STAGE/isofast/" + +EXTRA_CONF="$STAGE/txq2.conf" +if [ "$VARIANT" = isofast ]; then + EXTRA_CONF="$EXTRA_CONF;$STAGE/isofast.conf" +fi + +west build -p always --no-sysbuild -b sp1 -d "$BUILD" "$STAGE" -- \ + -DBOARD_ROOT="$BOARD_ROOT" -DCONFIG_ROM_START_OFFSET=0 \ + -DEXTRA_CONF_FILE="$EXTRA_CONF" + +ELF="$BUILD/zephyr/zephyr.elf" +TOOLBIN="$ZEPHYR_SDK_INSTALL_DIR/arm-zephyr-eabi/bin" +[ -x "$TOOLBIN/arm-zephyr-eabi-objcopy" ] || { + echo "!! ARM objcopy not found under the Zephyr SDK" >&2; exit 1; } +"$TOOLBIN/arm-zephyr-eabi-objcopy" -O binary "$ELF" "$OUT" + +# Read symbols once: nm can otherwise receive SIGPIPE under pipefail. +SYMS="$("$TOOLBIN/arm-zephyr-eabi-nm" -C "$ELF")" +vt="$(awk '$3=="_vector_table"{print $1}' <<<"$SYMS")" +[ "$vt" = 00020000 ] || { echo "!! _vector_table at $vt, want 00020000" >&2; exit 1; } + +for sym in audio_start audio_thread i2s_nrfx_configure render \ + feed_wdt wdt_ensure_started power_boot power_poll system_off gesture_step \ + audio_shutdown led_init controls_init controls_read_raw buttons_scan \ + charge_gauge_bits battery_pct vol_step vol_q8 audio_set_volume_q8 \ + audio_volume_q8 audio_hp_poll usb_audio_init usb_audio_claim \ + usb_audio_push sample_usbd_init_device usbd_enable; do + grep -q " $sym\$" <<<"$SYMS" || { echo "!! $sym missing from image" >&2; exit 1; } +done + +grep -q '^CONFIG_I2S_NRFX_TX_BLOCK_COUNT=2$' "$BUILD/zephyr/.config" || { + echo "!! I2S TX queue is not 2 blocks" >&2; exit 1; } +grep -q '^CONFIG_USBD_AUDIO2_CLASS=y$' "$BUILD/zephyr/.config" || { + echo "!! UAC2 class is not enabled" >&2; exit 1; } + +if [ "$VARIANT" = stock ]; then + grep -q ' usbd_uac2_send$' <<<"$SYMS" || { + echo "!! stock image lacks usbd_uac2_send" >&2; exit 1; } + ! grep -q ' udc_nrf_iso_in_fast_set$' <<<"$SYMS" || { + echo "!! stock image unexpectedly contains the fast-path driver" >&2; exit 1; } +else + grep -q ' udc_nrf_iso_in_fast_set$' <<<"$SYMS" || { + echo "!! fast image lacks udc_nrf_iso_in_fast_set" >&2; exit 1; } + ! grep -q ' usbd_uac2_send$' <<<"$SYMS" || { + echo "!! fast image still links usbd_uac2_send" >&2; exit 1; } + ! grep -q '^CONFIG_UDC_NRF=y$' "$BUILD/zephyr/.config" || { + echo "!! fast image still enables Zephyr's stock nRF UDC" >&2; exit 1; } +fi + +size="$(stat -f %z "$OUT" 2>/dev/null || stat -c %s "$OUT")" +echo "sp1: audits passed (vectors, watchdog, power-off, audio, UAC2, 128-frame/2-block I2S, $VARIANT path)" +echo "sp1: $size B -> $OUT" diff --git a/third_party/sp1-usb-audio/upstream/test/run.sh b/third_party/sp1-usb-audio/upstream/test/run.sh new file mode 100644 index 0000000..5f18bd8 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/test/run.sh @@ -0,0 +1,12 @@ +#!/bin/sh +# Host tests for the packet regulator (uacring.c), at both producer block sizes +# the regulator is tuned for. Needs only a C compiler. +set -eu +D="$(cd "$(dirname "$0")/.." && pwd)" +T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT +for blk in 128 256; do + cc -std=c99 -O2 -Wall -DAUDIO_BLK_FRAMES=$blk -I"$D/usb-audio" \ + "$D/test/test_uacring.c" "$D/usb-audio/uacring.c" -o "$T/test_uacring$blk" + echo "== test_uacring, $blk-frame blocks" + "$T/test_uacring$blk" +done diff --git a/third_party/sp1-usb-audio/upstream/test/test_uacring.c b/third_party/sp1-usb-audio/upstream/test/test_uacring.c new file mode 100644 index 0000000..2b73395 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/test/test_uacring.c @@ -0,0 +1,183 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +/* test_uacring.c -- host tests for the UAC2 capture ring and packet regulator. */ +#include "uacring.h" + +#include +#include + +/* The producer's block: the firmware pushes one audio block per render. Built + * at both sizes by prep.sh (-DAUDIO_BLK_FRAMES=256 for the other). */ +#ifndef AUDIO_BLK_FRAMES +#define AUDIO_BLK_FRAMES 128u +#endif +#define BLK ((uint32_t)AUDIO_BLK_FRAMES) + +static int checks, failures; + +#define CHECK(cond, msg) do { \ + checks++; \ + if (!(cond)) { failures++; \ + printf(" FAIL %s:%d %s\n", __FILE__, __LINE__, (msg)); } \ +} while (0) + +static void pattern(int16_t *lr, uint32_t first, uint32_t frames) +{ + for (uint32_t i = 0; i < frames; i++) { + lr[i * 2u] = (int16_t)(first + i); + lr[i * 2u + 1u] = (int16_t)~(first + i); + } +} + +/* The producer is the firmware's audio thread: it takes an I2S slot when one + * frees -- paced by the audio clock, `ppm` off the host's -- claims the block, + * renders it, then pushes it. Render time sets when the push lands. + * + * steps: render-timing steps, as a chord starting and stopping does -- every + * 30 s renders go from light to near a whole block (RENDER_HI) and back, and one + * block in 997 takes RENDER_PEAK: at 128-sample blocks the bench saw 3417 us, 28% + * over the slot (worst-case patch re-struck, 2026-09-23); at 256 nothing above + * ~4.7 ms, so a whole block is the bound. The regulator must not read any of it as clock drift: at + * 2% for ~150 ms that was an audible click on macOS (2026-09-23). */ +#define PERIOD_US (BLK * 1000000.0 / 48000.0) +#define RENDER_LO 300.0 +#define RENDER_HI (BLK == 256u ? 4700.0 : 2500.0) /* the heaviest held chords */ +#define RENDER_PEAK (BLK == 256u ? 5333.0 : 3417.0) + +static void run_ppm(int ppm, bool steps) +{ + struct uacring r; + int16_t in[AUDIO_BLK_FRAMES * 2], out[49 * 2]; + uint32_t produced = 0, expected = 0, blocks = 0; + /* Slot k frees at k * period on the audio clock, seen from the host's. */ + const double period = PERIOD_US / (1.0 + ppm * 1e-6); + double next_slot = 0.0, busy_until = 0.0, push_at = 0.0; + bool rendering = false; + bool heard = false; + uint32_t win_fix = 0, win_max = 0, last_fix = 0; + + uacring_init(&r); + uacring_stream(&r, true); + for (uint32_t ms = 0; ms < 600000u; ms++) { + const double now = ms * 1000.0; + const bool heavy = steps && (ms / 30000u) % 2u; + for (;;) { + if (rendering && push_at <= now) { + pattern(in, produced, BLK); + CHECK(uacring_push(&r, in, BLK), "producer block fits"); + produced += BLK; + rendering = false; + busy_until = push_at; + continue; + } + const double start = next_slot > busy_until ? next_slot : busy_until; + if (!rendering && start <= now) { + double render = heavy ? RENDER_HI : RENDER_LO; + if (steps && ++blocks % 997u == 0u) render = RENDER_PEAK; + uacring_claim(&r, BLK); + rendering = true; + push_at = start + render; + next_slot += period; + continue; + } + break; + } + + uint32_t n = uacring_packet_frames(&r); + bool audio = uacring_pop(&r, out, n); + if (audio) { + if (!heard) { + /* Priming drops its overshoot: at most one block, once. */ + expected = (uint16_t)out[0]; + CHECK(expected < BLK, "priming skips less than a block"); + } + heard = true; + for (uint32_t i = 0; i < n; i++) { + if (out[i * 2u] != (int16_t)expected || + out[i * 2u + 1u] != (int16_t)~expected) { + CHECK(false, "output stream preserves every frame"); + return; + } + expected++; + } + } + CHECK(r.write - r.read < UACRING_CAPACITY, "fill remains in range"); + + /* Corrections per 1000 packets: the host must only ever see drift. */ + const uint32_t fixes = r.n47 + r.n49; + win_fix += fixes - last_fix; + last_fix = fixes; + if (ms % 1000u == 999u) { + if (win_fix > win_max) win_max = win_fix; + win_fix = 0; + } + } + CHECK(win_max <= 20, "at most 20 corrections a second (the host hears no clock jump)"); + if (steps && ppm == 0) { + CHECK(r.n47 + r.n49 <= 60, + "render-timing steps are not read as drift (few corrections at 0 ppm)"); + } + + CHECK(heard, "stream left priming"); + CHECK(r.under == 0, "no underflow after priming"); + CHECK(r.over == 0, "no overflow while regulated"); + if (ppm < 0) CHECK(r.n47 > r.n49, "slow producer selects more 47-frame packets"); + if (ppm > 0) CHECK(r.n49 > r.n47, "fast producer selects more 49-frame packets"); + if (ppm == 0) { + CHECK(r.n47 < 1000 && r.n49 < 1000, "zero ppm needs few corrections"); + CHECK(r.n47 > r.n49 ? r.n47 - r.n49 < 100 : r.n49 - r.n47 < 100, + "zero ppm corrections balance"); + } +} + +int main(void) +{ + struct uacring r; + int16_t block[AUDIO_BLK_FRAMES * 2], out[49 * 2]; + struct uacring_stats st; + static const int ppms[] = { -200, -50, 0, 50, 200 }; + + for (uint32_t i = 0; i < sizeof ppms / sizeof ppms[0]; i++) { + run_ppm(ppms[i], false); + run_ppm(ppms[i], true); + } + + uacring_init(&r); + pattern(block, 0, BLK); + CHECK(!uacring_push(&r, block, BLK), "disabled ring rejects input"); + uacring_stream(&r, true); + CHECK(uacring_push(&r, block, BLK), "enabled ring accepts input"); + CHECK(uacring_packet_frames(&r) == 48 && !uacring_pop(&r, out, 48), + "priming emits 48 silent frames"); + CHECK(r.under == 0, "priming silence is not an underflow"); + /* Top up to one block short of UACRING_PRIME; the next block reaches it. */ + while (r.write - r.read + BLK < UACRING_PRIME) { + CHECK(uacring_push(&r, block, BLK), "priming block fits"); + CHECK(uacring_packet_frames(&r) == 48 && !uacring_pop(&r, out, 48), + "still priming below UACRING_PRIME"); + } + CHECK(uacring_push(&r, block, BLK), "second block reaches prime target"); + uint32_t n = uacring_packet_frames(&r); + CHECK(uacring_pop(&r, out, n), "audio starts after target fill"); + r.read = r.write; + n = uacring_packet_frames(&r); + CHECK(n == 48 && !uacring_pop(&r, out, n) && r.under == 1, + "underflow emits one silent 48-frame packet and counts it"); + uacring_stream(&r, false); + CHECK(!r.streaming, "disable stops streaming"); + uacring_stream(&r, true); + uacring_stats(&r, &st); + CHECK(st.on && st.fill == 0 && st.packets == 0, "re-enable resets ring and counters"); + for (uint32_t b = 0; b < UACRING_CAPACITY / BLK; b++) { + CHECK(uacring_push(&r, block, BLK), "overflow setup block"); + } + CHECK(!uacring_push(&r, block, BLK) && r.over == 1, + "overflow drops the whole block and counts it"); + CHECK(r.write - r.read == UACRING_CAPACITY, "overflow does not partly write"); + + printf("uacring (%u-frame blocks): %d checks, %d failures\n", (unsigned)BLK, checks, failures); + return failures ? 1 : 0; +} diff --git a/third_party/sp1-usb-audio/upstream/usb-audio/README.md b/third_party/sp1-usb-audio/upstream/usb-audio/README.md new file mode 100644 index 0000000..c770a85 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/usb-audio/README.md @@ -0,0 +1,18 @@ +# usb-audio — the USB audio code + +The four files that send audio to the computer. Both firmwares in this repo build +these same files: [`../sp1/`](../sp1/README.md) and +[`../extras/nrf52840dk/`](../extras/nrf52840dk/README.md). + +| File | What it does | +|---|---| +| [`usb_audio.c`](usb_audio.c), [`usb_audio.h`](usb_audio.h) | connects Zephyr's UAC2 class to the ring: starts and stops the stream, sends one packet per USB frame (stock driver) or hands it to the fast-path driver | +| [`uacring.c`](uacring.c), [`uacring.h`](uacring.h) | the ring buffer and the packet regulator that sizes each packet 47, 48 or 49 frames to follow clock drift | + +To use them in your own firmware: call `usb_audio_init()` before `usbd_enable()`, +pass `usb_audio_usbd_msg` to `sample_usbd_init_device()`, and from your audio +thread call `usb_audio_claim(frames)` before rendering each block and +`usb_audio_push(lr, frames)` after. The details are in +[`../docs/ON-THE-SP-1.md`](../docs/ON-THE-SP-1.md) §3. + +The regulator's host tests are in [`../test/`](../test/run.sh). diff --git a/third_party/sp1-usb-audio/upstream/usb-audio/uacring.c b/third_party/sp1-usb-audio/upstream/usb-audio/uacring.c new file mode 100644 index 0000000..c6cf305 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/usb-audio/uacring.c @@ -0,0 +1,208 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +#include "uacring.h" + +#include + +#define RING_MASK (UACRING_CAPACITY - 1u) +/* The regulator must follow CLOCK DRIFT only -- a few hundred ppm at most -- and + * never a render-timing step. Corrected at 32 ms smoothing and +/-24 frames it + * sent ~150 ms of 47-frame packets whenever a chord started: to the host, our + * clock ran 2% slow, and macOS's correction of that was a click in the + * recording (bench, 2026-09-23). Now: ~1 s smoothing (alpha 1/1024 per packet), + * a dead band (UACRING_HYSTERESIS, uacring.h) and at most one correction per + * FIX_EVERY packets: 20 frames a second, ~417 ppm, twice the worst crystal. + * A render step never reaches the regulator: it steers on the CLAIMED fill + * (below). Steered on pushes, a chord starting shifted the fill by up to a + * render time, and the band had to be wider than that -- +/-192, where a band + * of 64 still corrected for seconds after every step (test_uacring, 2026-09-23). */ +#define EMA_SHIFT 10u +#define HYSTERESIS UACRING_HYSTERESIS +#define FIX_EVERY 50u + +/* What the regulator steers: the fill counted to the CLAIMED position, which + * advances when the audio thread takes an I2S slot -- a time the audio clock + * paces -- instead of when the render finishes. A chord starting makes renders + * longer and every push later, but moves no claim, so this does not step. */ +static uint32_t nominal_fill(const struct uacring *r) +{ + uint32_t claimed = r->claimed; + uint32_t write = r->write; + UACRING_BARRIER(); + /* A producer that never claims is steered on its pushes, as before. */ + if ((int32_t)(claimed - write) < 0) claimed = write; + return claimed - r->read; +} + +/* What is really there to send. */ +static uint32_t fill(const struct uacring *r) +{ + uint32_t write = r->write; + UACRING_BARRIER(); + return write - r->read; +} + +void uacring_init(struct uacring *r) +{ + memset(r, 0, sizeof *r); +} + +void uacring_stream(struct uacring *r, bool enabled) +{ + r->streaming = false; + UACRING_BARRIER(); + if (!enabled) return; + + /* Drain by moving the CONSUMER's index only. The USB thread that calls this + * can preempt a push mid-copy; zeroing `write` here would let that push + * finish by storing its stale write + frames, leaving write - read larger + * than the ring and the free-space check wrapped. A push in flight now just + * adds valid frames after the drain point. */ + r->read = r->write; + r->ema_q = 0; + r->since_fix = 0; + r->packets = 0; + r->n47 = 0; + r->n49 = 0; + r->under = 0; + r->over = 0; + r->priming = true; + r->silence = true; + UACRING_BARRIER(); + r->streaming = true; +} + +void uacring_claim(struct uacring *r, uint32_t frames) +{ + /* From `write`, which only this thread moves: a failed or skipped push + * leaves nothing behind for the next claim to inherit. */ + uint32_t claimed = r->write + frames; + r->blk = frames; + UACRING_BARRIER(); + r->claimed = claimed; +} + +bool uacring_push(struct uacring *r, const int16_t *lr, uint32_t frames) +{ + if (!r->streaming) return false; + + uint32_t write = r->write; + uint32_t read = r->read; + UACRING_BARRIER(); + if (frames > UACRING_CAPACITY - (write - read)) { + r->over++; + return false; + } + + uint32_t first = UACRING_CAPACITY - (write & RING_MASK); + if (first > frames) first = frames; + memcpy(&r->data[(write & RING_MASK) * 2u], lr, + first * 2u * sizeof(int16_t)); + if (first < frames) { + memcpy(r->data, &lr[first * 2u], + (frames - first) * 2u * sizeof(int16_t)); + } + UACRING_BARRIER(); + r->write = write + frames; + r->blk = frames; + return true; +} + +uint32_t uacring_packet_frames(struct uacring *r) +{ + uint32_t level = nominal_fill(r); + + if (r->priming) { + if (level < UACRING_PRIME) { + r->silence = true; + return 48; + } + r->priming = false; + /* The fill steps a whole block per claim while nothing drains, so it + * crosses PRIME by up to a block. Drop the overshoot -- stream-start + * audio, already a discontinuity -- so the fill averages TARGET from + * the first packet: the dead band is too narrow to absorb a block + * of start-up error without seconds of corrections. */ + uint32_t skip = level - UACRING_PRIME; + uint32_t avail = fill(r); + if (skip > avail) skip = avail; + UACRING_BARRIER(); + r->read += skip; + level -= skip; + /* Start the average AT the fill's mean, half a block below this + * sample, not at zero: from zero, a slow average reads "empty" for + * seconds and sends 47s the whole time. */ + r->ema_q = (level - r->blk / 2u) << EMA_SHIFT; + r->since_fix = 0; + } + + int32_t delta = (int32_t)(level << EMA_SHIFT) - (int32_t)r->ema_q; + r->ema_q = (uint32_t)((int32_t)r->ema_q + delta / (1 << EMA_SHIFT)); + if (r->since_fix < FIX_EVERY) r->since_fix++; + + uint32_t frames = 48; + uint32_t smooth = r->ema_q >> EMA_SHIFT; + if (r->since_fix >= FIX_EVERY) { + if (smooth > UACRING_TARGET + HYSTERESIS) { + frames = 49; + } else if (smooth < UACRING_TARGET - HYSTERESIS) { + frames = 47; + } + if (frames != 48) r->since_fix = 0; + } + if (fill(r) < frames) { + r->silence = true; + return 48; + } + if (frames == 47) r->n47++; + if (frames == 49) r->n49++; + r->silence = false; + return frames; +} + +bool uacring_pop(struct uacring *r, int16_t *lr, uint32_t frames) +{ + r->packets++; + uint32_t read = r->read; + uint32_t write = r->write; + UACRING_BARRIER(); + if (r->silence || r->priming || write - read < frames) { + memset(lr, 0, frames * 2u * sizeof(int16_t)); + if (!r->priming) r->under++; + return false; + } + + uint32_t first = UACRING_CAPACITY - (read & RING_MASK); + if (first > frames) first = frames; + memcpy(lr, &r->data[(read & RING_MASK) * 2u], + first * 2u * sizeof(int16_t)); + if (first < frames) { + memcpy(&lr[first * 2u], r->data, + (frames - first) * 2u * sizeof(int16_t)); + } + UACRING_BARRIER(); + r->read = read + frames; + return true; +} + +void uacring_stats(const struct uacring *r, struct uacring_stats *st) +{ + /* Unlike fill(), this is sampled by neither SPSC owner. Read the consumer + * first so a concurrent pop can only make the displayed fill too high. */ + uint32_t read = r->read; + UACRING_BARRIER(); + uint32_t write = r->write; + uint32_t level = write - read; + if (level > UACRING_CAPACITY) level = 0; + + st->on = r->streaming; + st->packets = r->packets; + st->n47 = r->n47; + st->n49 = r->n49; + st->under = r->under; + st->over = r->over; + st->fill = level; +} diff --git a/third_party/sp1-usb-audio/upstream/usb-audio/uacring.h b/third_party/sp1-usb-audio/upstream/usb-audio/uacring.h new file mode 100644 index 0000000..6d7a396 --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/usb-audio/uacring.h @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + */ +/* SPSC stereo-frame ring and USB packet regulator. Pure C99. */ +#pragma once + +#include +#include + +/* The producer's block (audio.h; prep.sh defines it for the whole app). The + * fill saw-tooths by one block, so the constants follow it. */ +#ifndef AUDIO_BLK_FRAMES +#define AUDIO_BLK_FRAMES 128 +#endif + +/* 2048: room above the dead band for a render-step burst (see uacring.c). */ +#define UACRING_CAPACITY 2048u +/* TARGET (average fill) and the dead band around it, per block size. The fill + * must stay above empty with everything at once: the regulator parked at the + * bottom of its dead band (-200 ppm does that), half a block of saw-tooth, and + * one block still rendering when its push is due -- a render time, up to the + * worst seen (RENDER_PEAK in test_uacring: 3417 us at 128, a whole block at + * 256), plus a packet. + * 256: 640 / +/-192, ~13 ms -- as first proven on hardware (2026-09-23). The + * band once had to cover a render step as well; claims took that out + * of the measurement, but these values are left as proven. + * 128: 416 / +/-64, ~8.7 ms. The claimed fill does not step with render time, + * so the band covers drift only. Underflow starts between 320 and 352 + * (test_uacring at 128); 416 is one 64-frame step clear of the last + * pass, the margin 640 has at 256. */ +#if AUDIO_BLK_FRAMES == 128 +#define UACRING_TARGET_DEF 416u +#define UACRING_HYSTERESIS_DEF 64u +#else +#define UACRING_TARGET_DEF 640u +#define UACRING_HYSTERESIS_DEF 192u +#endif +/* Overridable for test_uacring sweeps only. */ +#ifndef UACRING_TARGET +#define UACRING_TARGET UACRING_TARGET_DEF +#endif +#ifndef UACRING_HYSTERESIS +#define UACRING_HYSTERESIS UACRING_HYSTERESIS_DEF +#endif +/* Priming ends at TARGET + half a producer block, and drops any overshoot. The + * fill saw-tooths down a whole block between pushes, so priming at TARGET left + * its AVERAGE half a block low -- and the regulator, which sees the average, + * then corrected for minutes (test_uacring, 92 one-sided corrections at 0 ppm). */ +#define UACRING_PRIME (UACRING_TARGET + AUDIO_BLK_FRAMES / 2u) + +#ifndef UACRING_BARRIER +#define UACRING_BARRIER() do { } while (0) +#endif + +struct uacring_stats { + bool on; + uint32_t packets; + uint32_t n47; + uint32_t n49; + uint32_t under; + uint32_t over; + uint32_t fill; +}; + +struct uacring { + int16_t data[UACRING_CAPACITY * 2u]; + volatile uint32_t write; + volatile uint32_t read; + volatile uint32_t claimed; /* write + the block being rendered (uacring_claim) */ + uint32_t blk; /* frames per claim: the fill's saw-tooth */ + uint32_t ema_q; /* smoothed fill, Q(EMA_SHIFT) */ + uint32_t since_fix; /* packets since the last 47/49 correction */ + volatile bool streaming; + bool priming; + bool silence; + volatile uint32_t packets; + volatile uint32_t n47; + volatile uint32_t n49; + volatile uint32_t under; + volatile uint32_t over; +}; + +void uacring_init(struct uacring *r); +void uacring_stream(struct uacring *r, bool enabled); +/* Producer: at the START of each render, when the I2S slot is taken, the frames + * that render will push. Optional -- without it the regulator steers on pushes. */ +void uacring_claim(struct uacring *r, uint32_t frames); +bool uacring_push(struct uacring *r, const int16_t *lr, uint32_t frames); +uint32_t uacring_packet_frames(struct uacring *r); +bool uacring_pop(struct uacring *r, int16_t *lr, uint32_t frames); +void uacring_stats(const struct uacring *r, struct uacring_stats *st); diff --git a/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.c b/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.c new file mode 100644 index 0000000..58f1f4b --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.c @@ -0,0 +1,175 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + * + * UAC2 capture glue. The application pushes audio into a ring (uacring.c); once + * per 1 ms USB frame one packet leaves it, sized 47, 48 or 49 frames to keep the + * ring's average fill steady. That sizing is the whole clock-drift answer: the + * audio is paced by one clock, USB frames by the host's, and there is no feedback + * endpoint to tell the host which one is right. + * + * Two ways to send the packet: + * - stock Zephyr (default): the class's SOF callback pops a packet into a slab + * buffer and hands it to usbd_uac2_send(); + * - CONFIG_UDC_NRF_ISOFAST (isofast.conf): the patched driver calls + * uac2_fast_fill() from the USBD interrupt at SOF and DMAs what it returns -- + * no buffer, no send, no thread wake-up. + */ +#include "usb_audio.h" +#include "uacring.h" + +#include + +#include +#include +#include +#include +#ifdef CONFIG_UDC_NRF_ISOFAST +#include "udc_nrf_iso_in_fast.h" +#endif + +#define UAC2_OUT_TERMINAL_ID UAC2_ENTITY_ID(DT_NODELABEL(uac2_usb_out)) +/* 49 stereo 16-bit frames, the largest packet the regulator sends. */ +#define UAC2_MAX_PACKET 196u + +static const struct device *const uac2_dev = + DEVICE_DT_GET(DT_NODELABEL(uac2_synth)); +static struct uacring ring; +/* The stock path's packet buffers. The class asserts a release callback is + * registered for any IN endpoint, so both paths keep them. */ +K_MEM_SLAB_DEFINE_STATIC(uac2_tx_slab, + ROUND_UP(UAC2_MAX_PACKET, UDC_BUF_GRANULARITY), 4, UDC_BUF_ALIGN); + +#ifdef CONFIG_UDC_NRF_ISOFAST +/* Runs in the USBD interrupt, once a millisecond, while the capture endpoint + * is enabled: short, lock-free, never blocking. Silence until the stream is on + * -- the endpoint can be enabled a moment before terminal_update_cb runs. */ +static uint16_t uac2_fast_fill(uint8_t *buf, uint16_t max, void *user_data) +{ + ARG_UNUSED(user_data); + uint32_t frames = ring.streaming ? uacring_packet_frames(&ring) : 48u; + + if (frames * 4u > max) { + frames = max / 4u; + } + if (ring.streaming) { + (void)uacring_pop(&ring, (int16_t *)buf, frames); + } else { + memset(buf, 0, frames * 4u); + } + return (uint16_t)(frames * 4u); +} +#endif + +static void uac2_sof_cb(const struct device *dev, void *user_data) +{ + ARG_UNUSED(dev); + ARG_UNUSED(user_data); +#ifndef CONFIG_UDC_NRF_ISOFAST + if (!ring.streaming) { + return; + } + + uint32_t frames = uacring_packet_frames(&ring); + void *buf; + + if (k_mem_slab_alloc(&uac2_tx_slab, &buf, K_NO_WAIT) != 0) { + return; + } + (void)uacring_pop(&ring, buf, frames); + if (usbd_uac2_send(uac2_dev, UAC2_OUT_TERMINAL_ID, buf, + (uint16_t)(frames * 2u * sizeof(int16_t))) != 0) { + k_mem_slab_free(&uac2_tx_slab, buf); + } +#endif +} + +static void stream_set(bool enabled) +{ +#ifdef CONFIG_UDC_NRF_ISOFAST + /* The consumer is the USBD interrupt: keep it out while the ring's + * consumer state is reset. A few microseconds. */ + unsigned int key = irq_lock(); + + uacring_stream(&ring, enabled); + irq_unlock(key); +#else + uacring_stream(&ring, enabled); +#endif +} + +static void uac2_terminal_update_cb(const struct device *dev, uint8_t terminal, + bool enabled, bool microframes, void *user_data) +{ + ARG_UNUSED(dev); + ARG_UNUSED(microframes); + ARG_UNUSED(user_data); + if (terminal == UAC2_OUT_TERMINAL_ID) { + stream_set(enabled); + } +} + +void usb_audio_usbd_msg(struct usbd_context *const ctx, const struct usbd_msg *const msg) +{ + ARG_UNUSED(ctx); + switch (msg->type) { + case USBD_MSG_VBUS_REMOVED: + case USBD_MSG_RESET: + /* The class reports a stream stopping only when the host selects + * alternate setting 0. A pulled cable never does, and a bus reset + * returns every interface to 0 without telling the class. The host + * selects the stream again when it wants it. */ + if (ring.streaming) { + stream_set(false); + } + break; + case USBD_MSG_RESUME: + /* Nothing drained while the host slept, so the ring is full: a stream + * resumed on that would run ~40 ms late. Re-prime it. */ + if (ring.streaming) { + stream_set(true); + } + break; + default: + break; + } +} + +static void uac2_buf_release_cb(const struct device *dev, uint8_t terminal, + void *buf, void *user_data) +{ + ARG_UNUSED(dev); + ARG_UNUSED(terminal); + ARG_UNUSED(user_data); + k_mem_slab_free(&uac2_tx_slab, buf); +} + +static const struct uac2_ops uac2_ops = { + .sof_cb = uac2_sof_cb, + .terminal_update_cb = uac2_terminal_update_cb, + .buf_release_cb = uac2_buf_release_cb, +}; + +void usb_audio_init(void) +{ + uacring_init(&ring); + usbd_uac2_set_ops(uac2_dev, &uac2_ops, NULL); +#ifdef CONFIG_UDC_NRF_ISOFAST + /* Suppress SOF events too: this function has no ISO OUT or feedback + * endpoint, so no class needs them, and each one wakes the usbd thread. */ + udc_nrf_iso_in_fast_set(uac2_fast_fill, NULL, true); +#endif +} + +void usb_audio_claim(uint32_t frames) +{ + uacring_claim(&ring, frames); +} + +void usb_audio_push(const int16_t *lr, uint32_t frames) +{ + if (ring.streaming) { + (void)uacring_push(&ring, lr, frames); + } +} diff --git a/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.h b/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.h new file mode 100644 index 0000000..5f6d1aa --- /dev/null +++ b/third_party/sp1-usb-audio/upstream/usb-audio/usb_audio.h @@ -0,0 +1,20 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * + * SPDX-License-Identifier: Apache-2.0 + * + * UAC2 capture glue: 48 kHz, 16-bit stereo from the application to the host. + */ +#pragma once + +#include +#include + +void usb_audio_init(void); +/* Pass to sample_usbd_init_device(): stops the stream on a pulled cable or a + * bus reset, and re-primes it on resume. */ +void usb_audio_usbd_msg(struct usbd_context *const ctx, const struct usbd_msg *const msg); +/* The producer (one thread): optionally at the START of each block, the frames + * it is about to render; then the rendered interleaved L/R frames. */ +void usb_audio_claim(uint32_t frames); +void usb_audio_push(const int16_t *lr, uint32_t frames); From 1f1f1cf49a06af9ca9534d7b3cb6b0cd19769ba9 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 17:02:55 -0400 Subject: [PATCH 02/10] M5c: tune the USB audio regulator for 96-frame blocks; uactest Ryan Gilmore's ring and packet regulator is tuned upstream for 128- and 256-frame producer blocks; Wakes renders 96. firmware/src/sp1_uac_tuning.h holds Wakes' values, force-included ahead of uacring.h by the firmware and the host test alike, and stops the build if the audio block changes. Swept against Wakes' render times (50 % light, 97.5 % held on the heaviest patch, one block in 997 at 200 % -- the longest the speaker survives with one queued block): first clean pass at TARGET 336 with a +/-32 dead band; 384 (8.0 ms) adds half a block, upstream's margin, and leaves 55 frames at worst. No corrections from load alone; ~9.5/s at +/-200 ppm. tools/host-tests/uactest.c (derived from upstream's test_uacring.c, Apache-2.0) runs in hostbuild.sh and CI, with a -s sweep mode for re-tuning. zephyr-patches/README.md records the ISO IN port review against Ryan's base. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build.yml | 4 +- firmware/src/sp1_uac_tuning.h | 39 ++++++ tools/host-tests/README.md | 24 +++- tools/host-tests/hostbuild.sh | 7 + tools/host-tests/uactest.c | 255 ++++++++++++++++++++++++++++++++++ zephyr-patches/README.md | 10 +- 6 files changed, 335 insertions(+), 4 deletions(-) create mode 100644 firmware/src/sp1_uac_tuning.h create mode 100644 tools/host-tests/uactest.c diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index a5de285..701c800 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -32,7 +32,8 @@ jobs: SP1_HOST_BUILD_DIR: ${{ runner.temp }}/host run: | sh tools/host-tests/hostbuild.sh routetest.cc uitest.c miditest.cc miditest_alt.cc \ - miditest_pickup.cc miditest_clock.cc ../../third_party/feldd/test/test_usb_rt_parse.c + miditest_pickup.cc miditest_clock.cc ../../third_party/feldd/test/test_usb_rt_parse.c \ + uactest.c "$SP1_HOST_BUILD_DIR/routetest" "$SP1_HOST_BUILD_DIR/uitest" "$SP1_HOST_BUILD_DIR/miditest" @@ -41,6 +42,7 @@ jobs: "$SP1_HOST_BUILD_DIR/miditest_pickup_takeover" "$SP1_HOST_BUILD_DIR/miditest_clock" "$SP1_HOST_BUILD_DIR/test_usb_rt_parse" + "$SP1_HOST_BUILD_DIR/uactest" firmware: runs-on: ubuntu-latest diff --git a/firmware/src/sp1_uac_tuning.h b/firmware/src/sp1_uac_tuning.h new file mode 100644 index 0000000..8b4eff8 --- /dev/null +++ b/firmware/src/sp1_uac_tuning.h @@ -0,0 +1,39 @@ +/* + * Copyright (c) 2026 Adara Barami | Worldwave + * + * SPDX-License-Identifier: MIT + */ +/* USB audio out (M5c): Wakes' tuning of Ryan Gilmore's ring and packet regulator + * (third_party/sp1-usb-audio/upstream/usb-audio/uacring.{c,h}). Force-included ahead of + * uacring.h wherever it is compiled -- the firmware and tools/host-tests/uactest.c -- so the + * two cannot drift apart. + * + * Upstream tunes for 128- and 256-frame producer blocks; Wakes renders 96 (2 ms, one queued + * I2S block: sp1_audio.c). Found by sweeping TARGET and HYSTERESIS against Wakes' own render + * times (2026-10-05, uactest.c's model): light patch 50 % of the block, the heaviest held + * patch 97.5 % (the worst block measured, v0.6.0 rc1), and one block in 997 at 4000 us -- + * 200 %, the most the one queued I2S block absorbs before the speaker itself runs dry. USB + * audio must survive anything the speaker survives. + * + * dead band +/-32: underflow at TARGET 320, first clean pass at 336 (lowest fill 7 frames) + * dead band +/-48: underflow at 336, first clean pass at 352 + * + * The render time while held barely matters (the regulator steers on the CLAIMED position, + * which the audio clock paces); the 4000 us block sets the target. 384 = the first pass plus + * half a block, the margin upstream took at 128 (lowest fill 55 frames, ~1.1 ms). It is also + * the ring's latency: 8.0 ms. Every passing setting made 0 corrections at 0 ppm with the + * load stepping, and never more than 20 a second at +/-200 ppm. */ +#pragma once + +#if defined(CONFIG_SP1_AUDIO_BLOCK_FRAMES) && CONFIG_SP1_AUDIO_BLOCK_FRAMES != 96 +#error "USB audio is tuned for 96-frame blocks: re-run tools/host-tests/uactest.c's sweep" +#endif + +#define AUDIO_BLK_FRAMES 96 +/* Overridable on the compiler's command line for uactest's sweep only (README there). */ +#ifndef UACRING_TARGET +#define UACRING_TARGET 384u +#endif +#ifndef UACRING_HYSTERESIS +#define UACRING_HYSTERESIS 32u +#endif diff --git a/tools/host-tests/README.md b/tools/host-tests/README.md index 0fe6978..b1fe98f 100644 --- a/tools/host-tests/README.md +++ b/tools/host-tests/README.md @@ -13,13 +13,15 @@ proved on a laptop, and because there is exactly one SP-1 (`docs/SAFETY.md`). | `miditest_clock.cc` | the same as `miditest.cc`, with real cycle-counter stamps on every tick | MIDI clock and transport into Marbles (M5b): tempo and position from ticks, ±1 ms of USB jitter, a stopped clock waiting, Start arming beat 1 on its own Plaits block, Marbles' beats at the host's tempo, RATE as Marbles' ratio table (×4, ×1/4), Stop / Continue, a stalled clock, PLAY on the host's clock, and the cable pulled (Marbles stops, own clock again) | | `miditest_alt.cc` | the same, built against `midi-alt.ini` (pickup `sum`) | omni, legato on, Yarns' portamento curve, velocity -> LEVEL, aftertouch -> TIMBRE, no sustain pedal, bend range | | `third_party/feldd/test/test_usb_rt_parse.c` | feldd's packet validator | feldd's own test, unmodified | +| `uactest.c` | Ryan Gilmore's USB audio ring and packet regulator (`third_party/sp1-usb-audio`, unmodified) at Wakes' tuning, `firmware/src/sp1_uac_tuning.h` | USB audio out (M5c): ±200 ppm of clock drift, a heavy patch starting and stopping, a 200 % block every 997, with no underflow, no lost frame, a margin left in the ring, at most 20 packet-size corrections a second and none from load alone; priming, underflow, overflow | ```sh tools/host-tests/hostbuild.sh routetest.cc uitest.c miditest.cc miditest_alt.cc \ - miditest_pickup.cc miditest_clock.cc ../../third_party/feldd/test/test_usb_rt_parse.c + miditest_pickup.cc miditest_clock.cc ../../third_party/feldd/test/test_usb_rt_parse.c \ + uactest.c cd /tmp/wakes-sp1-host && ./routetest && ./uitest && ./miditest && ./miditest_alt \ && ./miditest_pickup_shared && ./miditest_pickup_takeover && ./miditest_clock \ - && ./test_usb_rt_parse + && ./test_usb_rt_parse && ./uactest ``` Builds go to `$TMPDIR/wakes-sp1-host` (override with `SP1_HOST_BUILD_DIR`); nothing is written @@ -61,3 +63,21 @@ value — and with STEPS smooth the lag processor ramps between the two. `routet exists for that, and the comment above it explains why measuring from the first sample after `sp1_marbles_set_params()` is wrong. The same one-tick lag is the hardware behaviour, so this is worth understanding rather than working around. + +## Re-tuning USB audio (`uactest`) + +The ring's target fill and dead band are tuned for the audio block, in +`firmware/src/sp1_uac_tuning.h`, which `#error`s if `CONFIG_SP1_AUDIO_BLOCK_FRAMES` changes. +To re-tune, change the block and the render times at the top of `uactest.c` if they changed, +then sweep: each run rebuilds `uactest` with one setting and prints a summary line. + +```sh +for T in 288 304 320 336 352 368 384; do + EXTRA_UAC_FLAGS="-DUACRING_TARGET=${T}u -DUACRING_HYSTERESIS=32u" \ + sh tools/host-tests/hostbuild.sh uactest.c >/dev/null && /tmp/wakes-sp1-host/uactest -s +done +``` + +Take the first target with `under 0` and add half a block (upstream's margin), then rebuild +without `EXTRA_UAC_FLAGS` and run the full `uactest`. The reasoning and the 96-frame sweep are +in the header. diff --git a/tools/host-tests/hostbuild.sh b/tools/host-tests/hostbuild.sh index 48baf13..77ab40c 100644 --- a/tools/host-tests/hostbuild.sh +++ b/tools/host-tests/hostbuild.sh @@ -11,6 +11,7 @@ mkdir -p "$SP" ER=$ROOT/third_party/eurorack SRC=$ROOT/firmware/src FELDD=$ROOT/third_party/feldd +UAC=$ROOT/third_party/sp1-usb-audio/upstream/usb-audio # #32: Plaits' block size, as CONFIG_SP1_PLAITS_BLOCK (default 24, the firmware's). The # overrides and the cached archive live in a directory per size, so switching sizes can # never link an archive built for the other one. @@ -102,6 +103,12 @@ for t in "$@"; do [ -f "$t" ] || t=$HERE/$t out=$SP/$(basename "${t%.*}") case $t in + *uactest.c) + # USB audio out (M5c): Ryan Gilmore's ring + regulator, unmodified, at Wakes' tuning -- + # sp1_uac_tuning.h force-included as the firmware does. EXTRA_UAC_FLAGS is for the + # re-tuning sweep only (README). + gcc -std=c99 -O2 -Wall -include "$SRC/sp1_uac_tuning.h" $EXTRA_UAC_FLAGS -I"$UAC" \ + "$t" "$UAC/uacring.c" -o "$out" ;; *test_usb_rt_parse.c) # feldd's own host test of the packet validator Wakes uses (third_party/feldd). gcc -std=gnu11 -O2 "$t" "$FELDD/src/usb_rt_parse.c" -o "$out" ;; diff --git a/tools/host-tests/uactest.c b/tools/host-tests/uactest.c new file mode 100644 index 0000000..9524876 --- /dev/null +++ b/tools/host-tests/uactest.c @@ -0,0 +1,255 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * Copyright (c) 2026 Adara Barami | Worldwave + * + * SPDX-License-Identifier: Apache-2.0 + */ +/* uactest.c -- USB audio out (M5c): Ryan Gilmore's ring and packet regulator + * (third_party/sp1-usb-audio/upstream/usb-audio/uacring.c, unmodified) at Wakes' tuning + * (firmware/src/sp1_uac_tuning.h, force-included by hostbuild.sh as the firmware does). + * + * Derived from upstream's test/test_uacring.c (Apache-2.0); changed: the producer model uses + * Wakes' measured render times instead of upstream's 128/256-frame bench, the overflow check + * allows for a ring that is not a whole number of blocks (2048 / 96), and the worst case must + * keep a margin of fill, not merely avoid running dry. + * + * Run with -s / --sweep-line to print one summary line instead of the checks: the sweep in + * README.md rebuilds it with -DUACRING_TARGET / -DUACRING_HYSTERESIS to re-tune. */ +#include "uacring.h" + +#include +#include + +#define BLK ((uint32_t)AUDIO_BLK_FRAMES) + +static int checks, failures; + +#define CHECK(cond, msg) do { \ + checks++; \ + if (!(cond)) { failures++; \ + printf(" FAIL %s:%d %s\n", __FILE__, __LINE__, (msg)); } \ +} while (0) + +static void pattern(int16_t *lr, uint32_t first, uint32_t frames) +{ + for (uint32_t i = 0; i < frames; i++) { + lr[i * 2u] = (int16_t)(first + i); + lr[i * 2u + 1u] = (int16_t)~(first + i); + } +} + +/* The producer is sp1_audio.c's audio thread: a render starts when I2S frees a slot -- paced + * by the audio clock (the 3.072 MHz oscillator), `ppm` off the host's -- claims the block, + * renders it, then pushes it. + * + * Render times, from the hardware logs at 2 ms blocks (private notes, #32 / v0.6.0 rc1): + * LO a light patch, ~50 % of the block + * HI the heaviest patch, held at its WORST measured block (97.5 %), every block -- harsher + * than the 82 % it averages + * PEAK one block in 997 at 200 %: with one queued I2S block, the longest render the speaker + * survives. Longer, and the speaker drops out too. + * steps: every 30 s the load goes LO -> HI and back, as a heavy patch starting and stopping + * does. The regulator must not read any of it as clock drift (upstream: 2 % for ~150 ms was + * an audible click on macOS). */ +#define PERIOD_US (BLK * 1000000.0 / 48000.0) +#define RENDER_LO (PERIOD_US * 0.50) +#define RENDER_HI (PERIOD_US * 0.975) +#define RENDER_PEAK (PERIOD_US * 2.0) + +/* The worst case must leave this much in the ring, not just not run dry: ~0.7 ms. */ +#define MARGIN_FRAMES 32u + +struct result { + uint32_t under, over, lost, fixes, n47, n49, win_max, fill_min; + bool heard; +}; + +static struct result run_ppm(int ppm, bool steps) +{ + static struct uacring r; + int16_t in[AUDIO_BLK_FRAMES * 2], out[49 * 2]; + uint32_t produced = 0, expected = 0, blocks = 0; + const double period = PERIOD_US / (1.0 + ppm * 1e-6); + double next_slot = 0.0, busy_until = 0.0, push_at = 0.0; + bool rendering = false; + uint32_t win_fix = 0, last_fix = 0; + struct result s = { .fill_min = UINT32_MAX }; + + uacring_init(&r); + uacring_stream(&r, true); + for (uint32_t ms = 0; ms < 600000u; ms++) { + const double now = ms * 1000.0; + const bool heavy = steps && (ms / 30000u) % 2u; + for (;;) { + if (rendering && push_at <= now) { + pattern(in, produced, BLK); + if (!uacring_push(&r, in, BLK)) { + s.over++; + } + produced += BLK; + rendering = false; + busy_until = push_at; + continue; + } + const double start = next_slot > busy_until ? next_slot : busy_until; + if (!rendering && start <= now) { + double render = heavy ? RENDER_HI : RENDER_LO; + if (steps && ++blocks % 997u == 0u) { + render = RENDER_PEAK; + } + uacring_claim(&r, BLK); + rendering = true; + push_at = start + render; + next_slot += period; + continue; + } + break; + } + + uint32_t n = uacring_packet_frames(&r); + if (uacring_pop(&r, out, n)) { + if (!s.heard) { + /* Priming drops its overshoot: at most one block, once. */ + expected = (uint16_t)out[0]; + CHECK(expected < BLK, "priming skips less than a block"); + } + s.heard = true; + for (uint32_t i = 0; i < n; i++) { + if (out[i * 2u] != (int16_t)expected || + out[i * 2u + 1u] != (int16_t)~expected) { + s.lost++; + expected = (uint16_t)out[i * 2u]; + } + expected++; + } + /* What is left after this packet, once settled (5 s). */ + const uint32_t left = r.write - r.read; + if (ms > 5000u && left < s.fill_min) { + s.fill_min = left; + } + } + CHECK(r.write - r.read <= UACRING_CAPACITY, "fill remains in range"); + + /* Corrections per 1000 packets: the host must only ever see drift. */ + const uint32_t fixes = r.n47 + r.n49; + win_fix += fixes - last_fix; + last_fix = fixes; + if (ms % 1000u == 999u) { + if (win_fix > s.win_max) { + s.win_max = win_fix; + } + win_fix = 0; + } + } + s.under = r.under; + s.n47 = r.n47; + s.n49 = r.n49; + s.fixes = r.n47 + r.n49; + return s; +} + +static const int ppms[] = { -200, -50, 0, 50, 200 }; + +static void sweep_line(void) +{ + uint32_t under = 0, over = 0, lost = 0, win_max = 0, fix0 = 0, fill_min = UINT32_MAX; + + for (uint32_t i = 0; i < sizeof ppms / sizeof ppms[0]; i++) { + for (int st = 0; st < 2; st++) { + struct result s = run_ppm(ppms[i], st); + under += s.under; + over += s.over; + lost += s.lost; + if (s.win_max > win_max) win_max = s.win_max; + if (ppms[i] == 0 && st) fix0 = s.fixes; + if (s.fill_min < fill_min) fill_min = s.fill_min; + } + } + printf("TARGET %4u HYST %3u (%.2f ms) under %u over %u lost %u " + "fixes/s max %u fixes at 0 ppm with steps %u lowest fill %u\n", + UACRING_TARGET, UACRING_HYSTERESIS, UACRING_TARGET / 48.0, + under, over, lost, win_max, fix0, fill_min); +} + +int main(int argc, char **argv) +{ + struct uacring r; + int16_t block[AUDIO_BLK_FRAMES * 2], out[49 * 2]; + struct uacring_stats st; + + if (argc > 1 && (!strcmp(argv[1], "-s") || !strcmp(argv[1], "--sweep-line"))) { + sweep_line(); + return 0; + } + + printf("== uactest: %u-frame blocks, TARGET %u (%.2f ms), dead band +/-%u\n", + (unsigned)BLK, UACRING_TARGET, UACRING_TARGET / 48.0, UACRING_HYSTERESIS); + + for (uint32_t i = 0; i < sizeof ppms / sizeof ppms[0]; i++) { + for (int steps = 0; steps < 2; steps++) { + const int ppm = ppms[i]; + struct result s = run_ppm(ppm, steps); + + CHECK(s.heard, "stream left priming"); + CHECK(s.lost == 0, "output stream preserves every frame"); + CHECK(s.under == 0, "no underflow after priming"); + CHECK(s.over == 0, "producer block fits (no overflow while regulated)"); + CHECK(s.fill_min >= MARGIN_FRAMES, + "the worst case keeps a margin in the ring, not just above empty"); + CHECK(s.win_max <= 20, + "at most 20 corrections a second (the host hears no clock jump)"); + if (ppm < 0) CHECK(s.n47 > s.n49, "slow producer selects more 47-frame packets"); + if (ppm > 0) CHECK(s.n49 > s.n47, "fast producer selects more 49-frame packets"); + if (ppm == 0) { + CHECK(s.n47 < 1000 && s.n49 < 1000, "zero ppm needs few corrections"); + CHECK(s.n47 > s.n49 ? s.n47 - s.n49 < 100 : s.n49 - s.n47 < 100, + "zero ppm corrections balance"); + } + if (steps && ppm == 0) { + CHECK(s.fixes <= 60, + "load steps and 200 % blocks are not read as drift"); + } + printf(" %+4d ppm %-6s under %u 47s %u 49s %u fixes/s max %u lowest fill %u\n", + ppm, steps ? "steps" : "steady", s.under, s.n47, s.n49, s.win_max, + s.fill_min); + } + } + + uacring_init(&r); + pattern(block, 0, BLK); + CHECK(!uacring_push(&r, block, BLK), "disabled ring rejects input"); + uacring_stream(&r, true); + CHECK(uacring_push(&r, block, BLK), "enabled ring accepts input"); + CHECK(uacring_packet_frames(&r) == 48 && !uacring_pop(&r, out, 48), + "priming emits 48 silent frames"); + CHECK(r.under == 0, "priming silence is not an underflow"); + /* Top up to one block short of UACRING_PRIME; the next block reaches it. */ + while (r.write - r.read + BLK < UACRING_PRIME) { + CHECK(uacring_push(&r, block, BLK), "priming block fits"); + CHECK(uacring_packet_frames(&r) == 48 && !uacring_pop(&r, out, 48), + "still priming below UACRING_PRIME"); + } + CHECK(uacring_push(&r, block, BLK), "the block that reaches the prime target fits"); + uint32_t n = uacring_packet_frames(&r); + CHECK(uacring_pop(&r, out, n), "audio starts after target fill"); + r.read = r.write; + n = uacring_packet_frames(&r); + CHECK(n == 48 && !uacring_pop(&r, out, n) && r.under == 1, + "underflow emits one silent 48-frame packet and counts it"); + uacring_stream(&r, false); + CHECK(!r.streaming, "disable stops streaming"); + uacring_stream(&r, true); + uacring_stats(&r, &st); + CHECK(st.on && st.fill == 0 && st.packets == 0, "re-enable resets ring and counters"); + /* 2048 is not a whole number of 96-frame blocks: fill with whole blocks while they fit. */ + const uint32_t whole = UACRING_CAPACITY / BLK; + for (uint32_t b = 0; b < whole; b++) { + CHECK(uacring_push(&r, block, BLK), "overflow setup block"); + } + CHECK(!uacring_push(&r, block, BLK) && r.over == 1, + "a block that does not fit is dropped whole and counted"); + CHECK(r.write - r.read == whole * BLK, "overflow does not partly write"); + + printf("uactest: %d checks, %d failures\n", checks, failures); + return failures ? 1 : 0; +} diff --git a/zephyr-patches/README.md b/zephyr-patches/README.md index bbd93b3..d12a481 100644 --- a/zephyr-patches/README.md +++ b/zephyr-patches/README.md @@ -33,7 +33,15 @@ the `zephyr/` checkout root) whenever the Zephyr tree is re-cloned or reset. - `CONFIG_UDC_NRF_ISO_IN_FAST` — Ryan Gilmore's ISO IN fast path from sp1-usb-audio, for USB audio out (M5c), with the two guards it relies on from nRF Connect SDK's later driver (a DMA left running across SOF; the - `dma_ep` reset). Compiles clean; untested until M5c. + `dma_ep` reset). Compiles clean; untested on hardware until M5c. + Reviewed against Ryan's base driver (nRF Connect SDK `sdk-zephyr` `fd9204a0`, + kept in `third_party/sp1-usb-audio/upstream/module/nrf-usbd-isofast/patches/`): + the code the fast path hooks into (`ev_sof_handler`, `usbd_dmareq_process`, + `nrf_usbd_dma_finished`) is the same in 4.3.1 apart from those two guards, and the + port matches Ryan's patch hunk for hunk. 4.3.1's other differences are in control + transfers (EP0) and in where an endpoint dequeue runs; neither touches ISO IN. + Endpoint abort and disable wait for any running DMA (`dma_available`) before + clearing the endpoint, so closing the stream cannot cut a fast-path DMA short. With neither option set the driver is unchanged. The two paths serve different endpoints through the driver's own DMA scheduler, which serves IN From e64de17c66a201f662b43128a15d038fd94a3ae6 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 17:06:06 -0400 Subject: [PATCH 03/10] M5c: word copies in the USB audio ring, not picolibc's byte loop uacring.c copies with memcpy/memset, and the SDK's picolibc memcpy is a byte loop (ldrb/strb, confirmed in the linked image; ~6.6 cycles a byte, #36). The ring's push (audio thread, 384 B every 2 ms) and pop (USB interrupt, 192 B every 1 ms) would cost ~4 points through it. third_party/sp1-usb-audio/patches/uacring.patch replaces those five calls with one 32-bit word per stereo frame (frames_copy, unrolled by four; frames_zero). Cortex-M4 at -Os: 14 instructions per 16 bytes, ~1 cycle a byte, ~0.65 points in all. Applied strictly to a copy (tools/apply_patch.py); the vendored file is untouched. Without -fno-tree-loop-distribute-patterns GCC turns the silence fill back into memset (checked), so the copy is built with it, and check_image.py now fails an image whose uacring_push/pop call memcpy/memset (silent until USB audio is linked; ELF helpers shared with the #36 rule, whose results are unchanged). uactest builds the patched copy the same way: 6 000 121 checks, 0 failures. Co-Authored-By: Claude Opus 5.5 --- NOTICE | 8 +- third_party/sp1-usb-audio/README.md | 31 +++++-- .../sp1-usb-audio/patches/uacring.patch | 81 +++++++++++++++++++ tools/ci/check_image.py | 70 ++++++++++++---- tools/host-tests/README.md | 2 +- tools/host-tests/hostbuild.sh | 14 ++-- 6 files changed, 175 insertions(+), 31 deletions(-) create mode 100644 third_party/sp1-usb-audio/patches/uacring.patch diff --git a/NOTICE b/NOTICE index 2838c00..098cc65 100644 --- a/NOTICE +++ b/NOTICE @@ -115,8 +115,12 @@ USB audio out (M5c) — vendored unmodified in third_party/sp1-usb-audio/upstrea (third_party/sp1-usb-audio/upstream/NOTICE) is carried forward with it: it credits Nordic Semiconductor ASA (Apache-2.0) for the modified driver in module/nrf-usbd-isofast/, and chattock/sp1-tape-looper (MIT) for the SP-1 - audio bring-up in sp1/fw/src/audio.c. Not yet compiled into Wakes. Commit - and what each part is for: third_party/sp1-usb-audio/README.md. + audio bring-up in sp1/fw/src/audio.c. Wakes uses usb-audio/uacring.c, + MODIFIED by third_party/sp1-usb-audio/patches/uacring.patch (word copies in + place of memcpy/memset), applied at build time to a copy; the vendored file + is unchanged. tools/host-tests/uactest.c is derived from its + test/test_uacring.c and stays Apache-2.0. Commit and what each part is for: + third_party/sp1-usb-audio/README.md. Zephyr RTOS — Apache-2.0 — https://github.com/zephyrproject-rtos/zephyr Licence text: LICENSES/Apache-2.0.txt diff --git a/third_party/sp1-usb-audio/README.md b/third_party/sp1-usb-audio/README.md index 5897713..1c9b09d 100644 --- a/third_party/sp1-usb-audio/README.md +++ b/third_party/sp1-usb-audio/README.md @@ -14,20 +14,38 @@ forward as Apache-2.0 asks: it credits Nordic Semiconductor for the driver in `upstream/module/nrf-usbd-isofast/` and chattock (MIT) for the SP-1 audio bring-up in `upstream/sp1/fw/src/audio.c`. -Nothing here is compiled yet. M5c is "USB audio out": the SP-1's output, sent to the host. Nothing +Not yet compiled into the firmware (the UAC1 class comes next); `uactest` builds the ring on the host. M5c is "USB audio out": the SP-1's output, sent to the host. Nothing in Wakes receives audio from the host. ## What is here, and what Wakes uses it for | path | what it is | for Wakes | |---|---|---| -| `usb-audio/uacring.{c,h}` | the ring buffer and the packet regulator: 47, 48 or 49 frames per 1 ms packet, following the drift between the SP-1's 3.072 MHz audio clock and the host's USB frames | **to be built.** Tuned upstream for 128- and 256-frame producer blocks; Wakes renders 96 (2 ms), so its constants need retuning (its host test fails at 96 as it stands) | -| `usb-audio/usb_audio.{c,h}` | glue between Zephyr's UAC2 class, the ring and the fast path, incl. stop on VBUS removed / bus reset and re-prime on resume | reference for M5c's glue; which class Wakes uses is still open (UAC1 or UAC2) | -| `test/test_uacring.c`, `test/run.sh` | host tests for the regulator | to be run by `tools/host-tests`, at 96 | +| `usb-audio/uacring.{c,h}` | the ring buffer and the packet regulator: 47, 48 or 49 frames per 1 ms packet, following the drift between the SP-1's 3.072 MHz audio clock and the host's USB frames | **used**, patched (below) and tuned for Wakes' 96-frame blocks in `firmware/src/sp1_uac_tuning.h` | +| `usb-audio/usb_audio.{c,h}` | glue between Zephyr's UAC2 class, the ring and the fast path, incl. stop on VBUS removed / bus reset and re-prime on resume | reference only: Wakes uses its own UAC1 class | +| `test/test_uacring.c`, `test/run.sh` | host tests for the regulator, on upstream's 128/256-frame bench | reference; it fails at 96 by design. Wakes' version with Wakes' render times is `tools/host-tests/uactest.c` | | `module/nrf-usbd-isofast/` | the ISO IN fast path: a patch against nRF Connect SDK's `udc_nrf.c` (`sdk-zephyr` `fd9204a0`), with that base kept as `patches/udc_nrf.c.upstream` | already ported to Zephyr 4.3.1 in `zephyr-patches/udc_nrf-fast-paths.patch` (`CONFIG_UDC_NRF_ISO_IN_FAST`, off). `udc_nrf.c.upstream` is the base for checking that port against 4.3.1's driver | | `docs/` | how it works, stock driver vs fast path (measured on an SP-1), lessons from the bench | reference | | `sp1/`, `extras/nrf52840dk/` | Ryan's complete SP-1 test firmware (a tone to speaker and USB) and a dev-board version | reference only; never built here | +## What Wakes' patch changes + +`patches/uacring.patch`, against `upstream/usb-audio/uacring.c`, applied STRICTLY to a copy at +build time (`tools/apply_patch.py`, as for feldd) and by `tools/host-tests/hostbuild.sh` for +`uactest`: + +- `uacring_push` and `uacring_pop` copy one 32-bit word per stereo frame (`frames_copy`, + `frames_zero`) instead of calling `memcpy` / `memset`. The SDK's picolibc copies one byte per + loop pass, ~6.6 cycles a byte on the SP-1 (#36); at 576 bytes per 2 ms that was ~4 points of + CPU, ~0.65 with the word copies (~1 cycle a byte, from the Cortex-M4 disassembly). +- The copy must be compiled with `-fno-tree-loop-distribute-patterns`, or GCC turns the loops + back into library calls (checked: it does, for the silence fill). `tools/ci/check_image.py` + fails an image where push or pop calls `memcpy`/`memset`. + +Nothing else: the ring, the regulator and the priming are upstream's. Wakes' tuning for 96-frame +blocks is not a patch either; it is `firmware/src/sp1_uac_tuning.h`, force-included ahead of +`uacring.h`. + Where Wakes deliberately differs from upstream (M5-PLAN, section E): - **USB audio follows VOL.** Upstream sends at a fixed −6 dB, independent of the volume. @@ -43,5 +61,6 @@ git -C archive | tar -x -C third_party/sp1-usb-audio/upstream ``` after emptying `upstream/`. Then read the upstream diff since the commit above (in particular -`module/nrf-usbd-isofast/patches/` against `zephyr-patches/udc_nrf-fast-paths.patch`), rebuild, -run the host tests, update the commit above, and test on hardware. +`module/nrf-usbd-isofast/patches/` against `zephyr-patches/udc_nrf-fast-paths.patch`), check +that `patches/uacring.patch` still applies (the build stops if it does not), re-run `uactest` +and its sweep if the regulator changed, update the commit above, and test on hardware. diff --git a/third_party/sp1-usb-audio/patches/uacring.patch b/third_party/sp1-usb-audio/patches/uacring.patch new file mode 100644 index 0000000..d42c660 --- /dev/null +++ b/third_party/sp1-usb-audio/patches/uacring.patch @@ -0,0 +1,81 @@ +--- a/uacring.c ++++ b/uacring.c +@@ -23,6 +23,42 @@ + #define HYSTERESIS UACRING_HYSTERESIS + #define FIX_EVERY 50u + ++/* Wakes (M5c): one 32-bit word per stereo frame instead of memcpy/memset. The SDK's ++ * picolibc copies ONE BYTE per loop pass (~6.6 cycles a byte on the SP-1, issue #36), and ++ * these run every 2 ms in the audio thread (push) and every 1 ms in the USB interrupt ++ * (pop): ~4 points of CPU through the library, ~0.5 this way. A frame is two int16_t, so ++ * every frame is a whole word. The buffers are at least 2-byte aligned (int16_t); the ++ * word type says so, and the Cortex-M4 loads and stores such words with single LDR/STR. ++ * ⚠️ Compiled with -fno-tree-loop-distribute-patterns, or GCC turns these loops straight ++ * back into memcpy/memset calls (sp1_zero.cc, #36). */ ++typedef uint32_t __attribute__((aligned(2), may_alias)) uac_frame_t; ++ ++static void frames_copy(int16_t *dst, const int16_t *src, uint32_t frames) ++{ ++ uac_frame_t *d = (uac_frame_t *)dst; ++ const uac_frame_t *s = (const uac_frame_t *)src; ++ ++ for (; frames >= 4u; frames -= 4u) { ++ const uint32_t f0 = s[0], f1 = s[1], f2 = s[2], f3 = s[3]; ++ ++ d[0] = f0; d[1] = f1; d[2] = f2; d[3] = f3; ++ d += 4; ++ s += 4; ++ } ++ for (; frames != 0u; frames--) { ++ *d++ = *s++; ++ } ++} ++ ++static void frames_zero(int16_t *dst, uint32_t frames) ++{ ++ uac_frame_t *d = (uac_frame_t *)dst; ++ ++ for (; frames != 0u; frames--) { ++ *d++ = 0u; ++ } ++} ++ + /* What the regulator steers: the fill counted to the CLAIMED position, which + * advances when the audio thread takes an I2S slot -- a time the audio clock + * paces -- instead of when the render finishes. A chord starting makes renders +@@ -99,11 +135,9 @@ + + uint32_t first = UACRING_CAPACITY - (write & RING_MASK); + if (first > frames) first = frames; +- memcpy(&r->data[(write & RING_MASK) * 2u], lr, +- first * 2u * sizeof(int16_t)); ++ frames_copy(&r->data[(write & RING_MASK) * 2u], lr, first); + if (first < frames) { +- memcpy(r->data, &lr[first * 2u], +- (frames - first) * 2u * sizeof(int16_t)); ++ frames_copy(r->data, &lr[first * 2u], frames - first); + } + UACRING_BARRIER(); + r->write = write + frames; +@@ -170,18 +204,16 @@ + uint32_t write = r->write; + UACRING_BARRIER(); + if (r->silence || r->priming || write - read < frames) { +- memset(lr, 0, frames * 2u * sizeof(int16_t)); ++ frames_zero(lr, frames); + if (!r->priming) r->under++; + return false; + } + + uint32_t first = UACRING_CAPACITY - (read & RING_MASK); + if (first > frames) first = frames; +- memcpy(lr, &r->data[(read & RING_MASK) * 2u], +- first * 2u * sizeof(int16_t)); ++ frames_copy(lr, &r->data[(read & RING_MASK) * 2u], first); + if (first < frames) { +- memcpy(&lr[first * 2u], r->data, +- (frames - first) * 2u * sizeof(int16_t)); ++ frames_copy(&lr[first * 2u], r->data, frames - first); + } + UACRING_BARRIER(); + r->read = read + frames; diff --git a/tools/ci/check_image.py b/tools/ci/check_image.py index 1af8138..7460990 100644 --- a/tools/ci/check_image.py +++ b/tools/ci/check_image.py @@ -183,6 +183,32 @@ def thumb_branch_targets(code, base): return out +def elf_func(elf): + """name -> (address, code bytes) of a linked function, or None.""" + symtab = elf.get_section_by_name(".symtab") + + def func(name): + for s in symtab.get_symbol_by_name(name) or []: + if s["st_info"]["type"] == "STT_FUNC" and s["st_size"] > 0: + addr = s["st_value"] & ~1 + for sec in elf.iter_sections(): + lo = sec["sh_addr"] + if sec["sh_type"] == "SHT_PROGBITS" and lo <= addr < lo + sec["sh_size"]: + return addr, sec.data()[addr - lo:addr - lo + s["st_size"]] + return None + return func + + +def libc_fills(func): + """picolibc's byte-loop copies and fills, by address.""" + libc = {} + for name in ("memset", "memcpy", "memmove"): + f = func(name) + if f: + libc[f[0]] = name + return libc + + def check_fast_clear(zd): """Plaits' engine-change clears must not run through picolibc's memset (issue #36). @@ -194,23 +220,8 @@ def check_fast_clear(zd): """ with open(zd / f"{NAME}.elf", "rb") as fh: elf = ELFFile(fh) - symtab = elf.get_section_by_name(".symtab") - - def func(name): - for s in symtab.get_symbol_by_name(name) or []: - if s["st_info"]["type"] == "STT_FUNC" and s["st_size"] > 0: - addr = s["st_value"] & ~1 - for sec in elf.iter_sections(): - lo = sec["sh_addr"] - if sec["sh_type"] == "SHT_PROGBITS" and lo <= addr < lo + sec["sh_size"]: - return addr, sec.data()[addr - lo:addr - lo + s["st_size"]] - return None - - libc = {} - for name in ("memset", "memcpy", "memmove"): - f = func(name) - if f: - libc[f[0]] = name + func = elf_func(elf) + libc = libc_fills(func) zero = func("_ZN6plaits8sp1_zeroEPvj") if zero is None: @@ -233,6 +244,30 @@ def func(name): ", ".join(calls) or "no libc fill") +def check_uac_copies(zd): + """USB audio's ring must not copy through picolibc (M5c). + + Its memcpy is a byte loop: ~4 points of CPU for the ring's push (audio thread, every + 2 ms) and pop (USB interrupt, every 1 ms), against ~0.65 with the word copies that + third_party/sp1-usb-audio/patches/uacring.patch puts in -- which GCC turns back into + library calls unless the patched copy is built with -fno-tree-loop-distribute-patterns. + Nothing to check while USB audio is not linked. + """ + with open(zd / f"{NAME}.elf", "rb") as fh: + elf = ELFFile(fh) + func = elf_func(elf) + if func("uacring_push") is None and func("uacring_pop") is None: + return + libc = libc_fills(func) + for name in ("uacring_push", "uacring_pop", "frames_copy", "frames_zero"): + f = func(name) + if f is None: + continue # the two helpers may be inlined + calls = [libc[t] for t in thumb_branch_targets(f[1], f[0]) if t in libc] + check(not calls, f"{name} copies without memcpy/memset (M5c)", + ", ".join(calls) or "word copies") + + def check_source(repo): # A header constant, not a build flag, so nothing else would catch a leftover 1: # the device would boot into the calibration wizard. @@ -258,6 +293,7 @@ def main(): if cfg.get("CONFIG_SP1_PLAITS") == "y": check_layouts(zd) check_fast_clear(zd) + check_uac_copies(zd) check_source(a.repo) failed = results.count(False) diff --git a/tools/host-tests/README.md b/tools/host-tests/README.md index b1fe98f..c1885fa 100644 --- a/tools/host-tests/README.md +++ b/tools/host-tests/README.md @@ -13,7 +13,7 @@ proved on a laptop, and because there is exactly one SP-1 (`docs/SAFETY.md`). | `miditest_clock.cc` | the same as `miditest.cc`, with real cycle-counter stamps on every tick | MIDI clock and transport into Marbles (M5b): tempo and position from ticks, ±1 ms of USB jitter, a stopped clock waiting, Start arming beat 1 on its own Plaits block, Marbles' beats at the host's tempo, RATE as Marbles' ratio table (×4, ×1/4), Stop / Continue, a stalled clock, PLAY on the host's clock, and the cable pulled (Marbles stops, own clock again) | | `miditest_alt.cc` | the same, built against `midi-alt.ini` (pickup `sum`) | omni, legato on, Yarns' portamento curve, velocity -> LEVEL, aftertouch -> TIMBRE, no sustain pedal, bend range | | `third_party/feldd/test/test_usb_rt_parse.c` | feldd's packet validator | feldd's own test, unmodified | -| `uactest.c` | Ryan Gilmore's USB audio ring and packet regulator (`third_party/sp1-usb-audio`, unmodified) at Wakes' tuning, `firmware/src/sp1_uac_tuning.h` | USB audio out (M5c): ±200 ppm of clock drift, a heavy patch starting and stopping, a 200 % block every 997, with no underflow, no lost frame, a margin left in the ring, at most 20 packet-size corrections a second and none from load alone; priming, underflow, overflow | +| `uactest.c` | Ryan Gilmore's USB audio ring and packet regulator (`third_party/sp1-usb-audio`, with Wakes' word-copy patch applied as the firmware will) at Wakes' tuning, `firmware/src/sp1_uac_tuning.h` | USB audio out (M5c): ±200 ppm of clock drift, a heavy patch starting and stopping, a 200 % block every 997, with no underflow, no lost frame, a margin left in the ring, at most 20 packet-size corrections a second and none from load alone; priming, underflow, overflow | ```sh tools/host-tests/hostbuild.sh routetest.cc uitest.c miditest.cc miditest_alt.cc \ diff --git a/tools/host-tests/hostbuild.sh b/tools/host-tests/hostbuild.sh index 77ab40c..55e46f1 100644 --- a/tools/host-tests/hostbuild.sh +++ b/tools/host-tests/hostbuild.sh @@ -104,11 +104,15 @@ for t in "$@"; do out=$SP/$(basename "${t%.*}") case $t in *uactest.c) - # USB audio out (M5c): Ryan Gilmore's ring + regulator, unmodified, at Wakes' tuning -- - # sp1_uac_tuning.h force-included as the firmware does. EXTRA_UAC_FLAGS is for the - # re-tuning sweep only (README). - gcc -std=c99 -O2 -Wall -include "$SRC/sp1_uac_tuning.h" $EXTRA_UAC_FLAGS -I"$UAC" \ - "$t" "$UAC/uacring.c" -o "$out" ;; + # USB audio out (M5c): Ryan Gilmore's ring + regulator with Wakes' patch (word copies, + # third_party/sp1-usb-audio/patches/uacring.patch) applied to a copy, STRICTLY, and + # built the way the firmware builds it; sp1_uac_tuning.h force-included. EXTRA_UAC_FLAGS + # is for the re-tuning sweep only (README). + python3 "$ROOT/tools/apply_patch.py" "$UAC/uacring.c" \ + "$ROOT/third_party/sp1-usb-audio/patches/uacring.patch" "$SP/uacring.c" + gcc -std=c99 -O2 -Wall -fno-tree-loop-distribute-patterns -fno-unroll-loops \ + -include "$SRC/sp1_uac_tuning.h" $EXTRA_UAC_FLAGS -I"$UAC" \ + "$t" "$SP/uacring.c" -o "$out" ;; *test_usb_rt_parse.c) # feldd's own host test of the packet validator Wakes uses (third_party/feldd). gcc -std=gnu11 -O2 "$t" "$FELDD/src/usb_rt_parse.c" -o "$out" ;; From 37ed74fabe6761e78b10703d5272e9da40c38b60 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 17:56:35 -0400 Subject: [PATCH 04/10] M5c: USB audio out -- a USB Audio Class 1.0 input, "Wakes Audio Out" The SP-1's output, after VOL and the output select (the samples the codecs get), goes to the host as a 48 kHz 16-bit stereo UAC1 input. Nothing is received from the host. - src/sp1_uac.{c,h} (Apache-2.0; the fill function and stream start/stop follow Ryan Gilmore's usb_audio.c): a hand-rolled UAC1 function in the shape of feldd's MIDI class. AudioControl (header, input terminal "line connector", USB streaming output terminal) + AudioStreaming alt 0/1, Type I PCM, one ISO IN endpoint, asynchronous with no feedback endpoint, 9-byte endpoint descriptor, 196-byte packets. No IAD, like the MIDI function the OP-XY accepts. Sample-rate requests answered though not advertised. Named "Wakes Audio Out" on its interfaces and input terminal. - Packets go out from the USB interrupt through the ISO IN fast path, registered when the host selects alternate setting 1 and removed on 0, disable, VBUS removed and bus reset; a resume re-primes the ring. - zephyr-patches/udc_nrf-fast-paths.patch: the SOF interrupt now runs only while a fill is registered (kept across a restart), and no SOF event reaches the stack then -- a device that is not streaming pays nothing. - sp1_audio.c: sp1_uac_claim() as a block starts rendering, sp1_uac_push() with the finished block. Ring = Ryan's uacring.c with Wakes' word-copy patch, built -fno-tree-loop-distribute-patterns with sp1_uac_tuning.h. - Class order by name: cdc_acm_0, usb_midi1, wakes_uac (checked in the image), so the console and MIDI keep their interface numbers. - USB identity: PID 0x5213 (interim; pid.codes 1209:4440 requested), product "Wakes" (was wakes-sp1 -- also the MIDI port's name; docs/MIDI.md says to re-select it), manufacturer "Worldwave". console-log.py knows 0x5213. - main.c: "audio out=" on the USB boot line; a UAC status line every 5 s while the stream is open. Build: 426 788 B (46.72 %), RAM 178 408 B, 0 warnings, check_image OK incl. the push/pop word-copy checks; fallback 86 372 B OK. Not yet on hardware. Co-Authored-By: Claude Opus 5.5 --- LICENSES/README.md | 2 +- NOTICE | 6 +- docs/MIDI.md | 3 +- firmware/CMakeLists.txt | 27 ++ firmware/Kconfig | 24 +- firmware/prj.conf | 3 + firmware/src/main.c | 31 +- firmware/src/sp1_audio.c | 14 + firmware/src/sp1_uac.c | 565 ++++++++++++++++++++++++ firmware/src/sp1_uac.h | 46 ++ firmware/src/sp1_usbd.c | 13 +- tools/console-log.py | 7 +- zephyr-patches/udc_nrf-fast-paths.patch | 54 ++- 13 files changed, 771 insertions(+), 24 deletions(-) create mode 100644 firmware/src/sp1_uac.c create mode 100644 firmware/src/sp1_uac.h diff --git a/LICENSES/README.md b/LICENSES/README.md index 270d11e..b7f719e 100644 --- a/LICENSES/README.md +++ b/LICENSES/README.md @@ -12,7 +12,7 @@ what was changed. | `MIT-sp1-tape-looper.txt` | chattock | the board definition, power-off and watchdog sequence, and codec bring-up adapted from chattock/sp1-tape-looper | | `MIT-SP-1-dev.txt` | Tim Knapen | the SP-1 pin map and hardware documentation from timknapen/SP-1-dev | | `MIT-sp1-midi.txt` | Eric Lewis | the original `stem_player` Zephyr board that the board definition descends from | -| `Apache-2.0.txt` | the Zephyr Project contributors; Ryan Gilmore | `third_party/sp1-usb-audio/` (USB audio out; it also carries its own `LICENSE` and `NOTICE`), `boards/teenageengineering/stem_player/Kconfig.defconfig`, `Kconfig.stem_player` and `stem_player_defconfig` (inherited from Zephyr's board template), `zephyr-patches/`, `firmware/src/sp1_usbd.c` (derived from Zephyr's USB sample helper), and the Zephyr RTOS compiled into every firmware image | +| `Apache-2.0.txt` | the Zephyr Project contributors; Ryan Gilmore | `third_party/sp1-usb-audio/` (USB audio out; it also carries its own `LICENSE` and `NOTICE`), `firmware/src/sp1_uac.{c,h}` and `tools/host-tests/uactest.c` (derived from it), `boards/teenageengineering/stem_player/Kconfig.defconfig`, `Kconfig.stem_player` and `stem_player_defconfig` (inherited from Zephyr's board template), `zephyr-patches/`, `firmware/src/sp1_usbd.c` (derived from Zephyr's USB sample helper), and the Zephyr RTOS compiled into every firmware image | A built firmware image also contains other Zephyr modules (CMSIS, Nordic's `hal_nordic`) under their own licences. Release archives will carry a generated bill of materials listing them. diff --git a/NOTICE b/NOTICE index 098cc65..1041f06 100644 --- a/NOTICE +++ b/NOTICE @@ -119,8 +119,10 @@ USB audio out (M5c) — vendored unmodified in third_party/sp1-usb-audio/upstrea MODIFIED by third_party/sp1-usb-audio/patches/uacring.patch (word copies in place of memcpy/memset), applied at build time to a copy; the vendored file is unchanged. tools/host-tests/uactest.c is derived from its - test/test_uacring.c and stays Apache-2.0. Commit and what each part is for: - third_party/sp1-usb-audio/README.md. + test/test_uacring.c and stays Apache-2.0. firmware/src/sp1_uac.{c,h} (the + USB Audio Class 1.0 function) follow its usb-audio/usb_audio.c for the fill + function and the stream start/stop, and are Apache-2.0. Commit and what each + part is for: third_party/sp1-usb-audio/README.md. Zephyr RTOS — Apache-2.0 — https://github.com/zephyrproject-rtos/zephyr Licence text: LICENSES/Apache-2.0.txt diff --git a/docs/MIDI.md b/docs/MIDI.md index f6ff821..ec58e85 100644 --- a/docs/MIDI.md +++ b/docs/MIDI.md @@ -1,7 +1,8 @@ # MIDI on Wakes Plug the SP-1 into a computer, phone or a USB host like the OP-XY, and Wakes shows up as a -class-compliant **USB-MIDI** port called `wakes-sp1` — no driver. It listens; it does not send. +class-compliant **USB-MIDI** port called `Wakes` — no driver. It listens; it does not send. +(Through v0.6.x the port was called `wakes-sp1`: re-select it once in your DAW or host.) Nothing about it needs setting up on the device, and there are **no new pages**: notes play Plaits straight away, and everything deeper is set in the MIDI script, diff --git a/firmware/CMakeLists.txt b/firmware/CMakeLists.txt index 5f18afa..9a20488 100644 --- a/firmware/CMakeLists.txt +++ b/firmware/CMakeLists.txt @@ -414,4 +414,31 @@ if(CONFIG_SP1_PLAITS) target_sources(app PRIVATE ${FELDD_OUT} ${FELDD}/src/usb_rt_parse.c) target_include_directories(app PRIVATE ${FELDD}/src) endif() + + if(CONFIG_SP1_USB_AUDIO) + # M5c: USB audio out. The class is ours (src/sp1_uac.c); the ring and packet + # regulator are Ryan Gilmore's uacring.c, vendored unmodified in + # third_party/sp1-usb-audio, with Wakes' patch (word copies instead of picolibc's + # byte-loop memcpy) applied to a copy STRICTLY, as for feldd above. + set(UAC ${CMAKE_CURRENT_SOURCE_DIR}/../third_party/sp1-usb-audio) + set(UAC_OUT ${CMAKE_CURRENT_BINARY_DIR}/sp1-usb-audio/uacring.c) + execute_process( + COMMAND ${Python3_EXECUTABLE} + ${CMAKE_CURRENT_SOURCE_DIR}/../tools/apply_patch.py + ${UAC}/upstream/usb-audio/uacring.c ${UAC}/patches/uacring.patch ${UAC_OUT} + RESULT_VARIABLE uac_rc) + if(NOT uac_rc EQUAL 0) + message(FATAL_ERROR "third_party/sp1-usb-audio/patches/uacring.patch does not apply") + endif() + set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS + ${UAC}/upstream/usb-audio/uacring.c ${UAC}/patches/uacring.patch + ${CMAKE_CURRENT_SOURCE_DIR}/../tools/apply_patch.py) + target_sources(app PRIVATE src/sp1_uac.c ${UAC_OUT}) + target_include_directories(app PRIVATE ${UAC}/upstream/usb-audio) + # Wakes' tuning (96-frame blocks) ahead of uacring.h, exactly as uactest builds it; + # and no loop distribution, or GCC turns the word copies back into memcpy/memset + # calls (tools/ci/check_image.py checks the image). + set_source_files_properties(${UAC_OUT} PROPERTIES COMPILE_OPTIONS + "-include;${CMAKE_CURRENT_SOURCE_DIR}/src/sp1_uac_tuning.h;-fno-tree-loop-distribute-patterns;-fno-unroll-loops") + endif() endif() diff --git a/firmware/Kconfig b/firmware/Kconfig index 241e075..1d4b8c0 100644 --- a/firmware/Kconfig +++ b/firmware/Kconfig @@ -15,17 +15,22 @@ config SP1_USB_VID config SP1_USB_PID hex "USB product ID" - default 0x5212 + default 0x5213 help - 0x5211 through M4e (console only); 0x5212 from M5a (console + MIDI). + 0x5211 through M4e (console only); 0x5212 from M5a (console + MIDI); + 0x5213 from M5c (console + MIDI + audio out). Interim: pid.codes + 1209:4440 is requested (pidcodes/pidcodes.github.com#1301). config SP1_USB_MANUFACTURER string "USB manufacturer string" - default "worldwave" + default "Worldwave" config SP1_USB_PRODUCT string "USB product string (the name hosts show for the device and its MIDI port)" - default "wakes-sp1" + default "Wakes" + help + "wakes-sp1" through v0.6.x; "Wakes" from M5c (Adara). DAWs remember MIDI routings by + port name, so a change means re-selecting the port once on each host. config SP1_USB_MAX_POWER int "bMaxPower, in units of 2 mA" @@ -111,6 +116,17 @@ config SP1_MIDI config/midi.ini at build time. Costs nothing until a host sends something. n: no MIDI function on the USB device at all. +config SP1_USB_AUDIO + bool "USB audio out: the SP-1's output to the host, USB Audio Class 1.0 (M5c)" + default y + depends on SP1_PLAITS && UDC_NRF_ISO_IN_FAST + help + The output the codecs get, after VOL, sent to the host as a 48 kHz 16-bit + stereo input (src/sp1_uac.c). Output only: nothing is received from the host. + Packets go out from the USB interrupt through the ISO IN fast path + (zephyr-patches/udc_nrf-fast-paths.patch), which is required. Costs nothing + until a host opens the stream. + config SP1_PLAITS bool "Plaits voice as the audio source (M3)" default y diff --git a/firmware/prj.conf b/firmware/prj.conf index dd5ca68..14d264d 100644 --- a/firmware/prj.conf +++ b/firmware/prj.conf @@ -49,6 +49,9 @@ CONFIG_RING_BUFFER=y # That frees Zephyr's USB threads to run below audio (CONFIG_SP1_USB_THREADS_BELOW_AUDIO, # on by default with it). CONFIG_UDC_NRF_OUT_FAST=y +# M5c: USB audio out sends every packet from the USB interrupt (Ryan Gilmore's ISO IN fast +# path, same patch). CONFIG_SP1_USB_AUDIO (default y) needs it. +CONFIG_UDC_NRF_ISO_IN_FAST=y CONFIG_LOG=n CONFIG_ASSERT=n diff --git a/firmware/src/main.c b/firmware/src/main.c index 702d296..4d6154d 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -92,6 +92,9 @@ #include "sp1_release_guard.h" #include "sp1_midi.h" #endif +#if defined(CONFIG_SP1_USB_AUDIO) +#include "sp1_uac.h" +#endif #define WDT_NODE DT_ALIAS(watchdog0) @@ -1040,11 +1043,12 @@ int main(void) (unsigned)((CONFIG_I2S_NRFX_TX_BLOCK_COUNT + 3) * (CONFIG_SP1_AUDIO_BLOCK_FRAMES / 48))); /* #32: which USB path this build takes, so every log says it. */ - printk("USB midi=%s threads=%s\n", + printk("USB midi=%s threads=%s audio out=%s\n", IS_ENABLED(CONFIG_UDC_NRF_OUT_FAST) ? "in the interrupt (fast path)" : "usbd thread", sp1_usbd_threads_demoted() == 2 ? "below audio" - : "above audio (stock)"); + : "above audio (stock)", + IS_ENABLED(CONFIG_SP1_USB_AUDIO) ? "UAC1 48k/16/2, fast path" : "off"); } sp1_playrow_reset(); uint32_t aud_print = 0; @@ -2013,6 +2017,29 @@ int main(void) } } } +#endif +#if defined(CONFIG_SP1_USB_AUDIO) + /* USB audio out (M5c), while the host has the stream open and once more + * after it closes. Counts are since the stream opened (the ring's), + * except replaced and sr (since boot). fill hovers near the target when + * the clocks agree; 47s / 49s are the regulator following drift + * (~10 a second at +/-200 ppm, none from load); under means a packet + * went out silent, over a block found no room. */ + { + static bool uac_was_open; + static uint32_t uac_opens_seen; + struct sp1_uac_stats us; + sp1_uac_get_stats(&us); + if (us.open || uac_was_open || us.opens != uac_opens_seen) { + printk("UAC open=%d opens=%u pkts=%u fill=%u (target %u)" + " 47s=%u 49s=%u under=%u over=%u replaced=%u sr=%u\n", + us.open ? 1 : 0, us.opens, us.packets, us.fill, + us.target, us.n47, us.n49, us.under, us.over, + us.replaced, us.sr_requests); + } + uac_was_open = us.open; + uac_opens_seen = us.opens; + } #endif } diff --git a/firmware/src/sp1_audio.c b/firmware/src/sp1_audio.c index 5d17dc5..7f09569 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -51,6 +51,10 @@ BUILD_ASSERT(BLK_FRAMES % 48u == 0u, * re-prime. tape-looper measured the structural peak at exactly queue + 3 (7 at 4). */ K_MEM_SLAB_DEFINE_STATIC(tx_slab, BLK_BYTES, TX_QUEUE + 4, 4); +#if defined(CONFIG_SP1_USB_AUDIO) +#include "sp1_uac.h" /* M5c: the same blocks, to the host */ +#endif + #if defined(CONFIG_SP1_MIDI) #include "sp1_midi.h" /* The MIDI clock leads by Wakes' own output delay (sp1_midi.h, SP1_MIDI_OUTPUT_LATENCY_MS), @@ -431,6 +435,12 @@ static void audio_thread(void *a, void *b, void *c) continue; /* slept 100 ms; re-check stop */ } +#if defined(CONFIG_SP1_USB_AUDIO) + /* M5c: this block's place on the audio clock, taken as its render starts -- + * the slot I2S just freed. USB audio's regulator steers on these claims, so + * a long render is not mistaken for clock drift (sp1_uac_tuning.h). */ + sp1_uac_claim(BLK_FRAMES); +#endif const uint32_t c0 = DWT->CYCCNT; #if defined(CONFIG_SP1_PROFILE_ICACHE) const uint32_t m0 = NRF_NVMC->IMISS; @@ -447,6 +457,10 @@ static void audio_thread(void *a, void *b, void *c) win_sum += cyc; win_n++; account_sections(cyc, miss); +#if defined(CONFIG_SP1_USB_AUDIO) + /* ...and the block itself, after VOL: what the codecs get, to the host. */ + sp1_uac_push((const int16_t *)blk, BLK_FRAMES); +#endif if (i2s_write(i2s_dev, blk, BLK_BYTES) != 0) { k_mem_slab_free(&tx_slab, blk); diff --git a/firmware/src/sp1_uac.c b/firmware/src/sp1_uac.c new file mode 100644 index 0000000..e4ac36f --- /dev/null +++ b/firmware/src/sp1_uac.c @@ -0,0 +1,565 @@ +/* + * Copyright (c) 2026 Ryan Gilmore + * Copyright (c) 2026 Adara Barami | Worldwave + * + * SPDX-License-Identifier: Apache-2.0 + */ +/* wakes-sp1 -- USB audio OUT (M5c). See sp1_uac.h. + * + * The SP-1's output goes to the host as a USB Audio Class 1.0 input: 48 kHz, 16-bit, + * stereo, the selected output configuration after VOL (M5-PLAN, A and E2). Nothing is + * received from the host: there is no ISO OUT endpoint and no feedback endpoint. + * + * ---- why a hand-rolled UAC1 class ---- + * One class, the cheapest on CPU and the most stable across the OP-XY and computers (Adara, + * 2026-10-05). The audio data costs the same either way: every packet goes through the ISO IN + * fast path in the USB interrupt (zephyr-patches/udc_nrf-fast-paths.patch), and a class only + * runs on the host's occasional control requests. What differs is stability. UAC2 requires an + * Interface Association Descriptor, and an IAD in front of an Audio function is what feldd found + * hard-faults the OP-XY (third_party/feldd). UAC1 has no IAD and no clock entities -- the same + * class family as the USB-MIDI 1.0 port the OP-XY already accepts -- and every OS has carried a + * UAC1 driver for decades. Zephyr has no UAC1 class, so this is one, in the shape of feldd's + * MIDI class (static descriptors, a usbd_class_api, no devicetree node). + * + * ---- what is Ryan's ---- + * Derived from Ryan Gilmore's sp1-usb-audio (third_party/sp1-usb-audio, Apache-2.0): the ring + * and packet regulator are his uacring.c (with Wakes' word-copy patch and 96-frame tuning), and + * the fill function, the stream start/stop and the bus-event handling below follow his + * usb_audio.c, which glues the same pieces to Zephyr's UAC2 class instead. + * + * ---- threads ---- + * - the class callbacks and sp1_uac_bus_event(): the usbd thread (below audio, #32) + * - fill(): the USB interrupt, once a millisecond while the stream is open + * - sp1_uac_claim() / sp1_uac_push(): the audio thread + * The ring is single-producer / single-consumer (uacring.h); the usbd thread only starts and + * stops it, with the interrupt held off while the consumer side is reset. + * + * ---- CPU (Adara's go-ahead, 2026-10-05) ---- + * Only while the host has the stream open: the 1 kHz SOF interrupt (the driver turns it on with + * the fast path and off again, so a device that is not streaming pays nothing), one 192-byte + * word copy in it, and one 384-byte word copy per 2 ms block in the audio thread. ~0.65 points + * for the copies by the Cortex-M4 disassembly; measure the whole on hardware. */ +#include "sp1_uac.h" + +#include +#include +#include +#include +#include +#include +#include + +#include "sp1_uac_tuning.h" /* before uacring.h, as the ring itself is built */ +#include "uacring.h" + +/* ---- USB Device Class Definition for Audio Devices, Release 1.0 ---- */ +#define UAC_CLASS 0x01 /* bInterfaceClass: Audio */ +#define UAC_SUBCLASS_CONTROL 0x01 +#define UAC_SUBCLASS_STREAMING 0x02 +/* A.5 / A.6 / A.8: class-specific descriptor subtypes */ +#define UAC_AC_HEADER 0x01 +#define UAC_AC_INPUT_TERMINAL 0x02 +#define UAC_AC_OUTPUT_TERMINAL 0x03 +#define UAC_AS_GENERAL 0x01 +#define UAC_AS_FORMAT_TYPE 0x02 +#define UAC_EP_GENERAL 0x01 +/* Terminal types (USB Audio Terminal Types 1.0): the stream to the host is a USB streaming + * output terminal, fed by an input terminal that is the SP-1's line output. "Line connector" + * is the conventional type for an instrument's capture input; hosts name the input after it. + * (Ryan's UAC2 build uses "synthesizer", 0x0713, and worked on macOS.) */ +#define UAC_TT_USB_STREAMING 0x0101 +#define UAC_TT_LINE_CONNECTOR 0x0603 +/* A.10 / A.9: format and requests */ +#define UAC_FORMAT_TYPE_I 0x01 +#define UAC_FORMAT_PCM 0x0001 +#define UAC_SET_CUR 0x01 +#define UAC_GET_CUR 0x81 +#define UAC_GET_MIN 0x82 +#define UAC_GET_MAX 0x83 +#define UAC_GET_RES 0x84 +#define UAC_EP_SAMPLING_FREQ 0x01 /* endpoint control selector */ + +#define IT_ID 1 +#define OT_ID 2 +#define SAMPLE_RATE 48000u +#define CHANNELS 2u +#define FRAME_BYTES (CHANNELS * 2u) +/* 49 frames: the largest packet the regulator sends (uacring.h). */ +#define MAX_PACKET (49u * FRAME_BYTES) +/* Isochronous, asynchronous (bmAttributes bits 1:0 = 01, 3:2 = 01): the SP-1's own 3.072 MHz + * clock paces the audio and the regulator sizes packets 47/48/49 to it -- no feedback + * endpoint, so none of the host-side quirks that come with one. */ +#define EP_ISO_ASYNC 0x05 +/* A hint: the stack assigns the real address at usbd_init, and on the nRF52840 the only + * isochronous IN endpoint is 0x88 (udc_nrf's ISO caps), which the fast path serves. */ +#define EP_IN_HINT 0x81 + +BUILD_ASSERT(MAX_PACKET <= UDC_NRF_ISO_IN_FAST_MAX, "a packet must fit the fast path's buffer"); +BUILD_ASSERT(AUDIO_BLK_FRAMES == CONFIG_SP1_AUDIO_BLOCK_FRAMES, + "the ring is tuned for another block (sp1_uac_tuning.h)"); + +struct uac_ac_header { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint16_t bcdADC; + uint16_t wTotalLength; + uint8_t bInCollection; + uint8_t baInterfaceNr1; +} __packed; + +struct uac_input_terminal { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint8_t bTerminalID; + uint16_t wTerminalType; + uint8_t bAssocTerminal; + uint8_t bNrChannels; + uint16_t wChannelConfig; + uint8_t iChannelNames; + uint8_t iTerminal; +} __packed; + +struct uac_output_terminal { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint8_t bTerminalID; + uint16_t wTerminalType; + uint8_t bAssocTerminal; + uint8_t bSourceID; + uint8_t iTerminal; +} __packed; + +struct uac_as_general { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint8_t bTerminalLink; + uint8_t bDelay; + uint16_t wFormatTag; +} __packed; + +struct uac_format_type_i { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint8_t bFormatType; + uint8_t bNrChannels; + uint8_t bSubframeSize; + uint8_t bBitResolution; + uint8_t bSamFreqType; + uint8_t tSamFreq[3]; +} __packed; + +/* The Audio 1.0 endpoint descriptor: the standard 7 bytes + bRefresh + bSynchAddress. feldd + * found that strict hosts drop a port whose audio-class endpoint is the 7-byte kind. The stack + * rewrites bEndpointAddress and wMaxPacketSize through the 7-byte layout, which is a prefix. */ +struct uac_iso_ep { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bEndpointAddress; + uint8_t bmAttributes; + uint16_t wMaxPacketSize; + uint8_t bInterval; + uint8_t bRefresh; + uint8_t bSynchAddress; +} __packed; + +struct uac_cs_iso_ep { + uint8_t bLength; + uint8_t bDescriptorType; + uint8_t bDescriptorSubtype; + uint8_t bmAttributes; + uint8_t bLockDelayUnits; + uint16_t wLockDelay; +} __packed; + +struct uac_descriptors { + struct usb_if_descriptor ac; /* AudioControl, no endpoints */ + struct uac_ac_header ac_header; + struct uac_input_terminal it; + struct uac_output_terminal ot; + struct usb_if_descriptor as0; /* AudioStreaming, zero bandwidth */ + struct usb_if_descriptor as1; /* AudioStreaming, the stream */ + struct uac_as_general as_general; + struct uac_format_type_i format; + struct uac_iso_ep ep; + struct uac_cs_iso_ep cs_ep; +}; + +#define AC_TOTAL_LENGTH (sizeof(struct uac_ac_header) + sizeof(struct uac_input_terminal) + \ + sizeof(struct uac_output_terminal)) + +static struct uac_descriptors desc = { + .ac = { + .bLength = sizeof(struct usb_if_descriptor), + .bDescriptorType = USB_DESC_INTERFACE, + .bInterfaceNumber = 0, /* stamped at usbd_init */ + .bAlternateSetting = 0, + .bNumEndpoints = 0, + .bInterfaceClass = UAC_CLASS, + .bInterfaceSubClass = UAC_SUBCLASS_CONTROL, + .bInterfaceProtocol = 0, + .iInterface = 0, + }, + .ac_header = { + .bLength = sizeof(struct uac_ac_header), + .bDescriptorType = USB_DESC_CS_INTERFACE, + .bDescriptorSubtype = UAC_AC_HEADER, + .bcdADC = sys_cpu_to_le16(0x0100), + .wTotalLength = sys_cpu_to_le16(AC_TOTAL_LENGTH), + .bInCollection = 1, + .baInterfaceNr1 = 1, /* the AS interface; fixed up in init */ + }, + .it = { + .bLength = sizeof(struct uac_input_terminal), + .bDescriptorType = USB_DESC_CS_INTERFACE, + .bDescriptorSubtype = UAC_AC_INPUT_TERMINAL, + .bTerminalID = IT_ID, + .wTerminalType = sys_cpu_to_le16(UAC_TT_LINE_CONNECTOR), + .bAssocTerminal = 0, + .bNrChannels = CHANNELS, + .wChannelConfig = sys_cpu_to_le16(0x0003), /* left front, right front */ + .iChannelNames = 0, + .iTerminal = 0, + }, + .ot = { + .bLength = sizeof(struct uac_output_terminal), + .bDescriptorType = USB_DESC_CS_INTERFACE, + .bDescriptorSubtype = UAC_AC_OUTPUT_TERMINAL, + .bTerminalID = OT_ID, + .wTerminalType = sys_cpu_to_le16(UAC_TT_USB_STREAMING), + .bAssocTerminal = 0, + .bSourceID = IT_ID, + .iTerminal = 0, + }, + .as0 = { + .bLength = sizeof(struct usb_if_descriptor), + .bDescriptorType = USB_DESC_INTERFACE, + .bInterfaceNumber = 1, /* stamped at usbd_init */ + .bAlternateSetting = 0, + .bNumEndpoints = 0, + .bInterfaceClass = UAC_CLASS, + .bInterfaceSubClass = UAC_SUBCLASS_STREAMING, + .bInterfaceProtocol = 0, + .iInterface = 0, + }, + .as1 = { + .bLength = sizeof(struct usb_if_descriptor), + .bDescriptorType = USB_DESC_INTERFACE, + .bInterfaceNumber = 1, /* stamped at usbd_init */ + .bAlternateSetting = 1, + .bNumEndpoints = 1, + .bInterfaceClass = UAC_CLASS, + .bInterfaceSubClass = UAC_SUBCLASS_STREAMING, + .bInterfaceProtocol = 0, + .iInterface = 0, + }, + .as_general = { + .bLength = sizeof(struct uac_as_general), + .bDescriptorType = USB_DESC_CS_INTERFACE, + .bDescriptorSubtype = UAC_AS_GENERAL, + .bTerminalLink = OT_ID, + .bDelay = 1, + .wFormatTag = sys_cpu_to_le16(UAC_FORMAT_PCM), + }, + .format = { + .bLength = sizeof(struct uac_format_type_i), + .bDescriptorType = USB_DESC_CS_INTERFACE, + .bDescriptorSubtype = UAC_AS_FORMAT_TYPE, + .bFormatType = UAC_FORMAT_TYPE_I, + .bNrChannels = CHANNELS, + .bSubframeSize = 2, + .bBitResolution = 16, + .bSamFreqType = 1, /* one discrete rate */ + .tSamFreq = { SAMPLE_RATE & 0xFFu, (SAMPLE_RATE >> 8) & 0xFFu, + (SAMPLE_RATE >> 16) & 0xFFu }, + }, + .ep = { + .bLength = sizeof(struct uac_iso_ep), + .bDescriptorType = USB_DESC_ENDPOINT, + .bEndpointAddress = EP_IN_HINT, /* assigned at usbd_init: 0x88 */ + .bmAttributes = EP_ISO_ASYNC, + .wMaxPacketSize = sys_cpu_to_le16(MAX_PACKET), + .bInterval = 1, /* every 1 ms frame */ + .bRefresh = 0, + .bSynchAddress = 0, + }, + .cs_ep = { + .bLength = sizeof(struct uac_cs_iso_ep), + .bDescriptorType = USB_DESC_CS_ENDPOINT, + .bDescriptorSubtype = UAC_EP_GENERAL, + /* No sampling-frequency control advertised: there is one rate. A host that sets + * it anyway is answered (control_to_dev / control_to_host below). */ + .bmAttributes = 0, + .bLockDelayUnits = 0, + .wLockDelay = 0, + }, +}; + +static const struct usb_desc_header *fs_desc[] = { + /* No IAD (see the top of this file): an Audio 1.0 function is grouped by its + * AudioControl header's collection, exactly as the MIDI function is. */ + (struct usb_desc_header *)&desc.ac, + (struct usb_desc_header *)&desc.ac_header, + (struct usb_desc_header *)&desc.it, + (struct usb_desc_header *)&desc.ot, + (struct usb_desc_header *)&desc.as0, + (struct usb_desc_header *)&desc.as1, + (struct usb_desc_header *)&desc.as_general, + (struct usb_desc_header *)&desc.format, + (struct usb_desc_header *)&desc.ep, + (struct usb_desc_header *)&desc.cs_ep, + NULL, +}; + +/* What hosts may call the input (Adara, 2026-10-05). On the AudioControl and both + * AudioStreaming interfaces and on the input terminal, so whichever one a host reads says the + * same; many show the device's product string (CONFIG_SP1_USB_PRODUCT, "Wakes") instead. */ +USBD_DESC_STRING_DEFINE(uac_name, "Wakes Audio Out", USBD_DUT_STRING_INTERFACE); + +static struct uacring ring; +static volatile bool stream_open; +static volatile uint32_t opens; +static volatile uint32_t sr_requests; + +/* ---- the fast path: the USB interrupt, once a millisecond while the stream is open ---- + * Ryan's uac2_fast_fill: short, lock-free, never blocking. uacring_pop() writes silence when + * there is nothing to send (priming, an underflow), so every frame carries a whole packet. */ +static uint16_t fill(uint8_t *buf, uint16_t max, void *user_data) +{ + ARG_UNUSED(user_data); + uint32_t frames = uacring_packet_frames(&ring); + + if (frames * FRAME_BYTES > max) { + frames = max / FRAME_BYTES; + } + (void)uacring_pop(&ring, (int16_t *)buf, frames); + return (uint16_t)(frames * FRAME_BYTES); +} + +/* ---- starting and stopping (the usbd thread) ---- */ +static void ring_restart(void) +{ + /* The consumer is the USB interrupt: keep it out while the ring's consumer state is + * reset. A few microseconds. (The producer may be mid-push; uacring_stream() only moves + * the consumer's index, so that is safe -- uacring.c.) */ + const unsigned int key = irq_lock(); + + uacring_stream(&ring, true); + irq_unlock(key); +} + +static void stream_on(void) +{ + ring_restart(); + stream_open = true; + opens = opens + 1u; + /* Registering also turns the SOF interrupt on; suppress SOF events to the stack, since + * no class here needs them and each one would wake the usbd thread. */ + udc_nrf_iso_in_fast_set(fill, NULL, true); +} + +static void stream_off(void) +{ + if (!stream_open) { + return; + } + /* Unregister first (and with it the SOF interrupt): from here the interrupt no longer + * reads the ring, so stopping it races nothing. */ + udc_nrf_iso_in_fast_set(NULL, NULL, true); + stream_open = false; + + const unsigned int key = irq_lock(); + + uacring_stream(&ring, false); + irq_unlock(key); +} + +void sp1_uac_bus_event(int type) +{ + switch (type) { + case USBD_MSG_VBUS_REMOVED: + case USBD_MSG_RESET: + /* The class hears a stream stop only as alternate setting 0. A pulled cable never + * sends one, and a bus reset returns every interface to 0 without telling the + * class (Ryan: "the stream stayed on and the unit stayed on battery"). The host + * selects the stream again when it wants it. */ + stream_off(); + break; + case USBD_MSG_RESUME: + /* Nothing drained while the host slept, so the ring is full: a stream resumed on + * that would run ~40 ms late and drift back for minutes. Re-prime it. ⚠️ Not yet + * exercised anywhere (upstream: macOS closes the stream before it sleeps). */ + if (stream_open) { + ring_restart(); + } + break; + default: + break; + } +} + +/* ---- the producer (the audio thread) ---- */ +void sp1_uac_claim(uint32_t frames) +{ + if (stream_open) { + uacring_claim(&ring, frames); + } +} + +void sp1_uac_push(const int16_t *lr, uint32_t frames) +{ + if (stream_open) { + (void)uacring_push(&ring, lr, frames); + } +} + +void sp1_uac_get_stats(struct sp1_uac_stats *st) +{ + struct uacring_stats rs; + struct udc_nrf_iso_in_fast_stats ds; + + uacring_stats(&ring, &rs); + udc_nrf_iso_in_fast_stats_get(&ds); + st->open = stream_open; + st->opens = opens; + st->packets = rs.packets; + st->n47 = rs.n47; + st->n49 = rs.n49; + st->under = rs.under; + st->over = rs.over; + st->fill = rs.fill; + st->target = UACRING_TARGET; + st->replaced = ds.replaced; + st->sr_requests = sr_requests; +} + +/* ---- usbd_class_api (the usbd thread) ---- */ +static void uac_update(struct usbd_class_data *const c_data, uint8_t iface, uint8_t alternate) +{ + ARG_UNUSED(c_data); + if (iface != desc.as0.bInterfaceNumber) { + return; + } + /* The stack has already enabled (alternate 1) or disabled (alternate 0) the endpoint + * when this runs (usbd_interface_set_alt), so the fast path finds it ready. */ + if (alternate == 1u) { + stream_on(); + } else { + stream_off(); + } +} + +static bool is_sample_rate_request(const struct usb_setup_packet *const setup) +{ + return setup->RequestType.type == USB_REQTYPE_TYPE_CLASS && + setup->RequestType.recipient == USB_REQTYPE_RECIPIENT_ENDPOINT && + (setup->wIndex & 0xFFu) == desc.ep.bEndpointAddress && + (setup->wValue >> 8) == UAC_EP_SAMPLING_FREQ; +} + +/* Not advertised (desc.cs_ep), but answered: SET_CUR to 48 kHz is accepted; anything else + * this function does not have is refused (a STALL), as the class convention is to say. */ +static int uac_control_to_dev(struct usbd_class_data *const c_data, + const struct usb_setup_packet *const setup, + const struct net_buf *const buf) +{ + ARG_UNUSED(c_data); + if (is_sample_rate_request(setup) && setup->bRequest == UAC_SET_CUR && + buf != NULL && buf->len >= 3u) { + sr_requests = sr_requests + 1u; + if (sys_get_le24(buf->data) == SAMPLE_RATE) { + return 0; + } + } + errno = -ENOTSUP; + return 0; +} + +static int uac_control_to_host(struct usbd_class_data *const c_data, + const struct usb_setup_packet *const setup, + struct net_buf *const buf) +{ + ARG_UNUSED(c_data); + if (is_sample_rate_request(setup) && setup->wLength >= 3u && + net_buf_tailroom(buf) >= 3u) { + switch (setup->bRequest) { + case UAC_GET_CUR: + case UAC_GET_MIN: + case UAC_GET_MAX: + sr_requests = sr_requests + 1u; + net_buf_add_le24(buf, SAMPLE_RATE); + return 0; + case UAC_GET_RES: + sr_requests = sr_requests + 1u; + net_buf_add_le24(buf, 0u); + return 0; + default: + break; + } + } + errno = -ENOTSUP; + return 0; +} + +static void uac_disable(struct usbd_class_data *const c_data) +{ + ARG_UNUSED(c_data); + stream_off(); +} + +static void uac_resumed(struct usbd_class_data *const c_data) +{ + ARG_UNUSED(c_data); + sp1_uac_bus_event(USBD_MSG_RESUME); +} + +/* After the stack has stamped bInterfaceNumber and bEndpointAddress + * (usbd_init.c:init_configuration_inst). The AudioControl header's reference to the streaming + * interface is not stamped -- the same fix-up feldd's MIDI class does. */ +static int uac_init(struct usbd_class_data *const c_data) +{ + desc.ac_header.baInterfaceNr1 = desc.as0.bInterfaceNumber; + + /* The name, as Zephyr's CDC ACM class adds its interface string. Once only: a string + * node may be added to the context one time. Without it the function still works, + * nameless. */ + if (desc.ac.iInterface == 0u && + usbd_add_descriptor(usbd_class_get_ctx(c_data), &uac_name) == 0) { + const uint8_t idx = usbd_str_desc_get_idx(&uac_name); + + desc.ac.iInterface = idx; + desc.as0.iInterface = idx; + desc.as1.iInterface = idx; + desc.it.iTerminal = idx; + } + uacring_init(&ring); + return 0; +} + +static void *uac_get_desc(struct usbd_class_data *const c_data, const enum usbd_speed speed) +{ + ARG_UNUSED(c_data); + ARG_UNUSED(speed); /* full speed only: the nRF52840 has no high speed */ + return fs_desc; +} + +static const struct usbd_class_api uac_api = { + .update = uac_update, + .control_to_dev = uac_control_to_dev, + .control_to_host = uac_control_to_host, + .disable = uac_disable, + .resumed = uac_resumed, + .init = uac_init, + .get_desc = uac_get_desc, +}; + +/* ⚠️ The NAME sets the interface order: usbd_register_all_classes() registers in linker + * order, which sorts by name -- cdc_acm_0, usb_midi1, wakes_uac. So the console and the MIDI + * port keep the interface numbers hosts already know, and the audio function comes last. On + * Windows' legacy audio grouping, a new collection starts at each AudioControl interface (the + * first interface's subclass may not repeat), so the MIDI and audio functions stay apart. */ +USBD_DEFINE_CLASS(wakes_uac, &uac_api, NULL, NULL); diff --git a/firmware/src/sp1_uac.h b/firmware/src/sp1_uac.h new file mode 100644 index 0000000..4c40617 --- /dev/null +++ b/firmware/src/sp1_uac.h @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2026 Adara Barami | Worldwave + * + * SPDX-License-Identifier: Apache-2.0 + */ +/* wakes-sp1 -- USB audio OUT (M5c): the SP-1's output, sent to the host as a USB Audio + * Class 1.0 input ("wakes-sp1", 48 kHz, 16-bit stereo). Nothing travels the other way. + * See sp1_uac.c. Apache-2.0 because sp1_uac.c is derived from Ryan Gilmore's usb_audio.c. */ +#pragma once + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* The producer: sp1_audio.c's audio thread, once per block. claim() when the block starts + * rendering (the regulator steers on it, sp1_uac_tuning.h), push() with the block it wrote + * to I2S -- after VOL, the same samples the codecs get. Both cost a load and a branch while + * no host has the stream open. */ +void sp1_uac_claim(uint32_t frames); +void sp1_uac_push(const int16_t *lr, uint32_t frames); + +/* USB bus events, from sp1_usbd.c's message callback (the usbd thread): a pulled cable or a + * bus reset closes the stream (the class never hears alternate setting 0 then), a resume + * re-primes it (the ring filled while the host slept). Takes enum usbd_msg_type. */ +void sp1_uac_bus_event(int type); + +struct sp1_uac_stats { + bool open; /* the host has the stream open (alternate setting 1) */ + uint32_t opens; /* times it was opened since boot */ + uint32_t packets; /* packets sent since the stream opened */ + uint32_t n47, n49; /* packet-size corrections since it opened */ + uint32_t under; /* packets with no audio to send, since it opened */ + uint32_t over; /* blocks the ring had no room for, since it opened */ + uint32_t fill; /* frames in the ring now */ + uint32_t target; /* the fill the regulator holds (sp1_uac_tuning.h) */ + uint32_t replaced; /* driver: packets superseded before their DMA (since boot) */ + uint32_t sr_requests; /* sample-rate requests from the host (since boot) */ +}; +void sp1_uac_get_stats(struct sp1_uac_stats *st); + +#ifdef __cplusplus +} +#endif diff --git a/firmware/src/sp1_usbd.c b/firmware/src/sp1_usbd.c index 1ceb217..f6266cb 100644 --- a/firmware/src/sp1_usbd.c +++ b/firmware/src/sp1_usbd.c @@ -15,6 +15,10 @@ #include #include +#if defined(CONFIG_SP1_USB_AUDIO) +#include "sp1_uac.h" +#endif + #if defined(CONFIG_SP1_MIDI) #include #include "sp1_midi.h" @@ -76,6 +80,10 @@ static void msg_cb(struct usbd_context *const ctx, const struct usbd_msg *const break; } #endif +#if defined(CONFIG_SP1_USB_AUDIO) + /* M5c: a pulled cable or a bus reset closes the audio stream, a resume re-primes it. */ + sp1_uac_bus_event(msg->type); +#endif } #if defined(CONFIG_SP1_USB_THREADS_BELOW_AUDIO) @@ -146,8 +154,9 @@ int sp1_usbd_init(void) err = usbd_add_configuration(&sp1_usbd, USBD_SPEED_FS, &sp1_fs_config); } if (err == 0) { - /* Every compiled-in class: CDC ACM (devicetree) and feldd's MIDI class - * (USBD_DEFINE_CLASS in usb_midi1.c). */ + /* Every compiled-in class: CDC ACM (devicetree), feldd's MIDI class + * (USBD_DEFINE_CLASS in usb_midi1.c) and USB audio out (wakes_uac, sp1_uac.c), + * in that order -- linker order is by name (sp1_uac.c says why it matters). */ err = usbd_register_all_classes(&sp1_usbd, USBD_SPEED_FS, 1, NULL); } if (err != 0) { diff --git a/tools/console-log.py b/tools/console-log.py index bd75d9a..59e37b4 100644 --- a/tools/console-log.py +++ b/tools/console-log.py @@ -45,10 +45,11 @@ except ImportError: sys.exit("pyserial is missing: python -m pip install --user pyserial") -# CONFIG_SP1_USB_PID in firmware/Kconfig: 0x5212 from M5a (console + MIDI), 0x5211 before -# (console only) -- both, so the logger works with either firmware. The VID is Zephyr's +# CONFIG_SP1_USB_PID in firmware/Kconfig: 0x5213 from M5c (+ audio out), 0x5212 from M5a +# (console + MIDI), 0x5211 before (console only) -- all of them, so the logger works with +# any firmware. The VID is Zephyr's # test VID until pid.codes grants one and may change, so match on PID. -WANT_PIDS = (0x5212, 0x5211) +WANT_PIDS = (0x5213, 0x5212, 0x5211) PIDS_TEXT = " or ".join(f"{x:04x}" for x in WANT_PIDS) diff --git a/zephyr-patches/udc_nrf-fast-paths.patch b/zephyr-patches/udc_nrf-fast-paths.patch index 30f7fdc..756b3c5 100644 --- a/zephyr-patches/udc_nrf-fast-paths.patch +++ b/zephyr-patches/udc_nrf-fast-paths.patch @@ -23,7 +23,7 @@ index bcb0e1f017b..f3ca0882918 100644 + endif # UDC_NRF diff --git a/drivers/usb/udc/udc_nrf.c b/drivers/usb/udc/udc_nrf.c -index 7b18862fa59..059efff1c14 100644 +index 7b18862fa59..ba0170ecf80 100644 --- a/drivers/usb/udc/udc_nrf.c +++ b/drivers/usb/udc/udc_nrf.c @@ -18,6 +18,7 @@ @@ -175,7 +175,7 @@ index 7b18862fa59..059efff1c14 100644 static void ev_sof_handler(void) { /* Process isochronous endpoints */ -@@ -432,10 +546,26 @@ static void ev_sof_handler(void) +@@ -432,10 +546,32 @@ static void ev_sof_handler(void) if (NRF_USBD->SIZE.ISOOUT) { iso_ready_mask |= (1U << ep2bit(NRF_USBD_COMMON_EPOUT8)); } @@ -194,7 +194,13 @@ index 7b18862fa59..059efff1c14 100644 m_ep_armed &= ~USBD_EPISO_BIT_MASK; +#if defined(CONFIG_UDC_NRF_ISO_IN_FAST) -+ if (iso_fast_sof() && iso_fast_suppress_sof) { ++ /* The SOF interrupt is on only while a fill is registered (udc_nrf_iso_in_fast_set), ++ * so with suppression no SOF event reaches the stack at all -- including the moments ++ * around an alternate-setting change, when the endpoint is not enabled yet and ++ * iso_fast_sof() has nothing to send. ++ */ ++ (void)iso_fast_sof(); ++ if (iso_fast_fill != NULL && iso_fast_suppress_sof) { + return; + } +#endif @@ -202,7 +208,7 @@ index 7b18862fa59..059efff1c14 100644 udc_submit_sof_event(udc_nrf_dev); } -@@ -588,6 +718,52 @@ static void usbd_dmareq_process(void) +@@ -588,6 +724,52 @@ static void usbd_dmareq_process(void) nrf_usbd_common_ep_t ep = bit2ep(pos); @@ -255,7 +261,20 @@ index 7b18862fa59..059efff1c14 100644 ep_cfg = udc_get_ep_cfg(udc_nrf_dev, ep); buf = udc_buf_peek(ep_cfg); -@@ -1558,6 +1734,83 @@ static void udc_nrf_power_handler(nrfx_power_usb_evt_t pwr_evt) +@@ -910,6 +1092,12 @@ static void nrf_usbd_legacy_start(bool enable_sof) + USBD_INTEN_USBEVENT_Msk | USBD_INTEN_EP0SETUP_Msk | + USBD_INTEN_EPDATA_Msk; + ++#if defined(CONFIG_UDC_NRF_ISO_IN_FAST) ++ /* A restart while the ISO IN fast path is registered keeps its SOF interrupt. */ ++ if (iso_fast_fill != NULL) { ++ enable_sof = true; ++ } ++#endif + if (enable_sof) { + int_mask |= USBD_INTEN_SOF_Msk; + } +@@ -1558,6 +1746,96 @@ static void udc_nrf_power_handler(nrfx_power_usb_evt_t pwr_evt) } } @@ -323,6 +342,19 @@ index 7b18862fa59..059efff1c14 100644 + */ + m_ep_dma_waiting &= ~BIT(ep2bit(NRF_USBD_COMMON_EPIN8)); + } ++#if !defined(CONFIG_UDC_ENABLE_SOF) ++ /* The 1 kHz SOF interrupt runs only while a fill is registered, so a device that is ++ * not streaming pays nothing for it. With the peripheral disabled (cable out) the ++ * next nrf_usbd_legacy_start() sets the mask instead. ++ */ ++ if (NRF_USBD->ENABLE) { ++ if (fill != NULL) { ++ NRF_USBD->INTENSET = USBD_INTEN_SOF_Msk; ++ } else { ++ NRF_USBD->INTENCLR = USBD_INTEN_SOF_Msk; ++ } ++ } ++#endif + + irq_unlock(key); +} @@ -341,10 +373,10 @@ index 7b18862fa59..059efff1c14 100644 struct net_buf *buf) diff --git a/include/zephyr/drivers/usb/udc_nrf_fast.h b/include/zephyr/drivers/usb/udc_nrf_fast.h new file mode 100644 -index 00000000000..c24cd9f5197 +index 00000000000..d56854eadb9 --- /dev/null +++ b/include/zephyr/drivers/usb/udc_nrf_fast.h -@@ -0,0 +1,99 @@ +@@ -0,0 +1,103 @@ +/* + * Copyright (c) 2026 Ryan Gilmore (ISO IN fast path) + * Copyright (c) 2026 Worldwave (bulk OUT fast path) @@ -428,8 +460,12 @@ index 00000000000..c24cd9f5197 +/** + * @brief Register (or remove, @p fill NULL) the ISO IN fast path. + * -+ * @param suppress_sof Also stop posting SOF to the stack while active; only valid when no -+ * class needs SOF events. ++ * Without CONFIG_UDC_ENABLE_SOF, this also switches the 1 kHz SOF interrupt on and off: it ++ * runs only while a fill is registered. So register when the host opens the stream and remove ++ * when it closes, not once for good. ++ * ++ * @param suppress_sof Also stop posting SOF to the stack while registered; only valid when ++ * no class needs SOF events. + */ +void udc_nrf_iso_in_fast_set(udc_nrf_iso_in_fill_t fill, void *user_data, bool suppress_sof); + From 1cc73774387e0b19d92616c365a8ee72c976bae2 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 18:37:33 -0400 Subject: [PATCH 05/10] M5c: the speaker is off while a host records USB audio out Adara: disable the onboard speaker while USB audio out is in use. It rides on the headphone mute: the jack is debounced as before, and every 40 ms poll now reconciles the TAS2505's driver with what the speaker should be doing -- off while headphones are in OR a host has the stream open (sp1_uac_open), on otherwise. Headphones always play, so they still monitor. - A stream closing (host stops, cable pulled) brings the speaker back within one poll; an ON entry with a host already recording mutes at bring-up, so the first 40 ms do not reach the speaker. - Same fail-safe as before: the amp state changes only when the write succeeds (retried and counted otherwise), and if detection gives up the speaker is ON -- the USB mute with it. Nothing can leave the device silent by mistake. - New poll results 3 / 4 log "SPEAKER off/on" for USB; sp1_audio_speaker_on(). Build: 427 028 B, 0 warnings, check_image OK; fallback 86 544 B OK. Co-Authored-By: Claude Opus 5.5 --- firmware/src/main.c | 10 ++++++- firmware/src/sp1_audio.c | 58 +++++++++++++++++++++++++++++++++------- firmware/src/sp1_audio.h | 9 ++++--- firmware/src/sp1_uac.c | 5 ++++ firmware/src/sp1_uac.h | 3 +++ 5 files changed, 71 insertions(+), 14 deletions(-) diff --git a/firmware/src/main.c b/firmware/src/main.c index 4d6154d..a66c261 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -1802,7 +1802,15 @@ int main(void) printk("JACK headphones in: speaker off\n"); break; case 0: - printk("JACK headphones out: speaker on\n"); + /* Stays off while a host records USB audio out (event 3/4). */ + printk("JACK headphones out: speaker %s\n", + sp1_audio_speaker_on() ? "on" : "off"); + break; + case 3: + printk("SPEAKER off: a host has USB audio out open\n"); + break; + case 4: + printk("SPEAKER on: USB audio out closed\n"); break; case 2: printk("JACK detect failed 3x: disabled, speaker on\n"); diff --git a/firmware/src/sp1_audio.c b/firmware/src/sp1_audio.c index 7f09569..1b6ae50 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -117,6 +117,8 @@ static struct sp1_audio_stats st; static bool thread_made; static void jack_reset(void); /* headphone detect, defined with its poll below */ +static bool speaker_wanted(void); /* ditto */ +static bool speaker_driver(bool on); /* ditto */ static bool jack_enabled; /* ditto; cleared by start() and stop() */ /* Per-report window of block costs (M3): the max since boot is dominated by the one @@ -779,6 +781,12 @@ int sp1_audio_start(void) /* Speaker is ON after bring-up; the jack poll decides from here. */ jack_reset(); + /* ...except that a host already recording USB audio (M5c) must not hear the first + * 40 ms of this session on the speaker: mute now. A failed write is retried by the + * first poll, which also counts it. */ + if (jack_enabled && !speaker_wanted()) { + (void)speaker_driver(false); + } return started ? 0 : -EIO; } @@ -922,6 +930,14 @@ void sp1_audio_take_sections(struct sp1_audio_sections *out) * Tim Knapen's sequence). DET_STATUS1 (0x1B77) bit 7 reads 1 while a plug is in. * While it is, the TAS2505's class-D driver is powered down (page 1, reg 0x2D). * + * M5c (Adara, 2026-10-05): the speaker is also off while a host has USB audio out open + * (sp1_uac_open) -- recording Wakes over USB, the speaker would only be a second, room + * copy. Headphones are untouched: they still monitor. The jack is debounced as before; + * the speaker is then reconciled on EVERY poll with what it should be doing + * (speaker_wanted), so a stream closing -- the host stops, the cable is pulled -- brings + * it back within one poll (40 ms). The USB mute rides on this same machinery and its + * fail-safe: if detection gives up, the speaker is ON whether or not USB is streaming. + * * ⚠️ FAIL-SAFE IS "SPEAKER ON". The one outcome this must never produce is a device * that is silent with nothing plugged in. So: * - the speaker is on after every bring-up, before the first read; @@ -962,6 +978,18 @@ static bool speaker_driver(bool on) return ok; } +/* What the speaker should be doing: on, unless headphones are in or a host is recording + * USB audio out. An unknown jack (-1, before the first debounced read) counts as out. */ +static bool speaker_wanted(void) +{ +#if defined(CONFIG_SP1_USB_AUDIO) + if (sp1_uac_open()) { + return false; + } +#endif + return jack_state != 1; +} + static void jack_reset(void) { jack_state = -1; @@ -1002,27 +1030,37 @@ int sp1_audio_jack_poll(uint32_t elapsed_ms) return jack_fail() ? 2 : -1; } + /* The jack: a change needs JACK_DEBOUNCE identical reads in a row. */ + int event = -1; const int c = (v >> 7) & 1; if (c != jack_cand) { jack_cand = c; jack_cnt = 1; - return -1; - } - if (jack_cnt < JACK_DEBOUNCE) { + } else if (jack_cnt < JACK_DEBOUNCE) { jack_cnt++; } - if (jack_cnt < JACK_DEBOUNCE || c == jack_state) { - return -1; + if (jack_cnt >= JACK_DEBOUNCE && c != jack_state) { + jack_state = c; + event = c; /* 1 in, 0 out */ } - /* Debounced change. Commit it only if the amp actually did what we asked. */ - if (!speaker_driver(c == 0)) { - return jack_fail() ? 2 : -1; /* retried on the next poll */ + + /* The speaker: whatever it should be doing, until the amp confirms it. `spk_on` + * changes only when the write SUCCEEDED, so a failed one is simply retried on the + * next poll (and counted). */ + const bool want = speaker_wanted(); + if (want != spk_on) { + if (!speaker_driver(want)) { + return jack_fail() ? 2 : event; + } + if (event < 0) { + event = want ? 4 : 3; /* not the jack: USB audio closed / opened */ + } } - jack_state = c; - return c; + return event; } int sp1_audio_jack_state(void) { return jack_state; } +bool sp1_audio_speaker_on(void) { return spk_on; } void sp1_audio_stats(struct sp1_audio_stats *out) { diff --git a/firmware/src/sp1_audio.h b/firmware/src/sp1_audio.h index 46f45ac..be8a45e 100644 --- a/firmware/src/sp1_audio.h +++ b/firmware/src/sp1_audio.h @@ -102,13 +102,16 @@ int sp1_audio_level_db_x10(void); /* tenths of dBFS, -9990 = mute */ void sp1_audio_tone_set(bool on); bool sp1_audio_tone_on(void); -/* ---- headphone detect -> speaker mute (M3) ---- +/* ---- headphone detect -> speaker mute (M3), and the USB audio mute (M5c) ---- * Call from the main loop every tick while ON, after sp1_audio_start(). Polls the * CS42L42 jack sense every 40 ms, debounced, and powers the speaker down while a plug - * is in. Returns -1 (nothing new), 0 (unplugged: speaker on), 1 (plugged: speaker - * off), or 2 (detect failed repeatedly: disabled for this session, speaker ON). */ + * is in -- or while a host has USB audio out open. Headphones always play. Returns -1 + * (nothing new), 0 (unplugged), 1 (plugged), 2 (detect failed repeatedly: disabled for + * this session, speaker ON -- the USB mute with it), 3 (USB audio opened: speaker off) + * or 4 (USB audio closed: speaker back on, unless headphones are in). */ int sp1_audio_jack_poll(uint32_t elapsed_ms); int sp1_audio_jack_state(void); /* 1 in, 0 out, -1 unknown */ +bool sp1_audio_speaker_on(void); /* what the speaker amp is actually set to */ /* Block cost since the last call: worst and mean cycles per block. Read-and-clear. */ void sp1_audio_take_cycles(uint32_t *max, uint32_t *avg); diff --git a/firmware/src/sp1_uac.c b/firmware/src/sp1_uac.c index e4ac36f..4f86de5 100644 --- a/firmware/src/sp1_uac.c +++ b/firmware/src/sp1_uac.c @@ -402,6 +402,11 @@ void sp1_uac_bus_event(int type) } } +bool sp1_uac_open(void) +{ + return stream_open; +} + /* ---- the producer (the audio thread) ---- */ void sp1_uac_claim(uint32_t frames) { diff --git a/firmware/src/sp1_uac.h b/firmware/src/sp1_uac.h index 4c40617..7a743de 100644 --- a/firmware/src/sp1_uac.h +++ b/firmware/src/sp1_uac.h @@ -27,6 +27,9 @@ void sp1_uac_push(const int16_t *lr, uint32_t frames); * re-primes it (the ring filled while the host slept). Takes enum usbd_msg_type. */ void sp1_uac_bus_event(int type); +/* The host has the stream open (alternate setting 1): sp1_audio.c mutes the speaker. */ +bool sp1_uac_open(void); + struct sp1_uac_stats { bool open; /* the host has the stream open (alternate setting 1) */ uint32_t opens; /* times it was opened since boot */ From 4c14949b466beb27999e3a08c49b089a88ebcf79 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 18:40:47 -0400 Subject: [PATCH 06/10] M5c: mute the speaker only while a host is actually taking USB audio Adara: check that the host accepts the stream, otherwise default to the speaker. Selecting the streaming alternate setting already requires the host's audio driver to have accepted the device and something to have opened the input, so a charger, a host without USB audio (or rejecting ours), a MIDI-only host and an unopened input all kept the speaker. The gap was a host that opened the stream and then stopped running the bus -- asleep, suspended, stalled: the speaker stayed muted. Now the speaker is muted only while sp1_uac_live(): the stream is open AND the USB interrupt has handed over packets since the previous 40 ms check (fill() runs at each start-of-frame, so a sleeping host stops it). Otherwise the speaker comes back within one poll, and goes quiet again when packets resume. One counter increment per millisecond in the interrupt. Build: 427 072 B, 0 warnings, check_image OK; fallback OK. Co-Authored-By: Claude Opus 5.5 --- firmware/src/main.c | 4 ++-- firmware/src/sp1_audio.c | 16 ++++++++++------ firmware/src/sp1_audio.h | 8 +++++--- firmware/src/sp1_uac.c | 17 +++++++++++++++++ firmware/src/sp1_uac.h | 7 ++++++- 5 files changed, 40 insertions(+), 12 deletions(-) diff --git a/firmware/src/main.c b/firmware/src/main.c index a66c261..72d1b93 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -1807,10 +1807,10 @@ int main(void) sp1_audio_speaker_on() ? "on" : "off"); break; case 3: - printk("SPEAKER off: a host has USB audio out open\n"); + printk("SPEAKER off: a host is taking USB audio out\n"); break; case 4: - printk("SPEAKER on: USB audio out closed\n"); + printk("SPEAKER on: no host is taking USB audio out\n"); break; case 2: printk("JACK detect failed 3x: disabled, speaker on\n"); diff --git a/firmware/src/sp1_audio.c b/firmware/src/sp1_audio.c index 1b6ae50..5d1df5c 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -930,9 +930,12 @@ void sp1_audio_take_sections(struct sp1_audio_sections *out) * Tim Knapen's sequence). DET_STATUS1 (0x1B77) bit 7 reads 1 while a plug is in. * While it is, the TAS2505's class-D driver is powered down (page 1, reg 0x2D). * - * M5c (Adara, 2026-10-05): the speaker is also off while a host has USB audio out open - * (sp1_uac_open) -- recording Wakes over USB, the speaker would only be a second, room - * copy. Headphones are untouched: they still monitor. The jack is debounced as before; + * M5c (Adara, 2026-10-05): the speaker is also off while a host is TAKING USB audio out + * (sp1_uac_live: the stream open AND packets going out since the last poll) -- recording + * Wakes over USB, the speaker would only be a second, room copy. Anything short of that + * defaults to the speaker (Adara): a charger, a host without USB audio or that rejects + * ours, a host using only MIDI, one that has not opened the input, and one that opened it + * and then went to sleep. Headphones are untouched: they still monitor. The jack is debounced as before; * the speaker is then reconciled on EVERY poll with what it should be doing * (speaker_wanted), so a stream closing -- the host stops, the cable is pulled -- brings * it back within one poll (40 ms). The USB mute rides on this same machinery and its @@ -978,12 +981,13 @@ static bool speaker_driver(bool on) return ok; } -/* What the speaker should be doing: on, unless headphones are in or a host is recording - * USB audio out. An unknown jack (-1, before the first debounced read) counts as out. */ +/* What the speaker should be doing: on, unless headphones are in or a host is taking USB + * audio out. An unknown jack (-1, before the first debounced read) counts as out. + * ⚠️ sp1_uac_live() remembers its last count: call this only from the bring-up and the poll. */ static bool speaker_wanted(void) { #if defined(CONFIG_SP1_USB_AUDIO) - if (sp1_uac_open()) { + if (sp1_uac_live()) { return false; } #endif diff --git a/firmware/src/sp1_audio.h b/firmware/src/sp1_audio.h index be8a45e..3131a4d 100644 --- a/firmware/src/sp1_audio.h +++ b/firmware/src/sp1_audio.h @@ -105,10 +105,12 @@ bool sp1_audio_tone_on(void); /* ---- headphone detect -> speaker mute (M3), and the USB audio mute (M5c) ---- * Call from the main loop every tick while ON, after sp1_audio_start(). Polls the * CS42L42 jack sense every 40 ms, debounced, and powers the speaker down while a plug - * is in -- or while a host has USB audio out open. Headphones always play. Returns -1 + * is in -- or while a host is taking USB audio out (stream open AND packets flowing). + * Headphones always play. Returns -1 * (nothing new), 0 (unplugged), 1 (plugged), 2 (detect failed repeatedly: disabled for - * this session, speaker ON -- the USB mute with it), 3 (USB audio opened: speaker off) - * or 4 (USB audio closed: speaker back on, unless headphones are in). */ + * this session, speaker ON -- the USB mute with it), 3 (a host started taking USB audio: + * speaker off) or 4 (no host is taking it any more: speaker back on, unless headphones + * are in). */ int sp1_audio_jack_poll(uint32_t elapsed_ms); int sp1_audio_jack_state(void); /* 1 in, 0 out, -1 unknown */ bool sp1_audio_speaker_on(void); /* what the speaker amp is actually set to */ diff --git a/firmware/src/sp1_uac.c b/firmware/src/sp1_uac.c index 4f86de5..4b99ab8 100644 --- a/firmware/src/sp1_uac.c +++ b/firmware/src/sp1_uac.c @@ -323,6 +323,7 @@ USBD_DESC_STRING_DEFINE(uac_name, "Wakes Audio Out", USBD_DUT_STRING_INTERFACE); static struct uacring ring; static volatile bool stream_open; static volatile uint32_t opens; +static volatile uint32_t fills; /* packets handed to the driver (the interrupt) */ static volatile uint32_t sr_requests; /* ---- the fast path: the USB interrupt, once a millisecond while the stream is open ---- @@ -333,6 +334,8 @@ static uint16_t fill(uint8_t *buf, uint16_t max, void *user_data) ARG_UNUSED(user_data); uint32_t frames = uacring_packet_frames(&ring); + fills = fills + 1u; /* the host is running frames: sp1_uac_live() */ + if (frames * FRAME_BYTES > max) { frames = max / FRAME_BYTES; } @@ -407,6 +410,20 @@ bool sp1_uac_open(void) return stream_open; } +bool sp1_uac_live(void) +{ + /* "Open" is only what the host last SAID. A host that opened the stream and then + * stopped running the bus -- asleep, suspended, or stalled -- calls fill() no more, + * because fill() runs at each start-of-frame. So: live while fill() has run since the + * previous call. One caller (sp1_audio.c's speaker check, every 40 ms ~ 40 frames). */ + static uint32_t seen; + const uint32_t n = fills; + const bool moved = (n != seen); + + seen = n; + return stream_open && moved; +} + /* ---- the producer (the audio thread) ---- */ void sp1_uac_claim(uint32_t frames) { diff --git a/firmware/src/sp1_uac.h b/firmware/src/sp1_uac.h index 7a743de..6db19b2 100644 --- a/firmware/src/sp1_uac.h +++ b/firmware/src/sp1_uac.h @@ -27,9 +27,14 @@ void sp1_uac_push(const int16_t *lr, uint32_t frames); * re-primes it (the ring filled while the host slept). Takes enum usbd_msg_type. */ void sp1_uac_bus_event(int type); -/* The host has the stream open (alternate setting 1): sp1_audio.c mutes the speaker. */ +/* The host has the stream open (alternate setting 1). */ bool sp1_uac_open(void); +/* ...and is actually taking packets: open, and at least one went out since the previous + * call. sp1_audio.c mutes the speaker only while this is true, so a host that opened the + * stream and then went to sleep gets the speaker back. ONE caller: it remembers the count. */ +bool sp1_uac_live(void); + struct sp1_uac_stats { bool open; /* the host has the stream open (alternate setting 1) */ uint32_t opens; /* times it was opened since boot */ From 420f54af06bfa15a872e21223d8e2e1231723220 Mon Sep 17 00:00:00 2001 From: Worldwave Date: Mon, 5 Oct 2026 18:52:23 -0400 Subject: [PATCH 07/10] M5c: USB audio out in the delay compensation -- the clock's lead follows it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adara: include USB audio output in the delay compensation, as #32 built it. Wakes makes up its own output delay by reading the host's MIDI clock ahead (`clock_lead = auto`, and `notes` until it has learnt the host's offset): the delay is counted from the code (SP1_MIDI_OUTPUT_LATENCY_MS, (queue + 3) blocks = 8 ms) and the module that owns the pipeline BUILD_ASSERTs it. That was the speaker's path. A host recording over USB hears a different one. - sp1_midi.h: SP1_MIDI_USB_OUTPUT_LATENCY_US = TARGET + BLK/2 frames = 9.0 ms (1 block to place the message + the ring's average wait from render start, 7.0 ms). sp1_uac.c BUILD_ASSERTs it against the ring's tuning, the same rule as sp1_audio.c's check, so re-tuning the ring cannot leave the lead stale. - sp1_midi.cc: Lead() = fixed ms, or the learnt notes lead, or auto -- the USB path's delay while a host takes USB audio out, the speaker's otherwise (+ Plaits' TRIG delay: 9.5 vs 8.5 ms). Taken once per audio block; a change is followed at kFollow, never backwards. A learnt notes lead does not change (notes and Marbles share the path). - sp1_uac_live() is now stateless (time of the last packet, 20 ms window), so main feeds sp1_midi_set_output_usb() every tick and the speaker check uses it too. - main.c: an "AUD USB audio out: ~9.0 ms in to out" boot line, from the constant. - Host suites: uactest measures the ring's delay through the real ring -- 7.01 ms at 0 ppm, within the dead band at +/-200 ppm (6.35 .. 7.69); miditest_clock §14: Marbles leads by the USB path's delay with a host taking USB audio, back to the speaker's when it stops, no beat skipped or doubled, the two leads 1.00 ms apart (want 1.0). All nine suites pass. - midi.ini, MIDI.md, the CC chart: auto is 9.5 ms while a host records over USB. Build: 427 272 B, 0 warnings, check_image OK; fallback OK. Co-Authored-By: Claude Opus 5.5 --- config/midi.ini | 2 + docs/MIDI.md | 5 +- firmware/src/main.c | 13 +++++ firmware/src/sp1_audio.c | 3 +- firmware/src/sp1_midi.cc | 32 +++++++++++-- firmware/src/sp1_midi.h | 22 +++++++++ firmware/src/sp1_uac.c | 33 +++++++++---- firmware/src/sp1_uac.h | 6 +-- tools/gen_midi.py | 3 +- tools/host-tests/miditest_clock.cc | 76 ++++++++++++++++++++++++++++++ tools/host-tests/uactest.c | 49 +++++++++++++++++-- 11 files changed, 218 insertions(+), 26 deletions(-) diff --git a/config/midi.ini b/config/midi.ini index 7f76ae2..5ef507a 100644 --- a/config/midi.ini +++ b/config/midi.ini @@ -142,6 +142,8 @@ clock = on ; grid: swing, triplets, playing by hand) it uses auto. The console's "MIDI notes vs ; clock" line shows the measurement and the lead in use. ; auto = Wakes' own delay (8.5 ms): Marbles' beats leave the output when the clock's do. +; While the host is recording Wakes over USB audio, that output is 1 ms later, and +; auto (and notes, until it has measured) follows it: 9.5 ms. ; A number: that many ms, for a host whose clock offset you would rather set here. ; With notes or auto, leave the host's own clock offset / sync delay for Wakes at 0. ; Beat 1 after a Start is the exception: nothing said when it would come, so it sounds diff --git a/docs/MIDI.md b/docs/MIDI.md index ec58e85..4d739b1 100644 --- a/docs/MIDI.md +++ b/docs/MIDI.md @@ -125,7 +125,8 @@ Marbles locks to the host, the way a Eurorack Marbles does with a cable in its C default `clock_lead = notes` Wakes measures where the host's quantised notes fall on its clock and leads by exactly that: Marbles' beats land with the notes, and **the host needs no clock offset for Wakes — leave it at 0**. Until notes arrive (or with notes off the 16th grid: - swing, triplets, playing by hand) it leads by Wakes' own delay (`auto`, 8.5 ms). The console's + swing, triplets, playing by hand) it leads by Wakes' own delay (`auto`, 8.5 ms; 9.5 ms while the + host records Wakes over USB audio, which leaves Wakes 1 ms later than the speaker). The console's `MIDI notes vs clock` line shows the measurement and the lead in use. Beat 1 after a Start is the exception — nothing said when it would come — so Marbles is on time from beat 2. Notes cannot be played early: give Wakes' track the DAW's usual hardware latency compensation. @@ -215,7 +216,7 @@ What it sets: - `pickup` — `shared` (default), `sum` or `takeover` (above). - `clock` — `on` (default): Marbles follows MIDI clock and transport (above); `off` ignores them. - `clock_lead` — `notes` (default: as far as the host's notes say), `auto` (8.5 ms, Wakes' own - delay) or 0–200 ms: how far ahead of the host's + delay; 9.5 ms while a host records Wakes over USB audio) or 0–200 ms: how far ahead of the host's clock Marbles runs (above). - one line per parameter — `name = cc N`, or `none`. - `[bind]` — `velocity` and `aftertouch` (channel pressure) can push a parameter by a depth diff --git a/firmware/src/main.c b/firmware/src/main.c index 72d1b93..713813e 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -1042,6 +1042,14 @@ int main(void) (unsigned)CONFIG_I2S_NRFX_TX_BLOCK_COUNT, (unsigned)((CONFIG_I2S_NRFX_TX_BLOCK_COUNT + 3) * (CONFIG_SP1_AUDIO_BLOCK_FRAMES / 48))); +#if defined(CONFIG_SP1_MIDI) && defined(CONFIG_SP1_USB_AUDIO) + /* M5c: the same count for USB audio out (sp1_midi.h): what the MIDI clock + * makes up for while a host takes it. */ + printk("AUD USB audio out: ~%u.%u ms in to out (speaker ~%u)\n", + (unsigned)(SP1_MIDI_USB_OUTPUT_LATENCY_US / 1000), + (unsigned)((SP1_MIDI_USB_OUTPUT_LATENCY_US % 1000) / 100), + (unsigned)SP1_MIDI_OUTPUT_LATENCY_MS); +#endif /* #32: which USB path this build takes, so every log says it. */ printk("USB midi=%s threads=%s audio out=%s\n", IS_ENABLED(CONFIG_UDC_NRF_OUT_FAST) ? "in the interrupt (fast path)" @@ -1797,6 +1805,11 @@ int main(void) } /* ---- headphones in -> speaker off (M3) ---- */ +#if defined(CONFIG_SP1_MIDI) && defined(CONFIG_SP1_USB_AUDIO) + /* M5c: the delay the MIDI clock makes up for is the path the host hears -- + * USB audio out while a host takes it, the speaker / headphones otherwise. */ + sp1_midi_set_output_usb(sp1_uac_live()); +#endif switch (sp1_audio_jack_poll(dt)) { case 1: printk("JACK headphones in: speaker off\n"); diff --git a/firmware/src/sp1_audio.c b/firmware/src/sp1_audio.c index 5d1df5c..3a91563 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -982,8 +982,7 @@ static bool speaker_driver(bool on) } /* What the speaker should be doing: on, unless headphones are in or a host is taking USB - * audio out. An unknown jack (-1, before the first debounced read) counts as out. - * ⚠️ sp1_uac_live() remembers its last count: call this only from the bring-up and the poll. */ + * audio out. An unknown jack (-1, before the first debounced read) counts as out. */ static bool speaker_wanted(void) { #if defined(CONFIG_SP1_USB_AUDIO) diff --git a/firmware/src/sp1_midi.cc b/firmware/src/sp1_midi.cc index b50aecc..bd139bd 100644 --- a/firmware/src/sp1_midi.cc +++ b/firmware/src/sp1_midi.cc @@ -194,8 +194,27 @@ const float kTrigDelayBlocks = 0.0f; #endif const float kLeadAutoBlocks = static_cast(SP1_MIDI_OUTPUT_LATENCY_MS * kBlocksPerMs) + kTrigDelayBlocks; +// ...and when the host hears USB audio out (M5c): that path's delay instead. +const float kLeadAutoUsbBlocks = + static_cast(SP1_MIDI_USB_OUTPUT_LATENCY_US) * static_cast(kBlocksPerMs) / + 1000.0f + kTrigDelayBlocks; +volatile bool out_usb; // main: a host is taking USB audio out // notes (#32, -2): the lead the host's notes ask for -- see "notes vs clock" below -- until -// they have said, auto. A fixed number of ms otherwise. +// they have said, auto (lead_learned < 0). A fixed number of ms otherwise. +float lead_learned = -1.0f; +float Lead() { + if (SP1_MIDI_CLOCK_LEAD_MS >= 0) { + return static_cast(SP1_MIDI_CLOCK_LEAD_MS) * static_cast(kBlocksPerMs); + } + if (SP1_MIDI_CLOCK_LEAD_MS == -2 && lead_learned >= 0.0f) { + return lead_learned; + } + return out_usb ? kLeadAutoUsbBlocks : kLeadAutoBlocks; +} +// The lead in use, taken once per audio block (ClockBlock) so a whole block reads one value. +// A change -- USB audio opening or closing, a lead learned -- moves where the line is read; +// the position follows it at kFollow, never backwards, so Marbles does not jump. +// Initialised as a constant (no function call at static-init time); ClockBlock sets it. float lead_blocks = SP1_MIDI_CLOCK_LEAD_MS < 0 ? kLeadAutoBlocks : static_cast(SP1_MIDI_CLOCK_LEAD_MS) * static_cast(kBlocksPerMs); @@ -977,6 +996,7 @@ void ClockBlock(uint32_t blocks) { if (blocks > kMaxBlocks) { blocks = kMaxBlocks; } + lead_blocks = Lead(); const float wrap = static_cast(kClockWrap); uint32_t r = 0; for (uint32_t j = 0; j < blocks; ++j) { @@ -1034,7 +1054,8 @@ void ClockBlock(uint32_t blocks) { if (SP1_MIDI_CLOCK_LEAD_MS == -2 && sk_n >= 8u && sd < 1000.0f) { float lead_ms = -mean * 1e-3f; lead_ms = lead_ms < 0.0f ? 0.0f : (lead_ms > 200.0f ? 200.0f : lead_ms); - lead_blocks = lead_ms * static_cast(kBlocksPerMs); + lead_learned = lead_ms * static_cast(kBlocksPerMs); + lead_blocks = Lead(); } } pub_lead_us = static_cast(lead_blocks * 1000.0f / static_cast(kBlocksPerMs)); @@ -1060,7 +1081,8 @@ void Neutral() { ClockForgetTempo(); pub_bpm10 = 0; if (SP1_MIDI_CLOCK_LEAD_MS == -2) { - lead_blocks = kLeadAutoBlocks; // notes: a new host has said nothing yet + lead_learned = -1.0f; // notes: a new host has said nothing yet + lead_blocks = Lead(); } session = false; AllNotesOff(); @@ -1156,6 +1178,10 @@ extern "C" void sp1_midi_port(bool up) { } // ==== main thread ========================================================================= +extern "C" void sp1_midi_set_output_usb(bool usb) { + out_usb = usb; +} + extern "C" void sp1_midi_on_enter(void) { reset_req = reset_req + 1u; } diff --git a/firmware/src/sp1_midi.h b/firmware/src/sp1_midi.h index 0afed82..d01ce96 100644 --- a/firmware/src/sp1_midi.h +++ b/firmware/src/sp1_midi.h @@ -121,6 +121,21 @@ extern "C" { #define SP1_MIDI_OUTPUT_LATENCY_MS 8 #endif +/* The same, when the sound a host hears is USB audio out (M5c), in microseconds. Counted from + * the ring (sp1_uac_tuning.h), not measured on hardware: + * 1 block the message is placed in the next audio block, as above + * TARGET + BLK/2 - BLK the frame's wait in the ring from its block's render start: the + * regulator holds the fill, counted from that moment (the claim), at + * TARGET, and the fill saw-tooths a block above it -- half a block on + * average. The regulator samples the fill just BEFORE each packet + * leaves, half a packet (0.5 ms) above its time average, which cancels + * the half of the 1 ms USB frame the packet spends in transit. + * = TARGET + BLK/2 frames = (384 + 48) / 48 = 9.0 ms, against the speaker's 8 -- `auto` 9.5 + * against 8.5. uactest measures the ring's part (7.0 ms at 0 ppm); clock drift moves it by up + * to the dead band, +/-0.67 ms. sp1_uac.c checks this number against the tuning at build + * time. */ +#define SP1_MIDI_USB_OUTPUT_LATENCY_US 9000 + #if defined(CONFIG_SP1_MIDI) /* ---- USB side (the interrupt, and the usbd thread for port changes) ---- */ @@ -144,6 +159,13 @@ uint8_t sp1_midi_mmc_feed(const uint8_t pkt[4]); /* The host enabled (up) or lost (down) our MIDI interface. */ void sp1_midi_port(bool up); +/* ---- main thread, every control tick (M5c) ---- + * Which output a host hears: true while it is taking USB audio out (sp1_uac_live), so the + * clock's `auto` lead is the USB path's delay (SP1_MIDI_USB_OUTPUT_LATENCY_US) instead of + * the speaker's. A learned `notes` lead does not depend on it (notes and Marbles take the + * same path); its starting value does. */ +void sp1_midi_set_output_usb(bool usb); + /* ---- main thread ---- */ /* On every entry to ON: forget anything that queued while OFF and start from neutral. */ void sp1_midi_on_enter(void); diff --git a/firmware/src/sp1_uac.c b/firmware/src/sp1_uac.c index 4b99ab8..ac892d0 100644 --- a/firmware/src/sp1_uac.c +++ b/firmware/src/sp1_uac.c @@ -51,6 +51,9 @@ #include "sp1_uac_tuning.h" /* before uacring.h, as the ring itself is built */ #include "uacring.h" +#if defined(CONFIG_SP1_MIDI) +#include "sp1_midi.h" /* the USB path's delay, for the clock's lead */ +#endif /* ---- USB Device Class Definition for Audio Devices, Release 1.0 ---- */ #define UAC_CLASS 0x01 /* bInterfaceClass: Audio */ @@ -97,6 +100,16 @@ BUILD_ASSERT(MAX_PACKET <= UDC_NRF_ISO_IN_FAST_MAX, "a packet must fit the fast path's buffer"); BUILD_ASSERT(AUDIO_BLK_FRAMES == CONFIG_SP1_AUDIO_BLOCK_FRAMES, "the ring is tuned for another block (sp1_uac_tuning.h)"); +#if defined(CONFIG_SP1_MIDI) +/* The delay MIDI's clock makes up for when a host takes USB audio (sp1_midi.h): the ring's + * average wait from a block's render start, TARGET + BLK/2 - BLK frames (uactest measures + * it), plus the one block a message waits to be placed. The same rule as sp1_audio.c's check + * of SP1_MIDI_OUTPUT_LATENCY_MS: re-tune the ring and this fails until the number is set. */ +BUILD_ASSERT(SP1_MIDI_USB_OUTPUT_LATENCY_US == + (UACRING_TARGET + AUDIO_BLK_FRAMES / 2u) * 1000u / 48u, + "the USB ring's tuning changed: set SP1_MIDI_USB_OUTPUT_LATENCY_US in sp1_midi.h to " + "(UACRING_TARGET + AUDIO_BLK_FRAMES / 2) frames, in us"); +#endif struct uac_ac_header { uint8_t bLength; @@ -323,7 +336,10 @@ USBD_DESC_STRING_DEFINE(uac_name, "Wakes Audio Out", USBD_DUT_STRING_INTERFACE); static struct uacring ring; static volatile bool stream_open; static volatile uint32_t opens; -static volatile uint32_t fills; /* packets handed to the driver (the interrupt) */ +/* When the interrupt last handed a packet over (system clock, k_cycle_get_32). */ +static volatile uint32_t last_fill; +/* Live: a packet within the last 20 ms. The host takes one every 1 ms while it runs frames. */ +#define LIVE_CYCLES ((uint32_t)(CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC / 50)) static volatile uint32_t sr_requests; /* ---- the fast path: the USB interrupt, once a millisecond while the stream is open ---- @@ -334,7 +350,7 @@ static uint16_t fill(uint8_t *buf, uint16_t max, void *user_data) ARG_UNUSED(user_data); uint32_t frames = uacring_packet_frames(&ring); - fills = fills + 1u; /* the host is running frames: sp1_uac_live() */ + last_fill = k_cycle_get_32(); /* the host is running frames: sp1_uac_live() */ if (frames * FRAME_BYTES > max) { frames = max / FRAME_BYTES; @@ -357,6 +373,7 @@ static void ring_restart(void) static void stream_on(void) { + last_fill = k_cycle_get_32() - 2u * LIVE_CYCLES; /* not live until a packet goes */ ring_restart(); stream_open = true; opens = opens + 1u; @@ -414,14 +431,10 @@ bool sp1_uac_live(void) { /* "Open" is only what the host last SAID. A host that opened the stream and then * stopped running the bus -- asleep, suspended, or stalled -- calls fill() no more, - * because fill() runs at each start-of-frame. So: live while fill() has run since the - * previous call. One caller (sp1_audio.c's speaker check, every 40 ms ~ 40 frames). */ - static uint32_t seen; - const uint32_t n = fills; - const bool moved = (n != seen); - - seen = n; - return stream_open && moved; + * because fill() runs at each start-of-frame. So: live while fill() ran in the last + * 20 ms. No state of its own, so any thread may ask: the speaker check and the MIDI + * clock's lead both do. */ + return stream_open && (k_cycle_get_32() - last_fill) < LIVE_CYCLES; } /* ---- the producer (the audio thread) ---- */ diff --git a/firmware/src/sp1_uac.h b/firmware/src/sp1_uac.h index 6db19b2..c789782 100644 --- a/firmware/src/sp1_uac.h +++ b/firmware/src/sp1_uac.h @@ -30,9 +30,9 @@ void sp1_uac_bus_event(int type); /* The host has the stream open (alternate setting 1). */ bool sp1_uac_open(void); -/* ...and is actually taking packets: open, and at least one went out since the previous - * call. sp1_audio.c mutes the speaker only while this is true, so a host that opened the - * stream and then went to sleep gets the speaker back. ONE caller: it remembers the count. */ +/* ...and is actually taking packets: open, and one went out in the last 20 ms. While this is + * true, sp1_audio.c mutes the speaker and the MIDI clock leads by the USB path's delay; a + * host that opened the stream and then went to sleep gets the speaker back. Any thread. */ bool sp1_uac_live(void); struct sp1_uac_stats { diff --git a/tools/gen_midi.py b/tools/gen_midi.py index 254af82..1888a3d 100644 --- a/tools/gen_midi.py +++ b/tools/gen_midi.py @@ -381,7 +381,8 @@ def write_charts(d, cfg, ccs, binds): '- Sustain pedal: %s' % ('CC %d' % cfg['sustain'] if cfg['sustain'] >= 0 else 'off'), '- MIDI clock: %s' % (('Marbles follows the host\'s clock, Start / Continue / Stop; ' 'RATE picks the ratio (1/4 … 4); running %s ahead' - % ("Wakes' own delay (auto)" if cfg['clock_lead'] == -1 + % ("Wakes' own delay, speaker or USB audio (auto)" + if cfg['clock_lead'] == -1 else "as far as the host's notes say (notes)" if cfg['clock_lead'] == -2 else '%d ms' % cfg['clock_lead'])) diff --git a/tools/host-tests/miditest_clock.cc b/tools/host-tests/miditest_clock.cc index 15d2a19..25ffdb8 100644 --- a/tools/host-tests/miditest_clock.cc +++ b/tools/host-tests/miditest_clock.cc @@ -516,6 +516,82 @@ int main() { tempo(0.0); } + // ---- §14 USB audio out (M5c): the lead follows the output the host hears ---- + // A host taking USB audio out hears Wakes later than the speaker (sp1_midi.h, + // SP1_MIDI_USB_OUTPUT_LATENCY_US), so `auto` -- and `notes` until it has learnt -- leads by + // that instead. Beats are timed as in §10. Then the host stops taking USB audio mid-play: + // the lead goes back to the speaker's, and Marbles gets there without skipping or doubling + // a beat (a skipped beat would put every later one ~500 ms off the host's). + { + printf("§14 USB audio out: the lead becomes the USB path's delay, and back\n"); + sp1_midi_port(false); // a new host: nothing learnt yet (notes) + synth(); + sp1_midi_port(true); + sp1_midi_set_output_usb(true); + jitter_cyc = 0; + tempo(120.0); + rt(0xFA, now_cyc + kJust); + next_tick = now_cyc + 0.6 * kBlockCyc; // beat 1's true time + const double b1 = next_tick, bc = tick_cyc * 24.0; + int bt = -1; + bool was = false; + // Marbles' t2 beats over n blocks, in ms against the host's beats, from beat `from` on. + auto measure = [&](int n, int from, std::vector* off) { + for (int i = 0; i < n; ++i) { + synth(); + const uint8_t* g = sp1_marbles_gate_frames(); + for (uint32_t j = 0; j < kBlocks; ++j) { + const bool t2 = (g[j] & 2u) != 0u; + if (t2 && !was) { + ++bt; + const double at = + static_cast(now_cyc) - kBlockCyc + j * (kBlockCyc / kBlocks); + if (bt >= from) { + off->push_back((at - (b1 + bt * bc)) / (kHz / 1000.0)); + } + } + was = t2; + } + } + }; + auto mean = [](const std::vector& v) { + double m = 0.0; + for (double o : v) m += o; + return v.empty() ? 0.0 : m / v.size(); + }; + const double trig = CONFIG_SP1_TRIGGER_DELAY_SAMPLES / 48.0; + const double usb_lead = SP1_MIDI_USB_OUTPUT_LATENCY_US / 1000.0 + trig; + const double spk_lead = SP1_MIDI_OUTPUT_LATENCY_MS + trig; + + std::vector usb, spk; + measure(200 * 15, 8, &usb); // 15 s, from beat 8 (the line settled) + sp1_midi_stats st; + sp1_midi_get_stats(&st); + printf(" USB audio out: %zu beats, %.2f ms vs the host's (lead %.1f ms in use, want %.1f)\n", + usb.size(), mean(usb), st.lead_us / 1000.0, usb_lead); + // Within 1 ms, as §10: timing a beat at its Plaits block reads ~0.5 ms early here too. + CHECK(usb.size() >= 20u && fabs(mean(usb) + usb_lead) < 1.0, + "with USB audio out, the lead is the USB path's: %.2f ms (want -%.1f)", mean(usb), + usb_lead); + CHECK(fabs(st.lead_us / 1000.0 - usb_lead) < 0.1, "the lead reported: %.1f ms (want %.1f)", + st.lead_us / 1000.0, usb_lead); + + sp1_midi_set_output_usb(false); // the host stops taking USB audio + measure(200 * 15, bt + 8, &spk); + printf(" speaker again: %zu beats, %.2f ms vs the host's (want -%.1f)\n", spk.size(), + mean(spk), spk_lead); + CHECK(spk.size() >= 20u && fabs(mean(spk) + spk_lead) < 1.0, + "USB audio closed: back to the speaker's lead, no beat skipped or doubled: %.2f ms " + "(want -%.1f)", mean(spk), spk_lead); + // The point of it, measured tightly: the two leads differ by the USB path's extra delay + // (the same ~0.5 ms reading cancels). + const double diff = mean(spk) - mean(usb); + CHECK(fabs(diff - (usb_lead - spk_lead)) < 0.2, + "USB audio out leads by its extra delay: %.2f ms more (want %.2f)", diff, + usb_lead - spk_lead); + tempo(0.0); + } + printf("\n%s (%d failure%s)\n", fails ? "FAILED" : "all checks passed", fails, fails == 1 ? "" : "s"); return fails ? 1 : 0; diff --git a/tools/host-tests/uactest.c b/tools/host-tests/uactest.c index 9524876..8f017e2 100644 --- a/tools/host-tests/uactest.c +++ b/tools/host-tests/uactest.c @@ -59,9 +59,19 @@ static void pattern(int16_t *lr, uint32_t first, uint32_t frames) /* The worst case must leave this much in the ring, not just not run dry: ~0.7 ms. */ #define MARGIN_FRAMES 32u +/* The delay MIDI's clock makes up for over USB (firmware/src/sp1_midi.h, + * SP1_MIDI_USB_OUTPUT_LATENCY_US = this + one block, checked by sp1_uac.c at build time) rests + * on this: a frame reaches the host, on average, TARGET + BLK/2 - BLK frames after its block + * starts rendering. (The regulator holds the fill sampled just before each packet, half a + * packet above its average; that cancels the half USB frame in transit.) Measured here, to the + * middle of the 1 ms frame that carries it. */ +#define RING_DELAY_MS ((UACRING_TARGET + BLK / 2u - BLK) / 48.0) + struct result { uint32_t under, over, lost, fixes, n47, n49, win_max, fill_min; bool heard; + double delay_sum, delay_min, delay_max; /* render start -> USB, us, once settled */ + uint64_t delay_n; }; static struct result run_ppm(int ppm, bool steps) @@ -73,7 +83,9 @@ static struct result run_ppm(int ppm, bool steps) double next_slot = 0.0, busy_until = 0.0, push_at = 0.0; bool rendering = false; uint32_t win_fix = 0, last_fix = 0; - struct result s = { .fill_min = UINT32_MAX }; + struct result s = { .fill_min = UINT32_MAX, .delay_min = 1e12, .delay_max = -1e12 }; + /* When each block started rendering, by block index (a window wider than the ring). */ + static double claim_t[256]; uacring_init(&r); uacring_stream(&r, true); @@ -97,6 +109,7 @@ static struct result run_ppm(int ppm, bool steps) if (steps && ++blocks % 997u == 0u) { render = RENDER_PEAK; } + claim_t[(produced / BLK) & 255u] = start; uacring_claim(&r, BLK); rendering = true; push_at = start + render; @@ -120,6 +133,21 @@ static struct result run_ppm(int ppm, bool steps) s.lost++; expected = (uint16_t)out[i * 2u]; } + if (ms > 20000u) { + /* The frame's full index, from its low 16 bits and `produced`. */ + uint32_t f = (produced & ~0xFFFFu) | (uint16_t)out[i * 2u]; + if (f >= produced) { + f -= 0x10000u; + } + const double t0 = claim_t[(f / BLK) & 255u] + + (f % BLK) * 1000.0 / 48.0; + /* The packet goes out in this 1 ms frame: half way, on average. */ + const double d = now + 500.0 - t0; + s.delay_sum += d; + s.delay_n++; + if (d < s.delay_min) s.delay_min = d; + if (d > s.delay_max) s.delay_max = d; + } expected++; } /* What is left after this packet, once settled (5 s). */ @@ -182,8 +210,10 @@ int main(int argc, char **argv) return 0; } - printf("== uactest: %u-frame blocks, TARGET %u (%.2f ms), dead band +/-%u\n", - (unsigned)BLK, UACRING_TARGET, UACRING_TARGET / 48.0, UACRING_HYSTERESIS); + printf("== uactest: %u-frame blocks, TARGET %u (%.2f ms), dead band +/-%u;" + " render start -> USB %.2f ms\n", + (unsigned)BLK, UACRING_TARGET, UACRING_TARGET / 48.0, UACRING_HYSTERESIS, + RING_DELAY_MS); for (uint32_t i = 0; i < sizeof ppms / sizeof ppms[0]; i++) { for (int steps = 0; steps < 2; steps++) { @@ -209,9 +239,18 @@ int main(int argc, char **argv) CHECK(s.fixes <= 60, "load steps and 200 % blocks are not read as drift"); } - printf(" %+4d ppm %-6s under %u 47s %u 49s %u fixes/s max %u lowest fill %u\n", + const double delay = s.delay_sum / (double)s.delay_n / 1000.0; + if (ppm == 0) { + CHECK(delay > RING_DELAY_MS - 0.25 && delay < RING_DELAY_MS + 0.25, + "at 0 ppm the ring's delay is the one MIDI's clock makes up for"); + } + CHECK(delay > RING_DELAY_MS - UACRING_HYSTERESIS / 48.0 - 0.1 && + delay < RING_DELAY_MS + UACRING_HYSTERESIS / 48.0 + 0.1, + "with drift, the ring's delay stays within the dead band of it"); + printf(" %+4d ppm %-6s under %u 47s %u 49s %u fixes/s max %u lowest fill %u" + " delay %.2f ms (%.2f .. %.2f)\n", ppm, steps ? "steps" : "steady", s.under, s.n47, s.n49, s.win_max, - s.fill_min); + s.fill_min, delay, s.delay_min / 1000.0, s.delay_max / 1000.0); } } From 272bc6cf706b7ab055118f5154aa8def74606d7a Mon Sep 17 00:00:00 2001 From: Worldwave Date: Tue, 6 Oct 2026 11:32:48 -0400 Subject: [PATCH 08/10] M5c: config/audio.ini -- USB audio out's level mode and the speaker Adara's spec: users choose how USB audio out sets its level and whether the speaker plays while a host records, in a new config file. config/audio.ini [usb] (-> tools/gen_audio.py -> sp1_audio_gen.h, like the MIDI script: a bad value fails the build, naming the line): - level = parked (default) | vol. parked: while a host takes USB audio out, VOL is set to parked_level and its buttons are locked ("LEVEL locked ..." logged on a press); when the host stops, VOL returns to where it was. Wakes has one output level, so this parks the headphones (and the speaker, if on) too -- Adara's call, and the file says why: it is the cheapest way (a separate USB level would need a second gain pass, ~0.3 % of the CPU). The level slews as VOL always does. vol: VOL moves USB audio out with everything else (the M5c build so far). - parked_level = -6 (default): one of VOL's steps, 0 .. -30 dB in 3 dB. BUILD_ASSERTs tie gen_audio.py's step list to sp1_audio.c's table. - speaker = off (default) | on: the speaker while a host takes USB audio out (speaker_wanted; headphones always play). Built both ways (shipped settings, and vol / -30 / on), 0 warnings; the generator rejects a bad mode, a level off VOL's steps, a positive level, a bad on/off and an unknown key, each naming its line. README lists the file. Build: 427 660 B, 0 warnings, check_image OK; fallback OK. Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + config/audio.ini | 43 ++++++++++++ firmware/CMakeLists.txt | 15 +++++ firmware/src/main.c | 71 +++++++++++++++++--- firmware/src/sp1_audio.c | 13 +++- tools/gen_audio.py | 142 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 275 insertions(+), 10 deletions(-) create mode 100644 config/audio.ini create mode 100644 tools/gen_audio.py diff --git a/README.md b/README.md index f857822..9fb8adb 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ Output: `build/zephyr/wakes-sp1.bin`. The Zephyr patch is required and is lost o | [`docs/DEFAULTS.md`](docs/DEFAULTS.md) | every default, and what a reset restores | | [`docs/MIDI.md`](docs/MIDI.md) | MIDI over USB: what it does, and how to change it | | [`config/midi.ini`](config/midi.ini) | the MIDI script: channel, legato, CC numbers (editable) | +| [`config/audio.ini`](config/audio.ini) | USB audio out: its level (parked or on VOL) and the speaker while a host records (editable) | | [`docs/SAFETY.md`](docs/SAFETY.md) | rules for anyone changing the firmware | ## Licence diff --git a/config/audio.ini b/config/audio.ini new file mode 100644 index 0000000..9e16a7d --- /dev/null +++ b/config/audio.ini @@ -0,0 +1,43 @@ +; ===================================================================================== +; Wakes — the audio settings +; ===================================================================================== +; +; How Wakes' sound leaves the device. Edit it in your fork, build (or let CI build) and +; flash: the build reads this file and FAILS with the line number if something in it is +; wrong, so a typo can never become a firmware that silently ignores your setting. +; +; Lines starting with ; are comments. Every setting can be left out to get its default. + + +[usb] +; USB AUDIO OUT. Plugged into a computer, phone or other USB host, Wakes shows up as an +; audio input ("Wakes Audio Out", or "Wakes" -- the name depends on the host): 48 kHz, +; 16-bit stereo, no driver. It carries what the speaker and headphones get -- the output +; select (OUT / AUX / OUT+AUX / OUTxAUX) and the drive included. Nothing changes until a +; host actually takes the audio (records or monitors the input); these settings apply only +; while it does. Headphones always play. + +; How USB audio out sets its level: +; parked (default) = while a host takes USB audio, VOL is set to `parked_level` and its +; buttons do nothing, so a recording's level never depends on where VOL happened to +; be. When the host stops, VOL goes back to where you left it. +; Wakes has ONE output level for every output, so parking it parks the headphones +; (and the speaker, if `speaker = on`) at that level too. That is deliberate: it is +; the cheapest way to do it. A separate level for USB alone would need a second gain +; pass over every block of audio (about 0.3 % of the CPU), which Wakes keeps for its +; engines. +; vol = VOL moves USB audio out like everything else, like the volume knob of a +; hardware synth on a mixer track. +level = parked + +; The level USB audio out is parked at, in dB: one of VOL's steps -- 0, -3, -6, -9, -12, +; -15, -18, -21, -24, -27 or -30. 0 is full scale, which Wakes' loudest patches (the +; drive's top steps) reach; -6 leaves a recording some headroom. +parked_level = -6 + +; The speaker while a host takes USB audio: +; off (default) = quiet: the host is recording, so the room only gets a second copy. +; It comes back as soon as the host stops taking the audio (or goes to sleep, or the +; cable is pulled). +; on = it keeps playing. +speaker = off diff --git a/firmware/CMakeLists.txt b/firmware/CMakeLists.txt index 9a20488..151e114 100644 --- a/firmware/CMakeLists.txt +++ b/firmware/CMakeLists.txt @@ -57,6 +57,21 @@ add_custom_command( add_custom_target(sp1_midi_gen DEPENDS ${SP1_MIDI_OUT}) add_dependencies(app sp1_midi_gen) +# ---- the audio settings: config/audio.ini -> sp1_audio_gen.h (M5c) ---- +# How sound leaves the device: USB audio out's level mode and the speaker while a host takes +# it. Same rule as the MIDI script: a bad value fails the build, naming the line. +set(SP1_AUDIO_INI ${CMAKE_CURRENT_SOURCE_DIR}/../config/audio.ini) +set(SP1_AUDIO_GEN ${CMAKE_CURRENT_SOURCE_DIR}/../tools/gen_audio.py) +set(SP1_AUDIO_H ${CMAKE_CURRENT_BINARY_DIR}/sp1_generated/sp1_audio_gen.h) +add_custom_command( + OUTPUT ${SP1_AUDIO_H} + COMMAND ${Python3_EXECUTABLE} ${SP1_AUDIO_GEN} ${SP1_AUDIO_INI} ${SP1_AUDIO_H} + DEPENDS ${SP1_AUDIO_INI} ${SP1_AUDIO_GEN} + COMMENT "Generating the audio settings from config/audio.ini" +) +add_custom_target(sp1_audio_gen DEPENDS ${SP1_AUDIO_H}) +add_dependencies(app sp1_audio_gen) + target_sources(app PRIVATE src/main.c src/sp1_led.c diff --git a/firmware/src/main.c b/firmware/src/main.c index 713813e..69c5b1a 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -94,6 +94,47 @@ #endif #if defined(CONFIG_SP1_USB_AUDIO) #include "sp1_uac.h" +#include "sp1_audio_gen.h" /* config/audio.ini */ +#endif + +/* ---- USB audio out's level (M5c; config/audio.ini [usb] level) ---- + * `parked`: while a host takes USB audio out (sp1_uac_live), VOL is set to audio.ini's + * parked_level and its buttons do nothing; when the host stops, VOL goes back to where the + * user left it. Wakes has ONE output level for every output, so this parks the headphones + * (and the speaker, if it is on) too -- deliberately: a separate USB level would be a second + * gain pass over every block (~0.3 % of the CPU, Adara: use this avenue instead). The level + * slews as VOL always does, so parking does not click. `vol`: nothing here happens. + * Across ON sessions the state stays, so a session started while a host records is parked + * on its first tick. */ +static bool vol_parked; +#if defined(CONFIG_SP1_USB_AUDIO) +static int vol_saved; + +static int usb_parked_db(void) +{ + return SP1_AUDIO_USB_PARKED_DB; +} + +static void usb_level_park(bool usb_live) +{ + if (!SP1_AUDIO_USB_LEVEL_PARKED) { + return; + } + if (usb_live && !vol_parked) { + vol_saved = sp1_audio_level_get(); + sp1_audio_level_step(SP1_AUDIO_USB_PARKED_STEP - vol_saved); + vol_parked = true; + printk("LEVEL parked at %d dBFS: a host takes USB audio out, VOL locked" + " (config/audio.ini)\n", (int)SP1_AUDIO_USB_PARKED_DB); + } else if (!usb_live && vol_parked) { + sp1_audio_level_step(vol_saved - sp1_audio_level_get()); + vol_parked = false; + printk("LEVEL back to step %d: no host takes USB audio out, VOL unlocked\n", + vol_saved); + } +} +#else +static int usb_parked_db(void) { return 0; } #endif #define WDT_NODE DT_ALIAS(watchdog0) @@ -1784,14 +1825,21 @@ int main(void) /* ---- VOL-/VOL+: output level, 3 dB steps, slewed (no clicks) ---- * Two steps is exactly one meter band (6.02 dB). Shifted, VOL is the * drive above instead, so this whole block stands down. */ - if (!fnc && sp1_button_pressed(SP1_BTN_VOL_DOWN)) { + if (!fnc && vol_parked && (sp1_button_pressed(SP1_BTN_VOL_DOWN) || + sp1_button_pressed(SP1_BTN_VOL_UP))) { + /* config/audio.ini level = parked: a host is recording, so VOL stays + * where audio.ini put it until the host stops (usb_level_park). */ + printk("LEVEL locked at %d dBFS while a host takes USB audio out" + " (config/audio.ini)\n", (int)usb_parked_db()); + } + if (!fnc && !vol_parked && sp1_button_pressed(SP1_BTN_VOL_DOWN)) { sp1_audio_level_step(+1); } - if (!fnc && sp1_button_pressed(SP1_BTN_VOL_UP)) { + if (!fnc && !vol_parked && sp1_button_pressed(SP1_BTN_VOL_UP)) { sp1_audio_level_step(-1); } - if (!fnc && (sp1_button_pressed(SP1_BTN_VOL_DOWN) || - sp1_button_pressed(SP1_BTN_VOL_UP))) { + if (!fnc && !vol_parked && (sp1_button_pressed(SP1_BTN_VOL_DOWN) || + sp1_button_pressed(SP1_BTN_VOL_UP))) { const int d = sp1_audio_level_db_x10(); if (d <= -9990) { printk("LEVEL muted (step %d)\n", @@ -1805,10 +1853,17 @@ int main(void) } /* ---- headphones in -> speaker off (M3) ---- */ -#if defined(CONFIG_SP1_MIDI) && defined(CONFIG_SP1_USB_AUDIO) - /* M5c: the delay the MIDI clock makes up for is the path the host hears -- - * USB audio out while a host takes it, the speaker / headphones otherwise. */ - sp1_midi_set_output_usb(sp1_uac_live()); +#if defined(CONFIG_SP1_USB_AUDIO) + { + const bool usb_live = sp1_uac_live(); +#if defined(CONFIG_SP1_MIDI) + /* M5c: the delay the MIDI clock makes up for is the path the host + * hears -- USB audio out while a host takes it, the speaker / + * headphones otherwise. */ + sp1_midi_set_output_usb(usb_live); +#endif + usb_level_park(usb_live); + } #endif switch (sp1_audio_jack_poll(dt)) { case 1: diff --git a/firmware/src/sp1_audio.c b/firmware/src/sp1_audio.c index 3a91563..50f39ad 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -53,6 +53,7 @@ K_MEM_SLAB_DEFINE_STATIC(tx_slab, BLK_BYTES, TX_QUEUE + 4, 4); #if defined(CONFIG_SP1_USB_AUDIO) #include "sp1_uac.h" /* M5c: the same blocks, to the host */ +#include "sp1_audio_gen.h" /* config/audio.ini: the speaker while a host takes them */ #endif #if defined(CONFIG_SP1_MIDI) @@ -235,6 +236,13 @@ static const int16_t TONE_AMP[SP1_LEVEL_STEPS] = { static const int16_t TONE_DB_X10[SP1_LEVEL_STEPS] = { 0, -30, -60, -90, -120, -151, -181, -211, -241, -271, -301, -9990, }; +/* config/audio.ini's parked_level is one of these steps, as tools/gen_audio.py knows them + * (0 .. -30 dB, 3 dB apart, then mute): parking USB audio out IS setting VOL (main.c). */ +BUILD_ASSERT(SP1_LEVEL_STEPS == 12, "VOL's steps changed: update VOL_STEPS in tools/gen_audio.py"); +#if defined(CONFIG_SP1_USB_AUDIO) +BUILD_ASSERT(SP1_AUDIO_USB_PARKED_STEP >= 0 && SP1_AUDIO_USB_PARKED_STEP < SP1_LEVEL_STEPS - 1, + "config/audio.ini parked_level is not one of VOL's steps"); +#endif static volatile bool tone_on; static volatile int tone_step = SP1_LEVEL_DEFAULT; /* the OUTPUT LEVEL step */ @@ -930,7 +938,8 @@ void sp1_audio_take_sections(struct sp1_audio_sections *out) * Tim Knapen's sequence). DET_STATUS1 (0x1B77) bit 7 reads 1 while a plug is in. * While it is, the TAS2505's class-D driver is powered down (page 1, reg 0x2D). * - * M5c (Adara, 2026-10-05): the speaker is also off while a host is TAKING USB audio out + * M5c (Adara, 2026-10-05): the speaker is also off while a host is TAKING USB audio out -- + * unless config/audio.ini says `speaker = on` (SP1_AUDIO_USB_SPEAKER; default off) * (sp1_uac_live: the stream open AND packets going out since the last poll) -- recording * Wakes over USB, the speaker would only be a second, room copy. Anything short of that * defaults to the speaker (Adara): a charger, a host without USB audio or that rejects @@ -986,7 +995,7 @@ static bool speaker_driver(bool on) static bool speaker_wanted(void) { #if defined(CONFIG_SP1_USB_AUDIO) - if (sp1_uac_live()) { + if (!SP1_AUDIO_USB_SPEAKER && sp1_uac_live()) { return false; } #endif diff --git a/tools/gen_audio.py b/tools/gen_audio.py new file mode 100644 index 0000000..832591b --- /dev/null +++ b/tools/gen_audio.py @@ -0,0 +1,142 @@ +#!/usr/bin/env python3 +"""wakes-sp1 -- generate the firmware's audio settings from config/audio.ini. + + gen_audio.py build step (CMake runs this) + +config/audio.ini holds the USER's choices for how Wakes' sound leaves the device: today, how +USB audio out sets its level and whether the speaker plays while a host records over USB. +This file holds the facts the user cannot choose (VOL's steps). + +The build fails, naming the line, on anything invalid -- an unknown section or key, a value +that is not one of the choices, a level that is not one of VOL's steps. A setting that +half-works is worse than one that refuses to build (the same rule as gen_midi.py). + +Standard library only. Read as UTF-8 (with or without a BOM). +""" +import configparser +import os +import re +import sys + +# ---- facts: NOT user configuration --------------------------------------------------------- +# VOL's steps (firmware/src/sp1_audio.c, TONE_AMP): 0 dB, then 3 dB apart down to -30 dB; step +# n is -3n dB. A parked level is one of them, because parking IS setting VOL (no second gain +# stage -- that is what keeps it free of CPU). +VOL_STEP_DB = 3 +VOL_STEPS = 11 # 0 .. -30 dB (the 12th step is mute) + +LEVEL = {'parked': 1, 'vol': 0} +ONOFF = {'on': 1, 'off': 0} +KEYS = {'usb': {'level', 'parked_level', 'speaker'}} +DEFAULTS = {'level': 'parked', 'parked_level': '-6', 'speaker': 'off'} + + +def fail(path, line, msg): + where = '%s:%d' % (path, line) if line else path + sys.stderr.write('\n%s: error: %s\n\n' + 'The audio settings are checked at build time so a mistake cannot reach\n' + 'the device. See the comments in config/audio.ini.\n' % (where, msg)) + sys.exit(1) + + +def line_of(text, section, key): + """Line number of `key` inside [section], for error messages.""" + cur = None + for i, ln in enumerate(text.splitlines(), 1): + s = ln.strip() + m = re.match(r'^\[(.+)\]$', s) + if m: + cur = m.group(1).strip().lower() + elif cur == section and re.match(r'^%s\s*[=:]' % re.escape(key), s, re.I): + return i + return 0 + + +def parse(path): + with open(path, encoding='utf-8-sig') as f: + text = f.read() + cp = configparser.ConfigParser(inline_comment_prefixes=(';', '#'), + comment_prefixes=(';', '#'), strict=True, + interpolation=None) + try: + cp.read_string(text, source=path) + except configparser.Error as e: + fail(path, getattr(e, 'lineno', 0), str(e).splitlines()[0]) + + def err(sec, key, msg): + fail(path, line_of(text, sec, key), msg) + + for sec in cp.sections(): + if sec not in KEYS: + fail(path, 0, 'unknown section [%s] (expected %s)' + % (sec, ', '.join('[%s]' % s for s in sorted(KEYS)))) + for key in cp[sec]: + if key not in KEYS[sec]: + err(sec, key, 'unknown setting "%s" in [%s] (expected %s)' + % (key, sec, ', '.join(sorted(KEYS[sec])))) + + usb = cp['usb'] if cp.has_section('usb') else {} + + def get(key): + return usb.get(key, DEFAULTS[key]).strip().lower() + + cfg = {} + v = get('level') + if v not in LEVEL: + err('usb', 'level', 'level must be parked or vol, not "%s"' % v) + cfg['parked'] = LEVEL[v] + + v = get('parked_level') + m = re.fullmatch(r'([+-]?\d+)\s*(db)?', v) + if not m: + err('usb', 'parked_level', 'parked_level must be a number of dB, like -6, not "%s"' % v) + db = int(m.group(1)) + if db > 0 or db % VOL_STEP_DB != 0 or -db > (VOL_STEPS - 1) * VOL_STEP_DB: + err('usb', 'parked_level', 'parked_level must be one of VOL\'s steps: %s dB, not %d' + % (', '.join(str(-VOL_STEP_DB * n) for n in range(VOL_STEPS)), db)) + cfg['parked_db'] = db + cfg['parked_step'] = -db // VOL_STEP_DB + + v = get('speaker') + if v not in ONOFF: + err('usb', 'speaker', 'speaker must be on or off, not "%s"' % v) + cfg['speaker'] = ONOFF[v] + return cfg + + +def header(cfg, src): + return '\n'.join([ + '/* GENERATED by tools/gen_audio.py from %s -- do not edit. */' % src, + '#pragma once', + '', + '/* [usb] level: 1 = parked (VOL set to the parked step and locked while a host takes', + ' * USB audio out), 0 = vol (VOL moves USB audio out with everything else). */', + '#define SP1_AUDIO_USB_LEVEL_PARKED %d' % cfg['parked'], + '/* [usb] parked_level, as VOL\'s step (sp1_audio.c TONE_AMP) and in dB. */', + '#define SP1_AUDIO_USB_PARKED_STEP %d' % cfg['parked_step'], + '#define SP1_AUDIO_USB_PARKED_DB (%d)' % cfg['parked_db'], + '/* [usb] speaker: 1 = the speaker keeps playing while a host takes USB audio out. */', + '#define SP1_AUDIO_USB_SPEAKER %d' % cfg['speaker'], + '', + ]) + + +def main(): + if len(sys.argv) != 3: + sys.stderr.write(__doc__) + sys.exit(2) + src, out = sys.argv[1], sys.argv[2] + text = header(parse(src), 'config/audio.ini') + try: + with open(out, encoding='utf-8') as f: + if f.read() == text: + return # unchanged: do not force a rebuild + except OSError: + pass + os.makedirs(os.path.dirname(os.path.abspath(out)), exist_ok=True) + with open(out, 'w', encoding='utf-8', newline='\n') as f: + f.write(text) + + +if __name__ == '__main__': + main() From fd3ad2d4887fd80ff4c2cac52de22104dd5edcbd Mon Sep 17 00:00:00 2001 From: Worldwave Date: Tue, 6 Oct 2026 14:24:43 -0400 Subject: [PATCH 09/10] M5c: fix the liveness race that let the speaker blip while a host records Seen on the OP-XY (logs/sp1-20261006-142157.log): 13 times in 5 minutes the speaker came back for one 40 ms poll ("SPEAKER on: no host is taking USB audio out", then "off" 43 ms later), and VOL unparked and re-parked within one tick ~30 times -- while the stream never paused (312 075 packets, under=0, over=0). sp1_uac_live() read the clock, THEN last_fill. A packet handed over between the two reads made last_fill later than now; the unsigned difference wrapped to ~2^32 and a live stream read as dead for that call. Likelier than it sounds: the clock read holds interrupts off, so a start-of-frame arriving during it fires exactly in that gap. Now last_fill is read first (a packet in between can only make it older) and the comparison is signed (a time ahead of now counts as live). Checked in the disassembly: the load precedes the clock call, the compare is signed. Build: 427 660 B, 0 warnings, check_image OK; fallback OK. Co-Authored-By: Claude Opus 5.5 --- firmware/src/sp1_uac.c | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/firmware/src/sp1_uac.c b/firmware/src/sp1_uac.c index ac892d0..f06c6b3 100644 --- a/firmware/src/sp1_uac.c +++ b/firmware/src/sp1_uac.c @@ -433,8 +433,20 @@ bool sp1_uac_live(void) * stopped running the bus -- asleep, suspended, or stalled -- calls fill() no more, * because fill() runs at each start-of-frame. So: live while fill() ran in the last * 20 ms. No state of its own, so any thread may ask: the speaker check and the MIDI - * clock's lead both do. */ - return stream_open && (k_cycle_get_32() - last_fill) < LIVE_CYCLES; + * clock's lead both do. + * + * ⚠️ ORDER: the packet time FIRST, then the clock. Read the other way round, a packet + * the interrupt hands over between the two reads makes `last_fill` LATER than `now`, the + * unsigned difference wraps to ~2^32 and a stream that never paused reads as dead for + * that one call -- the speaker came back for one 40 ms poll, and VOL unparked for one + * tick, a few times a minute on the OP-XY (logs/sp1-20261006-142157.log). Likelier than + * it sounds: the clock read holds interrupts off, so a start-of-frame arriving during it + * fires exactly in that gap. Read in this order, a packet in between can only make `t` + * look older. The signed comparison is a second guard: a `t` ahead of `now` is live. */ + const uint32_t t = last_fill; + const uint32_t now = k_cycle_get_32(); + + return stream_open && (int32_t)(now - t) < (int32_t)LIVE_CYCLES; } /* ---- the producer (the audio thread) ---- */ From 639231f661a6da20fcb1f03602dcaf593ccb16ba Mon Sep 17 00:00:00 2001 From: Worldwave Date: Tue, 6 Oct 2026 15:01:38 -0400 Subject: [PATCH 10/10] v0.7.0: version bump and the updated manual firmware/VERSION, README and the issue-form placeholders go to v0.7.0 for USB audio out (M5c). docs/Wakes - Manual.pdf is Adara's updated manual. Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/bug.yml | 2 +- .github/ISSUE_TEMPLATE/feature.yml | 2 +- README.md | 2 +- docs/Wakes - Manual.pdf | Bin 364083 -> 363637 bytes firmware/VERSION | 4 ++-- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index f68a1d0..2dd4a5c 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -89,7 +89,7 @@ body: attributes: label: Version description: The release you flashed (e.g. from its file name), or the commit if you built it yourself. - placeholder: v0.6.1 + placeholder: v0.7.0 validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index b4d2357..3016855 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -76,6 +76,6 @@ body: attributes: label: Version description: The release you are using, if the request is about something you've seen on hardware. - placeholder: v0.6.1 + placeholder: v0.7.0 validations: required: false diff --git a/README.md b/README.md index 9fb8adb..5ce1914 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ IMPORTANT: Flashing custom firmware on the SP-1 is at your own risk. SP-1s are a ## Status -**v0.6.1, pre-release for beta testing.** Report problems with the bug form under [Issues](https://github.com/Worldwave/Wakes/issues). +**v0.7.0, pre-release for beta testing.** Report problems with the bug form under [Issues](https://github.com/Worldwave/Wakes/issues). ## Flashing diff --git a/docs/Wakes - Manual.pdf b/docs/Wakes - Manual.pdf index 989f6d0f9d63462e2b59a87afa9f211dbad241ff..920283cd7125657087be256d390f5bdfe634ee34 100644 GIT binary patch delta 43047 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 delta 43260 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 Xn^v`khm{}`yE)m##kJGwGP3^