diff --git a/examples/README.md b/examples/README.md index 1ef2b03..e11f094 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,31 +1,46 @@ -# usbd-uac2 Examples +Two example backends are provided, both based on the LPCXpresso55S28 demo board, using the onboard WM8904 DAC. -This repository contains example implementations of a USB Audio Class 2 (UAC2) device. +## LPC55S28 (LPCXpresso55S28) -Two example backends are provided, both based on the LPCXpresso55S28 demo board, using the onboard WM8904 DAC: +These examples work on the +(LPCXpresso55S28)[https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso55s28-development-board:LPC55S28-EVK] +development board. They use the onboard WM8904 codec, so don't require any +additional hardware for audio I/O. -- **Interrupt-driven example** (`lpc55s28-evk`) -- **DMA-based example** (`lpc55s28-evk-dma`) +They can be programmed and debugged using the CMSIS-DAP that's on the board, +though due to the security features you may need to reset into the DFU +bootloader first. +``` +cargo embed --release +``` -## Examples Overview +Enable logging with `DEFMT_LOG` when building, but beware that enabling defmt +logs can cause timing failures, and _must_ be drained by the host, as it is +blocking. + +They work on either USBFS or USBHS, but not both at the same time. The default +is USBHS. If you would like to run the example on USBFS, disable default +features and select USBFS: + +``` +cargo embed --release --no-default-features --features usbfs +``` ### Interrupt-driven (`lpc55s28-evk`) -Running at 32bit/48khz. It can't keep up at 96khz. Works on USBFS and USBHS. +Running at 32bit/48khz. Simultaneous input and output. Works on USBFS and USBHS. This is a minimal implementation intended to demonstrate the fundamental -structure of the class driver. It fills a `bbqueue` as data comes in from USB, -and drains it into the I2S FIFO in the I2S interrupt. This requires a lot of -time-critical CPU work managing buffers. Particularly, the USB peripheral driver -uses a lot of interrupt-free critical sections which can cause late interrupts -and underruns. +structure of the class driver. The architecture is not recommended for a production +device, but it does work reliably on the happy path. -This is intended primarily as a learning/reference implementation +This is intended primarily as a reference implementation to aid understanding of +the class driver. ### DMA-based (`lpc55s28-evk-dma`) -Running at 32bit/96khz. Works on USBFS and USBHS. +Running at 32bit/96khz. Output only. Works on USBFS and USBHS. A more realistic and robust implementation using DMA. It fills a static ring buffer as data comes in from USB, while the DMA chases it around the ring, @@ -39,10 +54,3 @@ edge cases, error conditions and so on you would want in a fully fleshed out implementation. Particularly, it behaves poorly in underrun, since the DMA will keep emitting from the ring regardless of whether the data is valid, which sounds terrible. - -## Running the Examples - -You can flash and run either example using `cargo embed`: - -```sh -cargo embed --release --example lpc55s28-evk --features usbfs