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

const uint32 MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS = 64;
const uint32 MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS = 4;
const uint32 MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS = 64;
const uint32 MAX_COUNT_DAI_SUPPORTED_RATES = 64;
const uint32 MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT = 8;
const uint32 MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE = 8;

enum DaiSampleFormat : uint8 {
    /// Pulse Density Modulation samples.
    PDM = 1;

    /// Signed Linear Pulse Code Modulation samples at the host endianness.
    PCM_SIGNED = 2;

    /// Unsigned Linear Pulse Code Modulation samples at the host endianness.
    PCM_UNSIGNED = 3;

    /// Floating point samples IEEE-754 encoded.
    PCM_FLOAT = 4;
};

/// Either a standard or custom frame format.
union DaiFrameFormat {
    /// The format type of all samples in the DAI, listed in `DaiFrameFormatStandard`.
    1: DaiFrameFormatStandard frame_format_standard;

    /// The format type of all samples in the DAI, specified in `DaiFrameFormatCustom`.
    2: DaiFrameFormatCustom frame_format_custom;
};

/// Standard Frame format.
enum DaiFrameFormatStandard : 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 Frame format.
struct DaiFrameFormatCustom {
    /// 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;
};

/// DAI format. Frames are made up of `number_of_channels` samples which have `bits_per_sample` bits
/// of data within `bits_per_slot` arranged in `frame_format`. For more detailed information see
/// [Digital Audio Interface](//docs/concepts/drivers/driver_interfaces/audio_dai.md).
struct DaiFormat {
    /// Number of channels.
    uint32 number_of_channels;
    /// Which channels to use.
    uint64 channels_to_use_bitmask;
    /// The sample format of all samples.
    DaiSampleFormat sample_format;
    /// The frame format of all samples.
    DaiFrameFormat frame_format;
    /// The frame rate for all samples.
    uint32 frame_rate;
    /// The bits per slot for all channels.
    uint8 bits_per_slot;
    /// The bits per sample for all samples.  Must be smaller than bits per channel for samples to
    /// fit.
    uint8 bits_per_sample;
};

/// Formats supported by the DAI. Frames are made up of `number_of_channels` samples which have
/// `bits_per_sample` bits of data within `bits_per_slot` bits arranged in `frame_formats`.
/// All values listed in each vector are supported. When not all combinations supported by the driver
/// can be described with one `DaiSupportedFormats`, `GetDaiSupportedFormats` returns more than one
/// `DaiSupportedFormats` in the returned vector.
/// For more detailed information see
/// [Digital Audio Interface](//docs/concepts/drivers/driver_interfaces/audio_dai.md).
struct DaiSupportedFormats {
    /// Possible number of channels supported.
    vector<uint32>:MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS number_of_channels;
    /// Sample formats supported.
    vector<DaiSampleFormat>:MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS sample_formats;
    /// Frame formats supported.
    vector<DaiFrameFormat>:MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS frame_formats;
    /// Rates supported.
    vector<uint32>:MAX_COUNT_DAI_SUPPORTED_RATES frame_rates;
    /// The bits per slot supported.
    vector<uint8>:MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT bits_per_slot;
    /// Bits per sample supported.
    vector<uint8>:MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE bits_per_sample;
};