// Copyright 2018 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.input;

using zx;

alias ReportId = uint8;

enum BootProtocol : uint32 {
    NONE = 0;
    KBD = 1;
    MOUSE = 2;
};

const uint16 MAX_DESC_LEN = 8192;
const uint16 MAX_REPORT_LEN = 8192;
const uint16 MAX_REPORT_DATA = 8192;
const uint32 MAX_REPORTS_COUNT = 50;

enum ReportType : uint8 {
    INPUT = 1;
    OUTPUT = 2;
    FEATURE = 3;
};

/// DeviceIds lets a clients determine the vendor and product id for a device.
/// If the device is real HID device, then the id information
/// will come from the device itself. Mock HID devices may assign the
/// ids in the driver. If the mock HID driver does not assign ids, zeros
/// will be used instead.
struct DeviceIds {
    uint32 vendor_id;
    uint32 product_id;
    uint32 version;
};

/// A single HID Report.
struct Report {
    /// The time the report was created, from the view of the monotonic clock.
    zx.time time;
    /// The HID report data. This is guaranteed to always be a full HID report.
    vector<uint8>:MAX_REPORT_DATA data;
};

/// Each `DeviceReportsReader` has its own FIFO of reports in the driver.
/// Calling `ReadReports` drains the Report FIFO. If the Report FIFO
/// fills up between calls to `ReadReports` the channel will be closed.
protocol DeviceReportsReader {
    /// This is a Hanging-Get function to read the reports in the
    /// Report FIFO. This will block until there is at least one
    /// report available.
    /// If there is already one outstanding Hanging-Get, calling this
    /// again will return ZX_ERR_ALREADY_BOUND.
    ReadReports() -> (vector<Report>:MAX_REPORTS_COUNT reports) error zx.status;
};

// TODO(fxbug.dev/49329): This API doesn't follow best practices and needs to be
// cleaned up.
protocol Device {
    /// Get the HID boot interface protocol this device supports
    GetBootProtocol() -> (BootProtocol protocol);

    /// Get the Device's IDs. If this is a real HID device, the IDs will come from the device.
    /// If it is a mock HID decice, the IDs will either be 0's or user defined.
    GetDeviceIds() -> (DeviceIds ids);

    /// Get the report descriptor
    GetReportDesc() -> (vector<uint8>:MAX_DESC_LEN desc);

    /// Open a new DeviceReportsReader on this device. Opening a DeviceReportsReader
    /// allocates a new FIFO for receiving input reports.
    GetDeviceReportsReader(request<DeviceReportsReader> reader) -> () error zx.status;

    /// Read one report out of the report FIFO. Only a single report will be
    /// returned in this API. `time` is the time the report was created, from
    /// the view of the monotonic clock.
    /// If status is ZX_ERR_SHOULD_WAIT the client can wait on the event
    /// from `GetReportsEvent`.
    ReadReport() -> (zx.status status, vector<uint8>:MAX_REPORT_DATA data, zx.time time);

    /// Read up to MAX_REPORT_DATA bytes of reports that have been sent from a device.
    /// This is the interface that is supposed to be used for continuous polling.
    /// Multiple reports can be returned from this API at a time, it is up to the client
    /// to do the parsing of the reports with the correct sizes and offset.
    /// It is guaranteed that only whole reports will be sent.
    /// If there are no reports, this will return ZX_ERR_SHOULD_WAIT, and the client can
    /// wait on the event from `GetReportsEvent`.
    ReadReports() -> (zx.status status, vector<uint8>:MAX_REPORT_DATA data);

    /// Receive an event that will signal on `ZX_USER_SIGNAL_0` when there are reports in the
    /// Device's report FIFO. This signal will be de-asserted when there are no
    /// reports in the Device's report FIFO. This event can be re-used each time
    /// the client wishes to know if there are reports in the FIFO.
    GetReportsEvent() -> (zx.status status, zx.handle:EVENT event);

    /// Send a request to the hardware for a given report described by type and id.
    /// Returns the hardware's response. This interface is not intended
    /// to be used for continuous polling of the reports.
    GetReport(ReportType type, ReportId id) -> (zx.status status, vector<uint8>:MAX_REPORT_LEN report);

    /// Set a single report of the given (type, id) pair.
    SetReport(ReportType type, ReportId id, vector<uint8>:MAX_REPORT_LEN report) -> (zx.status status);

    /// Set the trace ID that is used for HID report flow events.
    SetTraceId(uint32 id);
};