// Copyright 2019 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 ddk.protocol.codec;
using zx;

enum SampleFormat : uint8 {
    PDM = 1;
    PCM_SIGNED = 2;
    PCM_UNSIGNED = 3;
    PCM_FLOAT = 4;
};

enum JustifyFormat : uint8 {
    /// No justification as in samples without a frame sync like PDM.
    JUSTIFY_NONE = 1;
    /// Justification as specified in the I2S specification, i.e. left justified but with data
    /// starting one clock cycle after frame sync changes from high to low.
    JUSTIFY_I2S = 2;
    /// Left justified, data starts at frame sync changes from low to high. Note that TDM
    /// justification with data starting a variable number of clocks after frame sync is not
    /// supported.
    JUSTIFY_LEFT = 3;
    /// Right justified, data starts at frame sync changes from low to high.
    JUSTIFY_RIGHT = 4;
};

struct DaiFormat {
    /// Number of channels in the DAI.
    uint32 number_of_channels;
    /// Which channels to use in the DAI.
    vector<uint32> channels_to_use;
    /// The format of all samples in the DAI.
    SampleFormat sample_format;
    /// The justification of all samples in the DAI.
    JustifyFormat justify_format;
    /// The frame rate for all samples in the DAI.
    uint32 frame_rate;
    /// The bits per channel for all channels in the DAI.
    uint8 bits_per_channel;
    /// The bits per sample for all samples in the DAI.  Must be smaller than bits per channel for
    /// samples to fit.
    uint8 bits_per_sample;
};

struct DaiSupportedFormats {
    /// All possible number of channels supported by the codec.
    vector<uint32> number_of_channels;
    /// Sample formats supported by the codec.
    vector<SampleFormat> sample_formats;
    /// Justify formats supported by the codec.
    vector<JustifyFormat> justify_formats;
    /// Rates supported by the codec.
    vector<uint32> frame_rates;
    /// The bits per channel supported by the codec.
    vector<uint8> bits_per_channel;
    /// Bits per sample supported by the codec.
    vector<uint8> bits_per_sample;
};

enum GainType : 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;
};

struct GainFormat {
    /// Specifies what the numbers for gain represent, e.g. a percentage.
    GainType type;
    /// Minimum gain that could be set in the codec.
    float32 min_gain;
    /// Maximum gain that could be set in the codec.
    float32 max_gain;
    /// Smallest increment for gain values starting from min_gain.
    float32 gain_step;
    /// Is the codec capable of muting.
    bool can_mute;
    /// Is the codec capable of automatic gain control.
    bool can_agc;
};

struct GainState {
    /// Gain amount, this will have different meanings depending on the GainType value.
    float32 gain;
    /// Codec muted state.
    bool muted;
    /// Codec AGC enabled state.
    bool agc_enable;
};

struct Info {
    /// Unique identifier for the codec.
    string unique_id;
    /// Name of the codec manufacturer.
    string manufacturer;
    /// Product name of the codec.
    string product_name;
};

struct PlugState {
    // TODO(andresoportus):  Add can_notify bool to PlugState once asynchronous notifications are
    // added to Banjo.
    bool hardwired;
    bool plugged;
};

[Layout = "ddk-protocol"]
protocol Codec {

    // Main controls.
    /// Resets the codec.
    [Async]
    Reset() -> (zx.status status);
    /// Retrieves textual information about the codec.
    [Async]
    GetInfo() -> (Info info);


    // Bridged mode.
    /// Retrieves bridgeable mode from a codec.
    [Async]
    IsBridgeable() -> (bool supports_bridged_mode);
    /// Sets a codec's bridged mode.  Only required if the codec supports bridged mode as specified
    /// by IsBridgeable's reply.
    [Async]
    SetBridgedMode(bool enable_bridged_mode);


    // DAI Format.
    // TODO(andresoportus):  Add DAI format loss notification support once asynchronous
    // notifications are added to Banjo.
    /// 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.
    [Async]
    GetDaiFormats() -> (zx.status status, vector<DaiSupportedFormats> formats);
    /// Sets the DAI format to be used in the interface between the controller and codec, if
    /// the codec is not able to support the DAI format anymore, e.g. for a removable component
    /// then the function may return an error status.
    [Async]
    SetDaiFormat(DaiFormat format) -> (zx.status status);


    // Gain related.
    [Async]
    // Retrieves gain capabilites/format.
    GetGainFormat() -> (GainFormat format);
    [Async]
    // Retrieves gain related state.
    GetGainState() -> (GainState gain_state);
    [Async]
    // Sets gain state, the client can query current gain state state via GetGainState.
    SetGainState(GainState gain_state);


    // Plug Detect
    /// Retrieves plug detect state.
    [Async]
    GetPlugState() -> (PlugState plug_state);
};