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

using zx;
using fuchsia.hardware.audio.signalprocessing;

const MAX_DAI_UI_STRING_SIZE uint32 = 256;
const MAX_COUNT_DAI_FORMATS uint32 = MAX_COUNT_FORMATS;

type DaiProperties = table {
    /// Driver type is input (true) or output (false)
    ///
    /// Required.
    1: is_input bool;

    /// UI string for the manufacturer name. If not included, the manufacturer is unspecified.
    ///
    /// Optional.
    2: manufacturer string:MAX_DAI_UI_STRING_SIZE;

    /// UI string for the product name. If not included, the product name is unspecified.
    ///
    /// Optional.
    3: product_name string:MAX_DAI_UI_STRING_SIZE;

    /// A unique identifier for the driver.
    /// If not included, there is no unique id for the driver.
    ///
    /// Optional.
    @available(added=20)
    4: unique_id array<uint8, UNIQUE_ID_SIZE>;

    /// An identifier for the clock domain in which this hardware operates. If
    /// two hardware devices have the same clock domain, their clock rates are
    /// identical and perfectly synchronized. Although these two clocks have the
    /// same rate, the clock positions may be offset from each other by an
    /// arbitrary (but fixed) amount. The clock_domain typically comes from a
    /// system wide entity, such as a platform bus or global clock tree.
    ///
    /// There are two special values:
    ///
    /// *  `CLOCK_DOMAIN_MONOTONIC` means the hardware is operating at the same
    ///    rate as the system montonic clock.
    ///
    /// *  `CLOCK_DOMAIN_EXTERNAL` means the hardware is operating at an unknown
    ///    rate and is not synchronized with any known clock, not even with
    ///    other clocks in domain `CLOCK_DOMAIN_EXTERNAL`.
    ///
    /// If the domain is not `CLOCK_DOMAIN_MONOTONIC`, client must use position
    /// notification updates to recover the hardware's clock.
    ///
    /// Required.
    @available(added=20)
    5: clock_domain ClockDomain;
};

/// For an overview see
/// [Digital Audio Interface](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_dai).
/// # Deprecation
///
/// Not supported anymore, instead use an
/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
/// with one DAI and one Ring Buffer, see
/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
@available(deprecated=20)
closed protocol Dai {
    /// Allows providing driver health state.
    compose Health;

    /// Allows providing signal processing capabilities.
    compose fuchsia.hardware.audio.signalprocessing.Connector;

    /// Resets the DAI HW. The `ring_buffer` channel obtained via `CreateRingBuffer` may be closed
    /// by the driver, in this case the client needs to obtain a new `ring_buffer`.
    /// `Reset` returns when the reset is completed. If the driver can't successfully reset the HW,
    /// it will close the DAI protocol channel, in this case the client may obtain a new DAI
    /// protocol channel and retry.
    strict Reset() -> ();

    /// Retrieves top level static properties.
    strict GetProperties() -> (struct {
        properties DaiProperties;
    });

    /// Retrieves the DAI formats supported by the DAI, if not available at the time the DAI
    /// may reply with an error status and the client may retry at a later time.
    /// Retrieving multiple `DaiSupportedFormats` allows for cases where exclusive combinations of
    /// the parameters in SupportedFormats may be supported.
    strict GetDaiFormats() -> (struct {
        dai_formats vector<DaiSupportedFormats>:MAX_COUNT_DAI_FORMATS;
    }) error zx.Status;

    /// Retrieves the ring buffer formats supported by the DAI, if not available at the time the DAI
    /// may reply with an error status and the client may retry at a later time.
    /// Retrieving multiple `SupportedFormats` allows for cases where exclusive combinations of
    /// the parameters in `SupportedFormats` may be supported.
    strict GetRingBufferFormats() -> (struct {
        ring_buffer_formats vector<SupportedFormats>:MAX_COUNT_FORMATS;
    }) error zx.Status;

    /// `CreateRingBuffer` is sent by clients to select both a DAI format and a ring buffer format
    /// based on information that the driver provides in `GetDaiFormats` and `GetRingBufferFormats`,
    /// what is supported by the client, and any other requirement. The `ring_buffer` channel is
    /// used to control the audio buffer, if a previous ring buffer channel had been established and
    /// was still active, the driver must close that (ring buffer) channel and make every attempt to
    /// gracefully quiesce any on-going streaming operations in the process.
    strict CreateRingBuffer(resource struct {
        dai_format DaiFormat;
        ring_buffer_format Format;
        ring_buffer server_end:RingBuffer;
    });
};

/// # Deprecation
///
/// Not supported anymore, instead use an
/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
/// with one DAI and one Ring Buffer, see
/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
@available(deprecated=20)
service DaiService {
    dai client_end:Dai;
};