1#- 2# Copyright (c) 2019 Vladimir Kondratyev 3# 4# Redistribution and use in source and binary forms, with or without 5# modification, are permitted provided that the following conditions 6# are met: 7# 1. Redistributions of source code must retain the above copyright 8# notice, this list of conditions and the following disclaimer. 9# 2. Redistributions in binary form must reproduce the above copyright 10# notice, this list of conditions and the following disclaimer in the 11# documentation and/or other materials provided with the distribution. 12# 13# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23# SUCH DAMAGE. 24# 25# $FreeBSD$ 26# 27 28#include <sys/param.h> 29#include <sys/bus.h> 30#include <sys/kernel.h> 31#include <sys/malloc.h> 32#include <dev/hid/hid.h> 33 34# Any function listed here can do unbound sleeps waiting for IO to complete. 35 36INTERFACE hid; 37 38# Interrupts interface 39 40# 41# Allocate memory and initialise interrupt transfers. 42# intr callback function which is called if input data is available. 43# context is the private softc pointer, which will be used to callback. 44# rdesc is pointer to structire containing requested maximal sizes of input, 45# output and feature reports. It is used by hardware transport drivers 46# to determine sizes of internal buffers. 47# This function can be subsequently called with intr parameter set to NULL 48# to request intr_poll method support for transport driver. 49# 50METHOD void intr_setup { 51 device_t dev; 52 hid_intr_t intr; 53 void *context; 54 struct hid_rdesc_info *rdesc; 55}; 56 57# 58# Release all allocated resources associated with interrupt transfers. 59# 60METHOD void intr_unsetup { 61 device_t dev; 62}; 63 64# 65# Start the interrupt transfers if not already started. 66# 67METHOD int intr_start { 68 device_t dev; 69}; 70 71# 72# Stop the interrupt transfers if not already stopped. 73# 74METHOD int intr_stop { 75 device_t dev; 76}; 77 78# 79# The following function gets called from the HID keyboard driver when 80# the system has panicked. intr_setup method with NULL passed as intr parameter 81# must be called once before to let transport driver to be prepared. 82# 83METHOD void intr_poll { 84 device_t dev; 85}; 86 87# HID interface 88 89# 90# Read out an report descriptor from the HID device. 91# 92METHOD int get_rdesc { 93 device_t dev; 94 void *data; 95 hid_size_t len; 96}; 97 98# 99# Get input data from the device. Data should be read in chunks 100# of the size prescribed by the report descriptor. 101# This function interferes with interrupt transfers and should not be used. 102# 103METHOD int read { 104 device_t dev; 105 void *data; 106 hid_size_t maxlen; 107 hid_size_t *actlen; 108}; 109 110# 111# Send data to the device. Data should be written in 112# chunks of the size prescribed by the report descriptor. 113# 114METHOD int write { 115 device_t dev; 116 const void *data; 117 hid_size_t len; 118}; 119 120# 121# Get a report from the device without waiting for data on the interrupt. 122# Copies a maximum of len bytes of the report data into the memory specified 123# by data. Upon return actlen is set to the number of bytes copied. The type 124# field indicates which report is requested. It should be HID_INPUT_REPORT, 125# HID_OUTPUT_REPORT, or HID_FEATURE_REPORT. This call may fail if the device 126# does not support this feature. 127# 128METHOD int get_report { 129 device_t dev; 130 void *data; 131 hid_size_t maxlen; 132 hid_size_t *actlen; 133 uint8_t type; 134 uint8_t id; 135}; 136 137# 138# Set a report in the device. The type field indicates which report is to be 139# set. It should be HID_INPUT_REPORT, HID_OUTPUT_REPORT, or HID_FEATURE_REPORT. 140# The value of the report is specified by the data and the len fields. 141# This call may fail if the device does not support this feature. 142# 143METHOD int set_report { 144 device_t dev; 145 const void *data; 146 hid_size_t len; 147 uint8_t type; 148 uint8_t id; 149}; 150 151# 152# Set duration between input reports (in mSec). 153# 154METHOD int set_idle { 155 device_t dev; 156 uint16_t duration; 157 uint8_t id; 158}; 159 160# 161# Switch between the boot protocol and the report protocol (or vice versa). 162# 163METHOD int set_protocol { 164 device_t dev; 165 uint16_t protocol; 166}; 167 168# 169# Executes arbitrary transport backend command. 170# Format of command is defined by hardware transport driver. 171# 172METHOD int ioctl { 173 device_t dev; 174 unsigned long cmd; 175 uintptr_t data; 176}; 177