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 device_t child; 53 hid_intr_t intr; 54 void *context; 55 struct hid_rdesc_info *rdesc; 56}; 57 58# 59# Release all allocated resources associated with interrupt transfers. 60# 61METHOD void intr_unsetup { 62 device_t dev; 63 device_t child; 64}; 65 66# 67# Start the interrupt transfers if not already started. 68# 69METHOD int intr_start { 70 device_t dev; 71 device_t child; 72}; 73 74# 75# Stop the interrupt transfers if not already stopped. 76# 77METHOD int intr_stop { 78 device_t dev; 79 device_t child; 80}; 81 82# 83# The following function gets called from the HID keyboard driver when 84# the system has panicked. intr_setup method with NULL passed as intr parameter 85# must be called once before to let transport driver to be prepared. 86# 87METHOD void intr_poll { 88 device_t dev; 89 device_t child; 90}; 91 92# HID interface 93 94# 95# Read out an report descriptor from the HID device. 96# 97METHOD int get_rdesc { 98 device_t dev; 99 device_t child; 100 void *data; 101 hid_size_t len; 102}; 103 104# 105# Get input data from the device. Data should be read in chunks 106# of the size prescribed by the report descriptor. 107# This function interferes with interrupt transfers and should not be used. 108# 109METHOD int read { 110 device_t dev; 111 device_t child; 112 void *data; 113 hid_size_t maxlen; 114 hid_size_t *actlen; 115}; 116 117# 118# Send data to the device. Data should be written in 119# chunks of the size prescribed by the report descriptor. 120# 121METHOD int write { 122 device_t dev; 123 device_t child; 124 const void *data; 125 hid_size_t len; 126}; 127 128# 129# Get a report from the device without waiting for data on the interrupt. 130# Copies a maximum of len bytes of the report data into the memory specified 131# by data. Upon return actlen is set to the number of bytes copied. The type 132# field indicates which report is requested. It should be HID_INPUT_REPORT, 133# HID_OUTPUT_REPORT, or HID_FEATURE_REPORT. This call may fail if the device 134# does not support this feature. 135# 136METHOD int get_report { 137 device_t dev; 138 device_t child; 139 void *data; 140 hid_size_t maxlen; 141 hid_size_t *actlen; 142 uint8_t type; 143 uint8_t id; 144}; 145 146# 147# Set a report in the device. The type field indicates which report is to be 148# set. It should be HID_INPUT_REPORT, HID_OUTPUT_REPORT, or HID_FEATURE_REPORT. 149# The value of the report is specified by the data and the len fields. 150# This call may fail if the device does not support this feature. 151# 152METHOD int set_report { 153 device_t dev; 154 device_t child; 155 const void *data; 156 hid_size_t len; 157 uint8_t type; 158 uint8_t id; 159}; 160 161# 162# Set duration between input reports (in mSec). 163# 164METHOD int set_idle { 165 device_t dev; 166 device_t child; 167 uint16_t duration; 168 uint8_t id; 169}; 170 171# 172# Switch between the boot protocol and the report protocol (or vice versa). 173# 174METHOD int set_protocol { 175 device_t dev; 176 device_t child; 177 uint16_t protocol; 178}; 179 180# 181# Executes arbitrary transport backend command. 182# Format of command is defined by hardware transport driver. 183# 184METHOD int ioctl { 185 device_t dev; 186 device_t child; 187 unsigned long cmd; 188 uintptr_t data; 189}; 190