xref: /freebsd/sys/dev/hid/hid_if.m (revision a6fb86917362e3f6d24e95e940e80845c2cfde8a)
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 paniced. 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