fuchsia.audio.device

Added: HEAD

PROTOCOLS

Control

Defined in fuchsia.audio.device/control.fidl

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

NameType
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

NameType
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

NameType
payload ControlCreateRingBufferRequest

Response

NameType
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

NameType
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

NameType
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

NameType
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

NameType
payload ControlSetDaiFormatRequest

Response

NameType
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

NameType
processing_element_id fuchsia.hardware.audio.signalprocessing/ElementId
state fuchsia.hardware.audio.signalprocessing/ElementState

Response

NameType
payload fuchsia.hardware.audio.signalprocessing/SignalProcessing_SetElementState_Result

SetGain

Change the device's overall gain state.

Should only be called for StreamConfig devices.

Request

NameType
payload ControlSetGainRequest

Response

NameType
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

NameType
topology_id fuchsia.hardware.audio.signalprocessing/TopologyId

Response

NameType
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

NameType
processing_element_id fuchsia.hardware.audio.signalprocessing/ElementId

Response

NameType
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

NameType
topology_id fuchsia.hardware.audio.signalprocessing/TopologyId

ControlCreator

Defined in fuchsia.audio.device/control.fidl

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

NameType
payload ControlCreatorCreateRequest

Response

NameType
payload ControlCreator_Create_Result

Observer

Defined in fuchsia.audio.device/registry.fidl

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

NameType
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

NameType
payload Observer_GetReferenceClock_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

NameType
payload fuchsia.hardware.audio.signalprocessing/Reader_GetTopologies_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

NameType
processing_element_id fuchsia.hardware.audio.signalprocessing/ElementId

Response

NameType
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

NameType
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

NameType
payload Observer_WatchPlugState_Result

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

NameType
topology_id fuchsia.hardware.audio.signalprocessing/TopologyId

Provider

Defined in fuchsia.audio.device/provider.fidl

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

NameType
payload ProviderAddDeviceRequest

Response

NameType
payload Provider_AddDevice_Result

Registry

Defined in fuchsia.audio.device/registry.fidl

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

NameType
payload RegistryCreateObserverRequest

Response

NameType
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

NameType
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

NameType
payload Registry_WatchDevicesAdded_Result

RingBuffer

Defined in fuchsia.audio.device/control.fidl

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

NameType
payload RingBufferSetActiveChannelsRequest

Response

NameType
payload RingBuffer_SetActiveChannels_Result

Start

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

Request

NameType
payload RingBufferStartRequest

Response

NameType
payload RingBuffer_Start_Result

Stop

Stop the ring buffer.

Request

NameType
payload RingBufferStopRequest

Response

NameType
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

NameType
payload RingBuffer_WatchDelayInfo_Result

ENUMS

ControlCodecStartError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/CodecStart.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

3

The previous CodecStart call has not yet completed.

4

SetDaiFormat was not called before making this call.

5

The device was already started when this call was made.

6

The driver returned some other error. This call may be retried.

ControlCodecStopError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/CodecStop.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

3

The previous CodecStop call has not yet completed.

4

SetDaiFormat was not called before making this call.

5

The device was already stopped when this call was made.

6

The driver returned some other error. This call may be retried.

ControlCreateRingBufferError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/CreateRingBuffer.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

3

The previous CreateRingBuffer call has not yet completed.

4

The required element_id is missing or does not refer to a RING_BUFFER element.

5

The required options is missing.

6

The required options.format is missing.

7

The required options.ring_buffer_min_bytes is missing.

8

The required ring_buffer_server is missing.

9

An active RingBuffer instance already exists for this Control.

10

The device does not support the specified format.

11

The device cannot create a ring buffer with the specified options.

12

The driver returned some other error. This call may be retried.

ControlCreatorError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by ControlCreator/Create.

NameValueDescription
1

The required token_id is missing.

2

The required control_server is missing.

3

No device with token_id was found. Either this token has never been used, or the device with token_id has been removed.

4

The device with token_id encountered an error and cannot be controlled.

5

A Control associated with token_id already exists. This device is already being actively controlled.

ControlResetError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/CodecReset.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

ControlSetDaiFormatError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/SetDaiFormat.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

3

The previous SetDaiFormat call has not yet completed.

4

The required element_id is missing or does not refer to a DAI_INTERCONNECT element.

5

The required dai_format is missing or invalid.

6

The device does not support the specified dai_format.

7

The driver returned some other error. This call may be retried.

ControlSetGainError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by Control/SetGain.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

This device type does not support the method that was called.

3

The required target_state is missing.

4

The required target_state.gain_db is missing.

5

The specified gain is outside the device's allowed range.

6

MUTE is requested, but the device has no MUTE control.

7

Enabling AGC is requested, but the device has no AGC.

DeviceType flexible

Type: uint32

Defined in fuchsia.audio.device/device.fidl

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

NameValueDescription
1

The device uses the fuchsia.hardware.audio/Codec protocol.

2

The device uses the fuchsia.hardware.audio/Composite protocol.

3

The device uses the fuchsia.hardware.audio/Dai protocol.

4

The device uses fuchsia.hardware.audio/StreamConfig and is a source of audio streams.

5

Device uses fuchsia.hardware.audio/StreamConfig and is a destination for audio streams.

ObserverGetReferenceClockError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Observer/GetReferenceClock.

NameValueDescription
1

This device has encountered an error and can no longer be observed.

2

This device type does not support the method that was called.

3

The device's reference clock could not be returned.

ObserverWatchGainStateError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Observer/WatchGainState.

NameValueDescription
1

This device has encountered an error and can no longer be observed.

2

This device type does not support the method that was called.

3

The previous WatchGainState call has not yet completed.

ObserverWatchPlugStateError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Observer/WatchPlugState.

NameValueDescription
1

This device has encountered an error and can no longer be observed.

2

This device type does not support the method that was called.

3

The previous WatchPlugState call has not yet completed.

PlugDetectCapabilities flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

The device's hot-plug capabilities.

NameValueDescription
0

Device is always plugged in. Plug state cannot change.

1

Device can be un/plugged and can asynchronously notify of changes.

PlugState flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

The current plugged-in state for the device.

NameValueDescription
1

Connected and available for audio streaming.

2

Not connected; unavailable for audio streaming.

ProviderAddDeviceError flexible

Type: uint32

Defined in fuchsia.audio.device/provider.fidl

Errors returned by the Provider protocol.

NameValueDescription
1

The required device_name is incorrectly formed, empty or missing.

2

The required device_type is missing.

3

The required driver_client is invalid or missing.

4

The protocol in driver_client is incompatible with device_type or is not supported yet.

RegistryCreateObserverError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Registry/CreateObserver.

NameValueDescription
1

The required token_id is missing.

2

The required observer_server is missing.

3

No device with token_id was found. Either this token has never been used, or the device with token_id has been removed.

4

The device with token_id has encountered an error and can no longer be observed.

RegistryWatchDeviceRemovedError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Registry/WatchDeviceRemoved.

NameValueDescription
1

The previous WatchDeviceRemoved call has not yet completed.

RegistryWatchDevicesAddedError flexible

Type: uint32

Defined in fuchsia.audio.device/registry.fidl

Errors returned by Registry/WatchDevicesAdded.

NameValueDescription
1

The previous WatchDevicesAdded call has not yet completed.

RingBufferSetActiveChannelsError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by RingBuffer/SetActiveChannels.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

The previous SetActiveChannels call has not yet completed.

3

The device does not support SetActiveChannels. Individual channels cannot be deactivated (all channels are always active).

4

The required channel_bitmask is missing.

5

The passed channel_bitmask specifies channels that are beyond the range of channels currently configured for this ring buffer.

RingBufferStartError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by RingBuffer/Start.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

The previous Start call has not yet completed.

3

Start was called on a ring buffer that is already started.

RingBufferStopError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by RingBuffer/Stop.

NameValueDescription
1

This device has encountered an error and can no longer be controlled.

2

The previous Stop call has not yet completed.

3

Stop was called on a ring buffer that is already stopped.

RingBufferWatchDelayInfoError flexible

Type: uint32

Defined in fuchsia.audio.device/control.fidl

Errors returned by RingBuffer/WatchDelayInfo.

NameValueDescription
1

This device has encountered an error and can no longer be observed.

2

The previous WatchDelayInfo call has not yet completed.

TABLES

ChannelAttributes

Defined in fuchsia.audio.device/device.fidl

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

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

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

Defined in fuchsia.audio.device/device.fidl

One possible channel configuration for the device.

OrdinalFieldTypeDescription
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

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
element_id ElementId

The element ID for an ENDPOINT of type RING_BUFFER.

Required for Composite; ignored for StreamConfig.

options RingBufferOptions

Additional requirements about the actual ring buffer being created.

Required.

ring_buffer_server server_end<RingBuffer>

The server_end of the RingBuffer to be created.

Required.

ControlCreatorCreateRequest resource

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
token_id TokenId

The token id for the device to be controlled.

Required.

control_server server_end<Control>

The server_end of the Control to be created.

Required.

ControlCreator_Create_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

ControlSetDaiFormatRequest

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
element_id ElementId

The element ID for an ENDPOINT of type DAI_INTERCONNECT.

Required for Composite; ignored for Codec.

dai_format fuchsia.hardware.audio/DaiFormat

ControlSetGainRequest

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
target_state GainState

The gain state to be set.

Required.

Control_CodecStart_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
start_time zx/Time

Control_CodecStop_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
stop_time zx/Time

Control_CreateRingBuffer_Response resource

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
properties RingBufferProperties

Properties about the ring buffer and active audio stream as created.

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

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

Control_SetDaiFormat_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
state fuchsia.hardware.audio/CodecFormatInfo

Control_SetGain_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

DelayInfo

Defined in fuchsia.audio.device/control.fidl

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

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

Defined in fuchsia.audio.device/device.fidl

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

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

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

Defined in fuchsia.audio.device/device.fidl

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

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

format_sets vector<PcmFormatSet>[64]

The ring_buffer_format_set entries that this element supports.

Required. Must contain at least one entry.

GainCapabilities

Defined in fuchsia.audio.device/registry.fidl

The device's overall gain capabilities.

OrdinalFieldTypeDescription
min_gain_db float32

The device's minimum gain, in decibels.

Required.

max_gain_db float32

The device's maximum gain, in decibels.

Required.

gain_step_db float32

The precision of each gain-change step, in decibels.

Required.

can_mute bool

If true, the device contains a distinct MUTE control. If false or absent, it does not.

Optional.

can_agc bool

Automatic Gain Control. If absent, this hardware does not support AGC.

Optional.

GainState

Defined in fuchsia.audio.device/device.fidl

The device's current state of gain.

OrdinalFieldTypeDescription
gain_db float32

Device-wide gain, in decibels.

Required.

muted bool

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

Optional.

agc_enabled bool

Automatic Gain Control. If absent, disabled.

Optional.

Info

Defined in fuchsia.audio.device/registry.fidl

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.

OrdinalFieldTypeDescription
token_id TokenId

A device identifier that is guaranteed unique for this boot session, but may change across reboots.

Required for all device types.

device_type DeviceType

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

Required for all device types.

device_name string[256]

The device's high-level name, as received from devfs or the Provider/AddDevice caller.

Required for all device types.

manufacturer string[256]

The name of the device's manufacturer.

Optional for all device types.

product string[256]

The device's high-level product name.

Optional for all device types.

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.

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.

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.

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.

gain_caps GainCapabilities

The device's gain/mute capabilities.

Required for StreamConfig; absent for Codec and Composite.

plug_detect_caps PlugDetectCapabilities

The device's hot-plug capabilities.

Required for Codec and StreamConfig; absent for Composite.

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.

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.

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

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
reference_clock handle<clock>

The device's reference clock.

Observer_WatchGainState_Response

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
state GainState

The device's most recent gain state.

Observer_WatchPlugState_Response

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
state PlugState

The device's current plug state.

plug_time zx/Time

The time (in CLOCK_MONOTONIC) of the most-recent change in plug state.

PcmFormatSet

Defined in fuchsia.audio.device/device.fidl

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.

OrdinalFieldTypeDescription
channel_sets vector<ChannelSet>[64]

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

Required.

sample_types vector<fuchsia.audio/SampleType>[32]

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

Required.

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

Defined in fuchsia.audio.device/provider.fidl

OrdinalFieldTypeDescription
device_name string[256]

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

Required.

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.

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.

Provider_AddDevice_Response

Defined in fuchsia.audio.device/provider.fidl

OrdinalFieldTypeDescription

RegistryCreateObserverRequest resource

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
token_id TokenId

The token of the device to be observed.

Required.

observer_server server_end<Observer>

The server end of the Observer that will be created.

Required.

Registry_CreateObserver_Response

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription

Registry_WatchDeviceRemoved_Response

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
token_id TokenId

The token of the device least-recently removed.

Registry_WatchDevicesAdded_Response

Defined in fuchsia.audio.device/registry.fidl

OrdinalFieldTypeDescription
devices vector<Info>[256]

Devices added since WatchDevicesAdded was last called. This method returns all audio devices when called for the first time.

RingBufferOptions

Defined in fuchsia.audio.device/control.fidl

Parameters specified by a caller when creating a ring buffer.

OrdinalFieldTypeDescription
format fuchsia.audio/Format

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

Required.

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

Defined in fuchsia.audio.device/control.fidl

Information about the ring buffer or associated audio stream.

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

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

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
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

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

RingBufferStopRequest

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

RingBuffer_SetActiveChannels_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
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

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
start_time zx/Time

The CLOCK_MONOTONIC time when the stream was started.

Required.

RingBuffer_Stop_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription

RingBuffer_WatchDelayInfo_Response

Defined in fuchsia.audio.device/control.fidl

OrdinalFieldTypeDescription
delay_info DelayInfo

Required.

UNIONS

ControlCreator_Create_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response ControlCreator_Create_Response
err ControlCreatorError

Control_CodecStart_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_CodecStart_Response
err ControlCodecStartError

Control_CodecStop_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_CodecStop_Response
err ControlCodecStopError

Control_CreateRingBuffer_Result strict resource

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_CreateRingBuffer_Response
err ControlCreateRingBufferError

Control_Reset_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_Reset_Response
err ControlResetError

Control_SetDaiFormat_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_SetDaiFormat_Response
err ControlSetDaiFormatError

Control_SetGain_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response Control_SetGain_Response
err ControlSetGainError

DriverClient flexible resource

Defined in fuchsia.audio.device/device.fidl

The protocol channel used to configure and observe a device.

OrdinalVariantTypeDescription
codec fuchsia.hardware.audio/Codec

Populated for drivers that use the fuchsia_hardware_audio.Codec interface.

composite fuchsia.hardware.audio/Composite

Populated for drivers that use the fuchsia_hardware_audio.Composite interface.

dai fuchsia.hardware.audio/Dai

Populated for drivers that use the fuchsia_hardware_audio.Dai interface.

stream_config fuchsia.hardware.audio/StreamConfig

Populated for drivers that use the fuchsia_hardware_audio.StreamConfig interface.

Observer_GetReferenceClock_Result strict resource

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Observer_GetReferenceClock_Response
err ObserverGetReferenceClockError

Observer_WatchGainState_Result strict

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Observer_WatchGainState_Response
err ObserverWatchGainStateError

Observer_WatchPlugState_Result strict

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Observer_WatchPlugState_Response
err ObserverWatchPlugStateError

Provider_AddDevice_Result strict

Defined in fuchsia.audio.device/provider.fidl

OrdinalVariantTypeDescription
response Provider_AddDevice_Response
err ProviderAddDeviceError

Registry_CreateObserver_Result strict

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Registry_CreateObserver_Response
err RegistryCreateObserverError

Registry_WatchDeviceRemoved_Result strict

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Registry_WatchDeviceRemoved_Response
err RegistryWatchDeviceRemovedError

Registry_WatchDevicesAdded_Result strict

Defined in fuchsia.audio.device/registry.fidl

OrdinalVariantTypeDescription
response Registry_WatchDevicesAdded_Response
err RegistryWatchDevicesAddedError

RingBuffer_SetActiveChannels_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response RingBuffer_SetActiveChannels_Response
err RingBufferSetActiveChannelsError

RingBuffer_Start_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response RingBuffer_Start_Response
err RingBufferStartError

RingBuffer_Stop_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response RingBuffer_Stop_Response
err RingBufferStopError

RingBuffer_WatchDelayInfo_Result strict

Defined in fuchsia.audio.device/control.fidl

OrdinalVariantTypeDescription
response RingBuffer_WatchDelayInfo_Response
err RingBufferWatchDelayInfoError

CONSTANTS

NameValueTypeDescription
DEFAULT_DAI_INTERCONNECT_ELEMENT_ID 1 uint64

For devices with Codec or Dai drivers, there is only one DAI_INTERCONNECT entity. When a method requires us to address the interconnect by ID, we use element_id 1. Codec and Dai drivers that implement signalprocessing should not assign this ID to other elements.

DEFAULT_RING_BUFFER_ELEMENT_ID 0 uint64

For devices with Dai or StreamConfig drivers, there is only one RING_BUFFER entity. When a method requires us to address the RingBuffer by ID, we use element_id 0. Dai and StreamConfig drivers that implement signalprocessing should not assign this ID to other elements.

MAX_COUNT_CHANNELS fuchsia.hardware.audio/MAX_COUNT_CHANNELS_IN_RING_BUFFER uint32

Maximum number of channels that a device can report as supported.

MAX_COUNT_CHANNEL_SETS fuchsia.hardware.audio/MAX_COUNT_CHANNEL_SETS uint32

Maximum number of ChannelSets that a device can report in a single PcmFormatSet.

MAX_COUNT_DAI_FORMATS fuchsia.hardware.audio/MAX_COUNT_DAI_FORMATS uint32
MAX_COUNT_DEVICES 256 uint32

Maximum number of audio devices in the system at any time.

MAX_COUNT_FORMATS fuchsia.hardware.audio/MAX_COUNT_FORMATS uint32

Maximum number of PcmFormatSets that a device can report as supported.

MAX_COUNT_PROCESSING_ELEMENTS fuchsia.hardware.audio.signalprocessing/MAX_COUNT_PROCESSING_ELEMENTS uint32

Maximum number of processing elements supported by a single device.

MAX_COUNT_RATES fuchsia.hardware.audio/MAX_COUNT_SUPPORTED_RATES uint32

Maximum number of frame rates that a device can report in a PcmFormatSet.

MAX_COUNT_SAMPLE_TYPES 32 uint32

Maximum number of distinct sample formats that a single PcmFormatSet can contain.

MAX_STRING_SIZE fuchsia.hardware.audio/MAX_UI_STRING_SIZE uint32

Maximum length of the strings for device, manufacturer and product names.

UNIQUE_INSTANCE_ID_SIZE fuchsia.hardware.audio/UNIQUE_ID_SIZE uint32

The length of the device's unique ID, in bytes.

ALIASES

NameValueDescription
ClockDomain uint32

Common aliases, consts and types used by more than one of the fuchsia.audio.device protocols.

ElementId uint64
TokenId uint64
TopologyId uint64