fuchsia.hardware.audio

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

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

Name	Type
`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

Name	Type
`state`	`HealthState`

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

Name	Type
`properties`	`CodecProperties`

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>

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

Name	Type
`format`	`DaiFormat`

Response

Name	Type
`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

Name	Type
`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

Name	Type
`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

Name	Type
`stop_time`	`zx/Time`

WatchPlugState

Request

<EMPTY>

Response

Name	Type
`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

Connect

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

Request

Name	Type
`codec_protocol`	`server_end:Codec`

Composite

Added: HEAD

CreatePacketStream

CreatePacketStream is sent by clients to select a packet-stream format for the PACKET_STREAM processing element specified by processing_element_id. The format is based on information that the driver provides in GetPacketStreamFormats, what is supported by the client, and any other requirement. The returned packet_stream channel is used to access and control the packet stream protocol served 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 PACKET_STREAM. Returns SHOULD_WAIT if the server cannot create a packet stream for this element/format at this time, but it should be able to at some future time. This request can be retried. Returns NOT_SUPPORTED if the driver does not support packet streams, or if the specified format is not supported.

Added: HEAD

Request

Name	Type
`processing_element_id`	`ElementId`
`format`	`Format2`
`packet_stream_control`	`server_end:PacketStreamControl`

Response

Name	Type
`payload`	`Composite_CreatePacketStream_Result`

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. Returns NOT_SUPPORTED if the driver does not support ring buffers, or if the specified format is not supported.

Request

Name	Type
`processing_element_id`	`ElementId`
`format`	`Format2`
`ring_buffer`	`server_end:RingBuffer`

Response

Name	Type
`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 DaiSupportedFormats may be supported. The vector returned to the caller must contain at least one entry.

Request

Name	Type
`processing_element_id`	`ElementId`

Response

Name	Type
`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

Name	Type
`state`	`HealthState`

GetPacketStreamFormats

Retrieves the packet-stream formats supported by a PACKET_STREAM processing element in the topologies supported by this driver, as returned by GetElements and GetTopologies from fuchsia.hardware.audio.signalprocessing.

Returns SHOULD_WAIT if the packet-stream formats are not available at this time. The client may retry this request 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 PACKET_STREAM. Returns NOT_SUPPORTED if the driver does not support packet streams. Returning a vector with multiple SupportedFormats2 enables cases where exclusive combinations of the parameters in SupportedFormats2 may be supported. The vector returned to the caller must contain at least one entry.

Added: HEAD

Request

Name	Type
`processing_element_id`	`ElementId`

Response

Name	Type
`payload`	`Composite_GetPacketStreamFormats_Result`

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

Name	Type
`payload`	`Composite_GetProperties_Result`

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 SupportedFormats2 allows for cases where exclusive combinations of the parameters in SupportedFormats2 may be supported. The vector returned to the caller must contain at least one entry.

Request

Name	Type
`processing_element_id`	`ElementId`

Response

Name	Type
`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

Name	Type
`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

Name	Type
`processing_element_id`	`ElementId`
`format`	`DaiFormat`

Response

Name	Type
`payload`	`Composite_SetDaiFormat_Result`

SignalProcessingConnect

Request

Name	Type
`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

Name	Type
`composite_protocol`	`server_end:Composite`

Dai

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

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

Name	Type
`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

Name	Type
`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

Name	Type
`state`	`HealthState`

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

Name	Type
`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

Name	Type
`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

Request

Name	Type
`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

Connect

This connects to a DAI protocol server.

Request

Name	Type
`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

Name	Type
`state`	`HealthState`

PacketStreamControl

Defined in fuchsia.hardware.audio/packet_stream.fidl

Control protocol for establishing and managing the packet stream.

Added: HEAD

AllocateVmos

Request the driver to allocate VMOs for data transfer. Returns the allocated VMOs and their assigned IDs.

The returned VMO handle must include ZX_RIGHT_TRANSFER, ZX_RIGHT_READ and ZX_RIGHT_MAP. If the packet stream is an output stream, then the handle must also include ZX_RIGHT_WRITE.

Returns ZX_ERR_INVALID_ARGS if min_vmo_size is zero or vmo_count is zero. Returns ZX_ERR_NO_MEMORY if the driver cannot allocate the requested VMOs. Returns ZX_ERR_BAD_STATE if VMOs are already allocated or registered, or if the stream is already started. Call DeallocateVmos or UnregisterVmos first to reconfigure.

Request

Name	Type
`payload`	`AllocateVmosConfig`

Response

Name	Type
`payload`	`PacketStreamControl_AllocateVmos_Result`

DeallocateVmos

Releases all VMOs previously allocated via AllocateVmos. This also occurs automatically when the PacketStreamControl channel is closed.

Returns ZX_ERR_BAD_STATE if VMOs are not currently allocated, or if the stream is not stopped.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_DeallocateVmos_Result`

GetPacketStreamSink

Connects to the data sink implemented by the driver. This is used for audio Output where the driver consumes data.

Flow:

App writes audio data to a registered VMO.
App flushes the cache for the written region (if needs_cache_flush_or_invalidate is true).
App calls PacketStreamSink.PutPacket with the location of the data.
Driver consumes the data.

If this method is called multiple times, the previous PacketStreamSink channel is closed, and any pending requests on that channel are discarded. The new channel replaces the old one.

Returns ZX_ERR_NOT_SUPPORTED if the stream is an input stream, or if the driver does not support this method.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_GetPacketStreamSink_Result`

GetProperties

Accessor for top level static properties.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_GetProperties_Result`

RegisterVmos

Registers client-allocated VMOs with the driver.

The registered VMO handle must include ZX_RIGHT_TRANSFER, ZX_RIGHT_READ and ZX_RIGHT_MAP. If the packet stream is an input stream, then the handle must also include ZX_RIGHT_WRITE.

Returns ZX_ERR_INVALID_ARGS if vmo_infos is empty, or if any VMO handle is invalid, or if duplicate vmo_ids are found. Returns ZX_ERR_ACCESS_DENIED if any VMO does not have the required rights. Returns ZX_ERR_BAD_STATE if VMOs are already registered or allocated, or if the stream is already started. Call UnregisterVmos or DeallocateVmos first to reconfigure.

Request

Name	Type
`payload`	`RegisterVmosConfig`

Response

Name	Type
`payload`	`PacketStreamControl_RegisterVmos_Result`

SetPacketStreamSink

Provides a data sink to the driver. This is used for audio Input where the driver produces data.

Flow:

Driver writes audio data to a registered VMO.
Driver calls PacketStreamSink.PutPacket with the location of the data.
App receives PutPacket.
App invalidates the cache for the region (if needs_cache_flush_or_invalidate is true).
App reads the data.

If this method is called multiple times, the driver closes the previous PacketStreamSink channel. The new channel replaces the old one.

Returns ZX_ERR_NOT_SUPPORTED if the stream is an output stream, or if the driver does not support this method.

Request

Name	Type
`payload`	`PacketStreamControlSetPacketStreamSinkRequest`

Response

Name	Type
`payload`	`PacketStreamControl_SetPacketStreamSink_Result`

Start

Start the packet-stream.

Returns ZX_ERR_BAD_STATE if:

Buffers have not been allocated (if DRIVER_OWNED was specified) and/or registered (if CLIENT_OWNED was specified). This is not applicable if INLINE is supported.
The stream is already started.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_Start_Result`

Stop

Stop the packet-stream.

Once the response is received, the stream is halted.

Behavior depends on the stream direction:

Output: The driver stops consuming packets. Any pending PacketStreamSink.PutPacket requests will remain pending until Start is called again. Clients may call PacketStreamSink.FlushPackets after Stop to discard these pending packets.
Input: The driver stops producing packets. No further PacketStreamSink.PutPacket calls will be made by the driver until Start is called again.

Note that since PacketStreamSink uses a separate channel, there is no strict ordering guarantee between Stop and PacketStreamSink.PutPacket:

For Output, some in-flight PacketStreamSink.PutPacket calls may complete successfully after Stop has returned.
For Input, some in-flight PacketStreamSink.PutPacket calls may arrive at the client after Stop has returned.

Returns ZX_ERR_BAD_STATE if the stream is not started.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_Stop_Result`

UnregisterVmos

Unregisters all VMOs previously registered via RegisterVmos. This also occurs automatically when the PacketStreamControl channel is closed.

Returns ZX_ERR_BAD_STATE if VMOs are not currently registered, or if the stream is not stopped.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamControl_UnregisterVmos_Result`

PacketStreamSink

Defined in fuchsia.hardware.audio/packet_stream.fidl

The protocol for streaming packet-based audio data. This protocol functions as a data sink. The "server" of this protocol consumes packets, and the "client" produces packets.

This protocol can be used in two directions:

Output (Client -> Driver): The Driver implements PacketStreamSink. The Client (App) calls PutPacket.
Input (Driver -> Client): The Client (App) implements PacketStreamSink. The Driver calls PutPacket.

Added: HEAD

FlushPackets

Flushes all packets currently pending without processing them. This call waits until all pending packets are completed or canceled.

Note: A packet may be partially processed (e.g. if it contains multiple audio frames, or if the data does not align with encoded frame boundaries) before it is canceled.

Request

<EMPTY>

Response

Name	Type
`payload`	`PacketStreamSink_FlushPackets_Result`

PutPacket

Submits a packet to be processed by the server.

The client may queue multiple packets by calling PutPacket repeatedly. Packets are processed in the order they were submitted. This call blocks until the payload is processed. When this call returns, the buffer region is guaranteed to be available for reuse.

Returns ZX_ERR_BAD_STATE if the stream is not started or configured. Returns ZX_ERR_CANCELED if FlushPackets was called. Returns ZX_ERR_INVALID_ARGS if the packet is invalid. This includes:

The payload is missing.
inline_data is used but supported_buffer_types does not include INLINE.
vmo_transfer is used but supported_buffer_types does not include CLIENT_OWNED or DRIVER_OWNED.
vmo_id is unrecognized, or vmo_offset + payload_size exceeds the VMO size.

Note: The server is not required to detect if a VMO region is currently in use by a previous pending packet. Clients are responsible for managing buffer usage.

Request

Name	Type
`payload`	`PacketStreamSinkPutPacketRequest`

Response

Name	Type
`payload`	`PacketStreamSink_PutPacket_Result`

RingBuffer

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Ring buffers are used to convey audio between parties (usually in different processes), allowing concurrent, asynchronous data access without requiring locks. This pattern works because both parties share an understanding of which buffer areas are safe to access, and how those areas change over time.

For in-depth description of the responsibilities for both producers and consumers, before the ring buffer is started as well as while it is active, please see Ring Buffer Behavior.

GetProperties

Accessor for top level static properties.

Request

<EMPTY>

Response

Name	Type
`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

Name	Type
`min_frames`	`uint32`
`clock_recovery_notifications_per_ring`	`uint32`

Response

Name	Type
`payload`	`RingBuffer_GetVmo_Result`

SetActiveChannels

Sets which channels are active via a bitmask.

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). The least significant bit corresponds to channel index 0. Channels not set (bits are 0) in the bitmask are inactive. By default all channels are active. Hence creating a RingBuffer turns on the hardware associated for all channels.

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.

Deactivating one, several, or all channels does not Stop the ring buffer, nor does it change the ring buffer's behavior with regard to 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.

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

Name	Type
`active_channels_bitmask`	`uint64`

Response

Name	Type
`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 has started to read or write from or to the ring buffer position 0, subject to the overall position and buffering behavior described in 'Ring buffer behavior' below.

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. If Start is called before SetActiveChannels, then by default all channels are active.

Request

<EMPTY>

Response

Name	Type
`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.

WatchClockRecoveryPositionInfo may only be called after GetVmo was called, where a clock_recovery_notifications_per_ring was specified.

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.

The RingBufferPositionInfo return values must include 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

Name	Type
`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: 27

Request

<EMPTY>

Response

Name	Type
`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

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

Name	Type
`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

Name	Type
`state`	`HealthState`

GetProperties

Retrieves top level static properties.

Request

<EMPTY>

Response

Name	Type
`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

Name	Type
`supported_formats`	`vector<SupportedFormats>:64`

SetGain

Client update of the gain state.

Request

Name	Type
`target_state`	`GainState`

SignalProcessingConnect

Request

Name	Type
`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

Name	Type
`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

Name	Type
`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

Connect

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

Request

Name	Type
`protocol`	`server_end:StreamConfig`

STRUCTS

Codec_GetDaiFormats_Response

Field	Type	Description	Default
`formats`	`vector<DaiSupportedFormats>:64`		No default

Codec_SetDaiFormat_Response

Field	Type	Description	Default
`state`	`CodecFormatInfo`		No default

Composite_CreatePacketStream_Response

<EMPTY>

Composite_CreateRingBuffer_Response

<EMPTY>

Composite_GetDaiFormats_Response

Field	Type	Description	Default
`dai_formats`	`vector<DaiSupportedFormats>:64`		No default

Composite_GetPacketStreamFormats_Response

Field	Type	Description	Default
`packet_stream_formats`	`vector<SupportedFormats2>:64`		No default

Composite_GetProperties_Response

Field	Type	Description	Default
`properties`	`CompositeProperties`		No default

Composite_GetRingBufferFormats_Response

Field	Type	Description	Default
`ring_buffer_formats`	`vector<SupportedFormats2>:64`		No default

Composite_Reset_Response

<EMPTY>

Composite_SetDaiFormat_Response

<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.

Field	Type	Description	Default
`number_of_channels`	`uint32`	Number of channels. Must be 2, if `frame_format` is DaiFrameFormatStandard::I2S, STEREO_LEFT or STEREO_RIGHT.	No default
`channels_to_use_bitmask`	`uint64`	Sets which channels are active via a bitmask. The least significant bit corresponds to channel index 0. Must not set bits beyond the least-significant `number_of_channels` bits.	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 each channel. Must be smaller than `bits_per_slot` for all samples to fit.	No default

DaiFrameFormatCustom

Defined in fuchsia.hardware.audio/dai_format.fidl

Custom Frame format.

Field	Type	Description	Default
`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.

Field	Type	Description	Default
`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

Field	Type	Description	Default
`dai_formats`	`vector<DaiSupportedFormats>:64`		No default

Dai_GetRingBufferFormats_Response

Field	Type	Description	Default
`ring_buffer_formats`	`vector<SupportedFormats>:64`		No default

PacketStreamControl_AllocateVmos_Response resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Field	Type	Description	Default
`vmos`	`VmoInfos`		No default

PacketStreamControl_DeallocateVmos_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamControl_GetProperties_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

Field	Type	Description	Default
`properties`	`PacketStreamProperties`		No default

PacketStreamControl_RegisterVmos_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamControl_SetPacketStreamSink_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamControl_Start_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamControl_Stop_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamControl_UnregisterVmos_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PacketStreamSink_FlushPackets_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

<EMPTY>

PcmFormat

Defined in fuchsia.hardware.audio/pcm_format.fidl

Format supporting 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.

Field	Type	Description	Default
`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, must be greater than or equal to 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 less than or equal to `bytes_per_sample * 8`. If less than `bytes_per_sample * 8`, the valid bits (those containing audio) 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

Field Type Description Default

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

Field	Type	Description	Default
`num_frames`	`uint32`		No default
`ring_buffer`	`handle<vmo>`		No default

RingBuffer_SetActiveChannels_Response

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Field	Type	Description	Default
`set_time`	`zx/Time`		No default

RingBuffer_WatchDelayInfo_Response

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Field	Type	Description	Default
`delay_info`	`DelayInfo`		No default

ENUMS

DaiFrameFormatStandard strict

Type: uint8

Defined in fuchsia.hardware.audio/dai_format.fidl

Standard Frame format.

Name	Value	Description
NONE	`1`	No frame format as in samples without a frame sync like PDM.
I2S	`2`	Format as specified in the I2S specification (left justified, 2 channels, 32 bits per sample, 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).
STEREO_LEFT	`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_sample` bits for the first channel and low for `bits_per_sample` bits for the second channel.
STEREO_RIGHT	`4`	Right justified, 2 channels. The frame sync must stay high for `bits_per_sample` bits for the first channel and low for `bits_per_sample` bits for the second channel.
TDM1	`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.
TDM2	`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.
TDM3	`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

Name	Value	Description
PDM	`1`	Pulse Density Modulation samples.
PCM_SIGNED	`2`	Signed integer Linear Pulse Code Modulation samples, at the host endianness.
PCM_UNSIGNED	`3`	Unsigned integer Linear Pulse Code Modulation samples, at the host endianness.
PCM_FLOAT	`4`	Floating point samples, encoded per the IEEE-754 standard.

DeviceType flexible

Type: uint32

Defined in fuchsia.hardware.audio/device_type.fidl

Name	Value	Description
STREAM_CONFIG	`1`	Device supports the fuchsia.hardware.audio/StreamConfig protocol.
DAI	`2`	Device supports the fuchsia.hardware.audio/Dai protocol.
CODEC	`3`	Device supports the fuchsia.hardware.audio/Codec protocol.
COMPOSITE	`4`	Device supports the fuchsia.hardware.audio/Composite protocol.

DriverError flexible

Type: uint32

Defined in fuchsia.hardware.audio/common.fidl

Name	Value	Description
INTERNAL_ERROR	`1`	The driver encountered an otherwise unspecified error while performing the operation.
NOT_SUPPORTED	`2`	The operation is not implemented, supported, or enabled.
INVALID_ARGS	`3`	An argument is invalid.
WRONG_TYPE	`4`	The subject of the operation is the wrong type to perform the operation.
SHOULD_WAIT	`5`	The operation cannot be performed currently but potentially could succeed if the caller waits for a prerequisite to be satisfied.
FATAL_ERROR	`6`	A fatal error has occurred in the driver. The connection is no longer usable and the client should close it. Added: 29

EncodingType flexible

Type: uint32

Defined in fuchsia.hardware.audio/encoding.fidl

The type of encoding used for the stream.

Added: HEAD

Name	Value	Description
AAC	`1`
SBC	`2`

GetVmoError strict

Type: uint32

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Name	Value	Description
INVALID_ARGS	`1`	The ring buffer setup failed due to an invalid argument, e.g. min_frames is too big.
INTERNAL_ERROR	`2`	The ring buffer setup failed due to an internal error.

PlugDetectCapabilities strict

Type: uint32

Defined in fuchsia.hardware.audio/plug.fidl

Name	Value	Description
HARDWIRED	`0`	Driver is hardwired (will always be plugged in).
CAN_ASYNC_NOTIFY	`1`	Driver is able to asynchronously notify of plug state changes.

SampleFormat strict

Type: uint8

Defined in fuchsia.hardware.audio/pcm_format.fidl

Name	Value	Description
PCM_SIGNED	`1`	Signed integer Linear Pulse Code Modulation samples, at the host endianness.
PCM_UNSIGNED	`2`	Unsigned integer Linear Pulse Code Modulation samples, at the host endianness.
PCM_FLOAT	`3`	Floating point samples, encoded per the IEEE-754 standard.

SingularUniqueId flexible

Type: uint8

Defined in fuchsia.hardware.audio/unique_id.fidl

Identifies devices that are unique within the system. A UniqueId for these devices consists of the enum value followed by (UNIQUE_ID_SIZE - 1) zeroes.

Added: HEAD

Name	Value	Description
DSP	`0`
BUILTIN_SPEAKERS	`1`
BUILTIN_HEADPHONE_JACK	`2`
BUILTIN_MICROPHONE	`3`
BUILTIN_HEADSET_JACK	`4`

TABLES

AllocateVmosConfig

Defined in fuchsia.hardware.audio/packet_stream.fidl

Added: HEAD

Ordinal Field Type Description

1

min_vmo_size

uint64

The minimum size required for each VMO, in bytes.

Required.

2

vmo_count

uint32

The number of VMOs to allocate.

Required.

ChannelAttributes

Defined in fuchsia.hardware.audio/pcm_format.fidl

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

Ordinal Field Type Description

1

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.

2

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/pcm_format.fidl

The specification of a channel configuration.

Ordinal Field Type Description

1

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

Codec format information.

Ordinal Field Type Description

1

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.

2

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.

3

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

Ordinal	Field	Type	Description
1	`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.
2	`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.
3	`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.
4	`unique_id`	`UniqueId`	Unique identifier for the codec. If not included, there is no unique id for this Codec. See `unique_id.fidl` for considerations about specific pre-defined values and ranges. Optional.
5	`plug_detect_capabilities`	`PlugDetectCapabilities`	Plug Detect Capabilities. Required.

CompositeProperties

Ordinal	Field	Type	Description
2	`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.
3	`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.
4	`unique_id`	`UniqueId`	A unique identifier. If not included, there is no unique id for this Device. See `unique_id.fidl` for considerations about specific pre-defined values and ranges. Optional.
5	`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

Ordinal	Field	Type	Description
1	`is_input`	`bool`	Driver type is input (true) or output (false) Required.
2	`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.
3	`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.
4	`unique_id`	`UniqueId`	A unique identifier for the DAI. If not included, there is no unique id for this DAI. See `unique_id.fidl` for considerations about specific pre-defined values and ranges. Optional.
5	`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.

DelayInfo

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Delay information as returned by the driver.

Added: 27

Ordinal Field Type Description

1

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 DAI interconnect and the ring buffer (such as an SoC audio subsystem), whereas "external" refers to hardware on the far side of any DAI interconnect (such as hardware codecs).

For a given frame during playback, this is any delay after the driver copies it out of the ring buffer, before it exits any interconnect. For a given frame during recording, this is any delay after it enters the interconnect, before the driver moves 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.

2

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 DAI interconnect (such as hardware codecs), whereas "internal" refers to hardware between the DAI interconnect and the ring buffer (such as 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.

Encoding

Defined in fuchsia.hardware.audio/encoding.fidl

Format specification for an encoded audio stream.

Added: HEAD

Ordinal	Field	Type	Description
1	`decoded_channel_count`	`uint32`	Number of channels for the stream, once it is decoded. Required.
2	`decoded_frame_rate`	`uint32`	The frame rate for the stream, once it is decoded. This is a hint for decoders. Optional.
3	`average_encoding_bitrate`	`uint32`	The average bitrate of the stream in bits per second. Required.
4	`encoding_type`	`EncodingType`	The encoding type for the stream. Required.

Format

Deprecated: Use Format2 instead.

Ordinal	Field	Type	Description
1	`pcm_format`	`PcmFormat`

GainState

Defined in fuchsia.hardware.audio/stream_config.fidl

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

Ordinal Field Type Description

1

muted

bool

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

Optional.

2

agc_enabled

bool

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

Optional.

3

gain_db

float32

Current gain in decibels.

Required.

HealthState

Defined in fuchsia.hardware.audio/health.fidl

Ordinal Field Type Description

1

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.

PacketStreamControlSetPacketStreamSinkRequest resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Field	Type	Description
1	`stream`	`client_end:PacketStreamSink`

PacketStreamControl_GetPacketStreamSink_Response resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Field	Type	Description
1	`stream`	`client_end:PacketStreamSink`

PacketStreamProperties

Defined in fuchsia.hardware.audio/packet_stream.fidl

Properties of the packet-stream. These values don't change once the packet-stream is created.

Added: HEAD

Ordinal Field Type Description

1

needs_cache_flush_or_invalidate

bool

When set to true, indicates that the packet-stream runs in a different cache coherency domain. Clients must ensure data writes are flushed to main memory (during output) or invalidated before reading (during input).

When set to false, the server and client are in the same coherency domain. Synchronization (e.g., fences) is still required to order reads and writes.

Required.

2

supported_buffer_types

BufferType

The buffer methods supported by this driver.

Required.

PacketStreamSinkPutPacketRequest resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal Field Type Description

1

payload

DataTransfer

Location of the payload for this packet.

Required.

PacketStreamSink_PutPacket_Response

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Field	Type	Description

PcmSupportedFormats

Defined in fuchsia.hardware.audio/pcm_format.fidl

Format supporting 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. This implies a cross-product: any listed item in one vector is supported in combination with any listed item in another vector. When not all combinations supported by the driver can be described with one PcmSupportedFormats table, GetSupportedFormats must return a vector with multiple SupportedFormats entries.

For more detailed information see Audio Driver Streaming Interface.

Ordinal	Field	Type	Description
1	`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.
2	`sample_formats`	`vector<SampleFormat>:3`	Vector of possible `SampleFormat`s supported. Required.
3	`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.
4	`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.
5	`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'.

Ordinal	Field	Type	Description
1	`plugged`	`bool`	Driver is currently plugged in. Required
2	`plug_state_time`	`zx/Time`	Timestamps the information provided in the rest of the fields of this struct. Required.

RegisterVmosConfig resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Added: HEAD

Ordinal Field Type Description

1

vmo_infos

VmoInfos

The list of VMOs to register with the driver.

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.

Ordinal Field Type Description

3

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, or (more commonly) by obeying the Producer/Consumer pattern described in Ring Buffer Behavior.

Required.

4

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.

5

driver_transfer_bytes

uint32

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

The driver_transfer_bytes field is covered extensively in Ring Buffer Behavior.

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: 27

StreamProperties

Defined in fuchsia.hardware.audio/stream_config.fidl

Ordinal	Field	Type	Description
1	`unique_id`	`UniqueId`	A unique identifier. If not included, there is no unique id for this StreamConfig. See `unique_id.fidl` for considerations about specific pre-defined values and ranges. Optional.
2	`is_input`	`bool`	Driver type is input (true) or output (false) Required.
3	`can_mute`	`bool`	Gain mute capability. If not included, the StreamConfig can't mute. Optional.
4	`can_agc`	`bool`	Automatic Gain Control (AGC) capability. If not included, the StreamConfig can't AGC. Optional.
5	`min_gain_db`	`float32`	Minimum gain in decibels. Required.
6	`max_gain_db`	`float32`	Maximum gain in decibels. Required.
7	`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.
8	`plug_detect_capabilities`	`PlugDetectCapabilities`	Plug Detect Capabilities. Required.
9	`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.
10	`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.
11	`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.

SupportedEncodings

Defined in fuchsia.hardware.audio/encoding.fidl

Supported formats for encoded audio.

This table defines a valid set of configurations. All fields are independent, which implies a cross-product: any listed channel_set is supported at any listed frame_rate for any listed encoded_type.

If a device supports multiple encoders with different rate/channel constraints (e.g. AAC supports 48kHz but SBC only supports 44.1kHz), the device must report them as separate entries in the SupportedFormats vector.

Added: HEAD

Ordinal	Field	Type	Description
1	`decoded_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. Each entry in this vector must describe a unique channel count. For example, this vector cannot contain two different `ChannelSet` entries that both apply to a 2-channel configuration. Required.
2	`decoded_frame_rates`	`vector<uint32>:64`	Vector of possible frame rates supported. If present, must contain at least one value. Values must be listed in ascending order. Optional.
3	`min_encoding_bitrate`	`uint32`	The minimum encoding bitrate of the stream in bits per second. Cannot exceed 'max_encoding_bitrate', if both are present. Optional.
4	`max_encoding_bitrate`	`uint32`	The maximum encoding bitrate of the stream in bits per second. Cannot be less than 'min_encoding_bitrate', if both are present. Optional.
5	`encoding_types`	`vector<EncodingType>:64`	The encoder types that support the configurations listed above. Must contain at least one value. Values in this vector must be unique. Required.

SupportedFormats

Deprecated: Use SupportedFormats2 instead.

Ordinal	Field	Type	Description
1	`pcm_supported_formats`	`PcmSupportedFormats`

VmoInfo resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

VMO information for registering VMOs. Used in RegisterVmos and AllocateVmos to pair a VMO handle with a unique ID.

Added: HEAD

Ordinal Field Type Description

1

id

VmoId

ID corresponding to the VMO.

Required.

2

vmo

handle<vmo>

Handle to the VMO.

Required.

VmoTransfer resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

This describes a VMO section containing audio data.

Added: HEAD

Ordinal Field Type Description

1

vmo_id

VmoId

ID of a VMO that was previously registered or allocated.

Required.

2

vmo_offset

uint64

Offset into the VMO to start reading or writing. This is relative to the start of that VMO.

Required.

3

payload_size

uint64

Number of bytes to read/write from/to this VMO region.

Required.

UNIONS

Codec_GetDaiFormats_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Codec_GetDaiFormats_Response`
2	`err`	`zx/Status`

Codec_SetDaiFormat_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Codec_SetDaiFormat_Response`
2	`err`	`zx/Status`

Composite_CreatePacketStream_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_CreatePacketStream_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_CreateRingBuffer_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_CreateRingBuffer_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_GetDaiFormats_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_GetDaiFormats_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_GetPacketStreamFormats_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_GetPacketStreamFormats_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_GetProperties_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Composite_GetProperties_Response`
3	`framework_err`	`internal`

Composite_GetRingBufferFormats_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_GetRingBufferFormats_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_Reset_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_Reset_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

Composite_SetDaiFormat_Result strict

Ordinal	Variant	Type
1	`response`	`Composite_SetDaiFormat_Response`
2	`err`	`DriverError`
3	`framework_err`	`internal`

DaiFrameFormat strict

Defined in fuchsia.hardware.audio/dai_format.fidl

Either a standard or custom frame format.

Ordinal	Variant	Type	Description
1	`frame_format_standard`	`DaiFrameFormatStandard`	The format type of all samples in the DAI, listed in `DaiFrameFormatStandard`.
2	`frame_format_custom`	`DaiFrameFormatCustom`	The format type of all samples in the DAI, specified in `DaiFrameFormatCustom`.

Dai_GetDaiFormats_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Dai_GetDaiFormats_Response`
2	`err`	`zx/Status`

Dai_GetRingBufferFormats_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Dai_GetRingBufferFormats_Response`
2	`err`	`zx/Status`

DataTransfer flexible resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Data to be transferred. There are two supported ways data may be conveyed, corresponding to the two members of the DataTransfer union:

vmo_transfer: A region within a VMO previously known to the driver. This VMO must have been established via PacketStreamControl.RegisterVmos (if client-allocated) or PacketStreamControl.AllocateVmos (if driver-allocated). Future requests refer to this buffer by the unique vmo_id. Because VMOs are reused across requests, the one-time cost of pinning/mapping is amortized.
data: The payload is provided directly within the message. This mode is intended for small transfers or control information, not high-throughput streaming.

Added: HEAD

Ordinal	Variant	Type	Description
1	`vmo_transfer`	`VmoTransfer`	Data is stored in a region of a registered VMO. Requires `PacketStreamProperties.supported_buffer_types` to include `CLIENT_OWNED` or `DRIVER_OWNED`.
2	`inline_data`	`vector<uint8>:8192`	Embedded data buffer. Requires `PacketStreamProperties.supported_buffer_types` to include `INLINE`.

Format2 flexible

Added: HEAD

Ordinal	Variant	Type	Description
1	`pcm_format`	`PcmFormat`	Format for linear PCM (uncompressed) samples.
2	`encoding`	`Encoding`	Format for encoded audio.

PacketStreamControl_AllocateVmos_Result strict resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_AllocateVmos_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_DeallocateVmos_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_DeallocateVmos_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_GetPacketStreamSink_Result strict resource

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_GetPacketStreamSink_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_GetProperties_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type	Description
1	`response`	`PacketStreamControl_GetProperties_Response`
3	`framework_err`	`internal`

PacketStreamControl_RegisterVmos_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_RegisterVmos_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_SetPacketStreamSink_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_SetPacketStreamSink_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_Start_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_Start_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_Stop_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_Stop_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamControl_UnregisterVmos_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamControl_UnregisterVmos_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamSink_FlushPackets_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamSink_FlushPackets_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

PacketStreamSink_PutPacket_Result strict

Defined in fuchsia.hardware.audio/packet_stream.fidl

Ordinal	Variant	Type
1	`response`	`PacketStreamSink_PutPacket_Response`
2	`err`	`zx/Status`
3	`framework_err`	`internal`

RingBuffer_GetVmo_Result strict resource

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_GetVmo_Response`
2	`err`	`GetVmoError`

RingBuffer_SetActiveChannels_Result strict

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_SetActiveChannels_Response`
2	`err`	`zx/Status`

RingBuffer_WatchDelayInfo_Result strict

Defined in fuchsia.hardware.audio/ring_buffer.fidl

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_WatchDelayInfo_Response`
3	`framework_err`	`internal`

SupportedFormats2 flexible

All the possible formats supported by this device.

Added: HEAD

Ordinal	Variant	Type	Description
1	`pcm_supported_formats`	`PcmSupportedFormats`	Supported formats for linear PCM (uncompressed) samples, with attributes.
2	`supported_encodings`	`SupportedEncodings`	Supported formats for non-LPCM encoded audio (e.g. AAC, MP3).

BITS

BufferType flexible

Type: uint64

Defined in fuchsia.hardware.audio/packet_stream.fidl

Types of buffer ownership/transfer supported by the stream. Multiple values can be supported by the driver.

Added: HEAD

Name	Value	Description
CLIENT_OWNED	1	The client allocates the VMO and registers it with the driver.
DRIVER_OWNED	2	The driver allocates the VMO and passes handles to the client.
INLINE	4	Data is sent inline within the FIDL message.

CONSTANTS

Name	Value	Type	Description
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_ENCODED_CHANNEL_SETS	`64`	`uint32`	Added: HEAD
MAX_COUNT_ENCODED_SUPPORTED_RATES	`64`	`uint32`	Added: HEAD
MAX_COUNT_ENCODED_TYPES	`64`	`uint32`	Added: HEAD
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_INLINE_TRANSFER_SIZE	`8192`	`uint64`	Added: HEAD
MAX_UI_STRING_SIZE	`256`	`uint32`
UNIQUE_ID_SIZE	`16`	`uint32`
VMO_VECTOR_MAX	`256`	`uint32`	The maximum number of VMOs that can be registered or allocated. Added: HEAD

ALIASES

Name	Value	Description
ClockDomain	`uint32`
ElementId	`uint64`
TopologyId	`uint64`
UniqueId	`array`[`UNIQUE_ID_SIZE`]	UniqueId arrays starting with 0x42, 0x54, ... (or `BT` in ASCII) are reserved for drivers implementing Bluetooth technologies. UniqueId 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).
VmoId	`uint64`	Added: HEAD
VmoInfos	`vector`[`VMO_VECTOR_MAX`]	Added: HEAD

SERVICES

CodecConnectorService

Defined in fuchsia.hardware.audio/codec_connector.fidl

Name	Type	Transport
codec_connector	`fuchsia.hardware.audio/CodecConnector`	Channel

CodecService

Name	Type	Transport
codec	`fuchsia.hardware.audio/Codec`	Channel

CompositeConnectorService

Defined in fuchsia.hardware.audio/composite_connector.fidl

Name	Type	Transport
composite_connector	`fuchsia.hardware.audio/CompositeConnector`	Channel

DaiConnectorService

Defined in fuchsia.hardware.audio/dai_connector.fidl

Name	Type	Transport
dai_connector	`fuchsia.hardware.audio/DaiConnector`	Channel

DaiService

Name	Type	Transport
dai	`fuchsia.hardware.audio/Dai`	Channel

DeviceService