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

using zx;

const uint16 HID_MAX_DESC_LEN = 8192;

enum HidDescriptionType : uint8 {
    REPORT = 0x22;
};

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

enum HidProtocol : uint8 {
    BOOT = 0;
    REPORT = 1;
};

enum HidDeviceClass : uint8 {
    OTHER = 0;
    KBD = 1;
    POINTER = 2;
    KBD_POINTER = 3;
};

const uint8 HID_DEVICE_CLASS_FIRST = 0;
const uint8 HID_DEVICE_CLASS_LAS = 3;

struct HidInfo {
    uint8 dev_num;
    HidDeviceClass device_class;
    bool boot_device;

    uint32 vendor_id;
    uint32 product_id;
    uint32 version;
};

[Transport = "Banjo", BanjoLayout = "ddk-interface"]
protocol HidbusIfc {
    /// Queues a report received by the hidbus device.
    /// Timestamp should be whenever the report was created. Ideally it should
    /// come from the driver's IRQ callback. If the driver doesn't have
    /// something like that it should fill this with `zx_clock_get_monotonic()`
    IoQueue([Buffer] vector<uint8>:MAX buf, zx.time timestamp) -> ();
};

[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
protocol Hidbus {
    /// Obtain information about the hidbus device and supported features.
    /// Safe to call at any time.
    Query(uint32 options) -> (zx.status s, HidInfo info);
    /// Start the hidbus device. The device may begin queueing hid reports via
    /// ifc->io_queue before this function returns. It is an error to start an
    /// already-started hidbus device.
    Start(HidbusIfc ifc) -> (zx.status s);
    /// Stop the hidbus device. Safe to call if the hidbus is already stopped.
    Stop() -> ();
    GetDescriptor(HidDescriptionType desc_type) -> (zx.status s, [Buffer] vector<uint8>:MAX data);
    GetReport(HidReportType rpt_type, uint8 rpt_id) -> (zx.status s, [Buffer] vector<uint8>:MAX data);
    SetReport(HidReportType rpt_type, uint8 rpt_id, [Buffer] vector<uint8>:MAX data) -> (zx.status s);
    GetIdle(uint8 rpt_id) -> (zx.status s, uint8 duration);
    SetIdle(uint8 rpt_id, uint8 duration) -> (zx.status s);
    GetProtocol() -> (zx.status s, HidProtocol protocol);
    SetProtocol(HidProtocol protocol) -> (zx.status s);
};