### Basic CMake Project Setup

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Initializes the CMake version, includes common XMOS build scripts, and sets the project name. This is a standard starting point for CMake projects.

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

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

### Basic CMake Project Setup

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_sync_clk_plugin/CMakeLists.txt

Initializes the CMake version, includes common modules, and defines the project name.

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

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

### Integrate S/PDIF Receive with ClockGen and AudioHub

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_spdif_rx.rst

Example showing the integration of SpdifReceive, clockGen, and XUA_AudioHub in a parallel block. This setup buffers S/PDIF samples and forwards them to the AudioHub thread.

```c
chan c_dig_rx;
streaming chan c_spdif_rx;

par
{
    SpdifReceive(..., c_spdif_rx, ...);

    clockGen(c_spdif_rx, ..., c_dig_rx, ...);

    XUA_AudioHub(..., c_dig_rx, ...);
}
```

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

### CMake Project Setup

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_control/CMakeLists.txt

Initializes the CMake build system, includes common modules, and defines the project name. Ensure XMOS_CMAKE_PATH is set in your environment.

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

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

### Configure lib_xua Build Options

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

Configure build time options for lib_xua by defining macros in a custom xua_conf.h header file. This example sets the output channel count and product string.

```c
#ifndef _XUA_CONF_H_
#define _XUA_CONF_H_

/* Output channel count */
#define XUA_NUM_USB_CHAN_OUT (2)

/* Product string */
#define XUA_PRODUCT_STR_A2 "My Product"

#endif
```

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

### Instantiate Advanced Mixer

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_mixer.rst

Example of instantiating the mixer task within a parallel execution block. Ensure all required channel ends are declared and passed as parameters.

```c
chan c_aud_0, c_aud_1, c_mix_ctl;

par
{
    XUA_Buffer(..., c_aud_0, ...);

    mixer(c_aud0, c_aud_1, c_mix_ctl);

    XUA_AudioHub(c_aud_1, ...);

    XUA_Endpoint0(..., c_mix_ctl, ...);
}
```

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

### CMake Minimum Version and Project Setup

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_i2s_loopback/CMakeLists.txt

Specifies the minimum required CMake version and sets up the project name. Includes common XMOS CMake modules.

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

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

### Run SPDIF TX and AudioHub Tasks

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_spdif_tx.rst

Run the S/PDIF transmitter task and the XUA_AudioHub task in parallel. Ensure port and clock setup is done before running tasks in a par statement if sharing resources.

```c
par
{
    while(1)
    {
        /* Run the S/PDIF transmitter task */
        spdif_tx(p_spdif_tx, c_spdif_tx);
    }

    /* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves as
     * a hub for all audio).
     * Note, since we are not using I2S we pass in null for LR and Bit
     * clock ports and the I2S dataline ports */
    XUA_AudioHub(c_aud, clk_audio_mclk, null, p_mclk_in, null, null,
        null, null, c_spdif_tx);
}
```

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

### CMake Minimum Required and Project Setup

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_decouple_in_underflow/CMakeLists.txt

Sets the minimum CMake version and defines the project name. Includes common CMake modules for XMOS projects.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Enabling Debug mode" FORCE)
project(test_decouple_in_underflow)
```

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

### Reading ADAT Component Output

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_adat_rx.rst

Example demonstrating how to read control and sample data from the ADAT component output. Samples are 24-bit values within 32-bit words.

```C
control = inuint(oChan);

  for(int i = 0; i < 8; i++)
  {
      sample[i] = inuint(oChan);
  }
```

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

### Run ADAT Transmitter Task

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_adat_tx.rst

Start the ADAT transmitter task, passing the communication channel and output port.

```c
adat_tx_port(c_adat_out, p_adat_tx);
```

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

### Add Global Variables via xua_conf_globals.h

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

Insert global variables into main.xc by creating an optional xua_conf_globals.h file in the project's source tree. This example declares an unsigned integer variable.

```c
unsigned my_global_var = 42;
```

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

### Declare Master Clock Inputs for Separate Tiles

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_core_hw.rst

When XUA_AudioHub and XUA_Buffer cores are on separate tiles, each requires its own master clock input port. This example shows declarations for both the audio I/O tile and the USB feedback tile.

```c
/* Master clock for the audio IO tile */
in port p_mclk_in                   = PORT_MCLK_IN;

/* Resources for USB feedback */
in port p_mclk_in_usb               = PORT_MCLK_IN_USB;  /* Extra master clock input for the USB tile */
```

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

### Declare Core Hardware Resources

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_core_hw.rst

Example declaration of essential hardware resources: a master clock input port, a port for master clock counting, and the master clock block itself. Ensure PORT_MCLK_IN and PORT_MCLK_COUNT are defined in your project's XN file.

```c
in port p_mclk_in        = PORT_MCLK_IN;
in port p_for_mclk_count = PORT_MCLK_COUNT;   /* Extra port for counting master clock ticks */
clock clk_audio_mclk     = on tile[0]: XS1_CLKBLK_5;   /* Master clock */
```

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

### Calculate Master Clock and S/MUX Setting

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_adat_tx.rst

Example code snippet for calculating the master clock multiplier and S/MUX setting based on sampling frequency. This is part of the initial communication from XUA_AudioHub to the ADAT transmitter.

```c
/* Calculate what master clock we should be using */
    int master_clock_mult = (int) (master_clock_freq / sample_freq);
    int smux_setting = 1;

    if (sample_freq >= 88200) {
        smux_setting = 2;
    }
    if (sample_freq >= 176400) {
        smux_setting = 4;
    }

    /* Calculate master clock to bit clock */
```

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

### Declare S/PDIF Clock Block

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_spdif_rx.rst

Declare the clock block for the S/PDIF receiver. Example uses XS1_CLKBLK_1.

```c
clock clk_spd_rx = XS1_CLKBLK_1;
```

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

### Run Core Components

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_core_comp.rst

Basic execution of core components including endpoint, buffering, and audio hub threads.

```c
par
    {
        /* Endpoint 0 thread from lib_xua */
        XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, ...);

        /* Buffering threads - handles audio data to/from EP's and gives/gets data to/from the audio I/O thread */
        /* Note, this spawns two threads */
        XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);

        /* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves as a hub for all audio) */
        XUA_AudioHub(c_aud, ...) ;
    }
```

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

### Initialize USB Device Layer (lib_xud)

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_core_comp.rst

Initializes the low-level USB device layer thread using XUD_Main. This is required for USB connectivity.

```c
/* Low level USB device layer thread */
on tile[1]: XUD_Main(c_ep_out, 2, c_ep_in, 2, c_sof, epTypeTableOut, epTypeTableIn, null, null, -1, XUD_SPEED_HS, XUD_PWR_SELF);
```

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

### I2S Only Audio Configuration

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Configures compiler flags for an I2S-only audio setup, disabling USB channels and setting the codec to master mode. This is suitable for direct audio codec connections.

```cmake
set(APP_COMPILER_FLAGS_i2s_only ${COMMON_FLAGS}
                                -DBCD_DEVICE=0x0101
                                -DNUM_USB_CHAN_IN=0
                                -DNUM_USB_CHAN_OUT=0
                                -DI2S_CHANS_ADC=8
                                -DI2S_CHANS_DAC=8
                                -DCODEC_MASTER=1)
```

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

### Display Audio Output Channel Map Sources

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_mixer.rst

Lists all available sources that can be mapped to device outputs. Helps in identifying indices for re-mapping.

```bash
./xmos_mixer --display-aud-channel-map-sources
```

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

### Include Headers and Declare Functions via xua_conf_globals.h

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

Use xua_conf_globals.h to include additional headers or declare function prototypes, making them available for custom code within main.xc.

```c
#include "my_header.h"
void my_function(int x);
```

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

### Instantiate S/PDIF Receiver

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_spdif_rx.rst

Instantiate the spdif_rx function on the appropriate tile. Pass the output channel, input port, clock block, and estimated sample frequency.

```c
spdif_rx(c_spdif_rx, p_spdif_rx, clk_spd_rx, 192000);
```

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

### Configure XUA_AudioHub with I²S/TDM Resources

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using_adv_i2s.rst

Pass the declared clock blocks and ports to the XUA_AudioHub task. This configures the audio IO and I²S interface.

```c
/* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves
 * as a hub for all audio) */

on tile[0]: XUA_AudioHub(c_aud, clk_audio_mclk, clk_audio_bclk, p_mclk_in,
    p_lrclk, p_bclk, p_i2s_dac, p_i2s_adc);
```

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

### Baseline Test Flags Definition

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Sets baseline compiler flags for test cases, defining standard USB and I2S channel counts. These flags provide a common starting point for various test scenarios.

```cmake
set(BASE_TEST_FLAGS -DNUM_USB_CHAN_IN=2
                    -DNUM_USB_CHAN_OUT=2
                    -DI2S_CHANS_ADC=2
                    -DI2S_CHANS_DAC=2)
```

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

### Hardware Target and Include Paths

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_sync_clk_plugin/CMakeLists.txt

Sets the target hardware for the application and specifies the source include directory.

```cmake
set(APP_HW_TARGET test_xs3_600.xn)

set(APP_INCLUDES src)
```

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

### PDM Mics user callback functions

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

Provides weak callback APIs for user code execution at PDM microphone initialization and after each PCM sample is received, useful for custom hardware initialization or post-processing.

```APIDOC
## xua_user_pdm_init

### Description
Callback function executed before PDM microphone initialization.

## xua_user_pdm_process

### Description
Callback function executed after each PCM sample is received.
```

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

### Display DAW Output To Host Channel Map

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_mixer.rst

Displays the mapping of DAW outputs to host channels. By default, these bypass the mixer.

```bash
./xmos_mixer --display-daw-channel-map
```

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

### Register Application

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_decouple_in_underflow/CMakeLists.txt

Registers the application with the XMOS build system.

```cmake
XMOS_REGISTER_APP()
```

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

### Application Configuration

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_unit_tests/CMakeLists.txt

Defines the application's hardware target, dependent modules, and include directories. These settings are crucial for linking and compiling the application correctly.

```cmake
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../..)

set(APP_HW_TARGET XK-EVK-XU316)
set(APP_DEPENDENT_MODULES "lib_xua"
                          "lib_unity")

set(APP_INCLUDES src)
```

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

### External audio hardware configuration functions

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

These functions allow for the optional configuration of external audio hardware. An implementation of AudioHwConfig() is typically required.

```APIDOC
## AudioHwInit

### Description
Initializes the audio hardware.

## AudioHwConfig

### Description
Configures the audio hardware.

## AudioHwConfig_Mute

### Description
Mutes the audio hardware.

## AudioHwConfig_UnMute

### Description
Unmutes the audio hardware.

## AudioHwShutdown

### Description
Shuts down the audio hardware.
```

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

### Add Custom Tasks with xua_conf_tasks.h

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

Include additional tasks to run in parallel with the main application by creating an 'xua_conf_tasks.h' file. Its contents are inserted into 'main.xc' after the main 'par' statement.

```c
on tile[1]: my_user_interface_task(c_usb_to_user_interface);
```

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

### Include xua.h Header

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

All lib_xua functions can be accessed via the xua.h header file. Include this in your C/C++ source files.

```c
#include <xua.h>
```

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

### Application Hardware Target and Sandbox Directory

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_decouple_in_underflow/CMakeLists.txt

Specifies the target hardware for the application and defines the root directory for the XMOS sandbox.

```cmake
set(APP_HW_TARGET XK-EVK-XU316)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../..)
```

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

### Include Dependencies

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_sim_tests/test_decouple_in_underflow/CMakeLists.txt

Includes necessary dependency files for the application and testing environment.

```cmake
include(${CMAKE_CURRENT_LIST_DIR}/../../../examples/deps.cmake)
include(${CMAKE_CURRENT_LIST_DIR}/../../test_deps.cmake)
```

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

### Setting Project Directories and Includes

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Defines the sandbox directory and application include paths. These variables are used to locate project files and source code.

```cmake
set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../..)

set(APP_HW_TARGET xk-audio-316-mc.xn)
include(${CMAKE_CURRENT_LIST_DIR}/../../../examples/deps.cmake)
set(APP_INCLUDES src)
```

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

### Include Directories and Library Linking

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_control/host/CMakeLists.txt

Specifies the include directories for the project, including the 'src' directory and libusb include paths. It then links the necessary libraries to the application.

```cmake
target_include_directories(${APP_NAME}
    PUBLIC
        src
        ${libusb-1.0_INCLUDE_DIRS}
)

target_link_libraries(${APP_NAME}
    PUBLIC
        ${LINK_LIBS})
```

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

### Enable DSD Playback

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/opt_dsd.rst

Enable DSD playback by setting the DSD_CHANS_DAC define to a non-zero value. Typically set to 2 for stereo output.

```c
#define DSD_CHANS_DAC 2
```

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

### Add Custom Declarations with xua_conf_declarations.h

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/using.rst

Define custom channels or interfaces for inter-task communication by creating an 'xua_conf_declarations.h' file. Its contents are inserted into 'main.xc' before the main 'par' statement.

```c
chan c_usb_to_user_interface;
```

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

### PDM Microphone Resource Initialization (DDR)

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_pdm.rst

Initializes PDM microphone resources for Double Data Rate (DDR) operation. This configuration is used when two microphones share a single clock pin, clocking on alternate edges. It specifies port mappings, clock frequencies, and clock block assignments.

```c
unsigned mClk = MCLK_48, pdmClk = 3072000;
        pdm_rx_resources_t pdm_res = PDM_RX_RESOURCES_DDR(
            PORT_MCLK_IN,
            PORT_PDM_CLK,
            PORT_PDM_DATA,
            mClk,
            pdmClk,
            XS1_CLKBLK_1,
            XS1_CLKBLK_2);
        mic_array_init(&pdm_res, NULL, mic_samp_rate);
```

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

### PDM Microphone Resource Initialization (SDR)

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_pdm.rst

Initializes PDM microphone resources for Single Data Rate (SDR) operation. This configuration is used when each microphone has its own clock pin. It specifies port mappings, clock frequencies, and clock block assignments.

```c
#else
        pdm_rx_resources_t pdm_res = PDM_RX_RESOURCES_SDR(
            PORT_MCLK_IN,
            PORT_PDM_CLK,
            PORT_PDM_DATA,
            mClk,
            pdmClk,
            XS1_CLKBLK_1);
    #endif
        mic_array_init(&pdm_res, NULL, mic_samp_rate);
```

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

### Project and Common Includes

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_unit_tests/CMakeLists.txt

Sets the minimum CMake version, includes common XMOS build scripts, and defines the project name. This is standard boilerplate for XMOS CMake projects.

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

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

### Display Audio Output Channel Map

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_mixer.rst

Shows the current mapping of device outputs to audio channels. Useful for understanding current routing.

```bash
./xmos_mixer --display-aud-channel-map
```

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

### Factory Test Configuration

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Combines common flags with baseline test flags and a specific device code for factory testing. This configuration is used for initial device verification.

```cmake
set(APP_COMPILER_FLAGS_factory ${COMMON_FLAGS}
                               ${BASE_TEST_FLAGS}
                               -DBCD_DEVICE=0x0001)
```

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

### Configure SPDIF TX Port

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/feat_spdif_tx.rst

Declare and configure a 1-bit output port for S/PDIF transmission. This port should be clocked from the master clock.

```c
buffered out port:32 p_spdif_tx = PORT_SPDIF_OUT;     /* SPDIF transmit port */
spdif_tx_port_config(p_spdif_tx, clk_audio_mclk, p_mclk_in, delay);
```

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

### i8o8 USB Audio Configuration

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Sets compiler flags for an 8-channel input and 8-channel output USB audio configuration. This includes device class definition and channel counts.

```cmake
set(APP_COMPILER_FLAGS_i8o8 ${COMMON_FLAGS}
                            -DBCD_DEVICE=0x0100
                            -DNUM_USB_CHAN_IN=8
                            -DNUM_USB_CHAN_OUT=8
                            -DI2S_CHANS_ADC=8
                            -DI2S_CHANS_DAC=8)
```

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

### Set Mixer Source using xmos_mixer

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_mixer.rst

Use this command to change the audio source for a specific mixer input. Ensure the mixer and input indices are correct for your device configuration.

```bash
./xmos_mixer --set-mixer-source 0 0 4
```

```bash
./xmos_mixer --set-mixer-source 0 1 5
```

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

### Audio stream start/stop functions

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

These functions can be optionally used to manage audio streams, potentially for muting lines.

```APIDOC
## UserAudioStreamState

### Description
Manages the state of audio streams.
```

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

### Define S/PDIF Input Port

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/opt_spdif_rx.rst

Declare the S/PDIF input port in the application XN file. This port must be a 1-bit port.

```xml
<Port Location="XS1_PORT_1A"  Name="PORT_SPDIF_IN"/>
```

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

### Receive PCM Samples from Mic Array

Source: https://github.com/xmos/lib_xua/blob/develop/doc/rst/sw_pdm.rst

Call this function within the main IO loop to receive PCM frames from the mic array. The interface is sample-based, so MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME must be 1.

```c
ma_frame_rx(mic_samps_base_addr, c_m2a, MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME, MIC_ARRAY_CONFIG_MIC_COUNT);
```

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

### HID Controls Configuration

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_dfu/CMakeLists.txt

Sets compiler flags for a configuration that includes Human Interface Device (HID) controls alongside USB audio channels. This enables custom control interfaces.

```cmake
set(APP_COMPILER_FLAGS_hid ${COMMON_FLAGS}
                           -DBCD_DEVICE=0x0102
                           -DNUM_USB_CHAN_IN=8
                           -DNUM_USB_CHAN_OUT=8
                           -DI2S_CHANS_ADC=8
                           -DI2S_CHANS_DAC=8
                           -DHID_CONTROLS=1)
```

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

### Define Executable and Sources

Source: https://github.com/xmos/lib_xua/blob/develop/tests/xua_hw_tests/test_control/host/CMakeLists.txt

Defines the executable name for the host control test and specifies the source files to be compiled.

```cmake
project(host_vendor_specifc_control)

set(APP_NAME host_control_test)

add_executable(${APP_NAME})

target_sources(${APP_NAME}
                PRIVATE
                src/control_test.cpp
                src/device_access_usb.c)
```