// Copyright 2020 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.hardware.audio;

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

/// Textual information about the codec.
@available(deprecated=11, removed=12)
type CodecInfo = struct {
    /// Unique identifier for the codec.
    unique_id string:UNIQUE_ID_SIZE;

    /// Name of the codec manufacturer.
    manufacturer string:MAX_UI_STRING_SIZE;

    /// Product name of the codec.
    product_name string:MAX_UI_STRING_SIZE;
};

@available(added=20)
type CodecProperties = table {
    /// Driver type is input (true) or output (false)
    /// If not included, then the driver may be used for both input and output.
    ///
    /// Optional.
    1: is_input bool;

    /// UI string for the manufacturer name. If not included, the manufacturer is unspecified.
    ///
    /// Optional.
    2: manufacturer string:MAX_UI_STRING_SIZE;

    /// UI string for the product name. If not included, the product name is unspecified.
    ///
    /// Optional.
    3: product string:MAX_UI_STRING_SIZE;

    /// Unique identifier for the codec.
    /// If not included, there is no unique id for the Codec.
    ///
    /// Optional.
    4: unique_id array<uint8, UNIQUE_ID_SIZE>;

    /// Plug Detect Capabilities.
    ///
    /// Required.
    5: plug_detect_capabilities PlugDetectCapabilities;
};

/// Gain type of representation.
///
/// # Deprecation
///
/// Not needed anymore since the functionality is available in the signal processing API defined
/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
@available(deprecated=9, removed=12)
type GainType = strict enum : uint8 {
    /// Gain specified in dB, for example -103.0dB or +3.2dB.
    DECIBELS = 1;

    /// Gain specified as a percentage, for example 10.0% or 80.5%.
    PERCENT = 2;
};

/// Gain format/parameters.
///
/// # Deprecation
///
/// Not needed anymore since the functionality is available in the signal processing API defined
/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
@available(deprecated=9, removed=12)
type GainFormat = table {
    /// Specifies what the numbers for gain represent, e.g. a percentage.
    ///
    /// Required.
    1: type GainType;

    /// Minimum gain.
    ///
    /// Required.
    2: min_gain float32;

    /// Maximum gain.
    ///
    /// Required.
    3: max_gain float32;

    /// Gain step in decibels, this value must not be negative, but may be zero to convey an
    /// effectively continuous range of values. Must not exceed `max_gain_db` - `min_gain_db`.
    ///
    /// Required.
    4: gain_step float32;

    /// Gain mute capability. If not included, mute is not supported.
    ///
    /// Optional.
    5: can_mute bool;

    /// Automatic Gain Control (AGC) capability. If not included, AGC is not supported.
    ///
    /// Optional.
    6: can_agc bool;
};

/// Codec format information.
type CodecFormatInfo = table {
    /// The driver's best estimate of the external delay (in nanoseconds) present in the pipeline
    /// for the chosen format. When precisely synchronizing presentation across multiple entities
    /// (e.g. devices), the external delay should be taken into account.
    /// If not included `external_delay` is unknown.
    ///
    /// Optional.
    1: external_delay zx.Duration;

    /// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
    /// actually start playback/capture after a `Start` command is issued.
    /// It may take some time for the hardware to get into fully operational mode, for example due
    /// a power state change. This delay must be taken into account if not getting the initial audio
    /// samples played or captured is not acceptable.
    /// If not included `turn_on_delay` is unknown.
    ///
    /// Optional.
    2: turn_on_delay zx.Duration;

    /// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
    /// actually stop playback/capture after a `Stop` command is issued.
    /// It may take some time for the hardware to get into fully stopped mode, for example due
    /// a power state change. This delay must be taken into account if playback/capture of samples
    /// after a 'Stop' command is not acceptable.
    /// If not included, the turn off delay is unknown.
    ///
    /// Optional.
    3: turn_off_delay zx.Duration;
};

/// For an overview see
/// [[Audio Codec Interface]](https://fuchsia.dev/fuchsia-src/development/audio/drivers/codec).
/// # Deprecation
///
/// Not supported anymore, instead use an
/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
/// with one DAI and no Ring Buffer, see
/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
@available(deprecated=20)
closed protocol Codec {
    /// Allows providing driver health state.
    compose Health;

    /// Allows providing signal processing capabilities.
    compose fuchsia.hardware.audio.signalprocessing.Connector;

    /// Resets the codec.
    /// `Reset` returns when the reset is completed. If the driver can't successfully reset the
    /// codec it will close the codec protocol channel, in this case the client may obtain a new
    /// codec protocol channel and retry.
    strict Reset() -> ();

    /// Retrieves textual information about the codec.
    @available(deprecated=11, removed=12)
    strict GetInfo() -> (struct {
        info CodecInfo;
    });

    /// Retrieves top level static properties.
    @available(added=20)
    strict GetProperties() -> (struct {
        properties CodecProperties;
    });

    /// Stops the codec operation.
    /// `Stop` returns when configuring the codec to stop is completed. This method does not wait
    /// for the hardware to actually stop playback/capture (i.e. `turn_off_delay` impact is not
    /// taken into account), nor is any such delay reflected in the returned `stop_time`.
    /// `stop_time` indicates when the driver finished configuring the codec to stop, as measured
    /// in the CLOCK_MONOTONIC timeline.
    /// If the driver cannot successfully configure the codec to stop, it will close the codec
    /// protocol channel, in which case the client may obtain a new codec protocol channel and retry.
    strict Stop() -> (struct {
        @available(replaced=20, renamed="stop_time")
        start_time zx.Time;

        @available(added=20)
        stop_time zx.Time;
    });

    /// Start/Re-start the codec operation.
    /// `Start` returns when configuring the codec to start is completed. This method does not wait
    /// for the hardware to actually start playback/capture (i.e. `turn_on_delay` impact is not taken
    /// into account), nor is any such delay reflected in the returned `start_time`.
    /// `start_time` indicates when the driver finished configuring the codec to start, as measured
    /// in the CLOCK_MONOTONIC timeline.
    /// If the driver can't successfully start the codec, it will close the codec protocol channel,
    /// in which case the client may obtain a new codec protocol channel and retry.
    strict Start() -> (struct {
        start_time zx.Time;
    });

    /// Returns whether a codec is bridgeable.
    ///
    /// # Deprecation
    ///
    /// Not supported anymore, bridged configurations are no longer changeable at runtime.
    /// A driver can still be configured to operate in bridged mode or not at boot time.
    @available(deprecated=17, removed=20)
    strict IsBridgeable() -> (struct {
        supports_bridged_mode bool;
    });

    /// Sets a codec's bridged mode. This method is required, but it only needs to take action if
    /// the codec supports bridged mode as specified by its reply to `IsBridgeable`.
    ///
    /// # Deprecation
    ///
    /// Not supported anymore, bridged configurations are no longer changeable at runtime.
    /// A driver can still be configured to operate in bridged mode or not at boot time.
    @available(deprecated=17, removed=20)
    strict SetBridgedMode(struct {
        enable_bridged_mode bool;
    });

    /// Retrieves the DAI formats supported by the codec, if not available at the time the codec
    /// may reply with an error status and the controller may retry at a later time.
    /// Retrieving multiple DaiSupportedFormats allows for cases where exclusive
    /// combinations of the parameters in DaiSupportedFormats may be supported.
    strict GetDaiFormats() -> (struct {
        formats vector<DaiSupportedFormats>:MAX_COUNT_FORMATS;
    }) error zx.Status;

    /// Sets the DAI format to be used in the interface between the controller and codec.
    /// Returns an error if not supported at the time of the request (e.g. for removable hardware).
    strict SetDaiFormat(struct {
        format DaiFormat;
    }) -> (struct {
        state CodecFormatInfo;
    }) error zx.Status;

    /// Retrieves gain format.
    ///
    /// # Deprecation
    ///
    /// Not needed anymore since the functionality is available in the signal processing API defined
    /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
    /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
    @available(deprecated=9, removed=12)
    strict GetGainFormat() -> (struct {
        gain_format GainFormat;
    });

    /// Retrieves Plug Detect Capabilities.
    @available(deprecated=11, removed=12)
    strict GetPlugDetectCapabilities() -> (struct {
        plug_detect_capabilities PlugDetectCapabilities;
    });

    /// Get the gain state via a hanging get. The driver will reply to the first `WatchGainState`
    /// sent by the client and this reply must include a `gain_db` set to 0dB or lower. The driver
    /// will not respond to subsequent client `WatchGainState` calls until the gain state changes
    /// from what was most recently reported.
    ///
    /// # Deprecation
    ///
    /// Not needed anymore since the functionality is available in the signal processing API defined
    /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
    /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
    @available(deprecated=9, removed=12)
    strict WatchGainState() -> (struct {
        gain_state GainState;
    });

    /// Client update of the gain state.
    ///
    /// # Deprecation
    ///
    /// Not needed anymore since the functionality is available in the signal processing API defined
    /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
    /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
    @available(deprecated=9, removed=12)
    strict SetGainState(struct {
        target_state GainState;
    });

    /// Get the plug detect state via a hanging get. The driver will reply to the first
    /// `WatchPlugState` sent by the client. The driver will not respond to subsequent client
    /// `WatchPlugState` calls until the plug state changes from what was most recently reported.
    strict WatchPlugState() -> (struct {
        plug_state PlugState;
    });
};

/// # Deprecation
///
/// Not supported anymore, instead use an
/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
/// with one DAI and no Ring Buffer, see
/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
@available(deprecated=20)
service CodecService {
    codec client_end:Codec;
};