Add factory-compatible source audio passthrough

Author: matteius

README.md

@@ -99,8 +99,12 @@ An additional opt-in transition target now links the open application directly
 for the factory engine-slot ABI: vectors at ITCM zero, DTCM stack, pinned
 `SystemInit`, and a hard `0x1e000` copy limit. The recovered OEM updater packer
 can wrap it in a validated BINA stream and emits a byte-identical Metal restore
-alongside it. This is an offline packaging milestone, not a flash candidate:
-the source image does not initialize audio or any target-visible diagnostics.
+alongside it. An additional opt-in source path now reproduces the executed
+factory SAI1/eDMA contract, including the PLL, pins, four-slot framing,
+ping-pong TCD rings, IRQ0 handler, and a weak passthrough/DSP hook. It passes
+offline reset/register emulation and a synthetic DMA-block copy. This remains
+an offline packaging milestone, not a flash candidate, until the external
+analog mute/bypass sequencing is recovered.
 
 The application now has an allocation-free extensible effect registry,
 caller-sized processing chains, validated program/bank catalogs, and a

docs/hardware/FACTORY_AUDIO.md

@@ -149,14 +149,38 @@ python3 tools/emulate_factory_audio.py \
 Successful execution stops at Metal ITCM address `0x8110`, immediately after
 the factory initializer enables both SAI1 directions and their DMA requests.
 
+The source implementation can be built and checked independently:
+
+```sh
+cmake -S firmware -B build/factory-audio -G Ninja \
+  -DCMAKE_TOOLCHAIN_FILE="$PWD/firmware/cmake/arm-none-eabi-toolchain.cmake" \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DNCR2_BUILD_FACTORY_SLOT_APP=ON \
+  -DNCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH=ON \
+  -DNCR2_MCUX_SDK_ROOT="$PWD/third_party/mcux-sdk-workspace"
+cmake --build build/factory-audio --target ncr2_factory_slot_app
+python3 tools/check_factory_slot.py \
+  build/factory-audio/ncr2_factory_slot_app.elf
+PYTHONPATH=/path/to/unicorn \
+python3 tools/emulate_source_audio.py \
+  build/factory-audio/ncr2_factory_slot_app.elf
+```
+
+The source emulator validates the exact SAI1, PLL, pin, DMAMUX, and hardware
+TCD state and executes one synthetic RX-completion interrupt through the
+weak passthrough block hook. This is a strong digital-contract check, but it
+does not model the external converter or analog switching.
+
 ## Remaining hardware gates
 
-This is enough to implement the digital audio loop. It is not by itself enough
-to declare an image safe to flash. Before hardware deployment, the source
-target must also reproduce or conservatively preserve:
+The digital audio loop is now implemented. That is not by itself enough to
+declare an image safe to flash. Before hardware deployment, the source target
+must also reproduce or conservatively preserve:
 
 1. the analog mute/bypass/relay sequencing;
-2. cache coherency for DMA buffers;
-3. the eDMA IRQ vector and acknowledgement path;
-4. a bounded failure mode that leaves the analog path muted or bypassed;
-5. a byte-identical known-good Metal restore container.
+2. a bounded failure mode that leaves the analog path muted or bypassed;
+3. a byte-identical known-good Metal restore container.
+
+The current source buffers and TCDs are in DTCM, so data-cache coherency is
+not involved. External IRQ0 and the eDMA acknowledgement/copy path are
+validated by the post-link checker and source emulator.

docs/hardware/FACTORY_SLOT_APP.md

@@ -26,11 +26,12 @@ The source target therefore:
 - initializes `.data` and `.bss`; and
 - enforces the `0x1e000` load budget in the linker and post-link checker.
 
-The current payload is the hardware-neutral application/runtime skeleton. It
-does not initialize the audio codec, SAI, eDMA, GPIO, mute, or LEDs. Flashing
-it would at best produce a silent diagnostic loop. It is deliberately marked
-**offline only** until the source audio path and a non-destructive hardware
-diagnostic are implemented and reviewed.
+The default payload remains a hardware-neutral application/runtime skeleton.
+An additional, separately gated build reproduces the executed factory
+SAI1/eDMA contract and runs a four-slot, 32-bit passthrough with two 128-byte
+DTCM buffer halves. The source audio path has passed register-level emulation
+and an emulated DMA-block copy, but it is still marked **offline only**:
+the board's analog mute/bypass sequencing has not yet been recovered.
 
 ## Build and verify
 
@@ -44,13 +45,25 @@ cmake -S firmware -B build/factory-slot -G Ninja \
   -DCMAKE_TOOLCHAIN_FILE="$PWD/firmware/cmake/arm-none-eabi-toolchain.cmake" \
   -DCMAKE_BUILD_TYPE=Release \
   -DNCR2_BUILD_FACTORY_SLOT_APP=ON \
+  -DNCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH=ON \
   -DNCR2_MCUX_SDK_ROOT="$PWD/third_party/mcux-sdk-workspace"
 
 cmake --build build/factory-slot --target ncr2_factory_slot_app
 python3 tools/check_factory_slot.py \
   build/factory-slot/ncr2_factory_slot_app.elf
+
+PYTHONPATH=/path/to/unicorn \
+python3 tools/emulate_source_audio.py \
+  build/factory-slot/ncr2_factory_slot_app.elf
 ```
 
+Omit `NCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH=ON` to produce the deliberately
+hardware-inert default. The post-link checker validates the complete vector
+table, including external IRQ0 targeting the shared eDMA channel 0/16
+handler. The source emulator executes reset and initialization, checks the
+factory SAI1, PLL, pin, DMAMUX, and TCD values, injects one RX block, invokes
+the source ISR, and verifies the unchanged TX block. It does not access USB.
+
 ## Build an offline OEM-DFU package
 
 The packer starts from the verified private dump because the factory HID
@@ -76,15 +89,16 @@ refuses to overwrite existing artifacts.
 
 For the verified local dump, the generated Metal restore is byte-identical to
 the previously live-tested `eng3-slot1.bina`. The source package is still not
-approved for streaming: it lacks audio and target-visible diagnostics.
+approved for streaming: digital passthrough is implemented, but the analog
+mute/bypass state and live slot semantics remain unverified.
 
 ## Gates before first source-slot hardware test
 
-1. Recover and source-control exact audio clocks, pads, SAI framing, eDMA
-   channels, and ping-pong buffer geometry.
+1. ~~Recover and source-control exact audio clocks, pads, SAI framing, eDMA
+   channels, and ping-pong buffer geometry.~~
 2. Identify the converter/codec and prove mute/bypass sequencing.
-3. Implement a bounded passthrough path with DTCM DMA buffers and explicit
-   cache policy.
+3. ~~Implement a bounded passthrough path with DTCM DMA buffers and explicit
+   cache policy.~~ The first image keeps DMA state in uncached DTCM.
 4. Add a safe target-visible heartbeat that cannot drive an unknown output.
 5. Review the generated write range and exact BINA hash.
 6. Keep the byte-identical Metal restore package available before testing.

firmware/CMakeLists.txt

@@ -31,6 +31,11 @@ option(
     "Build the unapproved source app for the recovered factory slot ABI"
     OFF
 )
+option(
+    NCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH
+    "Enable the recovered unapproved SAI1/eDMA factory-slot passthrough"
+    OFF
+)
 option(
     NCR2_HARDWARE_RECOVERY_WRITE_ENABLE
     "Enable physical NOR mutation in the unapproved hardware bootloader"
@@ -224,36 +229,47 @@ if(NCR2_BUILD_FACTORY_SLOT_APP)
         NCR2_FACTORY_SLOT_SYSTEM_SOURCE
         ${NCR2_MCUX_SDK_ROOT}/core/devices/MIMXRT1051/system_MIMXRT1051.c
     )
+    set(
+        NCR2_FACTORY_SLOT_CLOCK_SOURCE
+        ${NCR2_MCUX_SDK_ROOT}/core/devices/MIMXRT1051/drivers/fsl_clock.c
+    )
     add_executable(
         ncr2_factory_slot_app
         EXCLUDE_FROM_ALL
         factory_slot/src/startup.S
+        factory_slot/src/audio_passthrough.c
+        factory_slot/src/main.c
         app/src/effect_runtime.c
         app/src/effects_basic.c
-        app/src/main.c
         app/src/program_runtime.c
         app/src/program_selector.c
         app/src/programs_builtin.c
         ${NCR2_FACTORY_SLOT_SYSTEM_SOURCE}
+        ${NCR2_FACTORY_SLOT_CLOCK_SOURCE}
     )
     target_include_directories(
         ncr2_factory_slot_app
         PRIVATE
             ${CMAKE_CURRENT_SOURCE_DIR}/app/include
+            ${CMAKE_CURRENT_SOURCE_DIR}/factory_slot/include
     )
     target_include_directories(
         ncr2_factory_slot_app
         SYSTEM PRIVATE
             ${NCR2_MCUX_SDK_ROOT}/core/CMSIS/Core/Include
             ${NCR2_MCUX_SDK_ROOT}/core/devices/MIMXRT1051
+            ${NCR2_MCUX_SDK_ROOT}/core/devices/MIMXRT1051/drivers
+            ${NCR2_MCUX_SDK_ROOT}/core/drivers/common
     )
     target_compile_definitions(
         ncr2_factory_slot_app
         PRIVATE
             CPU_MIMXRT1051DVL6B
+            NCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH=$<BOOL:${NCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH}>
     )
     set_source_files_properties(
         ${NCR2_FACTORY_SLOT_SYSTEM_SOURCE}
+        ${NCR2_FACTORY_SLOT_CLOCK_SOURCE}
         PROPERTIES COMPILE_OPTIONS "-w"
     )
     ncr2_firmware_target(

firmware/README.md

@@ -62,7 +62,9 @@ Implemented:
   preserved vectors, copies the engine to ITCM, and reproduces the stock
   handoff without embedding factory bytes.
 - an opt-in source application linked to the recovered factory ITCM slot ABI,
-  with a strict post-link checker and paired OEM-DFU/Metal-restore packer.
+  with a strict post-link checker and paired OEM-DFU/Metal-restore packer;
+- an opt-in factory-compatible SAI1/eDMA passthrough with DTCM ping-pong
+  buffers, a weak source DSP hook, and offline register/ISR emulation.
 
 Not implemented:
 
@@ -73,7 +75,9 @@ Not implemented:
   and watchdog confirmation/rollback;
 - source-controlled MPU/data-cache policy for the full open application;
 - source SEMC initialization;
-- GPIO diagnostics or audio.
+- physical validation of the source audio path and analog mute/bypass
+  sequencing;
+- GPIO diagnostics.
 
 ## Build
 
@@ -233,19 +237,23 @@ audit and corrected metadata layout.
 ## Build the source factory-slot application
 
 This transition target runs source-owned code through the still-recoverable
-factory launcher. It is excluded from the default build and currently has no
-audio or target-visible diagnostics:
+factory launcher. It is excluded from the default build. Its audio path is a
+second explicit opt-in because analog mute/bypass control is not yet known:
 
 ```sh
 cmake -S firmware -B build/factory-slot -G Ninja \
   -DCMAKE_MAKE_PROGRAM="$(command -v ninja)" \
   -DCMAKE_TOOLCHAIN_FILE="$PWD/firmware/cmake/arm-none-eabi-toolchain.cmake" \
   -DCMAKE_BUILD_TYPE=Release \
   -DNCR2_BUILD_FACTORY_SLOT_APP=ON \
+  -DNCR2_FACTORY_SLOT_AUDIO_PASSTHROUGH=ON \
   -DNCR2_MCUX_SDK_ROOT="$PWD/third_party/mcux-sdk-workspace"
 cmake --build build/factory-slot --target ncr2_factory_slot_app
 python3 tools/check_factory_slot.py \
   build/factory-slot/ncr2_factory_slot_app.elf
+PYTHONPATH=/path/to/unicorn \
+python3 tools/emulate_source_audio.py \
+  build/factory-slot/ncr2_factory_slot_app.elf
 ```
 
 When the private verified dump is present, an offline BINA plus a paired
@@ -259,8 +267,9 @@ python3 tools/nux_dfu.py make-factory-slot \
   build/factory-slot/metal-restore.bina
 ```
 
-Do not stream the source package yet. It is a structurally valid launch image,
-not a useful or approved pedal image. See
+Do not stream the source package yet. It is a structurally valid digital
+passthrough image, but it is not approved until analog mute/bypass sequencing
+has been recovered and reviewed. See
 [FACTORY_SLOT_APP.md](../docs/hardware/FACTORY_SLOT_APP.md).
 
 ## Build a guarded offline full image

firmware/factory_slot/include/factory_audio.h

@@ -0,0 +1,48 @@
+#ifndef NCR2_FACTORY_AUDIO_H
+#define NCR2_FACTORY_AUDIO_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+enum
+{
+    NCR2_FACTORY_AUDIO_OK = 0,
+    NCR2_FACTORY_AUDIO_DISABLED = 1,
+    NCR2_FACTORY_AUDIO_BAD_STATE = 2,
+};
+
+enum
+{
+    NCR2_FACTORY_AUDIO_SAMPLE_RATE_HZ = 48000,
+    NCR2_FACTORY_AUDIO_SLOTS = 4,
+    NCR2_FACTORY_AUDIO_FRAMES_PER_BLOCK = 8,
+    NCR2_FACTORY_AUDIO_WORDS_PER_BLOCK =
+        NCR2_FACTORY_AUDIO_SLOTS *
+        NCR2_FACTORY_AUDIO_FRAMES_PER_BLOCK,
+};
+
+typedef struct ncr2_factory_audio_counters
+{
+    volatile uint32_t rx_blocks;
+    volatile uint32_t copied_blocks;
+    volatile uint32_t unexpected_interrupts;
+} ncr2_factory_audio_counters_t;
+
+extern ncr2_factory_audio_counters_t
+    g_ncr2_factory_audio_counters;
+
+uint16_t ncr2_factory_audio_init(void);
+
+/*
+ * The weak default implementation copies all four factory slots unchanged.
+ * A source DSP runtime can override this symbol without changing the ISR or
+ * the hardware contract.
+ */
+void ncr2_factory_audio_process_block(
+    const int32_t *input,
+    int32_t *output,
+    size_t frames);
+
+void DMA0_DMA16_IRQHandler(void);
+
+#endif