// Copyright 2021 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.
@available(added=7)
library fuchsia.hardware.radar;
using zx;

/// Arbitrary limit on the number of VMOs in one call to `RegisterVmos()` or
/// `UnregisterVmos()`; enough for ten seconds of radar data for the existing
/// driver.
const VMO_VECTOR_MAX_COUNT uint32 = 300;

type StatusCode = strict enum {
    /// An unspecified error occurred (generally should not be used).
    UNSPECIFIED = 0;

    /// The request completed successfully.
    SUCCESS = 1;

    /// `Connect()` was called but the driver is busy handling another client.
    /// The other client will have to close its channel for the driver to become
    /// available again.
    ALREADY_BOUND = 2;

    /// `Connect()` encountered an error trying to bind to the provided server
    /// channel.
    BIND_ERROR = 3;

    /// The vectors passed to `RegisterVmos()` did not have the same size.
    INVALID_ARGS = 4;

    /// A VMO handle was invalid.
    VMO_BAD_HANDLE = 5;

    /// A VMO was already registered with this ID.
    VMO_ALREADY_REGISTERED = 6;

    /// No registered VMO was found for the given ID.
    VMO_NOT_FOUND = 7;

    /// A client VMO could not be written to or mapped due to insufficient
    /// permissions.
    VMO_ACCESS_DENIED = 8;

    /// A client VMO was smaller than the burst size (see `GetBurstSize()`).
    VMO_TOO_SMALL = 9;

    /// A burst was received, but no unlocked VMOs are available.
    OUT_OF_VMOS = 10;

    /// A burst was not received within the expected window.
    SENSOR_TIMEOUT = 11;

    /// An unspecified driver or sensor error was encountered.
    SENSOR_ERROR = 12;

    /// The radar driver or proxy was not in the correct state for this call.
    BAD_STATE = 13;
};

type Burst = struct {
    vmo_id uint32;
    timestamp zx.Time;
};

closed protocol RadarBurstReader {
    strict GetBurstProperties() -> (struct {
        size uint32;
        period zx.Duration;
    });

    /// Registers the VMOs for future use and associates them with vmo_ids,
    /// which can be used with `UnregisterVmos()` and `OnBurst()`. vmos will be
    /// mapped by the driver using `ZX_VM_PERM_WRITE`. The client should only
    /// read registered VMOs that are sent via `OnBurst()`. The size of vmo is
    /// assumed to be at least the burst size, and the sizes of `vmo_ids` and
    /// `vmos` must be the same.
    ///
    /// + request `vmo_ids` the ID numbers to associate with each VMO.
    /// + request `vmos` the VMO handles corresponding to each ID.
    /// * error one of the following `StatusCode` values:
    /// *     `INVALID_ARGS`: `vmo_ids` and `vmos` were of different sizes.
    /// *     `VMO_BAD_HANDLE`: A handle in `vmos` was invalid.
    /// *     `VMO_ALREADY_REGISTERED`: An ID in `vmo_ids` was already
    /// *         registered.
    /// *     `VMO_ACCESS_DENIED`: A VMO in `vmos` could not be mapped due to
    /// *         insufficient permissions.
    /// *     `VMO_TOO_SMALL`: A VMO in `vmos` was smaller than the burst size.
    strict RegisterVmos(resource struct {
        vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
        vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
    }) -> () error StatusCode;

    /// Removes the associations with the given VMO IDs and returns the VMOs to
    /// the client. The driver will not send any more `OnBurst()` events with
    /// these VMO IDs after replying, however the client may still receive
    /// bursts with these IDs if they were in flight during this call. The
    /// driver must return all of the requested VMOs, or return an error. In
    /// case of an error, the driver may have unregistered some or all of the
    /// requested VMOs.
    ///
    /// + request `vmo_ids` the IDs of the VMOs to unregister and return.
    /// - response `vmos` the VMO handles corresponding to `vmo_ids`.
    /// * error one of the following `StatusCode` values:
    /// *     `INVALID_ARGS`: `vmo_ids` was too big.
    /// *     `VMO_NOT_FOUND`: An ID in `vmo_ids` was not registered.
    strict UnregisterVmos(struct {
        vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
    }) -> (resource struct {
        vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
    }) error StatusCode;

    /// Tells the driver to start sending bursts via `OnBurst()`.
    strict StartBursts();

    /// Tells the driver to stop sending bursts via `OnBurst()`. If all clients
    /// call `StopBursts()` then the driver may choose to stop its worker thread.
    /// The driver may wait for a single burst read to complete, but will not
    /// access any of the client’s VMOs or call its observer after replying.
    ///
    /// Note that already inflight `OnBurst()` bursts may still be received by
    /// the client.
    strict StopBursts() -> ();

    /// Returns the ID of a VMO containing a single burst, the time the burst
    /// was received. Ownership of the VMO must be returned to the driver by
    /// calling `UnlockVmo()`, and won't be written by the driver until then.
    /// See the doc for the burst format specification.
    ///
    /// The driver will drop bursts if there are no unlocked VMOs. This also
    /// provides flow control for the number of events in flight. When a burst
    /// is received and no VMOs are unlocked, `OnBurst()` will be called with
    /// `OUT_OF_VMOS` set as the error. `OnBurst` will not be called again until
    /// at least one VMO has been unlocked.
    ///
    /// + request `burst` the ID of a VMO containing the burst, as well as the
    ///     time the burst was received.
    /// * error one of the following `StatusCode` values:
    /// *     `OUT_OF_VMOS`: No unlocked VMOs were available to hold the burst.
    /// *         The driver will wait for at least one VMO to become available
    /// *         before sending more events to this client.
    /// *     `SENSOR_TIMEOUT`: The driver could not drain the sensor FIFO
    /// *         quickly enough.
    /// *     `SENSOR_ERROR`: An unspecified driver or sensor error occurred
    /// *         when trying to read the burst.
    @available(added=14)
    strict -> OnBurst(flexible union {
        1: burst Burst;
        2: error StatusCode;
    });

    @available(removed=17, legacy=true)
    strict -> OnBurst2(flexible union {
        1: burst Burst;
        2: error StatusCode;
    });

    /// Signals to the driver that the client is no longer reading the VMO. The
    /// client must not access the VMO after calling this.
    ///
    /// + request `vmo_id` the ID of the VMO to return to the driver.
    strict UnlockVmo(struct {
        vmo_id uint32;
    });
};

/// The main protocol implemented by radar drivers. Clients use this protocol to
/// establish a `RadarBurstReader` connection with the driver.
@discoverable
closed protocol RadarBurstReaderProvider {
    /// + request `server` the `RadarBurstReader` server end for the driver to
    ///     bind to.
    /// * error one of the following `StatusCode` values:
    ///     `BIND_ERROR`: An error was encountered while trying to bind to the
    ///         provided server channel.
    ///     `ALREADY_BOUND`: Another client has already established a
    ///         `RadarBurstReader` connection with the driver.
    strict Connect(resource struct {
        server server_end:RadarBurstReader;
    }) -> () error StatusCode;
};

closed protocol RadarSensorInfo {
    /// Returns the size and period of bursts reported by the sensor.
    ///
    /// - response `size` the size of each radar burst in bytes.
    /// - response `period` the time between bursts in nanoseconds.
    strict GetBurstProperties() -> (struct {
        size uint32;
        period zx.Duration;
    });
};

type BurstData = resource struct {
    /// A VMO holding zero or more radar bursts of the size reported by
    /// `GetBurstProperties()`. Bursts are stored contiguously with no padding
    /// between them.
    vmo zx.Handle:<VMO, zx.Rights.READ | zx.Rights.MAP>;
    /// The number of bursts stored in `vmo`.
    burst_count uint32;
};

/// Test clients may use this protocol to inject burst data to radar clients
/// through a virtual radar driver. Only one client of this protocol can be
/// connected at a time. radar-proxy will send epitaph status code
/// `ZX_ERR_ALREADY_BOUND` to and close channels from any additional clients
/// that attempt to connect.
@discoverable
closed protocol RadarBurstInjector {
    compose RadarSensorInfo;

    /// Enqueues the given VMO with burst data to be injected. After all bursts
    /// from this VMO have been injected, radar-proxy will move on to the next
    /// VMO in the queue. The caller must not write to the VMO until it has been
    /// returned by `OnBurstsDelivered()`. The VMO will be closed and unmapped
    /// if the injector client unexpectedly disconnects.
    ///
    /// Bursts are injected by radar-proxy at the rate reported by the
    /// underlying driver's `GetBurstProperties()` method. If no VMOs are in the
    /// queue at the time that a burst is to be delivered, radar-proxy will stop
    /// sending bursts until either `EnqueueBursts()` or `StopBurstInjection()`
    /// is called.
    ///
    /// + request `bursts` the `BurstData` struct containing bursts to inject.
    /// - response `bursts_id` the ID to be passed back through
    ///     `OnBurstsDelivered()` after the final burst from this buffer has
    ///     been injected.
    /// * error one of the following `StatusCode` values:
    /// *   `VMO_BAD_HANDLE`: The VMO handle was invalid.
    /// *   `VMO_ACCESS_DENIED`: The VMO had insufficient rights.
    /// *   `VMO_TOO_SMALL`: The VMO was too small to hold the indicated number
    /// *     of bursts.
    /// *   `INVALID_ARGS`: The number of bursts was zero.
    /// *   `BAD_STATE`: A previous call to `StopBurstInjection()` is still
    /// *     pending.
    strict EnqueueBursts(resource struct {
        bursts BurstData;
    }) -> (struct {
        bursts_id uint32;
    }) error StatusCode;

    /// Returns an ID corresponding to a `BurstData` struct previously passed to
    /// `EnqueueBursts()`. Upon receiving this event the client is free to write
    /// to the VMO, and if desired, pass it back to radar-proxy for injection.
    ///
    /// + request `bursts_id` the ID returned by a previous call to
    ///     `EnqueueBursts()`.
    strict -> OnBurstsDelivered(struct {
        bursts_id uint32;
    });

    /// Tells radar-proxy to read future bursts from enqueued VMOs rather than
    /// from the real radar driver. radar-proxy will attempt to deliver the
    /// first injected burst at the time that the radar driver would have done
    /// so. If the queue is or becomes empty then sending of bursts will stop
    /// until more bursts are available in the queue. See `EnqueueBursts()`
    /// above.
    ///
    /// radar-proxy will call `StopBursts()` on the real radar driver before
    /// it starts to deliver the enqueued bursts.
    ///
    /// * error one of the following `StatusCode` values:
    /// *   `BAD_STATE`: Injection has already been started, or a previous call
    /// *     to `StopBurstInjection()` is still pending.
    strict StartBurstInjection() -> () error StatusCode;

    /// Tells radar-proxy to finish injecting bursts from VMOs currently on the
    /// queue then switch back to delivering bursts from the real radar driver.
    /// The reply to this call will not be sent until `OnBurstsDelivered()` has
    /// been called for the final VMO to be injected, and any other calls made
    /// in that time will return errors.
    ///
    /// radar-proxy will call `StartBursts()` on the real radar driver as part
    /// of this call. There may be a delay before RadarBurstReader clients start
    /// to receive bursts from the driver again.
    ///
    /// * error one of the following `StatusCode` values:
    /// *   `BAD_STATE`: Injection has already been stopped, or a call to this
    /// *     method is still pending.
    strict StopBurstInjection() -> () error StatusCode;
};