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

// Copyright 2022 The Fuchsia Authors.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.audio.controller;

using fuchsia.audio.device;
using fuchsia.hardware.audio.signalprocessing;
using fuchsia.hardware.audio;
using fuchsia.io;
using zx;

/// 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 must not assign this ID to other elements.
const DEFAULT_RING_BUFFER_ELEMENT_ID fuchsia.hardware.audio.signalprocessing.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 must not assign this ID to other elements.
const DEFAULT_DAI_INTERCONNECT_ELEMENT_ID fuchsia.hardware.audio.signalprocessing.ElementId = 1;

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 the `fuchsia.hardware.audio/StreamConfig` protocol and
    /// is an audio source.
    INPUT = 4;

    /// The device uses the `fuchsia.hardware.audio/StreamConfig` protocol and
    /// is an audio destination.
    OUTPUT = 5;
};

/// Identifies an audio device.
type DeviceSelector = flexible union {
    /// Driver node in devfs, e.g. `/dev/class/audio-input/3d99d780`.
    1: devfs struct {
        /// Name of this device's devfs node, e.g. `3d99d780`.
        name fuchsia.io.Name;

        /// Device type.
        device_type DeviceType;
    };

    /// A device available through the `fuchsia.audio.device/Registry` protocol.
    2: registry fuchsia.audio.device.TokenId;
};

/// Identifies a device ring buffer for playing/recording.
type DeviceRingBuffer = struct {
    /// The device that has a ring buffer.
    selector DeviceSelector;

    /// The ID of an ENDPOINT (with type RING_BUFFER) signal processing element
    /// of the desired ring buffer.
    ///
    /// For Dai and StreamConfig devices, this should be `DEFAULT_RING_BUFFER_ELEMENT_ID`.
    ring_buffer_element_id fuchsia.hardware.audio.signalprocessing.ElementId;
};

/// Enumerate, query, and control audio devices from clients.
@discoverable
open protocol DeviceControl {
    /// Sets the gain of the stream in decibels.
    flexible DeviceSetGainState(resource table {
        /// Id of the device to set the gain state.
        ///
        /// Required.
        1: device DeviceSelector;

        /// Desired gain state.
        ///
        /// Required.
        2: gain_state fuchsia.hardware.audio.GainState;
    }) -> () error zx.Status;
};