配置与选项
本节描述了lib_xua的关键选项。通常情况下，这些选项是通过构建时定义来进行控制的。如果必须定义某些内容，建议在xua_conf.h中进行定义，但也可以在应用程序的Makefile中进行定义。
有关所有选项的详细信息，请参阅：API
字符串和标识符
代码库包含了各种字符串和标识符，用户应根据产品需求进行自定义。这些在图7中列出。供应商ID（VID）应从 USB Implementers Forum 获取。在没有明确许可的情况下，不得使用XMOS VID或其他VID。供应商ID（VID）和产品ID（PID）必须对每个产品都是唯一的，否则可能导致驱动程序不兼容。
| 定义 | 描述 | 默认值 |
|---|---|---|
| VENDOR_STR | 厂商/制造商名称，注意会附加到各种字符串后面。 | "XMOS" |
| PRODUCT_STR_A2 | 在USB Audio Class 2.0模式下运行时的产品名称 | "XMOS xCORE (UAC2.0)" |
| PRODUCT_STR_A1 | 在USB Audio Class 1.0模式下运行时的产品名称 | "XMOS xCORE (UAC1.0)" |
| PID_AUDIO_2 | 在USB Audio Class 2.0模式下运行时的产品ID | 0x0002 |
| PID_AUDIO_1 | 在USB Audio Class 1.0模式下运行时的产品ID | 0x0003 |
代码位置
在设计系统时，可以选择为每个接口使用哪些硬件资源。在多片系统中，需要告知代码库要使用哪些 tile 来处理这些硬件资源和相关代码。一系列的定义用于允许用户轻松地在不同 tile 之间移动代码。其中最重要的可能是AUDIO_IO_TILE和XUD_TILE。图8显示了这些TILE定义的完整列表。
| 定义 | 描述 | 默认值 |
|---|---|---|
| AUDIO_IO_TILE | I2S、ADAT Rx、S/PDIF Rx和混音器所在的 tile | 0 |
| XUD_TILE | USB所在的 tile ，包括所有USB接口/端点的缓冲区 | 0 |
| MIDI_TILE | MIDI所在的 tile | 与AUDIO_IO_TILE相同 |
| SPDIF_TX_TILE | S/PDIF Tx所在的 tile | 与AUDIO_IO_TILE相同 |
| PDM_TILE | PDM麦克风所在的 tile | 与AUDIO_IO_TILE相同 |
| PLL_REF_TILE | 参考信号到CS2100的 tile | 与AUDIO_IO_TILE相同 |
应确保应用程序XN文件中的相关端口定义与代码位置定义相匹配。
通道数和采样率
代码库在通道数和采样率方面具有完全的可配置性。这些的实际限制通常基于USB数据包大小限制和I/O可用性。
例如，高速USB的最大数据包大小为1024字节，限制了以32位采样深度、192kHz采样率运行的设备的通道数为10个。
图9中的定义设置了向USB主机公开的通道数。
| 定义 | 描述 | 默认值 |
|---|---|---|
| NUM_USB_CHAN_OUT | 设备向USB主机公开的输出通道数 | N/A（必须定义） |
| NUM_USB_CHAN_IN | 设备向USB主机公开的输入通道数 | N/A（必须定义） |
采样率范围由图10中的定义设置。代码库将自动使用最小值和最大值之间的常用频率填充设备的采样率列表。所有值均以Hz为单位。
| 定义 | 描述 | 默认值 |
|---|---|---|
| MAX_FREQ | 最大支持的采样率（Hz） | 192000 |
| MIN_FREQ | 最小支持的采样率（Hz） | 44100 |
| DEFAULT_FREQ | 设备启动后的起始频率，与MIN_FREQ相同 | MIN_FREQ |
代码库需要知道主时钟端口上将存在的两个主时钟频率。一个用于44.1kHz、88.2kHz等，另一个用于48kHz、96kHz等。这些使用图11中的定义进行设置。所有值均以Hz为单位。
| 定义 | 描述 | 默认值 |
|---|---|---|
| MCLK_441 | 44100采样率的主时钟定义（Hz） | (256 * 44100) |
| MCLK_48 | 48000采样率的主时钟定义（Hz） | (256 * 48000) |
USB Audio Class 版本
代码库支持USB Audio Class 1.0和2.0。 USB Audio Class 2.0相比于USB Audio Class 1.0提供了许多改进，最显著的是对高速（High-speed）操作的完全支持。这意味着 Audio Class 设备不再限于全速（Full-speed）操作，可以实现更多的通道数、采样频率和采样位深度。其他改进还包括：
- 增加对多个时钟域、时钟描述和时钟控制的支持
- 广泛支持中断，以通知主机有关发生在不同实 体（如时钟等）上的动态变化
驱动程序支持
Audio Class 1.0
Apple OSX完全支持 Audio Class 1.0。所有现代Microsoft Windows操作系统（如Windows XP及更高版本）完全支持 Audio Class 1.0。
Audio Class 2.0
自10.6.4版本开始，Apple OSX完全支持 Audio Class 2.0。从Windows 10的1703版本开始，Windows附带了一个USB音频2.0驱动程序。 也提供第三方Windows驱动程序，但这些驱动程序的文档超出了本文档的范围，请联系我们获取更多详细信息。
Audio Class 1.0模式和回退
XMOS USB音频应用程序的默认设置是以高速 Audio Class 2.0设备运行。然而，某些产品可能更喜欢以 Audio Class 1.0模式运行，这通常是为了与旧版Windows操作系统实现“免驱”的操作。
为确保符合规范， Audio Class 1.0模式始终在全速USB上运行。 如果满足以下条件之一，则设备将以全速 Audio Class 1.0模式运行：
- 代码仅编译为USB Audio Class 1.0。
- 代码编译为USB Audio Class 2.0，并且通过全速链路连接到主机（并启用 Audio Class 回退）。
控制此行为的选项详见API。
在 Audio Class 1.0模式下运行时，将应用以下限制：
- MIDI被禁用。
- DFU被禁用（因为Windows操作系统会提示安装DFU驱动程序）。
由于全速USB的带宽限制，还会应用以下采样频率限制：
- 如果同时启用输入和输出，则采样率最大限制为48kHz。
- 如果只启用输入或输出，则采样率最大限制为96kHz。
相关定义
图12描述了影响 Audio Class 选择的定义。
| 定义 | 描述 | 默认值 |
|---|---|---|
| AUDIO_CLASS | Audio Class 版本（1或2） | N/A（必须定义） |
| AUDIO_CLASS_FALLBACK | 启用 Audio Class 回退功能 | 0（禁用） |
启用USB Audio Class 回退功能可能会对USB兼容性产生影响。
同步
代码库支持USB传输的“同步”和“异步”模式，这是由USB规范定义的。
异步模式（XUA_SYNCMODE_ASYNC）的优点是设备作为时钟主 机。这意味着可以利用高质量的本地主时钟源。它还具有将设备的主时钟与外部数字输入流（例如S/PDIF）同步的好处，从而避免了采样率转换。 此模式的缺点是它给主机带来了与设备同步的负担，某些主机可能不支持此功能。这对于嵌入式主机尤为重要，但大多数个人电脑和移动设备确实支持此模式。
同步模式（XUA_SYNCMODE_SYNC）是一种可选项。如果目标主机不支持异步模式或者希望将多个设备同步到单个主机时，应该使用同步模式。然而，需要注意的是，此模式下不支持来自数字流（如S/PDIF）的输入。
选择同步模式是在构建时进行的，无法动态更改。
设置设备的同步模式使用图13中的定义。
| 定义 | 描述 | 默认值 |
|---|---|---|
| XUA_SYNCMODE | USB同步模式 | XUA_SYNCMODE_ASYNC |
在同步模式下运行时，需要外部的Cirrus Logic CS2100设备用于主时钟生成。代码库期望向此外部设备提供同步信号。
用户应确保图14中的定义设置正确。
| 定义 | 描述 | 默认值 |
|---|---|---|
| PLL_REF_TILE | 参考信号到CS2100设备的 tile 位置 | AUDIO_IO_TILE |
代码库期望在应用程序的XN文件中定义此参考信号 端口为PORT_PLL_REF。这可以是任意位宽的端口，但假定连接到bit[0] 时：
<Port Location="XS1_PORT_1A" Name="PORT_PLL_REF"/>
对外部CS2100设备的配置（通常是通过I2C）超出了本文档的范围。
I2S/TDM
I2S/TDM通常是大多数产品的基础，并内置于XUA_AudioHub()核心。 图15中的定义影响了I2S的实现。
| 定义 | 描述 | 默认值 |
|---|---|---|
| I2S_CHANS_DAC | 通过I2S输出的期望输出通道数（0表示禁用） | N/A（必须定义） |
| I2S_CHANS_ADC | 通过I2S输入的期望输入通道数（0表示禁用） | N/A（必须定义） |
| XUA_PCM_FORMAT | 启用TDM或I2S模式 | XUA_PCM_FORMAT_I2S |
| CODEC_MASTER | xCORE是否为I2S主设备 | 0（xCORE是主设备） |
用户应当在应用程序的XN文件中定义所需的I2S端口（主时钟、左右时钟、位时钟和数据线）。例如：
<Tile Number="0" Reference="tile[0]">
<Port Location="XS1_PORT_1A" Name="PORT_MCLK_IN"/>
<Port Location="XS1_PORT_1B" Name="PORT_I2S_LRCLK"/>
<Port Location="XS1_PORT_1C" Name="PORT_I2S_BCLK"/>
<Port Location="XS1_PORT_1D" Name="PORT_I2S_DAC0"/>
<Port Location="XS1_PORT_1E" Name="PORT_I2S_DAC1"/>
<Port Location="XS1_PORT_1F" Name="PORT_I2S_ADC0"/>
<Port Location="XS1_PORT_1G" Name="PORT_I2S_ADC1"/>
</Tile>
所有与I2S相关的端口都必须是1位 端口。 TDM模式允许在每个数据线上提供至多16个通道（而不是2个）。
S/PDIF传输
代码库支持一个立体声S/PDIF发射器。可以通过75Ω同轴电缆或光纤输出。为了提供S/PDIF传输功能，lib_xua使用了lib_spdif。 通过图16中的定义可以实现对S/PDIF传输功能的基本配置。
| 定义 | 描述 | 默认值 |
|---|---|---|
| XUA_SPDIF_TX_EN | 启用S/PDIF发射器 | 0（禁用） |
| SPDIF_TX_INDEX | 用于S/PDIF传输的输出通道偏移 | 0 |
此外，开发人员还可以选择S/PDIF发射器运行的 tile 位置，参见图17中的定义。
| 定义 | 描述 | 默认值 |
|---|---|---|
| SPDIF_TX_TILE | S/PDIF发射器连接到的 tile 位置 | AUDIO_IO_TILE |
代码库期望在应用程序的XN文件中将S/PDIF发射器端口定义为PORT_SPDIF_OUT。这必须是一个1位端口，例如：
<Port Location="XS1_PORT_1A" Name="PORT_SPDIF_OUT"/>
S/PDIF接收
代码库支持一个立体声S/PDIF接收器。可以通过75Ω同轴电缆或光纤输入。为了提供S/PDIF功能，lib_xua使用了lib_spdif。 通过图18中的定义可以实现对S/PDIF接收功能的基本配置。
| 定义 | 描述 | 默认值 |
|---|---|---|
| XUA_SPDIF_RX_EN | 启用S/PDIF接收 | 0（禁用） |
| SPDIF_RX_INDEX | 指定S/PDIF输入通道 | N/A（必须定义） |
S/PDIF接收始终在由AUDIO_IO_TILE定义的 tile 上运行。 代码库期望在应用程序的XN文件中将S/PDIF接收端口定义为PORT_SPDIF_IN。这必须是一个1位端口，例如：
<Port Location="XS1_PORT_1A" Name="PORT_SPDIF_IN"/>
当启用S/PDIF接收时，代码库期望向外部的Cirrus Logic CS2100设备提供同步信号以生成主时钟。 用户应确保图19中的定义设置正确。
| 定义 | 描述 | 默认值 |
|---|---|---|
| PLL_REF_TILE | 参考信号到CS2100设备的 tile 位置 | AUDIO_IO_TILE |
代码库期望在应用程序的XN文件中将此参考信号端口定义为PORT_PLL_REF。这可以是任意位宽的端口，此处我们假定连接到bit[0]：
<Port Location="XS1_PORT_1A" Name="PORT_PLL_REF"/>
对外部CS2100设备的配置（通常通过I2C）超出了本文档的范围。
MIDI
代码库支持通过USB进行MIDI输入/输出，符合通用串行总线设备类定义的MIDI设备规范。 使用图20中的定义启用MIDI功能。
| 定义 | 描述 | 默认值 |
|---|---|---|
| MIDI | 启用MIDI功能 | 0（禁用） |
代码库支持4位或1位MIDI接收端口，默认情况下使用1位端口。支持任何位宽的MIDI发送端口。默认情况下，代码库假定发送和接收I/O连接到端口的bit[0]。图21提供了有关配置这些参数的信息。
| 定义 | 描述 | 默认值 |
|---|---|---|
| MIDI_RX_PORT_WIDTH | MIDI接收端口的位宽（1或4位） | 1（1位端口） |
| MIDI_SHIFT_TX | MIDI发送位的偏移（bit[0]） | 0 |
MIDI代码期望在应用程序的XN文件中定义接收和发送的端口。接收端口的预期名称为PORT_MIDI_IN，发送端口的预期名称为PORT_MIDI_OUT，例如：
<Tile Number="0" Reference="tile[0]">
<!-- MIDI -->
<Port Location="XS1_PORT_1F" Name="PORT_MIDI_IN"/>
<Port Location="XS1_PORT_4C" Name="PORT_MIDI_OUT"/>
</Tile>
PDM麦克风
代码库支持最多8个PDM麦克风的输入。 通过lib_mic_array提供了对PDM麦克风的支持。通过图22中的定义来控制PDM麦克风的设置。
| 定义 | 描述 | 默认值 |
|---|---|---|
| XUA_NUM_PDM_MICS | 启用的 麦克风数量（0表示禁用） | 0（禁用） |
| PDM_MIC_INDEX | 麦克风映射到的输入通道 | 0 |
代码库期望在应用程序的XN文件中为PORT_PDM_CLK和PORT_PDM_MCLK定义1位端口，并为PORT_PDM_DATA定义8位端口。例如：
<Tile Number="0" Reference="tile[0]">
<!-- Mic related ports -->
<Port Location="XS1_PORT_1E" Name="PORT_PDM_CLK"/>
<Port Location="XS1_PORT_8B" Name="PORT_PDM_DATA"/>
<Port Location="XS1_PORT_1F" Name="PORT_PDM_MCLK"/>
</Tile>
混音器
代码库支持高度灵活、带有路由选项的音频混音功能。 基本配置混音功能可以使用图23中的定义。
| 定义 | 描述 | 默认值 |
|---|---|---|
| MIXER | 启用混音器 | 0（禁用） |
| MAX_MIX_COUNT | 执行的独立混音输出数量 | 8 |
| MIX_INPUTS | 输入到混音器的通道数 | 18 |
混音器核心始终在由AUDIO_IO_TILE定义的 tile 上运行。
Direct Stream Digital（DSD）
直接流数字（DSD）用于在超级音频CD（SACD）上对音频信号进行数字编码。它使用脉冲密度调制（PDM）编码。 代码库支持通过“DSD over PCM”（DoP）和“Native”两种方式从主机播放DSD，并且“Native”实现是基于XMOS专有的USB规范。 通过将图24中的定义设置为非零值来启用DSD。
| 定义 | 描述 | 默认值 |
|---|---|---|
| DSD_CHANS_DAC | DSD通道数 | 0（禁用） |
通常，对于立体声输出，将其设置为2。 默认情况下，当启用DSD时，同时启用“Native”和DoP功能。Native DSD实现使用了一种替代的流接口，主机可以通过该接口通知设备正在流传输DSD数据。有关详细信息，请参阅§5.13。 如果只需要DoP功能，则可以使用图25中的定义禁用Native实现。
| 定义 | 描述 | 默认值 |
|---|---|---|
| NATIVE_DSD | 启用/禁用“Native” DSD实现 | 1（启用） |
通过PCM传输DSD（DoP）
DoP支持遵循DoP Open Standard 1.1中描述的方法。
虽然Windows提供了对Native DSD的支持，但OSX使用的USB驱动程序仅支持PCM，这也适用于核心音频引擎CoreAudio。因此，无法使用OSX内置的驱动程序来使用上述定义的“Native”方案。
由于Apple操作系统仅支持PCM传输，因此开发了一种在PCM帧上传输DSD音频数据的方法。
标准DSD的采样大小为1位，采样率为2.8224MHz，这是光盘（CD）音频速度的64倍。这相当于176.4kHz的16位PCM流的数据速率。
为了清楚地识别此PCM流中包含DSD还是PCM，样本中添加了一些header字节。
因此，使用24位PCM流，最高有效字节用于DSD标记（交替使用0x05和0xFA值）。
当启用Dop时，如果USB音频设计检测到这些样本的连续运行（超过定义的阈值），它将切换到DSD模式，并使用较低的16位作为DSD样本数据。
当检测DSD标头失败时，设计会回退到PCM模式。DoP的检测和切换完全在音频/I2S核心（audio.xc）中进行。所有其他代码将音频样本处理为PCM格式。
该设计通过简单地提高底层PCM采样率（例如从176.4kHz提高到352.8kHz）来支持更高的DSD/DoP速率（例如DSD128）。无论速率如何，标记字节方案保持完全相同。
DoP要求传输完全无误，因此任何音频/音量处理都会中断流。
"Native" vs DoP
由于DoP规范需要标头字节，这会占用数据带宽。"Native"实现没有这种开销，因此可以传输与DoP相同的DSD速率和一半的有效PCM速率。例如，在支持DSD128但不暴露352.8kHz PCM速率时，可能希望使用这种属性。
端口
代码库期望在应用XN文件中定义1位端口，用于DSD数据和时钟线，例如：
<Port Location="XS1_PORT_1M" Name="PORT_DSD_DAC0"/>
<Port Location="XS1_PORT_1N" Name="PORT_DSD_DAC1"/>
<Port Location="XS1_PORT_1G" Name="PORT_DSD_CLK"/>
DSD端口可能与I2S端口重叠或不重叠 - 当在PCM和DSD模式之间切换时，代码库将根据需要重新配置端口。
音频流格式
该设计目前支持 最多三种不同的播放流格式，可在运行时选择。这是使用音频流接口的标准备用设置来实现的。
音频流接口可以具有备用设置，用于更改接口和底层端点的某些特性。备用设置的典型用途是提供一种在活动的音频流接口上更改子帧大小和/或通道数的方法。每当音频流接口需要等时数据端点时，它必须至少提供默认备用设置（备用设置0），其带宽要求为零（未定义等时数据端点），并且包含实际等时数据端点的其他备用设置。设计始终实现此零带宽备用设置0。
有关更多信息，请参考《USB音频设备类定义》中的3.16.2章节。
设计提供的备用设置的可定制参数如下：
- 音频采样分辨率
- 音频采样子插槽大小
- 音频数据格式
目前仅支持单个格式的录制流。
默认情况下，设计为播放音频流接口公开了两组备用设置，一组用于16位播放，另一组用于24位播放。启用DSD时，还会公开另一种（32位）备用设置。
音频子插槽
音频子插槽包含一个音频样本。完整详情请参阅《USB音频数据格式的设备类定义》。这由设备描述符集中的bSubslotSize表示。
音频子插槽始终包含整数个字节。规范将可能的音频子插槽大小限制为每个音频子插槽的1、2、3或4个字节。
由于xCORE是32位机器，通常使用值4作为bSubSlot - 这意味着将样本打包/解包到/从数据包中很容易。然而，也可以使用其他值，设计支持值4、3和2。
可以出于以下原因使用除4之外的其他值：
- 需要有效利用总线带宽。例如，在全速操作中最大化通道数/采样率。
- 支持某些 主机的限制。例如，许多基于Android的主机仅支持2字节子插槽中的16位样本。
使用以下定义来设置bSubSlot大小：
- 在高速运行时：
- HS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES
- HS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES
- HS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES
- 在全速运行时：
- FS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES
- FS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES
- FS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES
音频采样分辨率
音频采样使用小于或等于音频子插槽中可用总位数的位数（bBitResolution）表示，即bBitResolution <= bSubslotSize * 8。设计支持16、24和32的值。
使用以下定义来设置bBitResolution：
- 在高速运行时：
- HS_STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS
- HS_STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS
- HS_STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS
- 在全速运行时：
- FS_STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS
- FS_STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS
- FS_STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS
音频格式
该设计支持两种音频格式，PCM和启用"Native" DSD时的直接流数字（DSD）。后者需要支持DSD的DAC。
使用USB音频原始数据格式来指示DSD数据（《USB音频数据格式的设备类定义》的2.3.1.7.5节）。XMOS将在备用设置中使用原始/DSD格式的这种用法称为Native DSD。
以下定义影响全速和高速操作：
- STREAM_FORMAT_OUTPUT_1_DATAFORMAT
- STREAM_FORMAT_OUTPUT_2_DATAFORMAT
- STREAM_FORMAT_OUTPUT_3_DATAFORMAT
支持以下选项：
- UAC_FORMAT_TYPEI_RAW_DATA
- UAC_FORMAT_TYPEI_PCM
目前，仅在输出/播放流上支持DSD。
RAW/DSD格式需要4字节槽大小和32位分辨率。Native DSD需要驱动程序支持，并且在Thesycon Windows驱动程序中通过ASIO可用。
其他选项
还有一些其他不常用的选项可用。
| 定义 | 描述 | 默认值 |
|---|---|---|
| XUA_USB_EN | 允许在没有USB的情况下使用音频子系统 | 1（启用） |
| INPUT_VOLUME_CONTROL | 启用输入通道的音量控制，包括描述符和处理 | 1（启用） |
| OUTPUT_VOLUME_CONTROL | 启用输出通道的音量控制，包括描述符和处理 | 1（启用） |