sdk/fidl/fuchsia.hardware.audio/ring_buffer_format.fidl

// Copyright 2023 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_CHANNELS_IN_RING_BUFFER uint32 = 64;
const MAX_COUNT_SUPPORTED_NUMBER_OF_CHANNELS uint32 = 64;
const MAX_COUNT_CHANNEL_SETS uint32 = 64;
const MAX_COUNT_SUPPORTED_SAMPLE_FORMATS uint32 = 3;
const MAX_COUNT_SUPPORTED_RATES uint32 = 64;
const MAX_COUNT_SUPPORTED_BYTES_PER_SAMPLE uint32 = 8;
const MAX_COUNT_SUPPORTED_VALID_BITS_PER_SAMPLE uint32 = 8;

type SampleFormat = strict enum : uint8 {
    /// Signed integer Linear Pulse Code Modulation samples, at the host endianness.
    PCM_SIGNED = 1;

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

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

/// The specification of a single channel, within the overall channel configuration.
type ChannelAttributes = table {
    /// Minimum frequency guaranteed to be emitted by (or captured in) this channel, in Hz.
    /// If `min_frequency` is not included, then this channel is assumed to cover the entire
    /// low-frequency range of this device.
    ///
    /// Optional.
    // TODO(https://fxbug.dev/42162232): Define expectations beyond these min/max limits and enable drivers
    // to express tolerances related to this.
    1: min_frequency uint32;

    /// Maximum frequency guaranteed to be emitted by (or captured in) this channel, in Hz.
    /// If `max_frequency` is not included, then this channel is assumed to cover the entire
    /// high-frequency range of this device.
    ///
    /// Optional.
    // TODO(https://fxbug.dev/42162232): Define expectations beyond these min/max limits and enable drivers
    // to express tolerances related to this.
    2: max_frequency uint32;
};

/// The specification of a channel configuration.
type ChannelSet = table {
    /// Describes attributes for this channel set.
    /// The size of this vector defines the number of channels supported by this `ChannelSet`.
    /// Each element of the `attributes` vector defines attributes of a single channel.
    ///
    /// Required.
    1: attributes vector<ChannelAttributes>:MAX_COUNT_CHANNELS_IN_RING_BUFFER;
};

/// All the possible formats supported by this device.
type SupportedFormats = table {
    /// Supported formats for non-compressed PCM samples, with attributes.
    ///
    /// Required.
    1: pcm_supported_formats PcmSupportedFormats;
};

/// Format supporting non-compressed PCM audio. Each frame consists of one or more
/// (number_of_channels) samples, stored contiguously. Within the `bytes_per_sample` allocated for
/// each sample, `valid_bits_per_sample` bits of data are stored in the most-significant
/// (left-justified) portion.
/// All values listed in each vector are supported. When not all combinations supported by
/// the driver can be described with one `SupportedFormats` or `PcmSupportedFormats`,
/// `GetSupportedFormats` returns more than one `SupportedFormats` in the returned vector.
/// For more detailed information see [Audio Driver Streaming Interface](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_streaming).
type PcmSupportedFormats = table {
    /// Vector of possible `ChannelSets` supported.
    /// A `ChannelSet` specifies a channel configuration (including a channel-count), plus a number
    /// of optional attributes.
    /// Only one `ChannelSet` is allowed for each unique channel-count. As a result, no two entries
    /// in `channel_sets` can contain `attributes` vectors with the same length.
    ///
    /// Required.
    1: channel_sets vector<ChannelSet>:MAX_COUNT_CHANNEL_SETS;

    /// Vector of possible `SampleFormat`s supported.
    ///
    /// Required.
    2: sample_formats vector<SampleFormat>:MAX_COUNT_SUPPORTED_SAMPLE_FORMATS;

    /// Vector of possible bytes allocated for each sample. Values must be listed in ascending
    /// order. All values listed in `valid_bits_per_sample` must fit into at least the largest
    /// `bytes_per_sample` value.
    ///
    /// Required.
    3: bytes_per_sample vector<uint8>:MAX_COUNT_SUPPORTED_BYTES_PER_SAMPLE;

    /// Vector of possible number of bits containing valid data, within the sample container defined
    /// by `bytes_per_sample`. Values must be listed in ascending order. All values listed must fit
    /// into the largest `bytes_per_sample` value. The valid data bits must be most-significant
    /// (left-justified) within the sample container, and any additional bits will be ignored.
    ///
    /// Required.
    4: valid_bits_per_sample vector<uint8>:MAX_COUNT_SUPPORTED_VALID_BITS_PER_SAMPLE;

    /// Vector of possible frame rates supported. Values must be listed in ascending order.
    ///
    /// Required.
    5: frame_rates vector<uint32>:MAX_COUNT_SUPPORTED_RATES;
};

type Format = table {
    /// Format supporting non-compressed PCM samples.
    ///
    /// Required.
    1: pcm_format PcmFormat;
};

/// Format supporting non-compressed PCM audio. Frames are made up of `number_of_channels` samples
/// which have `valid_bits_per_sample` bits of most-significant (left-justified) data within
/// `bytes_per_sample`. bytes. For more detailed information see
/// [Audio Driver Streaming Interface](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_streaming).
type PcmFormat = struct {
    /// Number of channels.
    number_of_channels uint8;

    /// The format of all samples.
    sample_format SampleFormat;

    /// Bytes allocated to hold a sample, equal or bigger than the valid sample size in
    /// `valid_bits_per_sample`.
    bytes_per_sample uint8;

    /// Number of valid bits in a sample, must be equal or smaller than bits in `bytes_per_sample`.
    /// If smaller, bits are left justified, and any additional bits must be ignored by the
    /// receiver.
    valid_bits_per_sample uint8;

    /// The frame rate for all samples.
    frame_rate uint32;
};