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

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

protocol RadarBurstReader {
    /// Returns the size in bytes of each burst reported by this driver. Clients
    /// should use this size to create VMOs to be registered by the driver.
    ///
    /// - response `burst_size` the size of each radar burst in bytes.
    GetBurstSize() -> (struct {
        burst_size uint32;
    });

    /// 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.
    RegisterVmos(resource struct {
        vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
        vmos vector<zx.handle:VMO>:VMO_VECTOR_MAX_COUNT;
    }) -> (struct {}) 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.
    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()`.
    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.
    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.
    -> OnBurst(struct {
        burst Burst;
    }) 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.
    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
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.
    Connect(resource struct {
        server server_end:RadarBurstReader;
    }) -> (struct {}) error StatusCode;
};