fuchsia.audio.device

A Control instance is used to change the settings or state of an audio device. It also creates the ring buffer used to pass audio data between client and device. Each Control is associated with an initialized audio device; conversely each device is associated with either zero or one Control at any time.

CodecStart

Start the Codec hardware. If successful, this returns after the Codec was started and start_time indicates the time when the hardware started. Note that the Codec's DaiFormat must be set (by a successful SetDaiFormat call) before calling this method.

Should only be called for Codec devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Control_CodecStart_Result`

CodecStop

Stop the Codec hardware. If successful, this returns after the Codec was stopped and stop_time indicates the time when the hardware stopped. Note that the Codec's DaiFormat must be set (by a successful SetDaiFormat call) before calling this method.

Should only be called for Codec devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Control_CodecStop_Result`

CreateRingBuffer

Create the ring buffer used to pass audio to/from this device. If the device is Composite, then the targeted RING_BUFFER ENDPOINT must be identified by element_id.

Should only be called for Composite and StreamConfig devices.

Request

Name	Type
`payload`	`ControlCreateRingBufferRequest`

Response

Name	Type
`payload`	`Control_CreateRingBuffer_Result`

GetElements

Returns a vector of supported processing elements. Must return one or more processing elements, or ZX_ERR_NOT_SUPPORTED.

Request

<EMPTY>

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/Reader_GetElements_Result`

GetTopologies

Returns a vector of supported topologies. Must return one or more topologies, or ZX_ERR_NOT_SUPPORTED. If more than one topology is returned, then the client may choose any of the topologies from the list with SetTopology. If only one topology is returned, then the topology definition is informational only since the one and only topology used can't be changed with SetTopology. If GetElements returns one or more elements, GetTopologies must return one or more topologies.

Request

<EMPTY>

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/Reader_GetTopologies_Result`

Reset

Reset the hardware -- stopping the hardware, releasing any ring buffers, and clearing any DaiFormats or RingBufferFormats that were set.

This method returns when the hardware reset is complete. After calling this method, the device is still controlled, but any ring buffers must be re-created and re-started. For devices with DAI_INTERCONNECTs (such as Codecs and some Composites), SetDaiFormat and CodecStart must be called again (in that order) to return the interconnect to the active operational mode. As applicable, SetTopology and SetElementState must also be called.

Should only be called for Codec and Composite devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Control_Reset_Result`

SetDaiFormat

Set the wire format for the digital interconnect connected to this Codec endpoint. This method returns information related to the format that was set, including delay values. If the device is Composite, then the targeted DAI_INTERCONNECT ENDPOINT must be identified by element_id.

Should only be called for Codec and Composite devices.

Request

Name	Type
`payload`	`ControlSetDaiFormatRequest`

Response

Name	Type
`payload`	`Control_SetDaiFormat_Result`

SetElementState

Controls a processing element using a unique id returned by GetElements. Returns ZX_ERR_INVALID_ARGS if the processing_element_id does not match an id returned by GetElements or the type of TypeSpecificElementState does not match the ElementType of the processing element returned by GetElements for this id. The driver may return ZX_ERR_INVALID_ARGS if the state values are invalid, i.e. any of the values violates rules specified in this protocol, e.g. trying to change an EQUALIZER processing element's EqualizerBandState frequency when this processing element did not advertise CAN_CONTROL_FREQUENCY in its supported_controls.

SetElementState may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls then SetElementState may or may not require renegotiation of the driver state as reached with calls of the protocol composing SignalProcessing, e.g. Dai. For instance, SetElementState changing an AGL processing element's parameters may not require renegotiation of the Dai state because changing a gain parameter usually does not change the set of supported audio formats. By contrast, if SetElementState changes the parameters of a CONNECTION_POINT element, the change may require renegotiation because it may invalidate the set of supported formats returned in a previous GetDaiFormats Dai protocol call.

It is the driver's job to determine when renegotiation is required. If renegotiation is required, then SetElementState must return ZX_ERR_BAD_STATE and the client must close the protocol channel such that the protocol negotiations are started over. The client then must make the SetElementState call that returned ZX_ERR_BAD_STATE before any non-SignalProcessing protocol calls.

Request

Name	Type
`processing_element_id`	`fuchsia.hardware.audio.signalprocessing/ElementId`
`state`	`fuchsia.hardware.audio.signalprocessing/ElementState`

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/SignalProcessing_SetElementState_Result`

SetGain

Change the device's overall gain state.

Should only be called for StreamConfig devices.

Request

Name	Type
`payload`	`ControlSetGainRequest`

Response

Name	Type
`payload`	`Control_SetGain_Result`

SetTopology

Sets the topology to be used using an id to the vector returned by GetTopologies. The current topology is communicated by WatchTopology responses. To change which topology is active, a client uses SetTopology. If the specified topology_id is not within thetopologies returned by GetTopologies, this call will return ZX_ERR_INVALID_ARGS. If GetTopologies returns only one Topology, SetTopology is optional and has no effect.

SetTopology may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls, then SetTopology may return ZX_ERR_BAD_STATE to indicate that the operation can not proceed without renegotiation of the driver state. See SetElementState for further discussion.

Request

Name	Type
`topology_id`	`fuchsia.hardware.audio.signalprocessing/TopologyId`

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/SignalProcessing_SetTopology_Result`

WatchElementState

Get the processing element state via a hanging get. For a given processing_element_id, the driver will reply to the first WatchElementState sent by the client. The driver will not respond to subsequent client WatchElementState calls for a given processing_element_id until any field of the Element table changes from what was most recently reported for that processing_element_id. The driver will close the protocol channel with an error of ZX_ERR_BAD_STATE, if this method is called again while there is already a pending WatchElementState for this client and processing_element_id.

Request

Name	Type
`processing_element_id`	`fuchsia.hardware.audio.signalprocessing/ElementId`

Response

Name	Type
`state`	`fuchsia.hardware.audio.signalprocessing/ElementState`

WatchTopology

Get the current topology via a hanging get. The driver will immediately reply to the first WatchTopology sent by each client. The driver will not respond to subsequent WatchTopology calls from that client until the signal-processing topology changes, which occurs as a result of a SetTopology call. The driver will close the protocol channel with an error of ZX_ERR_BAD_STATE, if this method is called again while there is already a pending WatchTopology for this client.

Added: HEAD

Request

<EMPTY>

Response

Name	Type
`topology_id`	`fuchsia.hardware.audio.signalprocessing/TopologyId`

ControlCreator

A ControlCreator interface creates Control instances. Each Control binds to a single device. A device can only be bound to one Control at any time.

Create

Create a Control for the specified device.

Request

Name	Type
`payload`	`ControlCreatorCreateRequest`

Response

Name	Type
`payload`	`ControlCreator_Create_Result`

Observer

Observer instances are used to learn the capabilities and state of an audio device, and to stay informed as its state changes over time. Each Observer is associated with an initialized audio device. An audio device may be observed by multiple Observer instances.

GetElements

Returns a vector of supported processing elements. Must return one or more processing elements, or ZX_ERR_NOT_SUPPORTED.

Request

<EMPTY>

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/Reader_GetElements_Result`

GetReferenceClock

Retrieve the device's reference clock.

This clock will be in the domain specified in the device's Info table.

Should only be called for Composite or StreamConfig devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Observer_GetReferenceClock_Result`

GetTopologies

Request

<EMPTY>

Response

Name	Type
`payload`	`fuchsia.hardware.audio.signalprocessing/Reader_GetTopologies_Result`

WatchElementState

Request

Name	Type
`processing_element_id`	`fuchsia.hardware.audio.signalprocessing/ElementId`

Response

Name	Type
`state`	`fuchsia.hardware.audio.signalprocessing/ElementState`

WatchGainState

Request notification of any change to the device's gain state.

Note: this only notifies of changes to controls described in the device'sInfo table (GainCapabilities specifically). Use WatchElementState for gain processing exposed as SignalProcessing (GetTopologies, GetElements).

Should only be called for StreamConfig devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Observer_WatchGainState_Result`

WatchPlugState

Request notification of any change to the device's plug state. When called for the first time, it will return immediately.

Should only be called for Codec or StreamConfig devices.

Request

<EMPTY>

Response

Name	Type
`payload`	`Observer_WatchPlugState_Result`

WatchTopology

Added: HEAD

Request

<EMPTY>

Response

Name	Type
`topology_id`	`fuchsia.hardware.audio.signalprocessing/TopologyId`

Provider

Use the Provider interface to manually add devices that do not use the devfs mechanism. (Devices that use devfs are automatically added, upon detection.)

AddDevice

Request

Name	Type
`payload`	`ProviderAddDeviceRequest`

Response

Name	Type
`payload`	`Provider_AddDevice_Result`

Registry

Registry instances notify clients as devices arrive and depart, and they create observers (see Observer) that notify of more detailed state changes.

CreateObserver

Request an Observer for the specified device.

Request

Name	Type
`payload`	`RegistryCreateObserverRequest`

Response

Name	Type
`payload`	`Registry_CreateObserver_Result`

WatchDeviceRemoved

Register for notification when an (active, added) device is removed. Because the method only notifies of one removal, upon completion it should immediately be re-called, in case other removals have occurred.

Request

<EMPTY>

Response

Name	Type
`payload`	`Registry_WatchDeviceRemoved_Result`

WatchDevicesAdded

Register for notification when one or more devices are added. The devices vector will always contain at least one Info entry.

Request

<EMPTY>

Response

Name	Type
`payload`	`Registry_WatchDevicesAdded_Result`

RingBuffer

A RingBuffer instance controls data flow for the associated audio stream.

SetActiveChannels

Request that specific individual channels be powered down/up, if the device supports this. This is intended for idle power conservation.

Channels are specified by bitmask; the least significant bit corresponds to channel 0. Each bit not set indicates that the channel can be deactivated. SetActiveChannels does not change how a ring buffer responds to Start/Stop, specifically with regards to position.

Devices are not required to obey SetActiveChannels. For example, they are not required to zero-out an input stream's inactive channels, and data written to inactive channels of an output stream's ring buffer may still be played.

If not called, then by default all channels will be active.

Request

Name	Type
`payload`	`RingBufferSetActiveChannelsRequest`

Response

Name	Type
`payload`	`RingBuffer_SetActiveChannels_Result`

Start

Start the ring buffer, beginning at the first frame of the ring buffer.

Request

Name	Type
`payload`	`RingBufferStartRequest`

Response

Name	Type
`payload`	`RingBuffer_Start_Result`

Stop

Stop the ring buffer.

Request

Name	Type
`payload`	`RingBufferStopRequest`

Response

Name	Type
`payload`	`RingBuffer_Stop_Result`

WatchDelayInfo

Request delay information via a hanging get. The RingBuffer will respond immediately to the first WatchDelayInfo call. Subsequent calls will only be completed when the delay info has changed from previously communicated values.

Request

<EMPTY>

Response

Name	Type
`payload`	`RingBuffer_WatchDelayInfo_Result`

ENUMS

ControlCodecStartError flexible

Type: uint32

Errors returned by Control/CodecStart.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `CodecStart` call has not yet completed.
DAI_FORMAT_NOT_SET	`4`	`SetDaiFormat` was not called before making this call.
ALREADY_STARTED	`5`	The device was already started when this call was made.
OTHER	`6`	The driver returned some other error. This call may be retried.

ControlCodecStopError flexible

Type: uint32

Errors returned by Control/CodecStop.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `CodecStop` call has not yet completed.
DAI_FORMAT_NOT_SET	`4`	`SetDaiFormat` was not called before making this call.
ALREADY_STOPPED	`5`	The device was already stopped when this call was made.
OTHER	`6`	The driver returned some other error. This call may be retried.

ControlCreateRingBufferError flexible

Type: uint32

Errors returned by Control/CreateRingBuffer.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `CreateRingBuffer` call has not yet completed.
INVALID_ELEMENT_ID	`4`	The required `element_id` is missing or does not refer to a `RING_BUFFER` element.
INVALID_OPTIONS	`5`	The required `options` is missing.
INVALID_FORMAT	`6`	The required `options.format` is missing.
INVALID_MIN_BYTES	`7`	The required `options.ring_buffer_min_bytes` is missing.
INVALID_RING_BUFFER	`8`	The required `ring_buffer_server` is missing.
ALREADY_ALLOCATED	`9`	An active `RingBuffer` instance already exists for this `Control`.
FORMAT_MISMATCH	`10`	The device does not support the specified format.
BAD_RING_BUFFER_OPTION	`11`	The device cannot create a ring buffer with the specified options.
OTHER	`12`	The driver returned some other error. This call may be retried.

ControlCreatorError flexible

Type: uint32

Errors returned by ControlCreator/Create.

Name	Value	Description
INVALID_TOKEN_ID	`1`	The required `token_id` is missing.
INVALID_CONTROL	`2`	The required `control_server` is missing.
DEVICE_NOT_FOUND	`3`	No device with `token_id` was found. Either this token has never been used, or the device with `token_id` has been removed.
DEVICE_ERROR	`4`	The device with `token_id` encountered an error and cannot be controlled.
ALREADY_ALLOCATED	`5`	A `Control` associated with `token_id` already exists. This device is already being actively controlled.

ControlResetError flexible

Type: uint32

Errors returned by Control/CodecReset.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.

ControlSetDaiFormatError flexible

Type: uint32

Errors returned by Control/SetDaiFormat.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `SetDaiFormat` call has not yet completed.
INVALID_ELEMENT_ID	`4`	The required `element_id` is missing or does not refer to a `DAI_INTERCONNECT` element.
INVALID_DAI_FORMAT	`5`	The required `dai_format` is missing or invalid.
FORMAT_MISMATCH	`6`	The device does not support the specified dai_format.
OTHER	`7`	The driver returned some other error. This call may be retried.

ControlSetGainError flexible

Type: uint32

Errors returned by Control/SetGain.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
INVALID_GAIN_STATE	`3`	The required `target_state` is missing.
INVALID_GAIN_DB	`4`	The required `target_state.gain_db` is missing.
GAIN_OUT_OF_RANGE	`5`	The specified gain is outside the device's allowed range.
MUTE_UNAVAILABLE	`6`	MUTE is requested, but the device has no MUTE control.
AGC_UNAVAILABLE	`7`	Enabling AGC is requested, but the device has no AGC.

DeviceType flexible

Type: uint32

The protocol used by the driver, and (if StreamConfig) its directionality.

Name	Value	Description
CODEC	`1`	The device uses the `fuchsia.hardware.audio/Codec` protocol.
COMPOSITE	`2`	The device uses the `fuchsia.hardware.audio/Composite` protocol.
DAI	`3`	The device uses the `fuchsia.hardware.audio/Dai` protocol.
INPUT	`4`	The device uses `fuchsia.hardware.audio/StreamConfig` and is a source of audio streams.
OUTPUT	`5`	Device uses `fuchsia.hardware.audio/StreamConfig` and is a destination for audio streams.

ObserverGetReferenceClockError flexible

Type: uint32

Errors returned by Observer/GetReferenceClock.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be observed.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
DEVICE_CLOCK_UNAVAILABLE	`3`	The device's reference clock could not be returned.

ObserverWatchGainStateError flexible

Type: uint32

Errors returned by Observer/WatchGainState.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be observed.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `WatchGainState` call has not yet completed.

ObserverWatchPlugStateError flexible

Type: uint32

Errors returned by Observer/WatchPlugState.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be observed.
WRONG_DEVICE_TYPE	`2`	This device type does not support the method that was called.
ALREADY_PENDING	`3`	The previous `WatchPlugState` call has not yet completed.

PlugDetectCapabilities flexible

Type: uint32

The device's hot-plug capabilities.

Name	Value	Description
HARDWIRED	`0`	Device is always plugged in. Plug state cannot change.
PLUGGABLE	`1`	Device can be un/plugged and can asynchronously notify of changes.

PlugState flexible

Type: uint32

The current plugged-in state for the device.

Name	Value	Description
PLUGGED	`1`	Connected and available for audio streaming.
UNPLUGGED	`2`	Not connected; unavailable for audio streaming.

ProviderAddDeviceError flexible

Type: uint32

Errors returned by the Provider protocol.

Name	Value	Description
INVALID_NAME	`1`	The required `device_name` is incorrectly formed, empty or missing.
INVALID_TYPE	`2`	The required `device_type` is missing.
INVALID_DRIVER_CLIENT	`3`	The required `driver_client` is invalid or missing.
WRONG_CLIENT_TYPE	`4`	The protocol in `driver_client` is incompatible with `device_type` or is not supported yet.

RegistryCreateObserverError flexible

Type: uint32

Errors returned by Registry/CreateObserver.

Name	Value	Description
INVALID_TOKEN_ID	`1`	The required `token_id` is missing.
INVALID_OBSERVER	`2`	The required `observer_server` is missing.
DEVICE_NOT_FOUND	`3`	No device with `token_id` was found. Either this token has never been used, or the device with `token_id` has been removed.
DEVICE_ERROR	`4`	The device with `token_id` has encountered an error and can no longer be observed.

RegistryWatchDeviceRemovedError flexible

Type: uint32

Errors returned by Registry/WatchDeviceRemoved.

Name	Value	Description
ALREADY_PENDING	`1`	The previous `WatchDeviceRemoved` call has not yet completed.

RegistryWatchDevicesAddedError flexible

Type: uint32

Errors returned by Registry/WatchDevicesAdded.

Name	Value	Description
ALREADY_PENDING	`1`	The previous `WatchDevicesAdded` call has not yet completed.

RingBufferSetActiveChannelsError flexible

Type: uint32

Errors returned by RingBuffer/SetActiveChannels.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
ALREADY_PENDING	`2`	The previous `SetActiveChannels` call has not yet completed.
METHOD_NOT_SUPPORTED	`3`	The device does not support `SetActiveChannels`. Individual channels cannot be deactivated (all channels are always active).
INVALID_CHANNEL_BITMASK	`4`	The required `channel_bitmask` is missing.
CHANNEL_OUT_OF_RANGE	`5`	The passed `channel_bitmask` specifies channels that are beyond the range of channels currently configured for this ring buffer.

RingBufferStartError flexible

Type: uint32

Errors returned by RingBuffer/Start.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
ALREADY_PENDING	`2`	The previous `Start` call has not yet completed.
ALREADY_STARTED	`3`	`Start` was called on a ring buffer that is already started.

RingBufferStopError flexible

Type: uint32

Errors returned by RingBuffer/Stop.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be controlled.
ALREADY_PENDING	`2`	The previous `Stop` call has not yet completed.
ALREADY_STOPPED	`3`	`Stop` was called on a ring buffer that is already stopped.

RingBufferWatchDelayInfoError flexible

Type: uint32

Errors returned by RingBuffer/WatchDelayInfo.

Name	Value	Description
DEVICE_ERROR	`1`	This device has encountered an error and can no longer be observed.
ALREADY_PENDING	`2`	The previous `WatchDelayInfo` call has not yet completed.

TABLES

ChannelAttributes

The attributes (e.g. frequency range) of a single channel.

Ordinal Field Type Description

1

min_frequency

uint32

Minimum frequency that this channel guarantees to emit/capture, in Hz. If absent, this channel extends to the bottom of the device range.

Optional.

2

max_frequency

uint32

Maximum frequency that this channel guarantees to emit/capture, in Hz. If absent, this channel extends to the top of the device range.

Optional.

ChannelSet

One possible channel configuration for the device.

Ordinal Field Type Description

1

attributes

vector<ChannelAttributes>[64]

Each item in this vector describes the attributes (e.g. frequency range) of that channel. The length of this vector defines the number of channels supported by this ChannelSet. Must contain at least one entry.

Required.

ControlCreateRingBufferRequest resource

Ordinal Field Type Description

1

element_id

ElementId

The element ID for an ENDPOINT of type RING_BUFFER.

Required for Composite; ignored for StreamConfig.

2

options

RingBufferOptions

Additional requirements about the actual ring buffer being created.

Required.

3

ring_buffer_server

server_end<RingBuffer>

The server_end of the RingBuffer to be created.

Required.

ControlCreatorCreateRequest resource

Ordinal Field Type Description

1

token_id

TokenId

The token id for the device to be controlled.

Required.

2

control_server

server_end<Control>

The server_end of the Control to be created.

Required.

ControlCreator_Create_Response

Ordinal	Field	Type	Description

ControlSetDaiFormatRequest

Ordinal Field Type Description

1

element_id

ElementId

The element ID for an ENDPOINT of type DAI_INTERCONNECT.

Required for Composite; ignored for Codec.

2

dai_format

fuchsia.hardware.audio/DaiFormat

ControlSetGainRequest

Ordinal Field Type Description

1

target_state

GainState

The gain state to be set.

Required.

Control_CodecStart_Response

Ordinal	Field	Type	Description
1	`start_time`	`zx/Time`

Control_CodecStop_Response

Ordinal	Field	Type	Description
1	`stop_time`	`zx/Time`

Control_CreateRingBuffer_Response resource

Ordinal	Field	Type	Description
1	`properties`	`RingBufferProperties`	Properties about the ring buffer and active audio stream as created.
2	`ring_buffer`	`fuchsia.audio/RingBuffer`	An object that represents the audio stream and ring memory itself. Note: ring-buffer VMO memory ranges must be cache-invalidated before each read, and cache-flushed after each write.

Control_Reset_Response

Ordinal	Field	Type	Description

Control_SetDaiFormat_Response

Ordinal	Field	Type	Description
1	`state`	`fuchsia.hardware.audio/CodecFormatInfo`

Control_SetGain_Response

Ordinal	Field	Type	Description

DelayInfo

Ordinal Field Type Description

1

internal_delay

zx/Duration

The driver's best estimate of the delay internal to the hardware it abstracts for the chosen format. This duration must be non-negative.

Required.

2

external_delay

zx/Duration

The amount of pipeline delay beyond the interconnect (subsequent to the DMA "read" position for output devices, or prior to the DMA "write" position for input devices). If present, this duration must be non-negative.

Optional.

ElementDaiFormatSet

This table represents the possible Dai formats that this endpoint can support.

Ordinal Field Type Description

1

element_id

ElementId

The ID of the element being described. This must match an ENDPOINT (DAI_INTERCONNECT) entry in the list of elements contained in the device's Info table. If describing the supported DAI formats for a Codec or Dai device, this value should be DEFAULT_DAI_INTERCONNECT_ELEMENT_ID (1).

Required.

2

format_sets

vector<fuchsia.hardware.audio/DaiSupportedFormats>[64]

The dai_format_set entries that this element supports.

Required. Must contain at least one entry.

ElementRingBufferFormatSet

This table represents the possible RingBuffer formats that this endpoint can support.

Ordinal Field Type Description

1

element_id

ElementId

The ID of the element being described. This must match an ENDPOINT (RING_BUFFER) entry in the list of elements contained in the device's Info table. If describing the supported RingBuffer formats for a Dai or StreamConfig device, this value should be DEFAULT_RING_BUFFER_ELEMENT_ID (0).

Required.

2

format_sets

vector<PcmFormatSet>[64]

The ring_buffer_format_set entries that this element supports.

Required. Must contain at least one entry.

GainCapabilities

The device's overall gain capabilities.

Ordinal	Field	Type	Description
1	`min_gain_db`	`float32`	The device's minimum gain, in decibels. Required.
2	`max_gain_db`	`float32`	The device's maximum gain, in decibels. Required.
3	`gain_step_db`	`float32`	The precision of each gain-change step, in decibels. Required.
4	`can_mute`	`bool`	If true, the device contains a distinct MUTE control. If false or absent, it does not. Optional.
5	`can_agc`	`bool`	Automatic Gain Control. If absent, this hardware does not support AGC. Optional.

GainState

The device's current state of gain.

Ordinal Field Type Description

1

gain_db

float32

Device-wide gain, in decibels.

Required.

2

muted

bool

Mute state for all channels. If absent, all channels are unmuted.

Optional.

3

agc_enabled

bool

Automatic Gain Control. If absent, disabled.

Optional.

Info

When a device is detected (or added via Provider/AddDevice), it is queried for its properties and capabilities. Once this enumeration process completes, it is announced to clients that are watching for device arrivals via Registry/WatchDevicesAdded.

An Info table is returned for each audio device that has been added.

Ordinal	Field	Type	Description
1	`token_id`	`TokenId`	A device identifier that is guaranteed unique for this boot session, but may change across reboots. Required for all device types.
2	`device_type`	`DeviceType`	The protocol used by the driver, and (if StreamConfig) its directionality. Required for all device types.
3	`device_name`	`string[256]`	The device's high-level name, as received from devfs or the `Provider/AddDevice` caller. Required for all device types.
4	`manufacturer`	`string[256]`	The name of the device's manufacturer. Optional for all device types.
5	`product`	`string[256]`	The device's high-level product name. Optional for all device types.
6	`unique_instance_id`	`uint8[16]`	A 16-character ID provided by the driver that (if present) can be used to differentiate instances of the same device. This value should not change across system reboots. Optional for all device types.
7	`is_input`	`bool`	Whether the device is a source (is_input TRUE) or destination (is_input FALSE) of audio. Required for StreamConfig; optional for Codec; absent for Composite.
8	`ring_buffer_format_sets`	`vector<ElementRingBufferFormatSet>[64]`	The union of all formats the device can support, across all combinations of device configuration settings. If the device exposes one or more RingBuffer ENDPOINT elements, this field must be present and its vector must contain exactly one entry for each relevant ENDPOINT element. If the device exposes NO RingBuffer ENDPOINT elements, this field must be omitted (entirely absent, rather than populated with an empty vector). Required for StreamConfig; optional for Composite; absent for Codec.
9	`dai_format_sets`	`vector<ElementDaiFormatSet>[64]`	The union of all DAI formats the device can support, across all combinations of device configuration settings. If the device exposes one or more Dai ENDPOINT elements, this field must be present and its vector must contain exactly one entry for each relevant ENDPOINT element. If the device exposes NO Dai ENDPOINT elements, this field must be omitted (entirely absent, rather than populated with an empty vector). Required for Codec; optional for Composite; absent for StreamConfig.
10	`gain_caps`	`GainCapabilities`	The device's gain/mute capabilities. Required for StreamConfig; absent for Codec and Composite.
11	`plug_detect_caps`	`PlugDetectCapabilities`	The device's hot-plug capabilities. Required for Codec and StreamConfig; absent for Composite.
12	`clock_domain`	`ClockDomain`	An identifier for the clock domain in which the device's clock hardware operates. Devices in the same clock domain remain perfectly synchronized. They may drift relative to some other clock domain, but all clocks in that domain will do so perfectly together. Although their clocks have the same rate, their positions may be offset by an arbitrary, fixed amount. There are two special values for clock domain: `CLOCK_DOMAIN_MONOTONIC` means the hardware is driven by the system montonic clock and will always be synchronized with that timeline. `CLOCK_DOMAIN_EXTERNAL` means the hardware is not synchronized with any other known clocks (even any other clocks in `CLOCK_DOMAIN_EXTERNAL`). Required for Composite and StreamConfig; absent for Codec.
13	`signal_processing_elements`	`vector<fuchsia.hardware.audio.signalprocessing/Element>[64]`	The vector of supported signal-processing elements. If present, must contain at least one element. Required for Composite; optional for Codec and StreamConfig.
14	`signal_processing_topologies`	`vector<fuchsia.hardware.audio.signalprocessing/Topology>[64]`	The vector of supported signal-processing topologies. If present, must contain at least one element. Required for Composite; optional for Codec and StreamConfig.

Observer_GetReferenceClock_Response resource

Ordinal	Field	Type	Description
1	`reference_clock`	`handle<clock>`	The device's reference clock.

Observer_WatchGainState_Response

Ordinal	Field	Type	Description
1	`state`	`GainState`	The device's most recent gain state.

Observer_WatchPlugState_Response

Ordinal	Field	Type	Description
1	`state`	`PlugState`	The device's current plug state.
2	`plug_time`	`zx/Time`	The time (in CLOCK_MONOTONIC) of the most-recent change in plug state.

PcmFormatSet

This table contains vectors representing three dimensions of device configuration (channelization, sample format, frame rate). The device should support all combinations of the items in these vectors.

Ordinal Field Type Description

1

channel_sets

vector<ChannelSet>[64]

The number of channel sets that the device supports. This must contain at least one ChannelSet entry.

Required.

2

sample_types

vector<fuchsia.audio/SampleType>[32]

The number of sample formats that the device supports. This must contain least one AudioSampleFormat entry.

Required.

3

frame_rates

vector<uint32>[64]

The number of frame rates that the device supports. This must contain at least one frame rate entry.

Required.

ProviderAddDeviceRequest resource

Ordinal Field Type Description

1

device_name

string[256]

The device's high-level name. Must not be an empty string.

Required.

2

device_type

DeviceType

Indicates the protocol used by the device, as well as (if StreamConfig) whether it is an input (a source of audio) or an output (a destination for audio).

Required.

3

driver_client

DriverClient

The client_end of the protocol channel (Codec, Composite, Dai or StreamConfig) that this service will use to configure/observe the device. For now, AddDevice only accepts a codec_client, composite_client or stream_config_client here.

Required.

Deprecation

Codec, Dai and StreamConfig are not supported anymore, instead use an Audio Composite , see Audio Drivers Architecture

Deprecated: HEAD

Provider_AddDevice_Response

Ordinal	Field	Type	Description

RegistryCreateObserverRequest resource

Ordinal Field Type Description

1

token_id

TokenId

The token of the device to be observed.

Required.

2

observer_server

server_end<Observer>

The server end of the Observer that will be created.

Required.

Registry_CreateObserver_Response

Ordinal	Field	Type	Description

Registry_WatchDeviceRemoved_Response

Ordinal	Field	Type	Description
1	`token_id`	`TokenId`	The token of the device least-recently removed.

Registry_WatchDevicesAdded_Response

Ordinal	Field	Type	Description
1	`devices`	`vector<Info>[256]`	Devices added since `WatchDevicesAdded` was last called. This method returns all audio devices when called for the first time.

RingBufferOptions

Parameters specified by a caller when creating a ring buffer.

Ordinal Field Type Description

1

format

fuchsia.audio/Format

The format (sample format, channelization, frame rate) of the ring buffer to be created.

Required.

2

ring_buffer_min_bytes

uint32

The minimum number of bytes required in the ring buffer. The actual buffer may be larger, as required by the encoding, driver, device or OS.

Required.

RingBufferProperties

Information about the ring buffer or associated audio stream.

Ordinal Field Type Description

1

valid_bits_per_sample

uint8

The number of bits (starting with the most significant) that are valid, within each individual sample. This may be be smaller than the actual sample size, in the case of an input ring buffer fed by an 18-bit ADC for example. Any additional bits of precision should be ignored.

Required.

2

turn_on_delay

zx/Duration

The maximum delay until disabled channels become fully operational, after calling SetActiveChannels. This is the worst-case duration when reenabling all channels. The value must be non-negative.

Required.

RingBufferSetActiveChannelsRequest

Ordinal Field Type Description

1

channel_bitmask

uint64

The channels to be activated (all others should be deactivated). No bit should be set above the channel_count specified in the ring buffer format (e.g. for a four-channel stream, channel_bitmask must be in the [0x00, 0x0F] range).

Required.

RingBufferStartRequest

Ordinal	Field	Type	Description

RingBufferStopRequest

Ordinal	Field	Type	Description

RingBuffer_SetActiveChannels_Response

Ordinal Field Type Description

1

set_time

zx/Time

The CLOCK_MONOTONIC time when the hardware was configured. Note: this does not include the effects of turn_on_delay on streams.

Required.

RingBuffer_Start_Response

Ordinal Field Type Description

1

start_time

zx/Time

The CLOCK_MONOTONIC time when the stream was started.

Required.

RingBuffer_Stop_Response

Ordinal	Field	Type	Description

RingBuffer_WatchDelayInfo_Response

Ordinal	Field	Type	Description
1	`delay_info`	`DelayInfo`	Required.

UNIONS

ControlCreator_Create_Result strict

Ordinal	Variant	Type	Description
1	`response`	`ControlCreator_Create_Response`
2	`err`	`ControlCreatorError`

Control_CodecStart_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Control_CodecStart_Response`
2	`err`	`ControlCodecStartError`

Control_CodecStop_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Control_CodecStop_Response`
2	`err`	`ControlCodecStopError`

Control_CreateRingBuffer_Result strict resource

Ordinal	Variant	Type	Description
1	`response`	`Control_CreateRingBuffer_Response`
2	`err`	`ControlCreateRingBufferError`

Control_Reset_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Control_Reset_Response`
2	`err`	`ControlResetError`

Control_SetDaiFormat_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Control_SetDaiFormat_Response`
2	`err`	`ControlSetDaiFormatError`

Control_SetGain_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Control_SetGain_Response`
2	`err`	`ControlSetGainError`

DriverClient flexible resource

The protocol channel used to configure and observe a device.

Deprecation

Codec, Dai and StreamConfig are not supported anymore, instead use an Audio Composite , see Audio Drivers Architecture

Deprecated: HEAD

Ordinal	Variant	Type	Description
1	`codec`	`fuchsia.hardware.audio/Codec`	Populated for drivers that use the `fuchsia_hardware_audio.Codec` interface.
2	`composite`	`fuchsia.hardware.audio/Composite`	Populated for drivers that use the `fuchsia_hardware_audio.Composite` interface.
3	`dai`	`fuchsia.hardware.audio/Dai`	Populated for drivers that use the `fuchsia_hardware_audio.Dai` interface.
4	`stream_config`	`fuchsia.hardware.audio/StreamConfig`	Populated for drivers that use the `fuchsia_hardware_audio.StreamConfig` interface.

Observer_GetReferenceClock_Result strict resource

Ordinal	Variant	Type	Description
1	`response`	`Observer_GetReferenceClock_Response`
2	`err`	`ObserverGetReferenceClockError`

Observer_WatchGainState_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Observer_WatchGainState_Response`
2	`err`	`ObserverWatchGainStateError`

Observer_WatchPlugState_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Observer_WatchPlugState_Response`
2	`err`	`ObserverWatchPlugStateError`

Provider_AddDevice_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Provider_AddDevice_Response`
2	`err`	`ProviderAddDeviceError`

Registry_CreateObserver_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Registry_CreateObserver_Response`
2	`err`	`RegistryCreateObserverError`

Registry_WatchDeviceRemoved_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Registry_WatchDeviceRemoved_Response`
2	`err`	`RegistryWatchDeviceRemovedError`

Registry_WatchDevicesAdded_Result strict

Ordinal	Variant	Type	Description
1	`response`	`Registry_WatchDevicesAdded_Response`
2	`err`	`RegistryWatchDevicesAddedError`

RingBuffer_SetActiveChannels_Result strict

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_SetActiveChannels_Response`
2	`err`	`RingBufferSetActiveChannelsError`

RingBuffer_Start_Result strict

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_Start_Response`
2	`err`	`RingBufferStartError`

RingBuffer_Stop_Result strict

Ordinal	Variant	Type	Description
1	`response`	`RingBuffer_Stop_Response`
2	`err`	`RingBufferStopError`

RingBuffer_WatchDelayInfo_Result strict