sdk/fidl/fuchsia.hardware.input/input.fidl

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

using 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 uint16 MAX_REPORT_IDS = 256;

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

// TODO(fxb/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 size of the report descriptor
    GetReportDescSize() -> (uint16 size);

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

    /// Get the number of reports in the report descriptor
    GetNumReports() -> (uint16 count);

    /// Get the report ids that are used in the report descriptor
    GetReportIds() -> (vector<ReportId>:MAX_REPORT_IDS ids);

    /// Get the size of a single report for the given (type, id) pair.
    GetReportSize(ReportType type, ReportId id) -> (zx.status status, uint16 size);

    /// Get the maximum size of a single input report.
    GetMaxInputReportSize() -> (uint16 size);

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