### CMakeLists.txt: Project Configuration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Example CMakeLists.txt file for an XMOS USB Audio project. It defines build configurations and enables various interfaces.

```cmake
cmake_minimum_required(VERSION 3.10)

project("app_usb_aud_xk_316_mc")

# Add XMOS specific CMake modules
include(${CMAKE_CURRENT_LIST_DIR}/xcore_cmake/xcore.cmake)

# Define the target architecture and core type
xcore_target_arch("xcore")
xcore_target_cpu("xcore")

# Define the application name
xcore_application("app_usb_aud_xk_316_mc")

# Add source directories
xcore_add_source_dir("src/core")
xcore_add_source_dir("src/extensions")

# Link against the USB Audio library
target_link_libraries("app_usb_aud_xk_316_mc" "xua")

# Example of enabling an interface via a build-time define
# if(ENABLE_SPDIF)
#   target_compile_definitions("app_usb_aud_xk_316_mc" PRIVATE "SPDIF_TX_ENABLE")
# endif

# Other build configurations would be defined here...
```

--------------------------------

### XMOS USB Audio: Custom Application Setup

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_modification.rst

Steps to create a custom codebase by copying a reference application, setting the target hardware, updating configuration, and adding custom code.

```cmake
set(APP_HW_TARGET "<your_target_platform>.xn")
```

--------------------------------

### CMake Project Setup

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Initializes the CMake build system, includes common XMOS modules, and defines the project name. It sets the minimum required CMake version and includes external dependencies.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_usb_aud_xk_evk_xu316_extrai2s)
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/xmos/sw_usb_audio/blob/develop/tests/README.rst

Installs the necessary Python modules for the project using pip. It is recommended to use a Python virtual environment for this installation.

```shell
pip install -r requirements.txt
```

--------------------------------

### CMake Project Setup and Base Flags

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_216_mc/CMakeLists.txt

Initializes the CMake build system, sets the project name, defines the target hardware, and establishes common compiler flags for the SW USB Audio application. It includes necessary common modules and sets up build-specific variables.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_usb_aud_xk_216_mc)

set(APP_HW_TARGET xk-audio-216-mc.xn)
include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)
set(APP_PCA_ENABLE ON)
set(SW_USB_AUDIO_FLAGS ${EXTRA_BUILD_FLAGS} -O3
                                            -report
                                            -lquadflash
                                            -g
                                            -fxscope
                                            -DBOARD_SUPPORT_BOARD=XK_AUDIO_216_MC_AB
                                            -DADAT_TX_USE_SHARED_BUFF=1)
```

--------------------------------

### xua_conf.h: Channel Count and Arrangement

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Defines for the number of audio channels for input and output, and their arrangement. Channel indexing starts from 0.

```c
/* Defines relating to channel count */
#if !defined(XUA_NUM_ANALOG_CHAN_IN) || !defined(XUA_NUM_ANALOG_CHAN_OUT)
#if defined(XUA_NUM_ANALOG_CHAN_IN_DEFAULT)
#define XUA_NUM_ANALOG_CHAN_IN XUA_NUM_ANALOG_CHAN_IN_DEFAULT
#else
#define XUA_NUM_ANALOG_CHAN_IN 8
#endif
#if defined(XUA_NUM_ANALOG_CHAN_OUT_DEFAULT)
#define XUA_NUM_ANALOG_CHAN_OUT XUA_NUM_ANALOG_CHAN_OUT_DEFAULT
#else
#define XUA_NUM_ANALOG_CHAN_OUT 8
#endif
#endif

/* Defines relating to channel */
```

--------------------------------

### XMOS USB Audio Initialization and Configuration Functions

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_316_mc.rst

Details key C functions involved in initializing and configuring the audio hardware. These functions manage I2C master setup, hardware power-up, and stream format adjustments.

```apidoc
Function: xk_audio_316_mc_ab_board_setup()
  - Purpose: Performs required port operations to enable audio hardware on the platform.
  - Called by: board_setup() during application initialization.

Function: xk_audio_316_mc_ab_i2c_master()
  - Purpose: Starts the I2C master task, enabling remote configuration of audio hardware over I2C.
  - Called by: After board_setup() during initialization.
  - Dependency: Required due to IO arrangement of the XK-AUDIO-316-MC board.

Function: AudioHwInit() (Wrapper)
  - Purpose: Powers up and initializes the audio hardware, preparing it for configuration.
  - Implementation: Calls lib_board_support function xk_audio_316_mc_ab_AudioHwInit().

Function: AudioHwConfig() (Wrapper)
  - Purpose: Configures the audio hardware post-initialization, typically on sample rate or stream format changes.
  - Implementation: Calls lib_board_support function xk_audio_316_mc_ab_AudioHwConfig().

Configuration Structure:
  - Type: xk_audio_316_mc_ab_config_t
  - Usage: Passed to xk_audio_316_mc_ab_board_setup(), xk_audio_316_mc_ab_AudioHwInit(), and xk_audio_316_mc_ab_AudioHwConfig() to set hardware parameters.
```

--------------------------------

### lib_xcore_math API Changes

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Details changes to the lib_xcore_math library, including documentation updates, renaming of examples, inclusion of a missing header, and removal of a submodule.

```APIDOC
lib_xcore_math API Changes (v2.3.0 -> v2.4.0):

Documentation and Examples:
  - CHANGED: Documentation updated.
  - CHANGED: Renamed examples to app_.

Header Inclusion Fix:
  - FIXED: Added missing xcore_math.h.

Submodule Removal:
  - REMOVED: xmos_cmake_toolchain submodule.
```

--------------------------------

### lib_board_support API Additions

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Details new features and support added to the lib_board_support library, including PHY address handling, power-down capabilities, core voltage control, and Ethernet PHY setup for specific XMOS boards.

```APIDOC
lib_board_support API Additions (v1.1.1 -> v1.3.0):

PHY Address Support for XK-EVK-XE216:
  - ADDED: Support for PHY address being either 0x1 or 0x4 for XK-EVK-XE216.

Power-Down Support for XK-AUDIO-316-MC:
  - ADDED: Power-down support for xk-audio-316-mc audio hardware.

Xcore Core Voltage Control API:
  - ADDED: xcore core voltage control API for xk-audio-316-mc.

Parameter Change in get_port_timings():
  - CHANGED: Replaced phy_idx parameter in get_port_timings() with enum, port_timing_index_t.

Documentation Note for XK_ETH_XU316_DUAL_100M:
  - ADDED: Note in documentation about XK_ETH_XU316_DUAL_100M being currently unreleased.

Fix for get_timings() in xk_eth_xu316_dual_100m:
  - FIXED: Second PHY index for get_timings() in xk_eth_xu316_dual_100m.

Ethernet PHY Setup Support:
  - ADDED: Support for xk_evk_xe216 board ethernet PHY setup.
  - ADDED: Initial support for xk_eth_xu316_dual_100m board ethernet PHY setup.

Fix for USB Issues in xk_evk_xu316_AudioHwInit():
  - FIXED: Long delay in xk_evk_xu316_AudioHwInit() causing USB issues.
```

--------------------------------

### Set Compiler Flags for Audio Class 1 Sync Mode

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_316_mc/CMakeLists.txt

Configures compiler flags for Audio Class 1, enabling synchronous mode and specifying I2S master with 2 inputs and 2 outputs. This setup is for USB audio devices operating under the Audio Class 1 specification.

```cmake
set(APP_COMPILER_FLAGS_1SMi2o2xxxxxx ${SW_USB_AUDIO_FLAGS}     -DAUDIO_CLASS=1
                                                               -DXUA_SYNCMODE=XUA_SYNCMODE_SYNC)
```

--------------------------------

### audiohw.xc: Hardware Initialization and Configuration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

XMOS C code implementing user functions for hardware initialization and configuration within the USB Audio framework.

```xcore
#include <xua_api.h>

/*
 * AudioHwInit is called by lib_xua on startup.
 * It is used to initialise the audio hardware.
 */
void AudioHwInit(void)
{
    // Initialize audio CODEC, clocks, etc.
    // Example: Configure I2S interface for audio output
    // i2s_config_t i2s_out_cfg = {
    //     .sample_rate = 48000,
    //     .bits_per_sample = 24,
    //     .num_channels = 2
    // };
    // i2s_init(I2S_OUT_PORT, &i2s_out_cfg);
}

/*
 * AudioHwConfig is called by lib_xua when the sample rate or channel configuration changes.
 * It is used to reconfigure the audio hardware.
 */
void AudioHwConfig(void)
{
    // Reconfigure audio hardware based on new settings
    // Example: Update I2S sample rate
    // i2s_set_sample_rate(I2S_OUT_PORT, xua_get_sample_rate());
}

/*
 * Other user functions like AudioHwStart, AudioHwStop, etc. can also be overridden.
 */
```

--------------------------------

### lib_mic_array API Changes

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Details changes to the lib_mic_array library, including documentation updates, renaming of examples, and renaming of the scripts directory.

```APIDOC
lib_mic_array API Changes (v5.4.0 -> v5.5.0):

Documentation and Examples:
  - CHANGED: Documentation updated.
  - CHANGED: Renamed examples to app_.

Directory Renaming:
  - CHANGED: Renamed the scripts/ directory to python/.
```

--------------------------------

### Build Firmware with XCommon CMake

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/quick.rst

Instructions for building the USB Audio firmware using the XCommon CMake build system. This process involves configuring the build environment and then executing the build command.

```bash
cmake -G "Unix Makefiles" -B build
xmake -j -C build
```

--------------------------------

### Audio Hardware Initialization and Configuration Functions

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_216_mc.rst

Details the core functions for initializing and configuring the audio hardware. These functions rely on the lib_board_support library.

```APIDOC
xk_audio_216_mc_ab_AudioHwInit()
  - Initializes the audio hardware, powering it up and preparing it for configuration.
  - Called during system initialization.
  - Relies on lib_board_support's xk_audio_216_mc_ab_AudioHwInit().

xk_audio_216_mc_ab_AudioHwConfig()
  - Configures the audio hardware after initialization, typically when sample rate or stream format changes.
  - Called at various points during runtime.
  - Relies on lib_board_support's xk_audio_216_mc_ab_AudioHwConfig().
  - Takes a config structure (xk_audio_216_mc_ab_config_t) as input.

Dependencies:
  - lib_board_support
  - lib_i2c (indirectly via lib_board_support)

Related Functions:
  - AudioHwInit() (wrapper function)
  - AudioHwConfig() (wrapper function)
```

--------------------------------

### Configure XMOS SW USB Audio Project (CMake)

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316/CMakeLists.txt

This CMake script initializes the build environment for the XMOS SW USB Audio project. It sets the project name, hardware target, includes necessary common modules and dependencies, and defines various compiler flags for optimization, debugging, and specific hardware features. It concludes by registering the application for the XMOS build system.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_usb_aud_xk_evk_xu316)

set(APP_HW_TARGET XK-EVK-XU316)
include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)
set(APP_PCA_ENABLE ON)
set(SW_USB_AUDIO_FLAGS ${EXTRA_BUILD_FLAGS} -fcomment-asm
                                            -Wall
                                            -O3
                                            -report
                                            -lquadflash
                                            -g
                                            -fxscope
                                            -DBOARD_SUPPORT_BOARD=XK_EVK_XU316
                                            -DADAT_TX_USE_SHARED_BUFF=1
                                            -DXSCOPE)

set(APP_COMPILER_FLAGS_1AMi2o2xxxxxx ${SW_USB_AUDIO_FLAGS} -DAUDIO_CLASS=1)

set(APP_COMPILER_FLAGS_2AMi2o2xxxxxx ${SW_USB_AUDIO_FLAGS})

include(${CMAKE_CURRENT_LIST_DIR}/configs_test.cmake)

set(APP_INCLUDES src src/core src/extensions)
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)

XMOS_REGISTER_APP()
```

--------------------------------

### xua_conf.h: Basic Functionality Defines

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Configuration header file defining basic functionality for the USB Audio framework. It uses #ifndef guards to allow overrides from CMakeLists.txt.

```c
#define XUA_CONF_H_INCLUDED

/* Defines relating to basic functionality */
#if !defined(XUA_NUM_USB_CHAN_IN) || !defined(XUA_NUM_USB_CHAN_OUT)
#if defined(XUA_NUM_USB_CHAN_IN_DEFAULT)
#define XUA_NUM_USB_CHAN_IN XUA_NUM_USB_CHAN_IN_DEFAULT
#else
#define XUA_NUM_USB_CHAN_IN 8
#endif
#if defined(XUA_NUM_USB_CHAN_OUT_DEFAULT)
#define XUA_NUM_USB_CHAN_OUT XUA_NUM_USB_CHAN_OUT_DEFAULT
#else
#define XUA_NUM_USB_CHAN_OUT 8
#endif
#endif

/* Defines relating to channel count */
```

--------------------------------

### Main CMakeLists.txt for SW USB Audio

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CMakeLists.txt

This CMakeLists.txt file configures the main project for XMOS USB Audio applications. It sets the minimum required CMake version, includes common XMOS build utilities from an environment path, defines the project name, and adds subdirectories for different audio application configurations.

```cmake
cmake_minimum_required(VERSION 3.21)\ninclude($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)\nproject(sw_usb_audio)\n\nadd_subdirectory(app_usb_aud_xk_316_mc)\nadd_subdirectory(app_usb_aud_xk_216_mc)\nadd_subdirectory(app_usb_aud_xk_evk_xu316)\nadd_subdirectory(app_usb_aud_xk_evk_xu316_extrai2s)\n
```

--------------------------------

### Dependency: sc_i2c Module Updates and Fixes

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Details changes and fixes for the sc_i2c library, including version updates and improvements to the module_i2c_simple and module_i2c_shared components. Fixes address ACK behavior, repeated starts, and shared bus access.

```text
sc_i2c: 2.2.1rc0 -> 2.3.0beta1
  + module_i2c_simple fixed to ACK correctly during multi-byte reads (all but the final byte will be now be ACKd)
  + module_i2c_simple can now be built with support to send repeated starts and retry reads and writes NACKd by slave
  + module_i2c_shared added to allow multiple logical cores to safely share a single I2C bus
  + Removed readreg() function from single_port module since it was not safe
```

--------------------------------

### Configure Project with CMake

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

This command initiates the build system configuration process using CMake. It generates Makefiles and other build-related files in a specified build directory, preparing the project for compilation.

```shell
cmake -G "Unix Makefiles" -B build
```

--------------------------------

### Set Compiler Flags for 96kHz Sample Rate and ADAT/S/PDIF

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_316_mc/CMakeLists.txt

Defines compiler flags for USB audio, limiting the sample rate to 96kHz and enabling ADAT and S/PDIF interfaces. This configuration is suitable for specific audio hardware setups requiring these digital audio interfaces.

```cmake
set(APP_COMPILER_FLAGS_2AMi18o18mssaax ${SW_USB_AUDIO_FLAGS}   -DMIDI=1
                                                               -DXUA_ADAT_RX_EN=1
                                                               -DXUA_ADAT_TX_EN=1
                                                               -DXUA_SPDIF_TX_EN=1
                                                               -DXUA_SPDIF_RX_EN=1
                                                               -DMAX_FREQ=96000)
```

--------------------------------

### xua_conf.h: Feature Placement on Tiles

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Specifies which XMOS tiles different interfaces (e.g., USB, S/PDIF) should be placed on, crucial for multi-tile architectures.

```c
/* Defines relating to audio frequencies */
#if !defined(XUA_USB_TILE)
#define XUA_USB_TILE 0
#endif

#if !defined(XUA_SPDIF_TILE)
#define XUA_SPDIF_TILE 0
#endif

/* Defines relating to feature placement */
```

--------------------------------

### XMOS USB Audio Framework Core - Main Functionality

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

This section describes the core USB audio task, USB interface thread (XUD_Main()), and audio buffering tasks within the XMOS USB Audio framework. It highlights the parallel execution of these critical components.

```XMOS C
/* Core USB audio task
   (This is a placeholder for the actual code block content)
*/
XUA_USB_EN
```

```XMOS C
/* USB interface core
   (This is a placeholder for the actual code block content)
*/;
```

```XMOS C
/* Endpoint & audio buffering
   (This is a placeholder for the actual code block content)
*/
//:
```

```XMOS C
/* Audio I/O task
   (This is a placeholder for the actual code block content)
*/
//:
```

```XMOS C
/* MIDI core */
   (This is a placeholder for the actual code block content)
#endif
```

--------------------------------

### sc_xud Version 2.4.0 Changes

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Details changes in sc_xud version 2.4.0, focusing on resolutions for intermittent initialization issues, SETUP transaction data CRC checks, RxError line handling, isochronous IN endpoint behavior, short packet reception, and DATA PID reset in ClearStallByAddr().

```release-notes
    - sc_xud: 2.3.2rc0 -> 2.4.0beta0

      + RESOLVED:   Intermittent initialisation issues with xCORE-200
      + RESOLVED:   SETUP transaction data CRC not properly checked
      + RESOLVED:   RxError line from phy handled
      + RESOLVED:   Isochronous IN endpoints now send an 0-length packet if not
        ready rather than an (invalid) NAK.
      + RESOLVED:   Receive of short packets sometimes prematurely ended
      + RESOLVED:   Data PID not reset to DATA0 in ClearStallByAddr() (used on
        ClearFeature(HALT) request from host) (#17092)
```

--------------------------------

### Build All Supported Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

This command executes the build process for all defined configurations using the xmake build tool. It reads the Makefiles generated by CMake and compiles the project accordingly.

```shell
xmake -C build
```

--------------------------------

### Basic Build Configuration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

Configures and builds the project using default settings, typically including only fully tested configurations. This involves running CMake to generate build files and then xmake to compile the project.

```shell
cmake -G "Unix Makefiles" -B build
xmake -C build
```

--------------------------------

### Base CMake Configuration and Common Flags

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_316_mc/CMakeLists.txt

Sets up the minimum CMake version, includes common XMOS modules, defines application include paths, and establishes common build flags for the USB audio project. This includes optimization levels, reporting, linking, debugging, and specific board support flags.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

set(APP_INCLUDES src src/core src/extensions)
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)
include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(APP_PCA_ENABLE ON)

set(SW_USB_AUDIO_FLAGS ${EXTRA_BUILD_FLAGS} -O3
                                            -report
                                            -lquadflash
                                            -g
                                            -fxscope
                                            -DBOARD_SUPPORT_BOARD=XK_AUDIO_316_MC_AB
                                            -DADAT_TX_USE_SHARED_BUFF=1)
```

--------------------------------

### Include Paths and Sandbox Directory

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Configures the include paths for the project's source files and defines the root directory for XMOS sandbox environments. This helps the compiler locate necessary header files.

```cmake
set(APP_INCLUDES src src/core src/extensions)
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)
```

--------------------------------

### Hardware Target and Dependencies

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Specifies the hardware target for the application and includes necessary dependency files. This ensures the build is configured for the correct hardware platform.

```cmake
set(APP_HW_TARGET XK-EVK-XU316)
include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)
```

--------------------------------

### Running Pytest Tests

Source: https://github.com/xmos/sw_usb_audio/blob/develop/tests/README.rst

Demonstrates how to execute tests using pytest. This includes selecting test levels (smoke, nightly, weekend), filtering tests by keywords, and specifying XTAG IDs for connected hardware.

```shell
pytest --level nightly
```

```shell
pytest -k "analogue_output and 2AMi10o10xssxxx"
```

```shell
pytest -o xk_216_mc=RdZ15gCf
```

--------------------------------

### XMOS USB Audio Build Configuration Naming Scheme

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_316_mc.rst

Explains the naming convention used for build configurations in the CMakeLists.txt file, allowing customization of audio class, sync mode, I2S role, and various input/output features.

```apidoc
Build Configuration Naming Scheme:

Format: [AudioClass][SyncMode][I2SRole][Input][Output][MIDI][SPDIF_In][SPDIF_Out][ADAT_In][ADAT_Out][DSD_Out]

- Audio Class:
  - 1: Audio Class 1.0
  - 2: Audio Class 2.0
- USB Sync Mode:
  - A: Asynchronous
  - S: Synchronous
- I²S Role:
  - S: Slave
  - M: Master
- Input:
  - i<channels>: Enabled with specified channel count (e.g., i10 for 10 channels)
  - x: Disabled
- Output:
  - i<channels>: Enabled with specified channel count (e.g., i10 for 10 channels)
  - x: Disabled
- MIDI:
  - m: Enabled
  - x: Disabled
- S/PDIF input:
  - s: Enabled
  - x: Disabled
- S/PDIF output:
  - s: Enabled
  - x: Disabled
- ADAT input:
  - a: Enabled
  - x: Disabled
- ADAT output:
  - a: Enabled
  - x: Disabled
- DSD output:
  - d: Enabled
  - x: Disabled

Optional Appends:
- tdm: Indicates TDM I²S mode.

Example:
`2AMi10o10xsxxxx` signifies: Audio Class 2.0, Asynchronous sync mode, I²S Master role, Input enabled (10 channels), Output enabled (10 channels), MIDI disabled, S/PDIF input enabled, S/PDIF output disabled, ADAT input disabled, ADAT output disabled, DSD output disabled.
```

--------------------------------

### xua_conf.h: USB Descriptor Information

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Defines general USB IDs and strings, typically set for a reference design but customizable per manufacturer.

```c
/* Defines relating to feature placement */
#if !defined(XUA_USB_VID)
#define XUA_USB_VID 0x20B1
#endif

#if !defined(XUA_USB_PID)
#define XUA_USB_PID 0x0001
#endif

#if !defined(XUA_USB_MANUFACTURER_STRING)
#define XUA_USB_MANUFACTURER_STRING "XMOS"
#endif

#if !defined(XUA_USB_PRODUCT_STRING)
#define XUA_USB_PRODUCT_STRING "USB Audio"
#endif

/* Defines relating to USB descriptor */
```

--------------------------------

### Run Compiled Firmware

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/quick.rst

Command to execute a compiled firmware binary on the target XMOS device. This command assumes the binary is located in the standard output directory after a successful build.

```bash
xrun ./bin/2AMi10o10xssxxx/app_usb_aud_xk_316_mc_2AMi10o10xssxxx.xe
```

--------------------------------

### Configuration Includes and App Registration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_216_mc/CMakeLists.txt

Includes additional CMake configuration files for partial, build, and test settings. It also sets the include paths for the source code and registers the application with the XMOS build system.

```cmake
include(${CMAKE_CURRENT_LIST_DIR}/configs_partial.cmake)
include(${CMAKE_CURRENT_LIST_DIR}/configs_build.cmake)
include(${CMAKE_CURRENT_LIST_DIR}/configs_test.cmake)

set(APP_INCLUDES src src/core src/extensions)
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)

XMOS_REGISTER_APP()
```

--------------------------------

### Standard Build Configurations (Audio Class 2)

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_316_mc/CMakeLists.txt

Defines standard build configurations for Audio Class 2.0 devices, covering various combinations of I2S modes (Master/Slave), channel counts, and features like Mixer, TDM, MIDI, SPDIF, and ADAT. Each configuration sets specific compiler preprocessor definitions.

```cmake
project(app_usb_aud_xk_316_mc)
set(APP_HW_TARGET xk-audio-316-mc.xn)


# Build config naming scheme:
#
# Audio Class:   1 or 2
# Sync Mode      A(sync) or S(ync)
# I2S            M(aster) or S(lave)
# Input          enabled: i (channelcount)
# Output         enabled: o (channelcount)
# MIDI           enabled: m, disabled: x
# SPDIF in       enabled: s, disabled: x
# SPDIF out      enabled: s, disabled: x
# ADAT in        enabled: a, disabled: x
# ADAT out       enabled: a, disabled: x
# DSD out        enabled: d, disabled: x
#
# e.g. 2AMi10o10xxsxxx: Audio class 2.0, Asynchronous, I2S Master, input and output enabled (10 channels each), no MIDI, SPDIF output, no SPDIF input, no ADAT
#
# Additional tags may be added to the end of the build config name to indicate special features or configurations.

#
# Tested build configs
#

# Audio Class 2, Async, I2S Master, 8xInput, 8xOutput
set(APP_COMPILER_FLAGS_2AMi8o8xxxxxx ${SW_USB_AUDIO_FLAGS})

# Audio Class 2, Async, I2S Master, 8xInput, 8xOutput, Mixer
set(APP_COMPILER_FLAGS_2AMi8o8xxxxxx_mix8 ${SW_USB_AUDIO_FLAGS}     -DMAX_MIX_COUNT=8)

# Audio Class 2, Async, I2S Master, 8xInput, 8xOutput, TDM
# Note, limited to 96kHz sample rate due to TDM limitations
set(APP_COMPILER_FLAGS_2AMi8o8xxxxxx_tdm8 ${SW_USB_AUDIO_FLAGS}     -DXUA_PCM_FORMAT=XUA_PCM_FORMAT_TDM
                                                                    -DMAX_FREQ=96000)
# Audio Class 2, Async, I2S Slave, 8xInput, 8xOutput, TDM
# Note, limited to 96kHz sample rate due to TDM limitations
set(APP_COMPILER_FLAGS_2ASi8o8xxxxxx_tdm8 ${SW_USB_AUDIO_FLAGS} -DCODEC_MASTER=1
                                                                -DXUA_PCM_FORMAT=XUA_PCM_FORMAT_TDM
                                                                -DMAX_FREQ=96000)
# Audio Class 2, Async, I2S Master, 8xInput, 8xOutput, MIDI
set(APP_COMPILER_FLAGS_2AMi8o8mxxxxx ${SW_USB_AUDIO_FLAGS}      -DMIDI=1)

# Audio Class 2, Async, I2S Master, 10xInput, 10xOutput, S/PDIF Tx, S/PDIF Rx
set(APP_COMPILER_FLAGS_2AMi10o10xssxxx ${SW_USB_AUDIO_FLAGS}   -DXUA_SPDIF_TX_EN=1
                                                               -DXUA_SPDIF_RX_EN=1)
# Audio Class 2, Async, I2S Master, 16xInput, 16xOutput, ADAT Tx, ADAT Rx
set(APP_COMPILER_FLAGS_2AMi16o16xxxaax ${SW_USB_AUDIO_FLAGS}   -DXUA_ADAT_RX_EN=1
                                                               -DXUA_ADAT_TX_EN=1)

# Audio Class 2, Async, I2S Master, 16xInput, 16xOutput, ADAT Tx, ADAT Rx

```

--------------------------------

### Core Compiler Flags

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Defines the primary set of compiler flags for the SW USB Audio project. These flags include optimization levels, reporting, linking to quadflash, debugging, XTAG support, and board-specific definitions.

```cmake
set(SW_USB_AUDIO_FLAGS ${EXTRA_BUILD_FLAGS} -fcomment-asm
                                            -Wall
                                            -O3
                                            -report
                                            -lquadflash
                                            -g
                                            -fxscope
                                            -DBOARD_SUPPORT_BOARD=XK_EVK_XU316
                                            -DADAT_TX_USE_SHARED_BUFF=1
                                            -DXSCOPE)
```

--------------------------------

### Flash Application Binary to XMOS Device

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/quick.rst

This command flashes an application binary onto the target XMOS device's boot flash. It requires the `xflash` tool and the path to the executable file. After flashing, the device automatically reboots and runs the new application.

```bash
xflash ./bin/2AMi10o10xssxxx/app_usb_aud_xk_316_mc_2AMi10o10xssxxx.xe
```

--------------------------------

### Build with Build Tested Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

Configures and builds the project including fully tested, partially tested, and build-tested configurations. Setting BUILD_TESTED_CONFIGS to 1 implicitly enables PARTIAL_TESTED_CONFIGS.

```shell
cmake -G "Unix Makefiles" -B build -DBUILD_TESTED_CONFIGS=1
xmake -C build
```

--------------------------------

### Python Project Dependencies

Source: https://github.com/xmos/sw_usb_audio/blob/develop/tests/requirements.txt

Lists the required Python packages and their specific versions for the /xmos/sw_usb_audio project. It includes standard libraries, development tools, and custom local packages, ensuring reproducible environments.

```python
# python_version 3.12.1
# pip_version 24.2

pytest==8.3.2
python-rtmidi==1.5.8
mido==1.3.2
pyyaml==6.0.2

-e ./../../hardware_test_tools
```

--------------------------------

### Application Registration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Registers the current CMakeLists.txt as an application within the XMOS build system. This command is essential for the build process to recognize and compile the project.

```cmake
XMOS_REGISTER_APP()
```

--------------------------------

### Compiler Flags for Specific Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_216_mc/CMakeLists.txt

Defines specific compiler flags for various target configurations, building upon the base SW USB Audio flags. These flags enable features like SPDIF, ADAT, and MIDI for different hardware variants and audio capabilities.

```cmake
set(APP_COMPILER_FLAGS_2AMi10o10xssxxx ${SW_USB_AUDIO_FLAGS} -DXUA_SPDIF_TX_EN=1
                                                             -DXUA_SPDIF_RX_EN=1)
```

```cmake
set(APP_COMPILER_FLAGS_2ASi10o10xssxxx ${SW_USB_AUDIO_FLAGS} -DXUA_SPDIF_TX_EN=1
                                                             -DXUA_SPDIF_RX_EN=1
                                                             -DCODEC_MASTER=1)
```

```cmake
set(APP_COMPILER_FLAGS_2AMi8o10mxsxxx ${SW_USB_AUDIO_FLAGS} -DMIDI=1
                                                            -DXUA_SPDIF_TX_EN=1)
```

```cmake
set(APP_COMPILER_FLAGS_2AMi16o16xxxaax ${SW_USB_AUDIO_FLAGS} -DXUA_ADAT_RX_EN=1 -DXUA_ADAT_TX_EN=1)
```

```cmake
set(APP_COMPILER_FLAGS_2AMi18o18mssaax ${SW_USB_AUDIO_FLAGS} -DMIDI=1 -DXUA_ADAT_RX_EN=1 -DXUA_ADAT_TX_EN=1 -DXUA_SPDIF_TX_EN=1 -DXUA_SPDIF_RX_EN=1 -DMAX_FREQ=96000)
```

--------------------------------

### XK-AUDIO-316-MC Audio Hardware Configuration Structure

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_316_mc.rst

Defines the configuration structure for the XK-AUDIO-316-MC audio hardware. This structure is passed to initialization and configuration functions to set up audio parameters.

```c
static xk_audio_316_mc_ab_config_t
{
  // Configuration parameters for audio hardware
  // ... (details omitted for brevity, actual structure members would be here)
};
```

--------------------------------

### xua_conf.h: Channel Indexing and Offsets

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_app_tutorial.rst

Sets channel indices and offsets based on enabled audio interfaces. The offset for analogue channels is always 0.

```c
/* Defines relating to channel */
#if !defined(SPDIF_TX_INDEX)
#define SPDIF_TX_INDEX 0
#endif

/* Channel index of S/PDIF */
```

--------------------------------

### Build with Partially Tested Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

Configures and builds the project including both fully tested and partially tested configurations. This is achieved by setting the PARTIAL_TESTED_CONFIGS CMake variable to 1.

```shell
cmake -G "Unix Makefiles" -B build -DPARTIAL_TESTED_CONFIGS=1
xmake -C build
```

--------------------------------

### XMOS USB Audio: Customization Defines and Headers

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_modification.rst

Utilize defines like USER_MAIN_TASKS, USER_MAIN_DECLARATIONS, and USER_MAIN_GLOBALS, or optional header files (xua_conf_tasks.h, xua_conf_globals.h, xua_conf_declarations.h) for cleaner custom task integration.

```xc
#define USER_MAIN_TASKS
#define USER_MAIN_DECLARATIONS
#define USER_MAIN_GLOBALS
```

```xc
#include "xua_conf_tasks.h"
#include "xua_conf_globals.h"
#include "xua_conf_declarations.h"
```

--------------------------------

### XMOS xcore.ai Audio Board Hardware Configuration Functions

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_316_mc.rst

Provides an overview of key functions used for configuring the XMOS XU316 Multichannel Audio board. These functions are part of the lib_board_support library and handle I2C communication and audio hardware initialization.

```c
xk_audio_316_mc_ab_board_setup()
xk_audio_316_mc_ab_i2c_master()
xk_audio_316_mc_ab_AudioHwInit()
xk_audio_316_mc_ab_AudioHwConfig()
```

--------------------------------

### Audio Hardware Configuration Structure

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/app_216_mc.rst

Defines the configuration structure for the audio hardware on the XK-AUDIO-216-MC board. This structure is passed to initialization and configuration functions.

```c
static const xk_audio_216_mc_ab_config_t
{
  // Configuration parameters for audio hardware
  // ... (details omitted for brevity, but would include sample rate, channel config, etc.)
};
```

--------------------------------

### XMOS USB Audio Hardware Configuration Functions

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/api_user_functions.rst

Implement these functions to configure external audio hardware. They cover initialization, general configuration, mute/unmute control, and shutdown procedures for the audio subsystem.

```APIDOC
AudioHwInit()
  - Initializes external audio hardware.
  - Called during device startup.

AudioHwConfig(config_params)
  - Configures general audio hardware parameters.
  - Parameters:
    - config_params: Structure or values defining audio configuration.

AudioHwConfig_Mute()
  - Mutes the audio output.

AudioHwConfig_UnMute()
  - Unmutes the audio output.

AudioHwShutdown()
  - Shuts down external audio hardware.
  - Called during device shutdown.
```

--------------------------------

### Build a Specific Configuration

Source: https://github.com/xmos/sw_usb_audio/blob/develop/doc/rst/prog_build_configs.rst

This command builds a single, specific build configuration. After running CMake, you can use xmake with the configuration name to compile only that particular variant of the project.

```shell
xmake -C build 2AMi10o10xssxxx
```

--------------------------------

### Configuration Defines for Application Customization

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Defines for customizing application behavior, including user declarations for main functions and core additions, and product string definitions.

```xc
#define USER_MAIN_DECLARATIONS
#define USER_MAIN_CORES
#define PRODUCT_STR "XMOS USB Audio Device"
```

--------------------------------

### Specific Compiler Flags for Audio Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_evk_xu316_extrai2s/CMakeLists.txt

Sets compiler flags tailored for specific audio interface configurations, such as 1 analog input and 2 analog outputs, or 2 analog inputs and 2 analog outputs. These build upon the core flags.

```cmake
set(APP_COMPILER_FLAGS_1AMi2o2xxxxxx ${SW_USB_AUDIO_FLAGS} -DAUDIO_CLASS=1)
set(APP_COMPILER_FLAGS_2AMi2o2xxxxxx ${SW_USB_AUDIO_FLAGS})
```

--------------------------------

### Include Partially Tested Build Configurations

Source: https://github.com/xmos/sw_usb_audio/blob/develop/app_usb_aud_xk_316_mc/CMakeLists.txt

Includes CMake configuration files that contain partially tested build settings. This directive allows for the incorporation of specific, but not fully validated, build options into the project.

```cmake
include(${CMAKE_CURRENT_LIST_DIR}/configs_partial.cmake)
```

--------------------------------

### Added: PRODUCT_STR Define

Source: https://github.com/xmos/sw_usb_audio/blob/develop/CHANGELOG.rst

Introduces the PRODUCT_STR define for specifying product strings, which can be used for device identification.

```text
ADDED:      PRODUCT_STR define for Product Strings
```