sdk/fidl/fuchsia.audio.device/device.fidl

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.audio.device;

using fuchsia.hardware.audio;
using fuchsia.hardware.audio.signalprocessing;
using fuchsia.audio;

/// Common aliases, consts and types used by more than one of the fuchsia.audio.device protocols.
///
alias ClockDomain = fuchsia.hardware.audio.ClockDomain;
alias TokenId = uint64;
alias ElementId = fuchsia.hardware.audio.signalprocessing.ElementId;
alias TopologyId = fuchsia.hardware.audio.signalprocessing.TopologyId;

/// Maximum number of audio devices in the system at any time.
const MAX_COUNT_DEVICES uint32 = 256;

/// Maximum number of `PcmFormatSet`s that a device can report as supported.
const MAX_COUNT_FORMATS uint32 = fuchsia.hardware.audio.MAX_COUNT_FORMATS;
const MAX_COUNT_DAI_FORMATS uint32 = fuchsia.hardware.audio.MAX_COUNT_DAI_FORMATS;

/// Maximum number of `ChannelSet`s that a device can report in a single PcmFormatSet.
const MAX_COUNT_CHANNEL_SETS uint32 = fuchsia.hardware.audio.MAX_COUNT_CHANNEL_SETS;

/// Maximum number of distinct sample formats that a single PcmFormatSet can contain.
const MAX_COUNT_SAMPLE_TYPES uint32 = 32;

/// Maximum number of frame rates that a device can report in a PcmFormatSet.
const MAX_COUNT_RATES uint32 = fuchsia.hardware.audio.MAX_COUNT_SUPPORTED_RATES;

/// Maximum number of channels that a device can report as supported.
const MAX_COUNT_CHANNELS uint32 = fuchsia.hardware.audio.MAX_COUNT_CHANNELS_IN_RING_BUFFER;

/// Maximum length of the strings for device, manufacturer and product names.
const MAX_STRING_SIZE uint32 = fuchsia.hardware.audio.MAX_UI_STRING_SIZE;

/// Maximum number of processing elements supported by a single device.
const MAX_COUNT_PROCESSING_ELEMENTS uint32
        = fuchsia.hardware.audio.signalprocessing.MAX_COUNT_PROCESSING_ELEMENTS;

/// 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.
const DEFAULT_RING_BUFFER_ELEMENT_ID ElementId = 0;

/// 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.
const DEFAULT_DAI_INTERCONNECT_ELEMENT_ID ElementId = 1;

/// The protocol channel used to configure and observe a device.
/// # Deprecation
///
/// Codec, Dai and StreamConfig are not supported anymore, instead use an
/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
/// , see
/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
@available(deprecated=HEAD)
type DriverClient = flexible resource union {
    /// Populated for drivers that use the `fuchsia_hardware_audio.Codec` interface.
    1: codec client_end:fuchsia.hardware.audio.Codec;

    /// Populated for drivers that use the `fuchsia_hardware_audio.Composite` interface.
    2: composite client_end:fuchsia.hardware.audio.Composite;

    /// Populated for drivers that use the `fuchsia_hardware_audio.Dai` interface.
    3: dai client_end:fuchsia.hardware.audio.Dai;

    /// Populated for drivers that use the `fuchsia_hardware_audio.StreamConfig` interface.
    4: stream_config client_end:fuchsia.hardware.audio.StreamConfig;
};

/// The protocol used by the driver, and (if StreamConfig) its directionality.
type DeviceType = flexible enum {
    /// The device uses the `fuchsia.hardware.audio/Codec` protocol.
    CODEC = 1;

    /// The device uses the `fuchsia.hardware.audio/Composite` protocol.
    COMPOSITE = 2;

    /// The device uses the `fuchsia.hardware.audio/Dai` protocol.
    DAI = 3;

    /// The device uses `fuchsia.hardware.audio/StreamConfig` and is a source of audio streams.
    // We maintain this enum as entirely distinct from `OUTPUT`, despite their using the same
    // protocol, because the two device types are detected at entirely different devfs locations
    // (`dev/class/audio-input` vs. `dev/class/audio-output`).
    INPUT = 4;

    /// Device uses `fuchsia.hardware.audio/StreamConfig` and is a destination for audio streams.
    // We maintain this enum as entirely distinct from `INPUT`, despite their using the same
    // protocol, because the two device types are detected at entirely different devfs locations
    // (`dev/class/audio-output` vs. `dev/class/audio-input`).
    OUTPUT = 5;
};

/// 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.
type PcmFormatSet = table {
    /// The number of channel sets that the device supports. This must contain
    /// at least one `ChannelSet` entry.
    ///
    /// Required.
    1: channel_sets vector<ChannelSet>:MAX_COUNT_CHANNEL_SETS;

    /// The number of sample formats that the device supports. This must
    /// contain least one `AudioSampleFormat` entry.
    ///
    /// Required.
    2: sample_types vector<fuchsia.audio.SampleType>:MAX_COUNT_SAMPLE_TYPES;

    /// The number of frame rates that the device supports. This must contain at
    /// least one frame rate entry.
    ///
    /// Required.
    3: frame_rates vector<uint32>:MAX_COUNT_RATES;
};

/// This table represents the possible RingBuffer formats that this endpoint can support.
type ElementRingBufferFormatSet = table {
    /// 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.
    1: element_id ElementId;

    /// The ring_buffer_format_set entries that this element supports.
    ///
    /// Required. Must contain at least one entry.
    2: format_sets vector<PcmFormatSet>:MAX_COUNT_FORMATS;
};

/// This table represents the possible Dai formats that this endpoint can support.
type ElementDaiFormatSet = table {
    /// 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.
    1: element_id ElementId;

    /// The dai_format_set entries that this element supports.
    ///
    /// Required. Must contain at least one entry.
    2: format_sets vector<fuchsia.hardware.audio.DaiSupportedFormats>:MAX_COUNT_DAI_FORMATS;
};

/// One possible channel configuration for the device.
type ChannelSet = table {
    /// 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.
    1: attributes vector<ChannelAttributes>:MAX_COUNT_CHANNELS;

    // TODO(https://fxbug.dev/105130): Incorporate this, once it lands.
    //   2: config AudioChannelConfig;
};

/// The attributes (e.g. frequency range) of a single channel.
type ChannelAttributes = table {
    /// Minimum frequency that this channel guarantees to emit/capture, in Hz.
    /// If absent, this channel extends to the bottom of the device range.
    ///
    /// Optional.
    1: min_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.
    2: max_frequency uint32;
};

/// The device's current state of gain.
//
// TODO(https://fxbug.dev/102027): Remove legacy gain aspects once driver API does.
// Going forward, gain will be handled by `SignalProcessing`.
type GainState = table {
    /// Device-wide gain, in decibels.
    ///
    /// Required.
    1: gain_db float32;

    /// Mute state for all channels. If absent, all channels are unmuted.
    ///
    /// Optional.
    2: muted bool;

    /// Automatic Gain Control. If absent, disabled.
    ///
    /// Optional.
    3: agc_enabled bool;
};