xref: /freebsd/sys/dev/usb/usbhid.h (revision 2ed3236082a4473c1da8f72c1ebc071a7b54321f)
1 /* $FreeBSD$ */
2 /*-
3  * SPDX-License-Identifier: BSD-2-Clause-NetBSD
4  *
5  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
6  * Copyright (c) 1998 The NetBSD Foundation, Inc. All rights reserved.
7  * Copyright (c) 1998 Lennart Augustsson. All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, this list of conditions and the following disclaimer.
14  * 2. Redistributions in binary form must reproduce the above copyright
15  *    notice, this list of conditions and the following disclaimer in the
16  *    documentation and/or other materials provided with the distribution.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  */
30 
31 #ifndef _USB_HID_H_
32 #define	_USB_HID_H_
33 
34 #ifndef USB_GLOBAL_INCLUDE_FILE
35 #include <dev/usb/usb_endian.h>
36 #endif
37 
38 #define	UR_GET_HID_DESCRIPTOR	0x06
39 #define	UDESC_HID		0x21
40 #define	UDESC_REPORT		0x22
41 #define	UDESC_PHYSICAL		0x23
42 #define	UR_SET_HID_DESCRIPTOR	0x07
43 #define	UR_GET_REPORT		0x01
44 #define	UR_SET_REPORT		0x09
45 #define	UR_GET_IDLE		0x02
46 #define	UR_SET_IDLE		0x0a
47 #define	UR_GET_PROTOCOL		0x03
48 #define	UR_SET_PROTOCOL		0x0b
49 
50 struct usb_hid_descriptor {
51 	uByte	bLength;
52 	uByte	bDescriptorType;
53 	uWord	bcdHID;
54 	uByte	bCountryCode;
55 	uByte	bNumDescriptors;
56 	struct {
57 		uByte	bDescriptorType;
58 		uWord	wDescriptorLength;
59 	}	descrs[1];
60 } __packed;
61 
62 #define	USB_HID_DESCRIPTOR_SIZE(n) (9+((n)*3))
63 
64 /* Usage pages */
65 #define	HUP_UNDEFINED		0x0000
66 #define	HUP_GENERIC_DESKTOP	0x0001
67 #define	HUP_SIMULATION		0x0002
68 #define	HUP_VR_CONTROLS		0x0003
69 #define	HUP_SPORTS_CONTROLS	0x0004
70 #define	HUP_GAMING_CONTROLS	0x0005
71 #define	HUP_KEYBOARD		0x0007
72 #define	HUP_LEDS		0x0008
73 #define	HUP_BUTTON		0x0009
74 #define	HUP_ORDINALS		0x000a
75 #define	HUP_TELEPHONY		0x000b
76 #define	HUP_CONSUMER		0x000c
77 #define	HUP_DIGITIZERS		0x000d
78 #define	HUP_PHYSICAL_IFACE	0x000e
79 #define	HUP_UNICODE		0x0010
80 #define	HUP_ALPHANUM_DISPLAY	0x0014
81 #define	HUP_MONITOR		0x0080
82 #define	HUP_MONITOR_ENUM_VAL	0x0081
83 #define	HUP_VESA_VC		0x0082
84 #define	HUP_VESA_CMD		0x0083
85 #define	HUP_POWER		0x0084
86 #define	HUP_BATTERY_SYSTEM	0x0085
87 #define	HUP_BARCODE_SCANNER	0x008b
88 #define	HUP_SCALE		0x008c
89 #define	HUP_CAMERA_CONTROL	0x0090
90 #define	HUP_ARCADE		0x0091
91 #define	HUP_MICROSOFT		0xff00
92 
93 /* Usages, generic desktop */
94 #define	HUG_POINTER		0x0001
95 #define	HUG_MOUSE		0x0002
96 #define	HUG_JOYSTICK		0x0004
97 #define	HUG_GAME_PAD		0x0005
98 #define	HUG_KEYBOARD		0x0006
99 #define	HUG_KEYPAD		0x0007
100 #define	HUG_X			0x0030
101 #define	HUG_Y			0x0031
102 #define	HUG_Z			0x0032
103 #define	HUG_RX			0x0033
104 #define	HUG_RY			0x0034
105 #define	HUG_RZ			0x0035
106 #define	HUG_SLIDER		0x0036
107 #define	HUG_DIAL		0x0037
108 #define	HUG_WHEEL		0x0038
109 #define	HUG_HAT_SWITCH		0x0039
110 #define	HUG_COUNTED_BUFFER	0x003a
111 #define	HUG_BYTE_COUNT		0x003b
112 #define	HUG_MOTION_WAKEUP	0x003c
113 #define	HUG_VX			0x0040
114 #define	HUG_VY			0x0041
115 #define	HUG_VZ			0x0042
116 #define	HUG_VBRX		0x0043
117 #define	HUG_VBRY		0x0044
118 #define	HUG_VBRZ		0x0045
119 #define	HUG_VNO			0x0046
120 #define	HUG_TWHEEL		0x0048	/* M$ Wireless Intellimouse Wheel */
121 #define	HUG_SYSTEM_CONTROL	0x0080
122 #define	HUG_SYSTEM_POWER_DOWN	0x0081
123 #define	HUG_SYSTEM_SLEEP	0x0082
124 #define	HUG_SYSTEM_WAKEUP	0x0083
125 #define	HUG_SYSTEM_CONTEXT_MENU	0x0084
126 #define	HUG_SYSTEM_MAIN_MENU	0x0085
127 #define	HUG_SYSTEM_APP_MENU	0x0086
128 #define	HUG_SYSTEM_MENU_HELP	0x0087
129 #define	HUG_SYSTEM_MENU_EXIT	0x0088
130 #define	HUG_SYSTEM_MENU_SELECT	0x0089
131 #define	HUG_SYSTEM_MENU_RIGHT	0x008a
132 #define	HUG_SYSTEM_MENU_LEFT	0x008b
133 #define	HUG_SYSTEM_MENU_UP	0x008c
134 #define	HUG_SYSTEM_MENU_DOWN	0x008d
135 #define	HUG_APPLE_EJECT		0x00b8
136 
137 /* Usages Digitizers */
138 #define	HUD_UNDEFINED		0x0000
139 #define	HUD_DIGITIZER		0x0001
140 #define	HUD_PEN			0x0002
141 #define	HUD_TOUCHSCREEN		0x0004
142 #define	HUD_TOUCHPAD		0x0005
143 #define	HUD_CONFIG		0x000e
144 #define	HUD_FINGER		0x0022
145 #define	HUD_TIP_PRESSURE	0x0030
146 #define	HUD_BARREL_PRESSURE	0x0031
147 #define	HUD_IN_RANGE		0x0032
148 #define	HUD_TOUCH		0x0033
149 #define	HUD_UNTOUCH		0x0034
150 #define	HUD_TAP			0x0035
151 #define	HUD_QUALITY		0x0036
152 #define	HUD_DATA_VALID		0x0037
153 #define	HUD_TRANSDUCER_INDEX	0x0038
154 #define	HUD_TABLET_FKEYS	0x0039
155 #define	HUD_PROGRAM_CHANGE_KEYS	0x003a
156 #define	HUD_BATTERY_STRENGTH	0x003b
157 #define	HUD_INVERT		0x003c
158 #define	HUD_X_TILT		0x003d
159 #define	HUD_Y_TILT		0x003e
160 #define	HUD_AZIMUTH		0x003f
161 #define	HUD_ALTITUDE		0x0040
162 #define	HUD_TWIST		0x0041
163 #define	HUD_TIP_SWITCH		0x0042
164 #define	HUD_SEC_TIP_SWITCH	0x0043
165 #define	HUD_BARREL_SWITCH	0x0044
166 #define	HUD_ERASER		0x0045
167 #define	HUD_TABLET_PICK		0x0046
168 #define	HUD_CONFIDENCE		0x0047
169 #define	HUD_WIDTH		0x0048
170 #define	HUD_HEIGHT		0x0049
171 #define	HUD_CONTACTID		0x0051
172 #define	HUD_INPUT_MODE		0x0052
173 #define	HUD_DEVICE_INDEX	0x0053
174 #define	HUD_CONTACTCOUNT	0x0054
175 #define	HUD_CONTACT_MAX		0x0055
176 #define	HUD_SCAN_TIME		0x0056
177 #define	HUD_SURFACE_SWITCH	0x0057
178 #define	HUD_BUTTONS_SWITCH	0x0058
179 #define	HUD_BUTTON_TYPE		0x0059
180 #define	HUD_LATENCY_MODE	0x0060
181 
182 /* Usages, Consumer */
183 #define	HUC_AC_PAN		0x0238
184 
185 #define	HID_USAGE2(p,u) (((p) << 16) | (u))
186 
187 #define	UHID_INPUT_REPORT 0x01
188 #define	UHID_OUTPUT_REPORT 0x02
189 #define	UHID_FEATURE_REPORT 0x03
190 
191 /* Bits in the input/output/feature items */
192 #define	HIO_CONST	0x001
193 #define	HIO_VARIABLE	0x002
194 #define	HIO_RELATIVE	0x004
195 #define	HIO_WRAP	0x008
196 #define	HIO_NONLINEAR	0x010
197 #define	HIO_NOPREF	0x020
198 #define	HIO_NULLSTATE	0x040
199 #define	HIO_VOLATILE	0x080
200 #define	HIO_BUFBYTES	0x100
201 
202 /* Units of Measure */
203 #define	HUM_CENTIMETER	0x11
204 #define	HUM_RADIAN	0x12
205 #define	HUM_INCH	0x13
206 #define	HUM_DEGREE	0x14
207 
208 #ifdef _KERNEL
209 struct usb_config_descriptor;
210 
211 enum hid_kind {
212 	hid_input, hid_output, hid_feature, hid_collection, hid_endcollection
213 };
214 
215 struct hid_location {
216 	uint32_t size;
217 	uint32_t count;
218 	uint32_t pos;
219 };
220 
221 struct hid_item {
222 	/* Global */
223 	int32_t	_usage_page;
224 	int32_t	logical_minimum;
225 	int32_t	logical_maximum;
226 	int32_t	physical_minimum;
227 	int32_t	physical_maximum;
228 	int32_t	unit_exponent;
229 	int32_t	unit;
230 	int32_t	report_ID;
231 	/* Local */
232 	int32_t	usage;
233 	int32_t	usage_minimum;
234 	int32_t	usage_maximum;
235 	int32_t	designator_index;
236 	int32_t	designator_minimum;
237 	int32_t	designator_maximum;
238 	int32_t	string_index;
239 	int32_t	string_minimum;
240 	int32_t	string_maximum;
241 	int32_t	set_delimiter;
242 	/* Misc */
243 	int32_t	collection;
244 	int	collevel;
245 	enum hid_kind kind;
246 	uint32_t flags;
247 	/* Location */
248 	struct hid_location loc;
249 };
250 
251 /* prototypes from "usb_hid.c" */
252 
253 struct hid_data *hid_start_parse(const void *d, usb_size_t len, int kindset);
254 void	hid_end_parse(struct hid_data *s);
255 int	hid_get_item(struct hid_data *s, struct hid_item *h);
256 int	hid_report_size(const void *buf, usb_size_t len, enum hid_kind k,
257 	    uint8_t *id);
258 int	hid_locate(const void *desc, usb_size_t size, int32_t usage,
259 	    enum hid_kind kind, uint8_t index, struct hid_location *loc,
260 	    uint32_t *flags, uint8_t *id);
261 int32_t hid_get_data(const uint8_t *buf, usb_size_t len,
262 	    struct hid_location *loc);
263 uint32_t hid_get_data_unsigned(const uint8_t *buf, usb_size_t len,
264 	    struct hid_location *loc);
265 void hid_put_data_unsigned(uint8_t *buf, usb_size_t len,
266 	    struct hid_location *loc, unsigned int value);
267 int	hid_is_collection(const void *desc, usb_size_t size, int32_t usage);
268 struct usb_hid_descriptor *hid_get_descriptor_from_usb(
269 	    struct usb_config_descriptor *cd,
270 	    struct usb_interface_descriptor *id);
271 usb_error_t usbd_req_get_hid_desc(struct usb_device *udev, struct mtx *mtx,
272 	    void **descp, uint16_t *sizep, struct malloc_type *mem,
273 	    uint8_t iface_index);
274 int32_t	hid_item_resolution(struct hid_item *hi);
275 int	hid_is_mouse(const void *d_ptr, uint16_t d_len);
276 int	hid_is_keyboard(const void *d_ptr, uint16_t d_len);
277 #endif					/* _KERNEL */
278 #endif					/* _USB_HID_H_ */
279