sdk/banjo/ddk.protocol.codec/codec.banjo

// 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 FrameFormat : uint8 {
    /// No frame format as in samples without a frame sync like PDM.
    NONE = 1;
    /// Format as specified in the I2S specification (left justified, 2 channels, 32 bits per
    /// channel, frame sync stays low for the left channel and high for the right channel, data
    /// starts one clock cycle after frame sync changes clocked out at the falling edge of sclk).
    I2S = 2;
    /// Left justified, 2 channels, data starts at frame sync changes from low to high clocked out
    /// at the falling edge of sclk. The frame sync must stay high for bits_per_channel bits for the
    /// first channel and low for bits_per_channel bits for the second channel.
    STEREO_LEFT = 3;
    /// Right justified, 2 channels. The frame sync must stay high for bits_per_channel bits for the
    /// first channel and low for bits_per_channel bits for the second channel.
    STEREO_RIGHT = 4;
    /// Left justified, variable number of channels, data starts at frame sync changes from low to
    /// high clocked out at the rising edge of sclk. The frame sync must stay high for exactly 1
    /// clock cycle.
    TDM1 = 5;
    /// Custom format specified via FrameFormatCustom.
    CUSTOM = 6;
};

/// Frame format only used if FrameFormat is set to CUSTOM.
struct FrameFormatCustom {
    /// Justification of the samples within a slot.
    bool left_justified;
    /// Clocking of data samples and frame sync output on either raising or falling sclk.
    bool sclk_on_raising;
    /// Number of sclks between the beginning of a frame sync change and audio samples.
    /// For example, for I2S set to 1 and for stereo left justified set to 0.
    int8 frame_sync_sclks_offset;
    /// Number of sclks the frame sync is high within a frame.
    /// For example, for I2S with 32 bits slots set to 32, for TDM usually set to 1.
    uint8 frame_sync_size;
};

struct DaiFormat {
    /// Number of channels in the DAI.
    uint32 number_of_channels;
    /// Which channels to use in the DAI.
    uint64 channels_to_use_bitmask;
    /// The format of all samples in the DAI.
    SampleFormat sample_format;
    /// The format of all samples in the DAI.
    FrameFormat frame_format;
    /// Frame format if frame_format is set to CUSTOM, ignored otherwise.
    FrameFormatCustom frame_format_custom;
    /// The frame rate for all samples in the DAI.
    uint32 frame_rate;
    /// The bits per slot for all channels in the DAI.
    uint8 bits_per_slot;
    /// 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;
    /// Frame formats supported by the codec.
    vector<FrameFormat> frame_formats;
    /// For frame formats supported by the codec specified to be CUSTOM.
    vector<FrameFormatCustom> frame_formats_custom;
    /// Rates supported by the codec.
    vector<uint32> frame_rates;
    /// The bits per slot supported by the codec.
    vector<uint8> bits_per_slot;
    /// 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);
    /// Stops the codec operation.
    [Async]
    Stop() -> (zx.status status);
    /// Start/Re-start the codec operation.
    [Async]
    Start() -> (zx.status status);


    // 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);
};