fuchsia.hardware.audio

Added: 7

PROTOCOLS

Codec

Defined in fuchsia.hardware.audio/codec.fidl

For an overview see [Audio Codec Interface].

Deprecation

Not supported anymore, instead use an Audio Composite with one DAI and no Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

GetDaiFormats

Retrieves the DAI formats supported by the codec, if not available at the time the codec may reply with an error status and the controller may retry at a later time. Retrieving multiple DaiSupportedFormats allows for cases where exclusive combinations of the parameters in DaiSupportedFormats may be supported.

Request

<EMPTY>

Response

NameType
payload Codec_GetDaiFormats_Result

GetHealthState

Retrieves top level health state. A driver not responding promptly can be used as an indication of an unhealthy driver.

Request

<EMPTY>

Response

NameType
state HealthState

GetProperties

Retrieves top level static properties.

Added: 20

Request

<EMPTY>

Response

NameType
properties CodecProperties

IsBridgeable

Returns whether a codec is bridgeable.

Deprecation

Not supported anymore, bridged configurations are no longer changeable at runtime. A driver can still be configured to operate in bridged mode or not at boot time.

Removed: 20 Deprecated: 17

Request

<EMPTY>

Response

NameType
supports_bridged_mode bool

Reset

Resets the codec. Reset returns when the reset is completed. If the driver can't successfully reset the codec it will close the codec protocol channel, in this case the client may obtain a new codec protocol channel and retry.

Request

<EMPTY>

Response

<EMPTY>

SetBridgedMode

Sets a codec's bridged mode. This method is required, but it only needs to take action if the codec supports bridged mode as specified by its reply to IsBridgeable.

Deprecation

Not supported anymore, bridged configurations are no longer changeable at runtime. A driver can still be configured to operate in bridged mode or not at boot time.

Removed: 20 Deprecated: 17

Request

NameType
enable_bridged_mode bool

SetDaiFormat

Sets the DAI format to be used in the interface between the controller and codec. Returns an error if not supported at the time of the request (e.g. for removable hardware).

Request

NameType
format DaiFormat

Response

NameType
payload Codec_SetDaiFormat_Result

SignalProcessingConnect

Connect to a SignalProcessing protocol. Multiple connections may be supported, if a new connection request is not supported, i.e. the maximum number of connections have already been created, for instance one, then the protocol channel (not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_ALREADY_BOUND epitaph. If signal processing is not supported at all, then the protocol channel (again, not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_NOT_SUPPORTED epitaph. This method is named SignalProcessingConnect instead of Connect because this protocol is intended to be composed, and hence the more verbose name allows differentiation and improved clarity.

Request

NameType
protocol server_end:fuchsia.hardware.audio.signalprocessing/SignalProcessing

Start

Start/Re-start the codec operation. Start returns when configuring the codec to start is completed. This method does not wait for the hardware to actually start playback/capture (i.e. turn_on_delay impact is not taken into account), nor is any such delay reflected in the returned start_time. start_time indicates when the driver finished configuring the codec to start, as measured in the CLOCK_MONOTONIC timeline. If the driver can't successfully start the codec, it will close the codec protocol channel, in which case the client may obtain a new codec protocol channel and retry.

Request

<EMPTY>

Response

NameType
start_time zx/Time

Stop

Stops the codec operation. Stop returns when configuring the codec to stop is completed. This method does not wait for the hardware to actually stop playback/capture (i.e. turn_off_delay impact is not taken into account), nor is any such delay reflected in the returned stop_time. stop_time indicates when the driver finished configuring the codec to stop, as measured in the CLOCK_MONOTONIC timeline. If the driver cannot successfully configure the codec to stop, it will close the codec protocol channel, in which case the client may obtain a new codec protocol channel and retry.

Request

<EMPTY>

Response

NameType
stop_time zx/Time

WatchPlugState

Get the plug detect state via a hanging get. The driver will reply to the first WatchPlugState sent by the client. The driver will not respond to subsequent client WatchPlugState calls until the plug state changes from what was most recently reported.

Request

<EMPTY>

Response

NameType
plug_state PlugState

CodecConnector

Defined in fuchsia.hardware.audio/codec_connector.fidl

For an overview of the Codec protocols see Codec Interface

Deprecation

Not supported anymore, instead use an Audio Composite with one DAI and no Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

Connect

Connect to a Codec protocol server. This indirection into the Codec protocol allows us to support independent codec client connections.

Request

NameType
codec_protocol server_end:Codec

Composite

Defined in fuchsia.hardware.audio/composite.fidl

The Composite interface is a FIDL protocol exposed by audio drivers. The Composite interface is generic and allows the configuration of various audio hardware types including those supported by the StreamConfig, Dai and Codec FIDL interfaces. The Composite interface is more generic and provides more flexible routing within audio subsystems. Also see Audio Driver Composite

CreateRingBuffer

CreateRingBuffer is sent by clients to select a ring buffer format for the RING_BUFFER processing element specified by processing_element_id. The format is based on information that the driver provides in GetRingBufferFormats, what is supported by the client, and any other requirement. The returned ring_buffer channel is used to access and control the audio buffer provided by the driver. Returns INVALID_ARGS if the processing_element_id does not match an id returned by GetElements. Returns WRONG_TYPE if the ElementType of the element represented by the id is not RING_BUFFER.

Request

NameType
processing_element_id ElementId
format Format
ring_buffer server_end:RingBuffer

Response

NameType
payload Composite_CreateRingBuffer_Result

GetDaiFormats

Retrieves the DAI formats supported by a DAI_INTERCONNECT processing element in the topology supported by this driver as returned by GetElements from fuchsia.hardware.audio.signalprocessing. Returns SHOULD_WAIT if the DAI formats are not available at the time, the client may retry at a later time. Returns INVALID_ARGS if the processing_element_id does not match an id returned by GetElements. Returns WRONG_TYPE if the ElementType of the element represented by the id is not DAI_INTERCONNECT. Retrieving multiple DaiSupportedFormats allows for cases where exclusive combinations of the parameters in SupportedFormats may be supported.

Request

NameType
processing_element_id ElementId

Response

NameType
payload Composite_GetDaiFormats_Result

GetHealthState

Retrieves top level health state. A driver not responding promptly can be used as an indication of an unhealthy driver.

Request

<EMPTY>

Response

NameType
state HealthState

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

NameType
properties CompositeProperties

GetRingBufferFormats

Retrieves the ring buffer formats supported by a RING_BUFFER processing element in the topology supported by this driver as returned by GetElements from fuchsia.hardware.audio.signalprocessing. Returns SHOULD_WAIT if the ring buffer formats are not available at the time, the client may retry at a later time. Returns INVALID_ARGS if the processing_element_id does not match an id returned by GetElements. Returns WRONG_TYPE if the ElementType of the element represented by the id is not RING_BUFFER. Retrieving multiple SupportedFormats allows for cases where exclusive combinations of the parameters in SupportedFormats may be supported.

Request

NameType
processing_element_id ElementId

Response

NameType
payload Composite_GetRingBufferFormats_Result

Reset

Resets the hardware including all DAI interconnects and signal processing. As a result, all channels obtained by CreateRingBuffer will be closed.

Reset returns when the hardware is fully reset. At this point, a client would need to reconfigure any DAI interconnects, select a signal processing topology and reconfigure any processing elements, and reconstruct any ring buffers.

If the driver can't successfully reset the hardware, it will return an error and then close the protocol channel, in this case the client may obtain a new protocol channel and retry.

Request

<EMPTY>

Response

NameType
payload Composite_Reset_Result

SetDaiFormat

SetDaiFormat is sent by clients to select a DAI format for the DAI_INTERCONNECT processing element specified by processing_element_id. The format is based on information that the driver provides in GetDaiFormats, what is supported by the client, and any other requirement. Returns INVALID_ARGS if the processing_element_id does not match an id returned by GetElements. Returns WRONG_TYPE if the ElementType of the element represented by the id is not DAI_INTERCONNECT.

Request

NameType
processing_element_id ElementId
format DaiFormat

Response

NameType
payload Composite_SetDaiFormat_Result

SignalProcessingConnect

Connect to a SignalProcessing protocol. Multiple connections may be supported, if a new connection request is not supported, i.e. the maximum number of connections have already been created, for instance one, then the protocol channel (not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_ALREADY_BOUND epitaph. If signal processing is not supported at all, then the protocol channel (again, not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_NOT_SUPPORTED epitaph. This method is named SignalProcessingConnect instead of Connect because this protocol is intended to be composed, and hence the more verbose name allows differentiation and improved clarity.

Request

NameType
protocol server_end:fuchsia.hardware.audio.signalprocessing/SignalProcessing

CompositeConnector

Defined in fuchsia.hardware.audio/composite_connector.fidl

For an overview see Audio Composite Devices.

Connect

Connect to a Device protocol. This method allows a component to serve FIDL outside the devhost's control.

Request

NameType
composite_protocol server_end:Composite

Dai

Defined in fuchsia.hardware.audio/dai.fidl

For an overview see Digital Audio Interface.

Deprecation

Not supported anymore, instead use an Audio Composite with one DAI and one Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

CreateRingBuffer

CreateRingBuffer is sent by clients to select both a DAI format and a ring buffer format based on information that the driver provides in GetDaiFormats and GetRingBufferFormats, what is supported by the client, and any other requirement. The ring_buffer channel is used to control the audio buffer, if a previous ring buffer channel had been established and was still active, the driver must close that (ring buffer) channel and make every attempt to gracefully quiesce any on-going streaming operations in the process.

Request

NameType
dai_format DaiFormat
ring_buffer_format Format
ring_buffer server_end:RingBuffer

GetDaiFormats

Retrieves the DAI formats supported by the DAI, if not available at the time the DAI may reply with an error status and the client may retry at a later time. Retrieving multiple DaiSupportedFormats allows for cases where exclusive combinations of the parameters in SupportedFormats may be supported.

Request

<EMPTY>

Response

NameType
payload Dai_GetDaiFormats_Result

GetHealthState

Retrieves top level health state. A driver not responding promptly can be used as an indication of an unhealthy driver.

Request

<EMPTY>

Response

NameType
state HealthState

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

NameType
properties DaiProperties

GetRingBufferFormats

Retrieves the ring buffer formats supported by the DAI, if not available at the time the DAI may reply with an error status and the client may retry at a later time. Retrieving multiple SupportedFormats allows for cases where exclusive combinations of the parameters in SupportedFormats may be supported.

Request

<EMPTY>

Response

NameType
payload Dai_GetRingBufferFormats_Result

Reset

Resets the DAI HW. The ring_buffer channel obtained via CreateRingBuffer may be closed by the driver, in this case the client needs to obtain a new ring_buffer. Reset returns when the reset is completed. If the driver can't successfully reset the HW, it will close the DAI protocol channel, in this case the client may obtain a new DAI protocol channel and retry.

Request

<EMPTY>

Response

<EMPTY>

SignalProcessingConnect

Connect to a SignalProcessing protocol. Multiple connections may be supported, if a new connection request is not supported, i.e. the maximum number of connections have already been created, for instance one, then the protocol channel (not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_ALREADY_BOUND epitaph. If signal processing is not supported at all, then the protocol channel (again, not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_NOT_SUPPORTED epitaph. This method is named SignalProcessingConnect instead of Connect because this protocol is intended to be composed, and hence the more verbose name allows differentiation and improved clarity.

Request

NameType
protocol server_end:fuchsia.hardware.audio.signalprocessing/SignalProcessing

DaiConnector

Defined in fuchsia.hardware.audio/dai_connector.fidl

For an overview of the DAI protocols see Digital Audio Interface

Deprecation

Not supported anymore, instead use an Audio Composite with one DAI and one Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

Connect

This connects to a DAI protocol server.

Request

NameType
dai_protocol server_end:Dai

Health

Defined in fuchsia.hardware.audio/health.fidl

GetHealthState

Retrieves top level health state. A driver not responding promptly can be used as an indication of an unhealthy driver.

Request

<EMPTY>

Response

NameType
state HealthState

RingBuffer

Defined in fuchsia.hardware.audio/ring_buffer.fidl

GetProperties

Accessor for top level static properties.

Request

<EMPTY>

Response

NameType
properties RingBufferProperties

GetVmo

Requests a shared buffer to be used for moving bulk audio data between client and driver. The client requests min_frames as the size for part of the ring buffer it needs. The driver returns the actual size of allocated ring buffer space in num_frames.

num_frames must be at least min_frames plus driver_transfer_bytes (in frames) such that ring buffer contents can be transfered in and out, or else the call must be failed with GetVmoError.INVALID_ARGS.

The driver may increase the ring buffer size beyond min_frames plus driver_transfer_bytes (in frames) due to any internal requirements, for instance alignment.

Clients can treat the entire returned ring buffer as safe to access, except for the driver_transfer_bytes immediately adjacent to the current position, see the driver_transfer_bytes parameter specification in RingBufferProperties for more details.

The returned VMO handle must include ZX_RIGHT_TRANSFER, ZX_RIGHT_READ and ZX_RIGHT_MAP. If the ring buffer is "outgoing" (conveys audio data from client to device), then the handle must also include ZX_RIGHT_WRITE.

If clock_recovery_notifications_per_ring is non-zero, the driver will send replies to WatchClockRecoveryPositionInfo client requests at most at clock_recovery_notifications_per_ring frequency. These notifications are meant to be used for clock recovery.

Request

NameType
min_frames uint32
clock_recovery_notifications_per_ring uint32

Response

NameType
payload RingBuffer_GetVmo_Result

SetActiveChannels

Sets which channels are active via a bitmask. The least significant bit corresponds to channel index 0. Channels not set (bits are 0) in the bitmask are inactive. Inactive channels indicate to the driver that it may turn off hardware associated with the inactive channels. A subsequent SetActiveChannels setting an inactive channel to active may incur in a turn_on_delay to actually restart playback/capture of the channels. The total number of channels is the number_of_channels in Format, specifically in PcmFormat, i.e. this bitmask has up to number_of_channels bits set (maximum 64). Deactivating one, several, or all channels does not Stop the ring buffer. SetActiveChannels does not change the ring buffer's behavior with regard to Start/Stop, specifically position. Once Start is called, a ring buffer's position advances (and position notifications sent as needed) regardless of the number of active channels, including if no channels are active. This means that the format in the ring buffer is not changed. By default all channels are active. If the driver does not support deactivating channels it must return ZX_ERR_NOT_SUPPORTED. If the mask is incorrect, i.e. enables channels outside the number of bits to use for a given number_of_channels, then the driver must return ZX_ERR_INVALID_ARGS. The set_time value (in the CLOCK_MONOTONIC timeline) indicates when configuring the hardware to activate or deactivate channels is completed. set_time does not include the potential turn_on_delay, the driver does not delay the reply waiting for the hardware to actually turn on, the driver replies with a set_time indicating when the hardware configuration was completed. If the requested channel configuration is already active, the returned set_time can be before SetActiveChannels was called but must be before the reply is sent. If called again with the same configuration, the reply must include the same set_time value as was previously returned. For input channels, it is not required that the driver zero-out inactive channels. If SetActiveChannels is called for a second time before the first call has completed, the channel must be closed with an error ZX_ERR_BAD_STATE returned.

Request

NameType
active_channels_bitmask uint64

Response

NameType
payload RingBuffer_SetActiveChannels_Result

Start

Start the ring buffer. The start_time value (in the CLOCK_MONOTONIC timeline) indicates when position began moving, starting at the beginning of the ring buffer, i.e. the driver/HW has started to read or write from or to the ring buffer position 0, subject to the buffering described in driver_transfer_bytes.

If Start is called before SetActiveChannels, then by default all channels are active. If Start is called before GetVmo, the channel must be closed with ZX_ERR_BAD_STATE. If Start is called while this RingBuffer is already started, or if Start is called for a second time before the first call has completed, then the channel must be closed with an error ZX_ERR_BAD_STATE returned.

Request

<EMPTY>

Response

NameType
start_time zx/Time

Stop

Stop the ring buffer. Once this call's response is received, no further position notifications will be sent until Start is called again. If Stop is called before GetVmo, the channel must be closed with ZX_ERR_BAD_STATE.

Request

<EMPTY>

Response

<EMPTY>

WatchClockRecoveryPositionInfo

Gets the ring buffer current position via a hanging get. The driver must respond to a client's first WatchClockRecoveryPositionInfo call, but will not respond to subsequent client calls until the position information has changed from what was most recently provided to that client. The driver must not respond to a WatchClockRecoveryPositionInfo until after it has replied to the Start command. At the start_time returned by Start, position is always 0. From there, it progresses at the rate specified by the rate, sample format (and clock domain, if the device is not in the same clock domain asCLOCK_MONOTONIC). If clock_recovery_notifications_per_ring is not zero, the driver will reply with its estimated position to be used for clock recovery at most at clock_recovery_notifications_per_ring frequency. WatchClockRecoveryPositionInfo may only be called after GetVmo was called, hence a clock_recovery_notifications_per_ring was specified. Must be delivered with timestamps that are monotonically increasing. The driver will close the protocol channel with an error of ZX_ERR_BAD_STATE, if there is already a pending WatchClockRecoveryPositionInfo for this client.

Request

<EMPTY>

Response

NameType
position_info RingBufferPositionInfo

WatchDelayInfo

Get information about delays via a hanging get. The driver will immediately reply to the first WatchDelayInfo sent by the client. The driver will not respond to subsequent client WatchDelayInfo calls until the delay info changes from what was most recently reported. If WatchDelayInfo is called for a second time before the first call has completed, the channel must be closed with an error ZX_ERR_BAD_STATE returned.

Added: HEAD

Request

<EMPTY>

Response

NameType
payload RingBuffer_WatchDelayInfo_Result

StreamConfig

Defined in fuchsia.hardware.audio/stream_config.fidl

For an overview see Audio Driver Streaming Interface

Deprecation

Not supported anymore, instead use an Audio Composite with one Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

CreateRingBuffer

CreateRingBuffer is sent by clients to select a stream format based on information that the driver provides in GetSupportedFormats what is supported by the client, and any other requirement. The ring_buffer channel is used to control the audio buffer, if a previous ring buffer channel had been established and was still active, the driver must close that (ring buffer) channel and make every attempt to gracefully quiesce any on-going streaming operations in the process.

Request

NameType
format Format
ring_buffer server_end:RingBuffer

GetHealthState

Retrieves top level health state. A driver not responding promptly can be used as an indication of an unhealthy driver.

Request

<EMPTY>

Response

NameType
state HealthState

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

NameType
properties StreamProperties

GetSupportedFormats

Gets formats supported by a given driver. When not all combinations supported by the driver can be described with one SupportedFormats, the driver returns more than one SupportedFormats in the returned vector. For example, if one SupportedFormats allows for 32 bits samples at 48KHz, and 16 bits samples at 96KHz, but not 32 bits samples at 96KHz, then the driver replies with 2 SupportedFormats: <<32bits>,<48KHz>> and <<16bits>,<96KHz>>. For simplicity, this example ignores parameters other than rate and bits per sample. In the case where the driver supports either 16 or 32 bits samples at either 48 or 96KHz, the driver would reply with 1 SupportedFormats: <<16bits,32bits>,<48KHz,96KHz>>.

Request

<EMPTY>

Response

NameType
supported_formats vector<SupportedFormats>:64

SetGain

Client update of the gain state.

Request

NameType
target_state GainState

SignalProcessingConnect

Connect to a SignalProcessing protocol. Multiple connections may be supported, if a new connection request is not supported, i.e. the maximum number of connections have already been created, for instance one, then the protocol channel (not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_ALREADY_BOUND epitaph. If signal processing is not supported at all, then the protocol channel (again, not the channel upon which SignalProcessingConnect is being called) will be closed with a ZX_ERR_NOT_SUPPORTED epitaph. This method is named SignalProcessingConnect instead of Connect because this protocol is intended to be composed, and hence the more verbose name allows differentiation and improved clarity.

Request

NameType
protocol server_end:fuchsia.hardware.audio.signalprocessing/SignalProcessing

WatchGainState

Get the gain state via a hanging get. The driver will reply to the first WatchGainState sent by the client and this reply must include a gain_db set to 0dB or lower. The driver will not respond to subsequent client WatchGainState calls until the gain state changes from what was most recently reported. If WatchGainState is called for a second time before the first call has completed, then the protocol channel must be closed with the error ZX_ERR_BAD_STATE.

Request

<EMPTY>

Response

NameType
gain_state GainState

WatchPlugState

Get the plug detect state via a hanging get. The driver will reply to the first WatchPlugState sent by the client. The driver will not respond to subsequent client WatchPlugState calls until the plug state changes from what was most recently reported. If WatchPlugState is called for a second time before the first call has completed, then the protocol channel must be closed with the error ZX_ERR_BAD_STATE.

Request

<EMPTY>

Response

NameType
plug_state PlugState

StreamConfigConnector

Defined in fuchsia.hardware.audio/stream_config_connector.fidl

For an overview see Audio Driver Streaming Interface.

Deprecation

Not supported anymore, instead use an Audio Composite with one Ring Buffer, see Audio Drivers Architecture

Deprecated: 20

Connect

Connect to a StreamConfig protocol. This method allows a component to serve FIDL outside the devhost's control.

Request

NameType
protocol server_end:StreamConfig

STRUCTS

Codec_GetDaiFormats_Response

Defined in fuchsia.hardware.audio/codec.fidl

FieldTypeDescriptionDefault
formats vector<DaiSupportedFormats>:64 No default

Codec_SetDaiFormat_Response

Defined in fuchsia.hardware.audio/codec.fidl

FieldTypeDescriptionDefault
state CodecFormatInfo No default

Composite_CreateRingBuffer_Response

Defined in fuchsia.hardware.audio/composite.fidl

<EMPTY>

Composite_GetDaiFormats_Response

Defined in fuchsia.hardware.audio/composite.fidl

FieldTypeDescriptionDefault
dai_formats vector<DaiSupportedFormats>:64 No default

Composite_GetRingBufferFormats_Response

Defined in fuchsia.hardware.audio/composite.fidl

FieldTypeDescriptionDefault
ring_buffer_formats vector<SupportedFormats>:64 No default

Composite_Reset_Response

Defined in fuchsia.hardware.audio/composite.fidl

<EMPTY>

Composite_SetDaiFormat_Response

Defined in fuchsia.hardware.audio/composite.fidl

<EMPTY>

DaiFormat

Defined in fuchsia.hardware.audio/dai_format.fidl

DAI format. Frames are made up of number_of_channels samples which have bits_per_sample bits of data within bits_per_slot arranged in frame_format. For more detailed information see Digital Audio Interface.

FieldTypeDescriptionDefault
number_of_channels uint32

Number of channels.

No default
channels_to_use_bitmask uint64

Sets which channels are active via a bitmask. The least significant bit corresponds to channel index 0.

No default
sample_format DaiSampleFormat

The sample format of all samples.

No default
frame_format DaiFrameFormat

The frame format of all samples.

No default
frame_rate uint32

The frame rate for all samples.

No default
bits_per_slot uint8

The bits per slot for all channels.

No default
bits_per_sample uint8

The bits per sample for all samples. Must be smaller than bits per channel for samples to fit.

No default

DaiFrameFormatCustom

Defined in fuchsia.hardware.audio/dai_format.fidl

Custom Frame format.

FieldTypeDescriptionDefault
left_justified bool

Justification of the samples within a slot.

No default
sclk_on_raising bool

Clocking of data samples and frame sync output on either raising or falling sclk. If true then the sclk raises on the raising edge of the data and frame sync, i.e. the data will be sampled on the falling edge of sclk (the middle of the sclk cycle). Hence, if false then data will be sampled on the raising edge of sclk.

No default
frame_sync_sclks_offset int8

Number of sclks between the beginning of a frame sync change and audio samples. For example, for I2S set to 1 and for stereo left justified set to 0.

No default
frame_sync_size uint8

Number of sclks the frame sync is high within a frame. For example, for I2S with 32 bits slots set to 32, for TDM usually set to 1.

No default

DaiSupportedFormats

Defined in fuchsia.hardware.audio/dai_format.fidl

Formats supported by the DAI. Frames are made up of number_of_channels samples which have bits_per_sample bits of data within bits_per_slot bits arranged in frame_formats. All values listed in each vector are supported. When not all combinations supported by the driver can be described with one DaiSupportedFormats, GetDaiSupportedFormats returns more than one DaiSupportedFormats in the returned vector. For more detailed information see Digital Audio Interface.

FieldTypeDescriptionDefault
number_of_channels vector<uint32>:64

Possible number of channels supported.

No default
sample_formats vector<DaiSampleFormat>:4

Sample formats supported.

No default
frame_formats vector<DaiFrameFormat>:64

Frame formats supported.

No default
frame_rates vector<uint32>:64

Rates supported. Values must be listed in ascending order.

No default
bits_per_slot vector<uint8>:8

The bits per slot supported. Values must be listed in ascending order.

No default
bits_per_sample vector<uint8>:8

Bits per sample supported. Values must be listed in ascending order.

No default

Dai_GetDaiFormats_Response

Defined in fuchsia.hardware.audio/dai.fidl

FieldTypeDescriptionDefault
dai_formats vector<DaiSupportedFormats>:64 No default

Dai_GetRingBufferFormats_Response

Defined in fuchsia.hardware.audio/dai.fidl

FieldTypeDescriptionDefault
ring_buffer_formats vector<SupportedFormats>:64 No default

PcmFormat

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

Format supporting non-compressed PCM audio. Frames are made up of number_of_channels samples which have valid_bits_per_sample bits of most-significant (left-justified) data within bytes_per_sample. bytes. For more detailed information see Audio Driver Streaming Interface.

FieldTypeDescriptionDefault
number_of_channels uint8

Number of channels.

No default
sample_format SampleFormat

The format of all samples.

No default
bytes_per_sample uint8

Bytes allocated to hold a sample, equal or bigger than the valid sample size in valid_bits_per_sample.

No default
valid_bits_per_sample uint8

Number of valid bits in a sample, must be equal or smaller than bits in bytes_per_sample. If smaller, bits are left justified, and any additional bits must be ignored by the receiver.

No default
frame_rate uint32

The frame rate for all samples.

No default

RingBufferPositionInfo

Defined in fuchsia.hardware.audio/ring_buffer.fidl

FieldTypeDescriptionDefault
timestamp zx/Time

The driver's best estimate of the time (in the CLOCK_MONOTONIC timeline) at which the playback/capture pointer reached the position indicated by position. turn_on_delay impact should not be incorporated into 'timestamp'. No delays indicated in DelayInfo should be incorporated.

No default
position uint32

The playback/capture pointer position (in bytes) in the ring buffer at time timestamp as estimated by the driver.

No default

RingBuffer_GetVmo_Response resource

Defined in fuchsia.hardware.audio/ring_buffer.fidl

FieldTypeDescriptionDefault
num_frames uint32 No default
ring_buffer handle<vmo> No default

RingBuffer_SetActiveChannels_Response

Defined in fuchsia.hardware.audio/ring_buffer.fidl

FieldTypeDescriptionDefault
set_time zx/Time No default

RingBuffer_WatchDelayInfo_Response

Defined in fuchsia.hardware.audio/ring_buffer.fidl

FieldTypeDescriptionDefault
delay_info DelayInfo No default

ENUMS

DaiFrameFormatStandard strict

Type: uint8

Defined in fuchsia.hardware.audio/dai_format.fidl

Standard Frame format.

NameValueDescription
1

No frame format as in samples without a frame sync like PDM.

2

Format as specified in the I2S specification (left justified, 2 channels, 32 bits per channel, frame sync stays low for the left channel and high for the right channel, data starts one clock cycle after frame sync changes clocked out at the falling edge of sclk).

3

Left justified, 2 channels. Data starts at frame sync changes from low to high clocked out at the falling edge of sclk. The frame sync must stay high for bits_per_channel bits for the first channel and low for bits_per_channel bits for the second channel.

4

Right justified, 2 channels. The frame sync must stay high for bits_per_channel bits for the first channel and low for bits_per_channel bits for the second channel.

5

Left justified, variable number of channels, data starts at frame sync changes from low to high clocked out at the rising edge of sclk. The frame sync must stay high for exactly 1 clock cycle.

6

Left justified, variable number of channels, data starts one clock cycle after the frame sync changes from low to high clocked out at the rising edge of sclk. The frame sync must stay high for exactly 1 clock cycle.

7

Left justified, variable number of channels, data starts two clock cycles after the frame sync changes from low to high clocked out at the rising edge of sclk. The frame sync must stay high for exactly 1 clock cycle.

DaiSampleFormat strict

Type: uint8

Defined in fuchsia.hardware.audio/dai_format.fidl

NameValueDescription
1

Pulse Density Modulation samples.

2

Signed integer Linear Pulse Code Modulation samples, at the host endianness.

3

Unsigned integer Linear Pulse Code Modulation samples, at the host endianness.

4

Floating point samples, encoded per the IEEE-754 standard.

DeviceType flexible

Type: uint32

Defined in fuchsia.hardware.audio/device_type.fidl

NameValueDescription
1

Device supports the fuchsia.hardware.audio/StreamConfig protocol.

2

Device supports the fuchsia.hardware.audio/Dai protocol.

3

Device supports the fuchsia.hardware.audio/Codec protocol.

4

Device supports the fuchsia.hardware.audio/Composite protocol.

DriverError flexible

Type: uint32

Defined in fuchsia.hardware.audio/common.fidl

NameValueDescription
1

The driver encountered an otherwise unspecified error while performing the operation.

2

The operation is not implemented, supported, or enabled.

3

An argument is invalid.

4

The subject of the operation is the wrong type to perform the operation.

5

The operation cannot be performed currently but potentially could succeed if the caller waits for a prerequisite to be satisfied.

GetVmoError strict

Type: uint32

Defined in fuchsia.hardware.audio/ring_buffer.fidl

NameValueDescription
1

The ring buffer setup failed due to an invalid argument, e.g. min_frames is too big.

2

The ring buffer setup failed due to an internal error.

PlugDetectCapabilities strict

Type: uint32

Defined in fuchsia.hardware.audio/plug.fidl

NameValueDescription
0

Driver is hardwired (will always be plugged in).

1

Driver is able to asynchronously notify of plug state changes.

SampleFormat strict

Type: uint8

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

NameValueDescription
1

Signed integer Linear Pulse Code Modulation samples, at the host endianness.

2

Unsigned integer Linear Pulse Code Modulation samples, at the host endianness.

3

Floating point samples, encoded per the IEEE-754 standard.

TABLES

ChannelAttributes

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

The specification of a single channel, within the overall channel configuration.

OrdinalFieldTypeDescription
min_frequency uint32

Minimum frequency guaranteed to be emitted by (or captured in) this channel, in Hz. If min_frequency is not included, then this channel is assumed to cover the entire low-frequency range of this device.

Optional.

max_frequency uint32

Maximum frequency guaranteed to be emitted by (or captured in) this channel, in Hz. If max_frequency is not included, then this channel is assumed to cover the entire high-frequency range of this device.

Optional.

ChannelSet

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

The specification of a channel configuration.

OrdinalFieldTypeDescription
attributes vector<ChannelAttributes>:64

Describes attributes for this channel set. The size of this vector defines the number of channels supported by this ChannelSet. Each element of the attributes vector defines attributes of a single channel.

Required.

CodecFormatInfo

Defined in fuchsia.hardware.audio/codec.fidl

Codec format information.

OrdinalFieldTypeDescription
external_delay zx/Duration

The driver's best estimate of the external delay (in nanoseconds) present in the pipeline for the chosen format. When precisely synchronizing presentation across multiple entities (e.g. devices), the external delay should be taken into account. If not included external_delay is unknown.

Optional.

turn_on_delay zx/Duration

The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to actually start playback/capture after a Start command is issued. It may take some time for the hardware to get into fully operational mode, for example due a power state change. This delay must be taken into account if not getting the initial audio samples played or captured is not acceptable. If not included turn_on_delay is unknown.

Optional.

turn_off_delay zx/Duration

The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to actually stop playback/capture after a Stop command is issued. It may take some time for the hardware to get into fully stopped mode, for example due a power state change. This delay must be taken into account if playback/capture of samples after a 'Stop' command is not acceptable. If not included, the turn off delay is unknown.

Optional.

CodecProperties

Defined in fuchsia.hardware.audio/codec.fidl

Added: 20

OrdinalFieldTypeDescription
is_input bool

Driver type is input (true) or output (false) If not included, then the driver may be used for both input and output.

Optional.

manufacturer string:256

UI string for the manufacturer name. If not included, the manufacturer is unspecified. If included, this string must be non-empty.

Optional.

product string:256

UI string for the product name. If not included, the product name is unspecified. If included, this string must be non-empty.

Optional.

unique_id array<uint8, 16>

Unique identifier for the codec. If not included, there is no unique id for the Codec.

Optional.

plug_detect_capabilities PlugDetectCapabilities

Plug Detect Capabilities.

Required.

CompositeProperties

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalFieldTypeDescription
manufacturer string:256

UI string for the manufacturer name. If not set, the manufacturer is unknown. If included, this string must be non-empty.

Optional.

product string:256

UI string for the product name. If not set, the product name is unknown. If included, this string must be non-empty.

Optional.

unique_id array<uint8, 16>

A unique identifier. If not included, there is no unique id for the Device. unique_id arrays starting with 0x42, 0x54, ... (or BT in ASCII) are reserved for drivers implementing Bluetooth technologies. unique_id arrays starting with 0x55, 0x53, 0x42, ... (or USB in ASCII) are reserved for drivers implementing USB technologies. Note that even though the above values map to readable ASCII characters, array values can span the entire uint8 range (0-255).

Optional.

clock_domain ClockDomain

An identifier for the clock domain in which this hardware operates. If two hardware devices have the same clock domain, their clock rates are identical and perfectly synchronized. Although these two clocks have the same rate, the clock positions may be offset from each other by an arbitrary (but fixed) amount. The clock_domain typically comes from a system wide entity, such as a platform bus or global clock tree.

There are two special values:

  • CLOCK_DOMAIN_MONOTONIC means the hardware is operating at the same rate as the system montonic clock.

  • CLOCK_DOMAIN_EXTERNAL means the hardware is operating at an unknown rate and is not synchronized with any known clock, not even with other clocks in domain CLOCK_DOMAIN_EXTERNAL.

If the domain is not CLOCK_DOMAIN_MONOTONIC, client must use position notification updates to recover the hardware's clock.

Required.

DaiProperties

Defined in fuchsia.hardware.audio/dai.fidl

OrdinalFieldTypeDescription
is_input bool

Driver type is input (true) or output (false)

Required.

manufacturer string:256

UI string for the manufacturer name. If not included, the manufacturer is unspecified. If included, this string must be non-empty.

Optional.

product_name string:256

UI string for the product name. If not included, the product name is unspecified. If included, this string must be non-empty.

Optional.

unique_id array<uint8, 16>

A unique identifier for the driver. If not included, there is no unique id for the driver.

Optional.

Added: 20
clock_domain ClockDomain

An identifier for the clock domain in which this hardware operates. If two hardware devices have the same clock domain, their clock rates are identical and perfectly synchronized. Although these two clocks have the same rate, the clock positions may be offset from each other by an arbitrary (but fixed) amount. The clock_domain typically comes from a system wide entity, such as a platform bus or global clock tree.

There are two special values:

  • CLOCK_DOMAIN_MONOTONIC means the hardware is operating at the same rate as the system montonic clock.

  • CLOCK_DOMAIN_EXTERNAL means the hardware is operating at an unknown rate and is not synchronized with any known clock, not even with other clocks in domain CLOCK_DOMAIN_EXTERNAL.

If the domain is not CLOCK_DOMAIN_MONOTONIC, client must use position notification updates to recover the hardware's clock.

Required.

Added: 20

DelayInfo

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Delay information as returned by the driver.

Added: HEAD

OrdinalFieldTypeDescription
internal_delay zx/Duration

The driver's best estimate (for the chosen format) of the delay internal to the hardware it abstracts.

"Internal" refers to the hardware between the hardware interconnect (DAI) and the ring buffer (e.g. an SoC audio subsystem), whereas "external" refers to hardware on the far side of any hardware interconnect (DAI) (e.g. hardware codecs).

For a given frame during playback, this is any delay after the driver/HW copies it out of the ring-buffer, before it exits any hardware interconnect. For a given frame during recording, this is any delay after it enters the hardware interconnect, before the driver/HW copies it into the ring-buffer.

internal_delay must be taken into account by the client when determining the requirements for minimum lead time (during playback) and minimum capture delay (during capture).

This delay must not include the inherent delay added by the temporary buffering needed to copy data in and out of the ring buffer, which is contained in RingBufferProperties field driver_transfer_bytes.

Required.

external_delay zx/Duration

The driver's best estimate (for the chosen format) of the delay external to the hardware it abstracts.

"External" refers to hardware on the far side of any hardware interconnect (DAI) (e.g. hardware codecs), whereas "internal" refers to hardware between the hardware interconnect (DAI) and the ring buffer (e.g. an SoC audio subsystem).

external_delay must be taken into account by the client when determining the requirements for minimum lead time (during playback) and minimum capture delay (during capture).

If not included, external_delay is unknown. If unknown, a client may treat it however it chooses (consider it zero or some large number, autodetect it, etc).

Like internal_delay, this delay must not include the inherent delay added by the temporary buffering needed to copy data in and out of the ring buffer, which is contained in RingBufferProperties field driver_transfer_bytes.

Optional.

Format

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

OrdinalFieldTypeDescription
pcm_format PcmFormat

Format supporting non-compressed PCM samples.

Required.

GainState

Defined in fuchsia.hardware.audio/stream_config.fidl

Gain state requested by the client or returned by the driver.

OrdinalFieldTypeDescription
muted bool

Current mute state. If not included, the state is unmuted.

Optional.

agc_enabled bool

Current Automatic Gain Control (AGC) state. If not included, AGC is disabled.

Optional.

gain_db float32

Current gain in decibels.

Required.

HealthState

Defined in fuchsia.hardware.audio/health.fidl

OrdinalFieldTypeDescription
healthy bool

Driver is currently healthy. No health information is provided if this field is not included. This allows drivers to signal their health state in scenarios where they have not enough capabilities or resources to recover on their own, for instance not able to power down the hardware via a GPIO or control over the power subsystem.

Optional.

PcmSupportedFormats

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

Format supporting non-compressed PCM audio. Each frame consists of one or more (number_of_channels) samples, stored contiguously. Within the bytes_per_sample allocated for each sample, valid_bits_per_sample bits of data are stored in the most-significant (left-justified) portion. All values listed in each vector are supported. When not all combinations supported by the driver can be described with one SupportedFormats or PcmSupportedFormats, GetSupportedFormats returns more than one SupportedFormats in the returned vector. For more detailed information see Audio Driver Streaming Interface.

OrdinalFieldTypeDescription
channel_sets vector<ChannelSet>:64

Vector of possible ChannelSets supported. A ChannelSet specifies a channel configuration (including a channel-count), plus a number of optional attributes. Only one ChannelSet is allowed for each unique channel-count. As a result, no two entries in channel_sets can contain attributes vectors with the same length.

Required.

sample_formats vector<SampleFormat>:3

Vector of possible SampleFormats supported.

Required.

bytes_per_sample vector<uint8>:8

Vector of possible bytes allocated for each sample. Values must be listed in ascending order. All values listed in valid_bits_per_sample must fit into at least the largest bytes_per_sample value.

Required.

valid_bits_per_sample vector<uint8>:8

Vector of possible number of bits containing valid data, within the sample container defined by bytes_per_sample. Values must be listed in ascending order. All values listed must fit into the largest bytes_per_sample value. The valid data bits must be most-significant (left-justified) within the sample container, and any additional bits will be ignored.

Required.

frame_rates vector<uint32>:64

Vector of possible frame rates supported. Values must be listed in ascending order.

Required.

PlugState

Defined in fuchsia.hardware.audio/plug.fidl

Plug state as returned by the driver. If the driver reports a plug_detect_capabilities equal to HARDWIRED, then the driver should respond to WatchPlugState only the first time it is called, with plugged set to true and plug_state_time set to time '0'.

OrdinalFieldTypeDescription
plugged bool

Driver is currently plugged in. Required

plug_state_time zx/Time

Timestamps the information provided in the rest of the fields of this struct. Required.

RingBufferProperties

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Properties of the ring buffer. These values don't change once the ring buffer is created.

OrdinalFieldTypeDescription
external_delay zx/Duration

The driver's best estimate (for the chosen format) of the delay external to the hardware it abstracts. External delay must be taken into account when precisely synchronizing presentation across multiple entities (e.g. devices). If not included external_delay is unknown.

Deprecation

Not needed anymore since the functionality is available via WatchDelayInfo below.

Removed: 20 Deprecated: 9
fifo_depth uint32

Size (in bytes) of the temporary buffer used by the driver when consuming or generating ring buffer contents. Required. The ring buffer contents must be produced and consumed at the rate specified with the CreateRingBuffer command, however some amount of buffering is required when the data is written into and read from the ring buffer. For playback the data is consumed by the driver by reading ahead up to fifo_depth bytes. For capture the data is produced by the driver holding up to fifo_depth bytes at the time before committing it to main system memory. Hence fifo_depth must be taken into account by the client when determining either the minimum lead time requirement (for playback) or the maximum capture delay (for capture).

To convert fifo_depth to the corresponding number of audio frames, use the frame size returned by CreateRingBuffer in the StreamConfig protocol, note that the fifo_depth is not necessarily a multiple size of an audio frame.

The ring buffer data may be directly consumed/generated by hardware, in this case fifo_depth maps directly to the size of a hardware FIFO block, since the hardware FIFO block determines the amount of data read ahead or held back.

The ring buffer data may instead be consumed/generated by audio driver software that is conceptually situated between the ring buffer and the audio hardware. In this case, for playback the fifo_depth read ahead amount is set large enough such that the driver guarantees no undetected underruns, this assuming the client is generating the data as determined by the CreateRingBuffer and Start commands. For capture, the fifo_depth held back amount is set large enough such that the driver guarantees no undetected underruns when generating the data as determined by the CreateRingBuffer and Start commands. The driver must set fifo_depth big enough such that the potential delays added by any software interfacing with the audio hardware do not occur under most scenarios, and must detect and report underruns. How an underrun is reported is not defined in this API.

Deprecation

Not needed anymore since the functionality is available via driver_transfer_bytes below.

Removed: 20 Deprecated: 9
needs_cache_flush_or_invalidate bool

When set to true, indicates that the ring buffer runs in a different cache coherency domain, and thus clients must ensure that their data writes are flushed all the way to main memory (during playback), or that their view of the ring buffer must be invalidated before any reads (during capture). This is because there may be hardware external to the CPUs that reads/writes main memory, bypassing the CPUs.

When set to false, indicates that the ring buffer runs in the same cache coherency domain as the CPUs, hence the driver is not required to flush/invalidate the ring buffer. Note that in this case, the driver and client still must synchronize their data access, for instance by inserting the appropriate acquire fences before reading and releasing fences after writing.

Required.

turn_on_delay zx/Duration

The driver's best estimate of the time needed for the hardware to emit (during playback) or accept (during capture) frames, after a channel is activated by SetActiveChannels. The driver estimates that after SetActiveChannels(channel)->(set_time) enables a channel, its data will resume flowing at approximately set_time + turn_on_delay. Hardware can take time to become fully operational (e.g. due to a power state change, or communication delays between a Bluetooth driver's multiple hardware entities). The client must take this delay into account, if it is unacceptable to drop the actual audio frames and instead play/capture silence during this interval. If not included, turn_on_delay is unknown.

Optional.

driver_transfer_bytes uint32

Size (in bytes) of the temporary buffer used by the driver/HW when consuming or generating the ring buffer contents.

The ring buffer contents must be produced and consumed at the rate specified with the CreateRingBuffer command, using data transfers between a temporary buffer and the ring buffer. For playback, audio frames are consumed by the driver in transfers as large as driver_transfer_bytes. For capture, audio frames are produced by the driver in transfers as large as driver_transfer_bytes. In both cases, this many frames must accumulate before they are read from or committed to the ring buffer.

These data transfers mean that there is always a section of the ring buffer that is unsafe for the client to be writing/reading. This unsafe buffer region is defined on one side by the current position 'P', and on the other side by the 'safe pointer' location 'S'. Once the ring buffer starts, these two pointers begin moving. 'P' begins moving from position 0 at the start_time from Start. The region between these pointers must not be read or written by the client at that time. The diagrams below note these pointers as 'P' and 'S'.

During playback, client must write data BEFORE hardware transfers occur. During capture, client can read captured data only AFTER hardware transfers occur. For this reason, during playback 'S' is always ahead of 'P', whereas during capture 'S' is always behind 'P'.

Playback

Before they start the ring buffer, clients may safely write any ring buffer location. It is recommended that they write at least driver_transfer_bytes of initial audio, since they must always stay at least that far ahead of where the driver/HW is reading, and upon Start the hardware might immediately consume that much data from the ring buffer. Otherwise, the client relies on the zeroed-out contents of the VMO to be the initial audio read by the driver/HW.

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

Once the ring buffer is started, it is not safe for the client to write data to the ring buffer between 'P' and 'S', because this represents data already in use (potentially already consumed). The client may safely write the rest of the ring buffer (between 'S' and '0/P').

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

As time passes, the driver/HW reads the data in chunks of driver_transfer_bytes or less, at the rate specified in CreateRingBuffer. The Position/Safe pointers move to the right at the same rate, but do so smoothly. As a result, the "unsafe for client writes" area moves gradually through the ring buffer, while maintaining a constant size equal to driver_transfer_bytes. Thus, after some period we now have:

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

Later, 'S' wraps around the ring buffer before 'P' does. Note that the region from 0 to 'S', plus the region from 'P' to the end of the ring buffer, adds up to driver_transfer_bytes:

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

In steady state, any area outside of the pointers 'P' and 'S' is safe to write:

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

Recording

While recording, it is only safe for the client to read that part of the ring buffer that is not simultaneously being written by the driver/HW. Before capture begins, it may read the entire ring buffer, but the driver has not yet written anything for the client to read. This is the ring buffer at the moment that the client starts the ring buffer:

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

Once capture begins, the driver/HW acquires frames, eventually making its first data transfer to the ring buffer starting at '0'. These transfers are of unknown size but may be as large as driver_transfer_bytes; they occur at the rate specified in CreateRingBuffer. Before the driver/HW has written at least driver_transfer_bytes into the ring buffer, the client cannot yet safely read any of the newly captured frames:

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

Once the driver/HW has written at least driver_transfer_bytes of data into the ring buffer, 'S' begins to smoothly move forward at the same rate as 'P' (as determined by the ring buffer's rate and sample format). The client can safely read frames in the region between '0' and 'S'. It is unsafe for the client to read data between 'S' and 'P', because this is where the driver/HW is simultaneously writing. This region gradually progresses across the ring buffer, maintaining a constant size of driver_transfer_bytes. After some time we have:

                                      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

Later, 'P' wraps around the ring buffer before 'S' does. Note that the region from 0 to 'P', plus the region from 'S' to the end of the ring buffer, adds up to driver_transfer_bytes:

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

In steady state, i.e. once the process has wrapped around the ring buffer, any area outside of pointers 'S' and 'P' is safe to read:

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

Hardware versus software

The ring buffer data may be directly consumed/generated by hardware, i.e. driver_transfer_bytes can be mapped directly to the size of a hardware FIFO block, since a hardware FIFO block determines the upper limit amount of data read ahead or held back. Note that if the FIFO buffer is not used in the traditional "high water" way (such as a "ping pong" design where only half the FIFO size is used at any time -- even during the very first transfers at Start time), then driver_transfer_bytes may be set to a smaller value but must be at least equal to the largest amount of data ever stored in the FIFO buffer. Even if the transfer size never exceeds half the size of the FIFO, if the full size of the FIFO is used (for instance, upon Start when filling an initially empty hardware FIFO), then driver_transfer_bytes must be set to the entire size of the FIFO buffer.

The ring buffer data may instead be consumed/generated by audio driver software that is conceptually situated between the ring buffer and the audio hardware. In this case, for playback, the driver_transfer_bytes read ahead amount must be large enough such that the driver guarantees no undetected underruns, based on the client requirement to generate data based on the CreateRingBuffer rate and the start_time from Start. For capture, driver_transfer_bytes must be large enough for the driver to guarantee no underruns when generating the data as determined by the CreateRingBuffer and Start commands.

driver_transfer_bytes must not include the impact of delays caused by hardware or software processing abstracted by the driver. Those delays are communicated by internal_delay and external_delay fields in DelayInfo; they are orthogonal to this value.

Required.

Added: HEAD

StreamProperties

Defined in fuchsia.hardware.audio/stream_config.fidl

OrdinalFieldTypeDescription
unique_id array<uint8, 16>

A unique identifier. If not included, there is no unique id for the StreamConfig. unique_id arrays starting with 0x42, 0x54, ... (or BT in ASCII) are reserved for drivers implementing Bluetooth technologies. unique_id arrays starting with 0x55, 0x53, 0x42, ... (or USB in ASCII) are reserved for drivers implementing USB technologies. Note that even though the above values map to readable ASCII characters, array values can span the entire uint8 range (0-255).

Optional.

is_input bool

Driver type is input (true) or output (false)

Required.

can_mute bool

Gain mute capability. If not included, the StreamConfig can't mute.

Optional.

can_agc bool

Automatic Gain Control (AGC) capability. If not included, the StreamConfig can't AGC.

Optional.

min_gain_db float32

Minimum gain in decibels.

Required.

max_gain_db float32

Maximum gain in decibels.

Required.

gain_step_db float32

Gain step in decibels, this value must not be negative, but may be zero to convey an effectively continuous range of values. Must not exceed max_gain_db - min_gain_db.

Required.

plug_detect_capabilities PlugDetectCapabilities

Plug Detect Capabilities.

Required.

manufacturer string:256

UI string for the manufacturer name. If not included, the manufacturer is unspecified. If included, this string must be non-empty.

Optional.

product string:256

UI string for the product name. If not included, the product name is unspecified. If included, this string must be non-empty.

Optional.

clock_domain ClockDomain

An identifier for the clock domain in which this hardware operates. If two hardware devices have the same clock domain, their clock rates are identical and perfectly synchronized. Although these two clocks have the same rate, the clock positions may be offset from each other by an arbitrary (but fixed) amount. The clock_domain typically comes from a system wide entity, such as a platform bus or global clock tree.

There are two special values:

  • CLOCK_DOMAIN_MONOTONIC means the hardware is operating at the same rate as the system montonic clock.

  • CLOCK_DOMAIN_EXTERNAL means the hardware is operating at an unknown rate and is not synchronized with any known clock, not even with other clocks in domain CLOCK_DOMAIN_EXTERNAL.

If the domain is not CLOCK_DOMAIN_MONOTONIC, client must use position notification updates to recover the hardware's clock.

Required.

SupportedFormats

Defined in fuchsia.hardware.audio/ring_buffer_format.fidl

All the possible formats supported by this device.

OrdinalFieldTypeDescription
pcm_supported_formats PcmSupportedFormats

Supported formats for non-compressed PCM samples, with attributes.

Required.

UNIONS

Codec_GetDaiFormats_Result strict

Defined in fuchsia.hardware.audio/codec.fidl

OrdinalVariantTypeDescription
response Codec_GetDaiFormats_Response
err zx/Status

Codec_SetDaiFormat_Result strict

Defined in fuchsia.hardware.audio/codec.fidl

OrdinalVariantTypeDescription
response Codec_SetDaiFormat_Response
err zx/Status

Composite_CreateRingBuffer_Result strict

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalVariantTypeDescription
response Composite_CreateRingBuffer_Response
err DriverError

Composite_GetDaiFormats_Result strict

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalVariantTypeDescription
response Composite_GetDaiFormats_Response
err DriverError

Composite_GetRingBufferFormats_Result strict

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalVariantTypeDescription
response Composite_GetRingBufferFormats_Response
err DriverError

Composite_Reset_Result strict

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalVariantTypeDescription
response Composite_Reset_Response
err DriverError

Composite_SetDaiFormat_Result strict

Defined in fuchsia.hardware.audio/composite.fidl

OrdinalVariantTypeDescription
response Composite_SetDaiFormat_Response
err DriverError

DaiFrameFormat strict

Defined in fuchsia.hardware.audio/dai_format.fidl

Either a standard or custom frame format.

OrdinalVariantTypeDescription
frame_format_standard DaiFrameFormatStandard

The format type of all samples in the DAI, listed in DaiFrameFormatStandard.

frame_format_custom DaiFrameFormatCustom

The format type of all samples in the DAI, specified in DaiFrameFormatCustom.

Dai_GetDaiFormats_Result strict

Defined in fuchsia.hardware.audio/dai.fidl

OrdinalVariantTypeDescription
response Dai_GetDaiFormats_Response
err zx/Status

Dai_GetRingBufferFormats_Result strict

Defined in fuchsia.hardware.audio/dai.fidl

OrdinalVariantTypeDescription
response Dai_GetRingBufferFormats_Response
err zx/Status

RingBuffer_GetVmo_Result strict resource

Defined in fuchsia.hardware.audio/ring_buffer.fidl

OrdinalVariantTypeDescription
response RingBuffer_GetVmo_Response
err GetVmoError

RingBuffer_SetActiveChannels_Result strict

Defined in fuchsia.hardware.audio/ring_buffer.fidl

OrdinalVariantTypeDescription
response RingBuffer_SetActiveChannels_Response
err zx/Status

RingBuffer_WatchDelayInfo_Result strict

Defined in fuchsia.hardware.audio/ring_buffer.fidl

OrdinalVariantTypeDescription
response RingBuffer_WatchDelayInfo_Response
framework_err internal

CONSTANTS

NameValueTypeDescription
CLOCK_DOMAIN_EXTERNAL 4294967295 uint32
CLOCK_DOMAIN_MONOTONIC 0 uint32
MAX_COUNT_CHANNELS_IN_RING_BUFFER 64 uint32
MAX_COUNT_CHANNEL_SETS 64 uint32
MAX_COUNT_DAI_FORMATS MAX_COUNT_FORMATS uint32
MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE 8 uint32
MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT 8 uint32
MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS 64 uint32
MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS 64 uint32
MAX_COUNT_DAI_SUPPORTED_RATES 64 uint32
MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS 4 uint32
MAX_COUNT_FORMATS 64 uint32
MAX_COUNT_SUPPORTED_BYTES_PER_SAMPLE 8 uint32
MAX_COUNT_SUPPORTED_NUMBER_OF_CHANNELS 64 uint32
MAX_COUNT_SUPPORTED_RATES 64 uint32
MAX_COUNT_SUPPORTED_SAMPLE_FORMATS 3 uint32
MAX_COUNT_SUPPORTED_VALID_BITS_PER_SAMPLE 8 uint32
MAX_DAI_UI_STRING_SIZE 256 uint32
MAX_UI_STRING_SIZE 256 uint32
UNIQUE_ID_SIZE 16 uint32

ALIASES

NameValueDescription
ClockDomain uint32
ElementId uint64
TopologyId uint64

SERVICES

CodecConnectorService

Defined in fuchsia.hardware.audio/codec_connector.fidl

NameTypeTransport
codec_connector fuchsia.hardware.audio/CodecConnector Channel

CodecService

Defined in fuchsia.hardware.audio/codec.fidl

NameTypeTransport
codec fuchsia.hardware.audio/Codec Channel

CompositeConnectorService

Defined in fuchsia.hardware.audio/composite_connector.fidl

NameTypeTransport
composite_connector fuchsia.hardware.audio/CompositeConnector Channel

DaiConnectorService

Defined in fuchsia.hardware.audio/dai_connector.fidl

NameTypeTransport
dai_connector fuchsia.hardware.audio/DaiConnector Channel

DaiService

Defined in fuchsia.hardware.audio/dai.fidl

NameTypeTransport
dai fuchsia.hardware.audio/Dai Channel

DeviceService

Defined in fuchsia.hardware.audio/composite.fidl

NameTypeTransport
device fuchsia.hardware.audio/Composite Channel

StreamConfigConnectorService

Defined in fuchsia.hardware.audio/stream_config_connector.fidl

NameTypeTransport
stream_config_connector fuchsia.hardware.audio/StreamConfigConnector Channel

StreamConfigService

Defined in fuchsia.hardware.audio/stream_config.fidl

NameTypeTransport
stream_config fuchsia.hardware.audio/StreamConfig Channel