声道数。

通过位掩码设置哪些通道为活动通道。 最低有效位对应于通道索引 0。

所有示例的示例格式。

所有样本的帧格式。

所有样本的帧速率。

所有通道的每个槽位的位数。

所有样本的每个样本的位数。必须小于每个通道的位数，才能适合样本。

说明槽中样本的理由。

升降 sclk 时数据样本和帧同步输出的时钟。 如果为 true，则 sclk 会在数据和帧同步的提升边缘上提升，即数据将在 sclk 的下降边缘（sclk 周期的中间）被采样。因此，如果为 false，则将在 sclk 的上升边缘对数据进行采样。

帧同步更改开始与音频样本之间的 Sclk 数。 例如，将 I2S 设为 1，将立体声左对齐设为 0。

帧内帧同步的 SCL 数量较高。 例如，对于 32 位槽位设置为 32 的 I2S，TDM 通常设置为 1。

支持的渠道数量。

支持的示例格式。

支持的帧格式。

支持费率。值必须按升序列出。

每个插槽支持的位数。值必须按升序列出。

支持每个样本的比特数。值必须按升序列出。

声道数。

所有示例的格式。

为容纳等于或大于 valid_bits_per_sample 中的有效样本大小的样本分配的字节。

样本中的有效位数必须等于或小于 bytes_per_sample 中的位数。如果较小的位，则左对齐，并且接收器必须忽略任何其他位。

所有样本的帧速率。

驱动程序对播放/捕获指针到达 position 指示位置的时间（在 CLOCK_MONOTONIC 时间轴中）的最佳估计。不应将 turn_on_delay 的影响并入“时间戳”中。不应纳入 DelayInfo 中指明的延迟。

驱动程序估计的 timestamp 时间在环形缓冲区中的播放/捕获指针位置（以字节为单位）。

无

没有样本中的帧格式，而不像 PDM 那样执行帧同步。

I2S 体验

I2S 规范中指定的格式（左对齐，2 个通道，每个通道 32 位，左通道的帧同步保持低电平，右通道的帧同步保持低电平，在帧同步发生更改后在 sclk 的下降边缘停止一个时钟周期后，数据开始一个时钟周期）。

STEREO_LEFT

左对齐，2 个通道。数据从帧同步变化（从低到高）开始，在 sclk 的下降边缘触发。对于第一个通道的位每通道位，帧同步必须保持高电平；对于第二个通道，帧同步必须保持低位。

STEREO_RIGHT

右对齐，2 个通道。对于第一个通道的位每通道位，帧同步必须保持高电平；对于第二个通道，帧同步必须保持低位。

TDM1

左对齐，通道数不同，在帧同步时，数据从低到高在 sclk 的上升边缘时钟输出。帧同步必须在正好 1 个时钟周期内保持高状态。

TDM2

左对齐，可变通道数，在帧同步从低到高变为时钟同步后，数据在 sclk 的上升边缘开始一个时钟周期开始一个时钟周期。帧同步必须保持高电平状态并正好持续 1 个时钟周期。

TDM3

左对齐，可变通道数，在帧同步从低到高变为时钟周期（在 sclk 的上升边缘）后，数据在两个时钟周期开始同步。帧同步必须保持高电平状态并正好持续 1 个时钟周期。

PDM

脉冲密度调制样本。

PCM_SIGNED

主机字节序处的有符号整数线性脉冲编码调制样本。

PCM_UNSIGNED

主机字节顺序处的无符号整数线性脉冲编码调制样本。

PCM_FLOAT

浮点样本，根据 IEEE-754 标准编码。

STREAM_CONFIG

设备支持 fuchsia.hardware.audio/StreamConfig 协议。

DAI

设备支持 fuchsia.hardware.audio/Dai 协议。

编解码器

设备支持 fuchsia.hardware.audio/Codec 协议。

组合

设备支持 fuchsia.hardware.audio/Composite 协议。

INTERNAL_ERROR

驱动程序在执行操作时遇到其他未指定的错误。

NOT_SUPPORTED

该操作未实现、不受支持或未启用。

INVALID_ARGS

参数无效。

WRONG_TYPE

操作主题的类型有误，无法执行操作。

SHOULD_WAIT

操作目前无法执行，但如果调用方等待满足前提条件，操作可能会成功。

INVALID_ARGS

环形缓冲区设置失败，因为参数无效（例如 min_frames 过大）。

INTERNAL_ERROR

由于内部错误，环形缓冲区设置失败。

硬质

驱动程序为固定连接线（始终会接通电源）。

CAN_ASYNC_NOTIFY

驱动程序能够异步通知插头状态变化。

PCM_SIGNED

主机字节序处的有符号整数线性脉冲编码调制样本。

PCM_UNSIGNED

主机字节顺序处的无符号整数线性脉冲编码调制样本。

PCM_FLOAT

浮点样本，根据 IEEE-754 标准编码。

1

保证由此通道发射（或捕获）此通道的最低频率（以 Hz 为单位）。如果未添加 min_frequency，系统会假定此通道涵盖此设备的整个低频范围。

可选。

2

保证由此通道发射（或捕获到）此通道的最大频率（以 Hz 为单位）。如果未添加 max_frequency，系统会假定此通道涵盖此设备的整个高频范围。

可选。

1

描述此渠道集的属性。 此矢量的大小定义了此 ChannelSet 支持的通道数量。attributes 矢量的每个元素都定义了单个通道的属性。

必选。

1

驱动程序对选定格式的流水线中存在的外部延迟的最佳估算值（以纳秒为单位）。在多个实体（例如设备）间精确同步呈现内容时，应考虑外部延迟。如果未提供，则 external_delay 未知。

可选。

2

驱动程序对发出 Start 命令后，硬件实际开始播放/捕获音频所需的时间（以纳秒为单位）的最佳估算值。硬件可能需要一段时间才能进入完全运行模式，例如当电源状态发生变化时。如果无法接受播放或捕获初始音频样本，则必须将这种延迟考虑在内。如果未提供，则 turn_on_delay 未知。

可选。

3

驱动程序对发出 Stop 命令后硬件实际停止播放/捕获所需的时间（以纳秒为单位）的最佳估算值。硬件可能需要一段时间才能进入完全停止模式，例如电源状态发生变化时。如果系统不接受在“停止”命令之后播放/捕获样本，则必须考虑到这种延迟。 如果不添加此属性，则关闭延迟时间未知。

可选。

1

驱动程序类型为输入 (true) 或输出 (false)。如果未包含，驱动程序可用于输入和输出。

可选。

2

制造商名称的界面字符串。如果您未添加该属性，则表示制造商未指定。

可选。

3

商品名称的界面字符串。如果未指定，则未指定产品名称。

可选。

4

编解码器的唯一标识符。 如果未添加此字段，则编解码器的唯一 ID 不存在。

可选。

5

插头检测功能。

必选。

2

制造商名称的界面字符串。如果未设置，则制造商未知。

可选。

3

商品名称的界面字符串。如果未设置，则产品名称未知。

可选。

4

唯一标识符。如果未包含此字段，则设备没有唯一 ID。 为实现蓝牙技术的驱动程序预留了以 0x42、0x54...（或 ASCII 中为 BT）开头的 unique_id 数组。系统会预留以 0x55、0x53、0x42...（在 ASCII 中为 USB）开头的 unique_id 数组，以供实现 USB 技术的驱动程序使用。请注意，即使上述值映射到可读的 ASCII 字符，数组值也可以跨越整个 uint8 范围 (0-255)。

可选。

5

运行此硬件的时钟域的标识符。如果两个硬件设备具有相同的时钟域，则它们的时钟频率相同且完全同步。虽然这两个时钟具有相同的速率，但时钟位置之间可能会存在任意（但固定）的量的偏差。时钟域通常来自系统级实体，例如平台总线或全局时钟树。

有两个特殊值：

• CLOCK_DOMAIN_MONOTONIC 表示硬件的运行频率与系统单调时钟相同。

• CLOCK_DOMAIN_EXTERNAL 表示硬件以未知速率运行，并且不与任何已知时钟同步，即使与 CLOCK_DOMAIN_EXTERNAL 网域中的其他时钟同步也不同步。

如果网域不是 CLOCK_DOMAIN_MONOTONIC，客户端必须使用位置通知更新来恢复硬件的时钟。

必选。

1

驱动程序类型为输入 (true) 或输出 (false)

必选。

2

制造商名称的界面字符串。如果您未添加该属性，则表示制造商未指定。

可选。

3

商品名称的界面字符串。如果未指定，则未指定产品名称。

可选。

4

驱动程序的唯一标识符。如果未包含此字段，则没有驱动程序的唯一 ID。

可选。

5

运行此硬件的时钟域的标识符。如果两个硬件设备具有相同的时钟域，则它们的时钟频率相同且完全同步。虽然这两个时钟具有相同的速率，但时钟位置之间可能会存在任意（但固定）的量的偏差。时钟域通常来自系统级实体，例如平台总线或全局时钟树。

有两个特殊值：

• CLOCK_DOMAIN_MONOTONIC 表示硬件的运行频率与系统单调时钟相同。

• CLOCK_DOMAIN_EXTERNAL 表示硬件以未知速率运行，并且不与任何已知时钟同步，即使与 CLOCK_DOMAIN_EXTERNAL 网域中的其他时钟同步也不同步。

如果网域不是 CLOCK_DOMAIN_MONOTONIC，客户端必须使用位置通知更新来恢复硬件的时钟。

必选。

1

驱动程序对所提取硬件内部延迟的最佳估算值（针对所选格式）。

“内部”是指硬件互连 (DAI) 与环形缓冲区（例如 SoC 音频子系统）之间的硬件，而“外部”是指任何硬件互连 (DAI) 背面的硬件（例如硬件编解码器）。

对于播放期间的给定帧，这是指驱动程序/硬件将其从环形缓冲区复制后、退出任何硬件互连之前的任何延迟。对于录制期间的给定帧，这是指该帧进入硬件互连后到驱动程序/硬件将其复制到环形缓冲区之前的任何延迟。

在确定最短准备时间（播放期间）和最短拍摄延迟时间（拍摄期间）的要求时，必须考虑 internal_delay。

此延迟不得包含由将数据复制到环形缓冲区或从中复制数据所需的临时缓冲所添加的固有延迟（包含在 RingBufferProperties 字段 driver_transfer_bytes 中）。

必选。

2

驱动程序在所提取硬件外部的延迟最优估算值（针对所选格式）。

“外部”是指任何硬件互连 (DAI) 背面的硬件（例如硬件编解码器），而“内部”是指硬件互连 (DAI) 和环形缓冲区（例如 SoC 音频子系统）之间的硬件。

在确定最短准备时间（播放期间）和最短拍摄延迟时间（拍摄期间）的要求时，必须考虑 external_delay。

如果不包含，则 external_delay 为未知。如果未知，客户端可能会按它选择的方式处理它（将其视为零个或很大的数字，自动检测它，等等）。

与 internal_delay 一样，此延迟不得包含由将数据复制进环形缓冲区或移出环形缓冲区所需的临时缓冲而添加的固有延迟，该延迟包含在 RingBufferProperties 字段 driver_transfer_bytes 中。

可选。

1

支持未压缩 PCM 样本的格式。

必选。

1

当前静音状态。如果未添加该属性，则该状态会被取消静音。

可选。

2

当前自动增益控制 (AGC) 状态。如果未添加，AGC 会被停用。

可选。

3

当前增益（以分贝为单位）。

必选。

1

驱动程序当前健康状况良好。 如果未添加此字段，则不会提供健康信息。 这样一来，驱动程序便可以在没有足够的功能或资源来自行恢复时（例如，无法通过 GPIO 关闭硬件或控制电源子系统），发出其运行状况信号。

可选。

1

支持的可能的 ChannelSets 向量。 ChannelSet 指定通道配置（包括通道数）以及多个可选属性。每个唯一身份频道数只允许有一个 ChannelSet。因此，channel_sets 中任何两个条目都不能包含相同长度的 attributes 向量。

必选。

2

支持的可能 SampleFormat 的矢量。

必选。

3

为每个样本分配的可能字节数的矢量。值必须按升序列出。valid_bits_per_sample 中列出的所有值必须至少为最大的 bytes_per_sample 值。

必选。

4

由 bytes_per_sample 定义的示例容器内包含有效数据的可能位数的矢量。值必须按升序列出。列出的所有值都必须适合最大的 bytes_per_sample 值。在采样容器中，有效数据位必须是最高有效位（左对齐），并且所有额外的位都将被忽略。

必选。

5

支持的可能帧速率矢量。值必须按升序列出。

必选。

1

驱动程序目前已插入。必需

2

为在此结构体其余字段中提供的信息设置时间戳。必选。

3

如果设置为 true，则表示环形缓冲区在不同的缓存相干域中运行，因此客户端必须确保其数据写入始终刷新到主内存（播放期间），或者其环形缓冲区视图必须在任何读取操作（捕获期间）之前失效。这是因为 CPU 外部的硬件可能会绕过 CPU 读取/写入主内存。

如果设置为 false，则表示环形缓冲区在与 CPU 相同的缓存一致性域中运行，因此驱动程序无需刷新/使环形缓冲区失效。 请注意，在这种情况下，驱动程序和客户端仍必须同步其数据访问，例如，在写入后读取和释放栅栏，之前插入适当的获取栅栏。

必选。

4

驱动程序对在通道被 SetActiveChannels 激活后硬件发出（播放期间）或接受（拍摄期间）帧所需的时间做出的最佳估计。驱动程序估计，在 SetActiveChannels(channel)->(set_time) 启用某个通道后，其数据将在大约 set_time + turn_on_delay 时继续流动。硬件可能需要一段时间才能完全正常运行（例如，由于电源状态发生变化，或蓝牙驱动程序的多个硬件实体之间的通信延迟）。如果不可在此时间间隔内丢弃实际音频帧而改为播放/捕获无声音频，则客户端必须考虑这种延迟。 如果不包含，则 turn_on_delay 为未知。

可选。

5

使用或生成环形缓冲区内容时驱动程序/硬件使用的临时缓冲区的大小（以字节为单位）。

环形缓冲区内容必须通过临时缓冲区和环形缓冲区之间的数据传输，以 CreateRingBuffer 命令指定的速率生成和使用。对于播放，驱动程序在大小为 driver_transfer_bytes 的传输中使用音频帧。为进行捕获，驱动程序在大小为 driver_transfer_bytes 的传输中生成音频帧。在这两种情况下，在读取或提交到环形缓冲区之前，这些帧必须累积。

这些数据传输意味着，环形缓冲区中始终存在对客户端来说不安全的部分写入/读取。这个不安全的缓冲区区域在一侧由当前位置“P”定义，在另一侧由“安全指针”位置“S”定义。当环形缓冲区启动后，这两个指针便开始移动。“P”开始从 Start 处 start_time 的位置 0 开始移动。届时，客户端不得读取或写入这些指针之间的区域。下图将这些指针标注为“P”和“S”。

在播放期间，客户端必须在进行硬件传输之前写入数据。在捕获期间，客户端只能在硬件传输之后读取捕获的数据。因此，在播放期间，“S”始终在“P”之前，而在拍摄期间，“S”始终在“P”之后。

播放

在启动环形缓冲区之前，客户端可以安全地写入任何环形缓冲区位置。建议它们至少写入 driver_transfer_bytes 的初始音频，因为它们必须始终至少比驱动程序/硬件读取的位置提前足够远，并且当达到 Start 时，硬件可能会立即消耗环形缓冲区中的这么多数据。否则，客户端依赖 VMO 的清零内容作为驱动程序/硬件读取的初始音频。

                                      Ring Buffer
 +-------------------------+-------------------------------------------------------------+
 |<---                                 safe to write                                 --->|
 |             (to pre-populate the ring buffer before starting the hardware)            |
 +-------------------------+-------------------------------------------------------------+
 0=P                       S                                                             0

启动环形缓冲区后，客户端在“P”和“S”之间向环形缓冲区写入数据是不安全的，因为这表示数据已在使用（可能已被消耗）。客户端可以安全地写入环形缓冲区的其余部分（介于“S”和“0/P”之间）。

                                      Ring Buffer
 +-------------------------+-------------------------------------------------------------+
 |<--- unsafe to write --->|<---                    safe to write                    --->|
 |< driver_transfer_bytes >|           (empty unless prewritten by the client)           |
 +-------------------------+-------------------------------------------------------------+
 0=P                       S                                                             0

随着时间的推移，驱动程序/硬件会以 CreateRingBuffer 中指定的速率读取数据块（大小不超过 driver_transfer_bytes 块）。位置/安全指针以相同的频率向右移动，但要平稳地移动。因此，“不安全客户端写入”区域会逐步在环形缓冲区中移动，同时保持大小等于 driver_transfer_bytes 的恒定大小。因此，经过一段时间后，我们得到：

                                      Ring Buffer
 +------------+-------------------------+------------------------------------------------+
 |<-- safe -->|<--- unsafe to write --->|<--               safe to write              -->|
 |  to write  |< driver_transfer_bytes >|       (not yet consumed by the hardware)       |
 +------------+-------------------------+------------------------------------------------+
 0            P                         S                                                0

之后，“S”先于“P”封装环形缓冲区。请注意，从 0 到“S”的区域，加上从“P”到环形缓冲区末尾的区域，相加等于 driver_transfer_bytes：

                                      Ring Buffer
 +---------------+------------------------------------------------------------+----------+
 |<--- unsafe -->|<---                   safe to write                    --->|<-unsafe->|
 |< driver_transf|                                                            |er_bytes >|
 +---------------+------------------------------------------------------------+----------+
 0               S                                                            P          0

在稳定状态下，指针“P”和“S”之外的任何区域都可以安全写入：

                                      Ring Buffer
 +--------------------------------+-------------------------+----------------------------+
 [<--       safe to write      -->|<--- unsafe to write --->|<--     safe to write    -->|
 |  (prior data already consumed) |< driver_transfer_bytes >|                            |
 +--------------------------------+-------------------------+----------------------------+
 0                                P                         S                            0

录制

记录时，只有客户端可以安全地读取驱动程序/硬件未同时写入的环形缓冲区中的那部分内容。在捕获开始前，它可以读取整个环缓冲区，但驱动程序尚未写入任何内容供客户端读取。这是客户端启动环形缓冲区时的环形缓冲区：

                                      Ring Buffer
 +---------------------------------------------------------------------------------------+
 [<---                     empty (not yet written by the hardware)                    -->|
 +---------------------------------------------------------------------------------------+
0=S=P                                                                                    0

捕获开始后，驱动程序/硬件会获取帧，最终从“0”开始将其第一次数据传输到环形缓冲区。这些传输的大小未知，但最大可达 driver_transfer_bytes；它们以 CreateRingBuffer 中指定的速率进行。在驱动程序/硬件将至少 driver_transfer_bytes 写入环形缓冲区之前，客户端还无法安全地读取任何新捕获的帧：

                                      Ring Buffer
 +--------------+------------------------------------------------------------------------+
 [<-- unsafe -->|<--                           safe to read                           -->|
 |< driver_transfer_bytes >|     (but empty, not yet written by the hardware)            |
 +--------------+------------------------------------------------------------------------+
0=S             P                                                                        0

驱动程序/硬件将至少 driver_transfer_bytes 的数据写入环形缓冲区后，“S”开始以与“P”相同的速率平滑向前移动（由环形缓冲区的速率和样本格式决定）。客户端可以安全地读取“0”和“S”之间的区域中帧。客户端读取“S”和“P”之间的数据不安全，因为这是驱动程序/硬件同时写入的位置。该区域在环形缓冲区中逐渐扩大，并保持 driver_transfer_bytes 的恒定大小。一段时间后，结果如下：

                                      Ring Buffer
 +----------------+-------------------------+--------------------------------------------+
 [< safe to read >|<---  unsafe to read --->|<--             safe to read             -->|
 | captured audio |< driver_transfer_bytes >|      (not yet written by the hardware)     |
 +----------------+-------------------------+--------------------------------------------+
 0                S                         P                                            0

之后，“P”会先于环形缓冲区封装，然后才是“S”。请注意，从 0 到“P”的区域，再加上从“S”到环形缓冲区末尾的区域，相加等于 driver_transfer_bytes：

                                      Ring Buffer
 +-----------+------------------------------------------------------------+--------------+
 |<--unsafe->|<---                    safe to read                    --->|<---unsafe--->|
 |< driver_tr|                      (captured audio)                      |ansfer_bytes >|
 +-----------+------------------------------------------------------------+--------------+
 0           P                                                            S              0

在稳定状态（即进程封装到环形缓冲区）下，指针“S”和“P”之外的任何区域都可以安全地读取：

                                      Ring Buffer
 +--------------------------------+-------------------------+----------------------------+
 [<--       safe to read       -->|<---      unsafe     --->|<--     safe to read     -->|
 |                                |< driver_transfer_bytes >|                            |
 +--------------------------------+-------------------------+----------------------------+
 0                                S                         P                            0

硬件与软件

环形缓冲区数据可以直接由硬件使用/生成，也就是说，driver_transfer_bytes 可以直接映射到硬件 FIFO 块的大小，因为硬件 FIFO 块决定了提前读取或保留的数据量的上限。 请注意，如果未以传统的“高水量”方式使用 FIFO 缓冲区（例如，在任何时候只使用 FIFO 一半大小的“乒乓球”设计，即使是在 Start 时间的最初传输期间），则可以将 driver_transfer_bytes 设置为较小的值，但必须至少等于 FIFO 缓冲区中曾存储的最大数据量。 即使传输大小绝不会超过 FIFO 大小的一半，如果使用了 FIFO 的完整大小（例如，在 Start 填充最初为空的硬件 FIFO 时），也必须将 driver_transfer_bytes 设置为 FIFO 缓冲区的整个大小。

环形缓冲区数据可能由概念上位于环形缓冲区和音频硬件之间的音频驱动程序软件使用/生成。在这种情况下，对于播放来说，driver_transfer_bytes 预读量必须足够大，以便驱动程序根据客户端要求根据 CreateRingBuffer 速率和 Start 中的 start_time 生成数据，保证不会出现未检测到的欠载。对于捕获，driver_transfer_bytes 必须足够大，以便驱动程序在生成由 CreateRingBuffer 和 Start 命令确定的数据时保证不会出现欠载。

driver_transfer_bytes 不得包含由驱动程序提取的硬件或软件处理导致的延迟影响。这些延迟通过 DelayInfo 中的 internal_delay 和 external_delay 字段传达；它们与此值正交。

必选。

1

唯一标识符。如果不包含，则 StreamConfig 没有唯一 ID。为实现蓝牙技术的驱动程序预留了以 0x42、0x54...（或 ASCII 中为 BT）开头的 unique_id 数组。系统会预留以 0x55、0x53、0x42...（在 ASCII 中为 USB）开头的 unique_id 数组，以供实现 USB 技术的驱动程序使用。请注意，即使上述值映射到可读的 ASCII 字符，数组值也可以跨越整个 uint8 范围 (0-255)。

可选。

2

驱动程序类型为输入 (true) 或输出 (false)

必选。

3

获得静音功能。如果不包含，则 StreamConfig 无法静音。

可选。

4

自动增益控制 (AGC) 功能。如果不包含，则 StreamConfig 无法使用 AGC。

可选。

5

最小增益（以分贝为单位）。

必选。

6

最大增益（分贝）。

必选。

7

增益步长（以分贝为单位），该值不得为负数，但可以为零以表示有效连续的值范围。不得超过 max_gain_db - min_gain_db。

必选。

8

插头检测功能。

必选。

9

制造商名称的界面字符串。如果您未添加该属性，则表示制造商未指定。

可选。

10

商品名称的界面字符串。如果未指定，则未指定产品名称。

可选。

11

运行此硬件的时钟域的标识符。如果两个硬件设备具有相同的时钟域，则它们的时钟频率相同且完全同步。虽然这两个时钟具有相同的速率，但时钟位置之间可能会存在任意（但固定）的量的偏差。时钟域通常来自系统级实体，例如平台总线或全局时钟树。

有两个特殊值：

• CLOCK_DOMAIN_MONOTONIC 表示硬件的运行频率与系统单调时钟相同。

• CLOCK_DOMAIN_EXTERNAL 表示硬件以未知速率运行，并且不与任何已知时钟同步，即使与 CLOCK_DOMAIN_EXTERNAL 网域中的其他时钟同步也不同步。

如果网域不是 CLOCK_DOMAIN_MONOTONIC，客户端必须使用位置通知更新来恢复硬件的时钟。

必选。

1

支持未压缩 PCM 样本的格式，包含属性。

必选。

1

2

1

2

1

2

1

2

1

2

1

2

1

2

1

DAI 中所有样本的格式类型，在 DaiFrameFormatStandard 中列出。

2

DAI 中所有样本的格式类型，在 DaiFrameFormatCustom 中指定。

1

2

1

2

1

2

1

2