// 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 fuchsia.virtualaudio;

using zx;

const uint32 MAX_UI_STRING_SIZE = 256;

// fuchsia.virtualaudio.Forwarder
//

/// Using this Simple Layout (C-bound) protocol, an intermediary (such as the
/// virtual audio service) forwards FIDL protocol requests to the virtual audio
/// driver, which enables clients to use more full-featured (C++ based) bindings
/// with this driver -- specifically the Control, Input and Output protocols.
[ForDeprecatedCBindings]
protocol Forwarder {
    SendControl(request<Control> control);
    SendInput(request<Input> input);
    SendOutput(request<Output> output);
};

// fuchsia.virtualaudio.Control
//

/// This protocol provides the caller a high-level ON/OFF switch for overall
/// virtual audio functionality at the system level. When virtualaudio is
/// disabled, device configurations can be created and changed, but no devices
/// can be added. When virtualaudio is enabled, device configurations can again
/// be converted into devices by calling `Add()`.
[Discoverable]
protocol Control {
    /// Allow inputs and outputs to be activated, but do not automatically
    /// reactivate those previously deactivated by `Disable()`. Does not affect
    /// existing Configs. By default, virtualaudio is enabled on system startup.
    /// This method's callback can be used as a mechanism to synchronize with
    /// other asynchronous in-flight virtualaudio FIDL operations.
    Enable() -> ();

    /// Deactivate all active inputs/outputs; disallow subsequent activations.
    /// This method's callback can be used as a mechanism to synchronize with
    /// other asynchronous in-flight virtualaudio FIDL operations.
    Disable() -> ();

    /// Return the number of active input and output virtual devices.
    /// This method's callback can be used as a mechanism to synchronize with
    /// other asynchronous in-flight virtualaudio FIDL operations.
    GetNumDevices() -> (uint32 num_input_devices,
                        uint32 num_output_devices);
};

//
// The Input and Output protocols closely correspond to the capabilities
// exposed by the Audio Driver Streaming Interface, fully documented at
// driver-interfaces/audio.md and declared at device/audio.h.
//

// fuchsia.virtualaudio.Input
//
/// This protocol represents an active virtual audio input device. It inherits
/// the parent protocols Device and Configuration. This protocol, as well as the
/// contents of Device, represent actions that can be taken by an active input
/// device -- actions that should be immediately detected and reacted upon by
/// the audio subsystem.
[Discoverable]
protocol Input {
    compose Device;

    // TODO(mpuryear): `SetCaptureSignal()` -- indicate what to "capture".
    // E.g. sinusoid, constant, square, ramp, saw, noise. Can differ by channel.

    // TODO(mpuryear): `PairWithOutput()` -- client passes an output (server)
    // binding; input device returns as captured data the streamed output data.
};

// fuchsia.virtualaudio.Output
//

/// This protocol represents an active virtual audio output device. It inherits
/// the parent protocols Device and Configuration. This protocol, as well as the
/// contents of Device, represent actions that can be taken by an active output
/// device -- actions that should be immediately detected and reacted upon by
/// the audio subsystem.
[Discoverable]
protocol Output {
    compose Device;

    // TODO(mpuryear): any render-specific configuration or runtime triggers.
};

/// This protocol represents the base functionality of active Input and Output
/// audio devices -- methods that are common to both protocols. This protocol,
/// as well as the contents of Output and Input, represent actions that can be
/// taken by an active device -- actions that should be immediately detected and
/// reacted upon by the audio subsystem.
protocol Device {
    compose Configuration;

    /// Activate (`DdkAdd`) the virtual audio device as currently configured. A
    /// device node will be published and detected by the AudioDeviceManager,
    /// and a driver for the virtual device will be loaded and queried. Device
    /// arrivals are exposed to clients by the
    /// `fuchsia.media.AudioDeviceEnumerator` protocol, in `GetDevices()` and
    /// the `->OnDeviceAdded()` event.
    Add();

    /// Deactivate (`DdkRemove`) the active virtual audio device, but retain its
    /// configuration for future activation. The driver for the virtual device
    /// will be unloaded, and the device node closed. Device removals are
    /// exposed to clients by `fuchsia.media.AudioDeviceEnumerator`, in
    /// `GetDevices()` and `->OnDeviceRemoved()`.
    Remove();

    /// Return the format selected by the client, when that client issued an
    /// `AUDIO_STREAM_CMD_SET_FORMAT` command. This can only occur after a
    /// device has been added, and is only allowed to occur before the device's
    /// ring buffer has been returned (i.e., before an
    /// `AUDIO_RB_CMD_GET_BUFFER` command).
    GetFormat() -> (uint32 frames_per_second, uint32 sample_format,
                    uint32 num_channels, zx.duration external_delay);

    /// Notify all subscribed listeners when the above format is set or changed.
    -> OnSetFormat(uint32 frames_per_second, uint32 sample_format,
                   uint32 num_channels, zx.duration external_delay);

    /// Return the current gain state for this device. After a device has been
    /// added, a client can call this at any time -- even before the ring buffer
    /// has been established, or before the format has been set.
    GetGain() -> (bool current_mute, bool current_agc, float32 current_gain_db);

    /// Notify all subscribed listeners when the above gain is set or changed.
    -> OnSetGain(bool current_mute, bool current_agc, float32 current_gain_db);

    /// Return details about the ring buffer that was established in response
    /// to a client `AUDIO_RB_CMD_GET_BUFFER` command. This will only occur
    /// after the client sets the format and retrieves other driver information.
    GetBuffer() -> (zx.handle:VMO ring_buffer, uint32 num_ring_buffer_frames,
                    uint32 notifications_per_ring);

    /// Notify all subscribed listeners when the above buffer has been created.
    -> OnBufferCreated(zx.handle:VMO ring_buffer, uint32 num_ring_buffer_frames,
                       uint32 notifications_per_ring);

    /// Override the position notification frequency set by AudioCore for this
    /// stream, with the given value. Although this method can be called at any
    /// time (including before this Input|Output is added, or after it is
    /// started), logically it makes most sense to call this immediately after
    /// receiving details about the just-created ring buffer, via `GetBuffer` or
    /// the `->OnBufferCreated` event.
    SetNotificationFrequency(uint32 notifications_per_ring);

    /// Notify all subscribed listeners when the device is commanded to Start
    /// streaming. This can only occur after a device is fully configured
    /// (format is set; ring buffer is established and fetched).
    -> OnStart(zx.time start_time);

    /// Notify all subscribed listeners when the device is commanded to Stop
    /// streaming. This can only occur when the device is already Started. Stop
    /// returns the device to a fully-configured state. Upon this command, the
    /// already-set format and ring buffer are retained without change, but
    /// position will re-begin at 0, if the device is again Started.
    -> OnStop(zx.time stop_time, uint32 ring_position);

    /// Return the current position (in bytes) within the ring buffer, along
    /// with the time (per MONOTONIC clock) that corresponds with that position.
    /// This can only be called after the ring buffer is established. If the
    /// device has not yet Started streaming, then zero will always be returned.
    GetPosition() -> (zx.time monotonic_time, uint32 ring_position);

    /// Notify all subscribed listeners, when any `AUDIO_RB_POSITION_NOTIFY`
    /// position notification is issued by the driver. The frequency of these
    /// per-stream notifications is set by AudioCore, reported to VAD clients
    /// via `GetBuffer` or the `->OnBufferCreated` event. VirtualAudioDevice
    /// clients can enable an alternate notification frequency for a given
    /// stream by calling `SetNotificationFrequency`. As with a direct call to
    /// `GetPosition`, the returned parameters are the current position (in
    /// bytes) in the ring buffer, as well as the time (per MONOTONIC clock)
    /// that corresponds with that ring buffer position.
    -> OnPositionNotify(zx.time monotonic_time, uint32 ring_position);

    /// Hot-plug or hot-unplug an active virtual device, at the specified time.
    /// For devices marked as capable of asynchronously notifying the system of
    /// plug changes, the driver will now send the values using
    /// `AUDIO_STREAM_PLUG_DETECT_NOTIFY`. Else, values will be reflected when
    /// the driver is next sent an `AUDIO_STREAM_CMD_PLUG_DETECT` command. This
    /// information is used by the system when determining which device is
    /// default. This, in turn, is exposed to clients by the
    /// `fuchsia.media.AudioDeviceEnumerator` protocol: in `GetDevices()`,
    /// `GetDefaultInputDevice()`/`GetDefaultOutputDevice()` and the
    /// `->OnDefaultDeviceChanged()` event.
    ChangePlugState(zx.time plug_change_time, bool plugged);

    /// Immediately change the virtual device's clock rate, as expressed in the
    /// timing and content of position notifications the driver emits.
    /// 'ppm_monotonic' cannot exceed [-1000,+1000]. Each rate change in rate is
    /// standalone; i.e. successive rate changes are not cumulative.
    AdjustClockRate(int32 ppm_from_monotonic);
};

/// This protocol is conceptually a base protocol to Device. It exposes the
/// methods used to specify the properties of a virtual audio device (its
/// configuration), before the virtual device is instantiated by the call to
/// `Add()`. Although the non-Add methods on this protocol can be called after
/// calling `Add()` (i.e., after Configuration has been converted into active
/// Device), this only changes how future Devices will be created; it has no
/// effect on already-created Devices.
protocol Configuration {
    /// Set the virtual audio device's name. This corresponds to the value
    /// associated with the device node for this virtual device. This must be
    /// called before calling `Add()`, or after `Remove()`.
    SetDeviceName(string device_name);

    /// Set the virtual audio device's manufacturer name. Must be called before
    /// `Add()` or after `Remove()`. After device activation, the driver returns
    /// this value in response to an `AUDIO_STREAM_CMD_GET_STRING` command of ID
    /// `AUDIO_STREAM_STR_ID_MANUFACTURER`. This is exposed to clients via the
    /// `fuchsia.media.AudioDeviceEnumerator` protocol, in an `AudioDeviceInfo`
    /// struct returned from `GetDevices()` and the `->OnDeviceAdded()` event.
    SetManufacturer(string:MAX_UI_STRING_SIZE manufacturer_name);

    /// Set the virtual audio device's product name. This must be called before
    /// `Add()` or after `Remove()`. After device activation, the driver returns
    /// this value in response to an `AUDIO_STREAM_CMD_GET_STRING` command of ID
    /// `AUDIO_STREAM_STR_ID_PRODUCT`. This name is exposed to clients via the
    /// `fuchsia.media.AudioDeviceEnumerator` protocol, in an `AudioDeviceInfo`
    /// struct returned from `GetDevices()` and the `->OnDeviceAdded()` event.
    SetProduct(string:MAX_UI_STRING_SIZE product_name);

    /// Set the virtual audio device's unique ID, a 16-character string. This
    /// must be called before calling `Add()`, or after `Remove()`. Once the
    /// device is activated, this value is returned by the driver in response
    /// to an `AUDIO_STREAM_CMD_GET_UNIQUE_ID` command. This value is exposed
    /// to clients by the `fuchsia.media.AudioDeviceEnumerator` protocol:
    /// returned in an `AudioDeviceInfo` struct by `GetDevices()` or
    /// `->OnDeviceAdded()`.
    SetUniqueId(array<uint8>:16 unique_id);

    /// Add a supported format range for this audio device. This must be called
    /// before calling `Add()`, or after `Remove()`. Once the device is
    /// activated, format ranges are returned by the driver in response to an
    /// `AUDIO_STREAM_CMD_GET_FORMATS` command. sample_format_flags is of type
    /// audio_sample_format_t, and rate_family_flags is a bit field of possible
    /// constants beginning with `ASF_RANGE_FLAG_FPS_`. See audio.h for details.
    AddFormatRange(uint32 sample_format_flags, uint32 min_frame_rate,
                   uint32 max_frame_rate, uint8 min_channels,
                   uint8 max_channels, uint16 rate_family_flags);

    /// Remove the minimal format range that is added by default to all
    /// configurations. As with `AddFormatRange()`, this method must be called
    /// before calling `Add()`, or after `Remove()`.
    ClearFormatRanges();

    [Transitional]
    SetClockDomain(int32 clock_domain);

    /// Set properties for this virtual device's clock. These include the clock
    /// domain and the initial rate difference (in ppm) between its clock and
    /// the local monotonic clock. The clock domain is an int32 provided by the
    /// clock tree to an audio driver; special values for CLOCK_DOMAIN_MONOTONIC
    /// [0], and CLOCK_DOMAIN_EXTERNAL [-1] (not locally controllable) are
    /// defined in fuchsia.hardware.audio/stream.fidl. Other than -1, any
    /// negative value for clock_domain is invalid and will be ignored. A
    /// non-zero value for 'initial_rate_adjustment_ppm' is only valid (and will
    /// only be accepted) if the clock_domain is NOT equal to 0. This method
    /// must be called before calling `Add()`, or after `Remove()`. Once the
    /// device is activated, the clock_domain value is returned by the driver in
    /// response to an `AUDIO_STREAM_CMD_GET_CLOCK_DOMAIN` command, and the
    /// clock rate is expressed in the timing, and values, of position
    /// notifications. Neither clock domain nor position notifications are
    /// directly exposed to clients by public APIs, but these are both used in
    /// AudioCore's device (or more accurately, domain) clock recovery.
    SetClockProperties(int32 clock_domain, int32 initial_rate_adjustment_ppm);

    /// Set the virtual audio device's fifo depth, in bytes. This must be called
    /// before calling `Add()`, or after `Remove()`. Once the device is
    /// activated, the depth of its FIFO is returned by the driver in response
    /// to an `AUDIO_RB_CMD_GET_FIFO_DEPTH` command on the ring buffer channel.
    SetFifoDepth(uint32 fifo_depth_bytes);

    /// Set the virtual audio device's external delay, in nanoseconds. This must
    /// be called before calling `Add()`, or after `Remove()`. Once the device
    /// is activated, this value is returned by the driver in response to an
    /// `AUDIO_STREAM_CMD_SET_FORMAT` command.
    //
    // Treating this as a static property is inadequate, considering that the
    // delay is intended to be calculated from the format that was just set.
    SetExternalDelay(zx.duration external_delay);

    /// Set restrictions for the device ring buffer. This must be called before
    /// calling `Add()`, or after `Remove()`. Once the device is activated, the
    /// ring buffer and its size are returned by the driver in response to an
    /// `AUDIO_RB_CMD_GET_BUFFER` command on the ring buffer channel.
    /// Note: both min_frames and max_frames must be multiples of modulo_frames.
    SetRingBufferRestrictions(uint32 min_frames, uint32 max_frames,
                              uint32 modulo_frames);

    /// Set gain properties for this virtual device. This must be called before
    /// calling `Add()`, or after `Remove()`. Once the device is activated, gain
    /// information is returned by the driver in an
    /// `audio_stream_cmd_get_gain_resp` struct, in response to an
    /// `AUDIO_STREAM_CMD_GET_GAIN` command. This information is exposed to
    /// clients by the `fuchsia.media.AudioDeviceEnumerator` protocol: returned
    /// in an `AudioGainInfo` struct by `GetDeviceGain()` and the
    /// `->OnDeviceGainChanged()` event.
    SetGainProperties(float32 min_gain_db, float32 max_gain_db,
                      float32 gain_step_db, float32 current_gain_db,
                      bool can_mute, bool current_mute,
                      bool can_agc, bool current_agc);

    /// Set plug properties for this virtual device. This must be called before
    /// calling `Add()`, or after `Remove()`. Once the device is activated, plug
    /// information is returned by the driver in response to an
    /// `AUDIO_STREAM_CMD_PLUG_DETECT` command. This information is used by the
    /// system when determining which device is default. This in turn is exposed
    /// to clients by the `fuchsia.media.AudioDeviceEnumerator` protocol: in
    /// `GetDevices()`, `GetDefaultInputDevice()`/`GetDefaultOutputDevice()` and
    /// the `->OnDefaultDeviceChanged()` event.
    SetPlugProperties(zx.time plug_change_time, bool plugged, bool hardwired,
                      bool can_notify);

    /// Return a configuration to its default settings. This call has no effect
    /// on active devices. In other words, it must be called before calling
    /// `Add()`, or after `Remove()`.
    ResetConfiguration();
};