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/.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/LICENSES/README.md b/LICENSES/README.md index a32a641..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 | `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 87f80dd..1041f06 100644 --- a/NOTICE +++ b/NOTICE @@ -107,6 +107,23 @@ 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. 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. 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 boards/teenageengineering/stem_player/Kconfig.defconfig, Kconfig.stem_player diff --git a/README.md b/README.md index f857822..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 @@ -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/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 f6ff821..4d739b1 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, @@ -124,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. @@ -214,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/docs/Wakes - Manual.pdf b/docs/Wakes - Manual.pdf index 989f6d0..920283c 100644 Binary files a/docs/Wakes - Manual.pdf and b/docs/Wakes - Manual.pdf differ diff --git a/firmware/CMakeLists.txt b/firmware/CMakeLists.txt index 5f18afa..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 @@ -414,4 +429,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/VERSION b/firmware/VERSION index d14d99e..217bf4e 100644 --- a/firmware/VERSION +++ b/firmware/VERSION @@ -1,5 +1,5 @@ VERSION_MAJOR = 0 -VERSION_MINOR = 6 -PATCHLEVEL = 1 +VERSION_MINOR = 7 +PATCHLEVEL = 0 VERSION_TWEAK = 0 EXTRAVERSION = 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..69c5b1a 100644 --- a/firmware/src/main.c +++ b/firmware/src/main.c @@ -92,6 +92,50 @@ #include "sp1_release_guard.h" #include "sp1_midi.h" #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) @@ -1039,12 +1083,21 @@ 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\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; @@ -1772,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", @@ -1793,12 +1853,32 @@ int main(void) } /* ---- headphones in -> speaker off (M3) ---- */ +#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: 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 is taking USB audio out\n"); + break; + case 4: + printk("SPEAKER on: no host is taking USB audio out\n"); break; case 2: printk("JACK detect failed 3x: disabled, speaker on\n"); @@ -2013,6 +2093,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..50f39ad 100644 --- a/firmware/src/sp1_audio.c +++ b/firmware/src/sp1_audio.c @@ -51,6 +51,11 @@ 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 */ +#include "sp1_audio_gen.h" /* config/audio.ini: the speaker while a host takes them */ +#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), @@ -113,6 +118,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 @@ -229,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 */ @@ -431,6 +445,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 +467,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); @@ -765,6 +789,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; } @@ -908,6 +938,18 @@ 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 -- + * 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 + * 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 + * 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; @@ -948,6 +990,18 @@ static bool speaker_driver(bool on) return ok; } +/* 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. */ +static bool speaker_wanted(void) +{ +#if defined(CONFIG_SP1_USB_AUDIO) + if (!SP1_AUDIO_USB_SPEAKER && sp1_uac_live()) { + return false; + } +#endif + return jack_state != 1; +} + static void jack_reset(void) { jack_state = -1; @@ -988,27 +1042,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..3131a4d 100644 --- a/firmware/src/sp1_audio.h +++ b/firmware/src/sp1_audio.h @@ -102,13 +102,18 @@ 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 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 (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 */ /* 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_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 new file mode 100644 index 0000000..f06c6b3 --- /dev/null +++ b/firmware/src/sp1_uac.c @@ -0,0 +1,612 @@ +/* + * 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" +#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 */ +#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)"); +#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; + 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; +/* 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 ---- + * 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); + + last_fill = k_cycle_get_32(); /* the host is running frames: sp1_uac_live() */ + + 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) +{ + last_fill = k_cycle_get_32() - 2u * LIVE_CYCLES; /* not live until a packet goes */ + 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; + } +} + +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() 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. + * + * ⚠️ 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) ---- */ +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..c789782 --- /dev/null +++ b/firmware/src/sp1_uac.h @@ -0,0 +1,54 @@ +/* + * 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); + +/* The host has the stream open (alternate setting 1). */ +bool sp1_uac_open(void); + +/* ...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 { + 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_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/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/third_party/sp1-usb-audio/README.md b/third_party/sp1-usb-audio/README.md new file mode 100644 index 0000000..1c9b09d --- /dev/null +++ b/third_party/sp1-usb-audio/README.md @@ -0,0 +1,66 @@ +# 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`. + +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 | **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. +- **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`), 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/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); 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/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/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() 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/README.md b/tools/host-tests/README.md index 0fe6978..c1885fa 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`, 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 \ - 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..55e46f1 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,16 @@ 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 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" ;; 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 new file mode 100644 index 0000000..8f017e2 --- /dev/null +++ b/tools/host-tests/uactest.c @@ -0,0 +1,294 @@ +/* + * 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 + +/* 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) +{ + 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, .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); + 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; + } + claim_t[(produced / BLK) & 255u] = start; + 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]; + } + 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). */ + 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;" + " 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++) { + 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"); + } + 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, delay, s.delay_min / 1000.0, s.delay_max / 1000.0); + } + } + + 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 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); +