// 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 HID_MAX_DESC_LEN uint16 = 8192;

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

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

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

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

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

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

    vendor_id uint32;
    product_id uint32;
    version uint32;
};

@transport("Banjo")
@banjo_layout("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(struct {
        @buffer
        buf vector<uint8>:MAX;
        timestamp zx.time;
    }) -> ();
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol Hidbus {
    /// Obtain information about the hidbus device and supported features.
    /// Safe to call at any time.
    Query(struct {
        options uint32;
    }) -> (struct {
        s zx.status;
        info HidInfo;
    });
    /// 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(resource struct {
        ifc client_end:HidbusIfc;
    }) -> (struct {
        s zx.status;
    });
    /// Stop the hidbus device. Safe to call if the hidbus is already stopped.
    Stop() -> ();
    GetDescriptor(struct {
        desc_type HidDescriptionType;
    }) -> (struct {
        s zx.status;
        @buffer
        data vector<uint8>:MAX;
    });
    GetReport(struct {
        rpt_type HidReportType;
        rpt_id uint8;
    }) -> (struct {
        s zx.status;
        @buffer
        data vector<uint8>:MAX;
    });
    SetReport(struct {
        rpt_type HidReportType;
        rpt_id uint8;
        @buffer
        data vector<uint8>:MAX;
    }) -> (struct {
        s zx.status;
    });
    GetIdle(struct {
        rpt_id uint8;
    }) -> (struct {
        s zx.status;
        duration uint8;
    });
    SetIdle(struct {
        rpt_id uint8;
        duration uint8;
    }) -> (struct {
        s zx.status;
    });
    GetProtocol() -> (struct {
        s zx.status;
        protocol HidProtocol;
    });
    SetProtocol(struct {
        protocol HidProtocol;
    }) -> (struct {
        s zx.status;
    });
};