// 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 MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS uint32 = 64;
const MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS uint32 = 4;
const MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS uint32 = 64;
const MAX_COUNT_DAI_SUPPORTED_RATES uint32 = 64;
const MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT uint32 = 8;
const MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE uint32 = 8;

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

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

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

    /// Floating point samples, encoded per the IEEE-754 standard.
    PCM_FLOAT = 4;
};

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

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

/// Standard Frame format.
type DaiFrameFormatStandard = strict enum : 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;
    /// Left justified, variable number of channels, data starts one clock cycle after the 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.
    @available(added=10)
    TDM2 = 6;
    /// Left justified, variable number of channels, data starts two clock cycles after the 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.
    @available(added=10)
    TDM3 = 7;
};

/// Custom Frame format.
type DaiFrameFormatCustom = struct {
    /// Justification of the samples within a slot.
    left_justified bool;
    /// Clocking of data samples and frame sync output on either raising or falling sclk.
    /// If true then the sclk raises on the raising edge of the data and frame sync, i.e.
    /// the data will be sampled on the falling edge of sclk (the middle of the sclk cycle).
    /// Hence, if false then data will be sampled on the raising edge of sclk.
    sclk_on_raising bool;
    /// 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.
    frame_sync_sclks_offset int8;
    /// 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.
    frame_sync_size uint8;
};

/// 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](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_dai).
type DaiFormat = struct {
    /// Number of channels.
    number_of_channels uint32;
    /// Sets which channels are active via a bitmask.
    /// The least significant bit corresponds to channel index 0.
    channels_to_use_bitmask uint64;
    /// The sample format of all samples.
    sample_format DaiSampleFormat;
    /// The frame format of all samples.
    frame_format DaiFrameFormat;
    /// The frame rate for all samples.
    frame_rate uint32;
    /// The bits per slot for all channels.
    bits_per_slot uint8;
    /// The bits per sample for all samples.  Must be smaller than bits per channel for samples to
    /// fit.
    bits_per_sample uint8;
};

/// 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](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_dai).
type DaiSupportedFormats = struct {
    /// Possible number of channels supported.
    number_of_channels vector<uint32>:MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS;
    /// Sample formats supported.
    sample_formats vector<DaiSampleFormat>:MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS;
    /// Frame formats supported.
    frame_formats vector<DaiFrameFormat>:MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS;
    /// Rates supported. Values must be listed in ascending order.
    frame_rates vector<uint32>:MAX_COUNT_DAI_SUPPORTED_RATES;
    /// The bits per slot supported. Values must be listed in ascending order.
    bits_per_slot vector<uint8>:MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT;
    /// Bits per sample supported. Values must be listed in ascending order.
    bits_per_sample vector<uint8>:MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE;
};