1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef _SYS_USB_HIDVAR_H
28 #define	_SYS_USB_HIDVAR_H
29 
30 
31 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 #include <sys/usb/usba/usbai_private.h>
36 
37 /*
38  * HID : This header file contains the internal structures
39  * and variable definitions used in hid driver.
40  */
41 
42 /*
43  * HID USB device state management :
44  *
45  *	ONLINE-----1--->SUSPENDED----2---->ONLINE
46  *	  |
47  *	  +-----3--->DISCONNECTED----4----->ONLINE
48  *	  |
49  *	  +-----7--->POWERED DOWN----8----->POWER CHANGE---9--->ONLINE
50  *						|
51  *						+---3--->DISCONNECTED
52  *
53  *	POWERED DOWN----1--->SUSPENDED------2----->POWERED DOWN
54  *	  |		      |     ^
55  *	  |		      5     |
56  *	  |		      |     6
57  *	  |		      v     |
58  *	  +---------3----->DISCONNECTED-------4----->POWERED DOWN
59  *
60  *	1 = CPR SUSPEND
61  *	2 = CPR RESUME (with original device)
62  *	3 = Device Unplug
63  *	4 = Original Device Plugged in
64  *	5 = CPR RESUME (with device disconnected or with a wrong device)
65  *	6 = CPR SUSPEND on a disconnected device
66  *	7 = Device idles for time T & transitions to low power state
67  *	8 = Remote wakeup by device OR Application kicking off IO to device
68  *          This results in a Transistion state till PM calls the power
69  *	    entry point to raise the power level of the device
70  *	9 = Device entry point called to raise power level of the device
71  *
72  */
73 
74 
75 /* Boot Interface Subclass for HID devices */
76 #define	BOOT_INTERFACE		0x01
77 
78 /* Boot protocol values for keyboard and mouse */
79 #define	KEYBOARD_PROTOCOL	0x01		/* legacy keyboard */
80 #define	MOUSE_PROTOCOL		0x02		/* legacy mouse */
81 #define	NONE_PROTOCOL		0
82 /*
83  * If the hid descriptor is not valid, the following values are
84  * used.
85  */
86 #define	USBKPSZ 		8	/* keyboard packet size */
87 #define	USBMSSZ 		3	/* mouse packet size */
88 #define	USB_KB_HID_DESCR_LENGTH 0x3f 	/* keyboard Report descr length */
89 #define	USB_MS_HID_DESCR_LENGTH 0x32 	/* mouse Report descr length */
90 
91 /*
92  * Flags for the default pipe.
93  */
94 #define	HID_DEFAULT_PIPE_BUSY	0x01
95 
96 /*
97  * Hid interrupt pipe states. Interrupt pipe
98  * can be in only one of these states :
99  *
100  *	open--1-->data_transferring--1-->open
101  *	 |
102  *	 |----2---->closed
103  *
104  *	1 = interrupt pipe callback
105  *	2 = hid_close
106  */
107 #define	HID_INTERRUPT_PIPE_CLOSED 0x00 /* Int. pipe is closed */
108 #define	HID_INTERRUPT_PIPE_OPEN	0x01 /* Int. pipe is opened */
109 
110 /* HID mctl processing return codes */
111 #define	HID_SUCCESS	0	/* mctl processed successfully */
112 #define	HID_INPROGRESS	1	/* mctl queued/deferred for execution */
113 #define	HID_ENQUEUE	2	/* mctl queued/deferred for execution */
114 #define	HID_FAILURE	-1	/* mctl processing failed */
115 
116 /* Data is being sent up */
117 #define	HID_INTERRUPT_PIPE_DATA_TRANSFERRING	0x03
118 
119 /* Attach/detach states */
120 #define	HID_LOCK_INIT		0x01	/* Initial attach state */
121 #define	HID_MINOR_NODES		0x02 	/* Set after minor node is created */
122 
123 /* HID Protocol Requests */
124 #define	SET_IDLE 		0x0a 	/* bRequest value to set idle request */
125 #define	DURATION 		(0<<8) 	/* no. of repeat reports (HID 7.2.4) */
126 #define	SET_PROTOCOL 		0x0b 	/* bRequest value for boot protocol */
127 
128 /* Hid PM scheme */
129 typedef enum {
130 	HID_PM_ACTIVITY,	/* device is power managed by idleness */
131 	HID_PM_OPEN_CLOSE,	/* device is busy on open, idle on close */
132 	HID_PM_APPLICATION	/* device is power managed by application */
133 } hid_pm_scheme_t;
134 
135 typedef struct hid_power {
136 
137 	void			*hid_state;	/* points back to hid_state */
138 
139 	int			hid_pm_busy;	/* device busy accounting */
140 
141 	hid_pm_scheme_t		hid_pm_strategy;	/* device PM */
142 
143 	uint8_t			hid_wakeup_enabled;
144 
145 	/* this is the bit mask of the power states that device has */
146 	uint8_t			hid_pwr_states;
147 
148 	/* wakeup and power transistion capabilites of an interface */
149 	uint8_t			hid_pm_capabilities;
150 
151 	/* flag to indicate if driver is about to raise power level */
152 	boolean_t		hid_raise_power;
153 
154 	/* current power level the device is in */
155 	uint8_t			hid_current_power;
156 
157 	/* mblk indicating that the device has powered up */
158 	mblk_t			*hid_pm_pwrup;
159 } hid_power_t;
160 
161 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_power_t::hid_state))
162 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_power_t::hid_pm_strategy))
163 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_power_t::hid_wakeup_enabled))
164 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_power_t::hid_pwr_states))
165 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_power_t::hid_pm_capabilities))
166 
167 /*
168  * multiple queue support
169  */
170 struct hid_state;
171 typedef struct hid_queue {
172 	struct hid_state	*hidq_statep;
173 	queue_t			*hidq_queue;
174 	minor_t			hidq_minor;
175 	struct hid_queue	*hidq_next;
176 } hid_queue_t;
177 
178 typedef struct hid_state {
179 	dev_info_t		*hid_dip;	/* per-device info handle */
180 	kmutex_t		hid_mutex;	/* for general locking */
181 	int			hid_instance;	/* instance number */
182 
183 	boolean_t		hid_km;		/* for virtual keyboard/mouse */
184 
185 	/* Attach/detach flags */
186 	int			hid_attach_flags;
187 
188 	/* device state flag */
189 	int			hid_dev_state;
190 
191 	/* outstanding requests on the default pipe */
192 	int			hid_default_pipe_req;
193 
194 	hid_power_t		*hid_pm;	/* ptr to power struct */
195 
196 	usb_client_dev_data_t	*hid_dev_data;	/* ptr to usb reg struct */
197 
198 	usb_dev_descr_t		*hid_dev_descr;	/* device descriptor. */
199 
200 	/* hid driver is attached to this interface */
201 	int			hid_interfaceno;
202 
203 	usb_if_descr_t		hid_if_descr;		/* interface descr */
204 	usb_hid_descr_t		hid_hid_descr;		/* hid descriptor */
205 	usb_ep_descr_t		hid_ep_intr_descr;
206 	hidparser_handle_t	hid_report_descr;	/* report descr */
207 
208 	usb_pipe_handle_t	hid_default_pipe;	/* default pipe */
209 	usb_pipe_handle_t	hid_interrupt_pipe;	/* intr pipe handle */
210 
211 	int			hid_streams_flags;	/* see below */
212 	int			hid_packet_size;	/* data packet size */
213 
214 	/* Pipe policy for the interrupt pipe is saved here */
215 	usb_pipe_policy_t	hid_intr_pipe_policy;
216 
217 	/*
218 	 * This field is only used if the device provides polled input
219 	 * This is state information for the usba layer.
220 	 */
221 	usb_console_info_t	hid_polled_console_info;
222 
223 	/*
224 	 * This is the buffer that the raw characters are stored in.
225 	 * for polled mode.
226 	 */
227 	uchar_t			*hid_polled_raw_buf;
228 
229 	/* handle for outputting messages */
230 	usb_log_handle_t	hid_log_handle;
231 
232 	/*
233 	 * This is the list of STREAMS queues built upon the device. Only
234 	 * one queue on this list is active at any time - the list head.
235 	 * Once the active queue is closed, the next one on the list
236 	 * will be activated. The USB pipes will be closed if all queues
237 	 * have been closed.
238 	 */
239 	hid_queue_t		*hid_queue_list;
240 } hid_state_t;
241 
242 /* warlock directives, stable data */
243 _NOTE(MUTEX_PROTECTS_DATA(hid_state_t::hid_mutex, hid_state_t))
244 _NOTE(MUTEX_PROTECTS_DATA(hid_state_t::hid_mutex, hid_power_t))
245 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dip))
246 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_pm))
247 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_data))
248 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_instance))
249 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_km))
250 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_interrupt_pipe))
251 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_ep_intr_descr))
252 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_default_pipe))
253 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_log_handle))
254 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_if_descr))
255 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_data))
256 _NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_descr))
257 _NOTE(SCHEME_PROTECTS_DATA("stable data", usb_ep_descr))
258 _NOTE(SCHEME_PROTECTS_DATA("stable data", hid_queue_t::hidq_queue))
259 _NOTE(SCHEME_PROTECTS_DATA("stable data", hid_queue_t::hidq_statep))
260 _NOTE(SCHEME_PROTECTS_DATA("stable data", hid_queue_t::hidq_minor))
261 
262 
263 /*
264  * The hid_polled_console_info field is a handle from usba.  The
265  * handle is used when the kernel is in the single thread mode
266  * so the field is tagged with this note.
267  */
268 _NOTE(SCHEME_PROTECTS_DATA("unique per call",
269 				hid_state_t::hid_polled_console_info))
270 
271 /*
272  * structure for argument for callback routine for async
273  * data transfer through default pipe.
274  */
275 typedef struct hid_default_pipe_argument {
276 	/* Pointer to the write queue from which the message comes from */
277 	queue_t		*hid_default_pipe_arg_queue;
278 
279 	/* Message to be sent up to the stream */
280 	struct iocblk	hid_default_pipe_arg_mctlmsg;
281 
282 	/* Pointer to the original mblk_t received from hid_wput() */
283 	mblk_t		*hid_default_pipe_arg_mblk;
284 
285 	/* Request that caused this callback to happen */
286 	uchar_t		hid_default_pipe_arg_bRequest;
287 
288 } hid_default_pipe_arg_t;
289 
290 /*
291  * An instance of this structure is created per command down to the
292  * device.  The control callback is not executed until the call is
293  * made into usba, so there is no danger of a callback happening when
294  * the fields of the structure are being set.
295  */
296 _NOTE(SCHEME_PROTECTS_DATA("unique per call", hid_default_pipe_arg_t))
297 
298 /*
299  * An instance of this structure is created per command down to the
300  * device.  The callback is not executed until the call is
301  * made into usba, so there is no danger of a callback happening when
302  * the fields of the structure are being set.
303  */
304 
305 /* Value for hid_streams_flags */
306 #define	HID_STREAMS_OPEN	0x00000001	/* Streams are open */
307 #define	HID_STREAMS_DISMANTLING	0x00000002	/* In hid_close() */
308 
309 #define	HID_BAD_DESCR		0x01		/* Bad hid report descriptor */
310 
311 #define	HID_MINOR_NAME_LEN	20	/* Max length of minor_name string */
312 
313 /* hid_close will wait 60 secons for callbacks to be over */
314 #define	HID_CLOSE_WAIT_TIMEOUT	10
315 
316 /* define a timeout for draining requests on the default control pipe */
317 #define	HID_DEFAULT_PIPE_DRAIN_TIMEOUT	5
318 
319 /* To support PM on SUN mice of later revisions */
320 #define	HID_SUN_MOUSE_VENDOR_ID	0x0430
321 #define	HID_SUN_MOUSE_PROD_ID	0x0100
322 #define	HID_SUN_MOUSE_BCDDEVICE	0x0105	/* and later revisions */
323 
324 
325 /*
326  * Debug message Masks
327  */
328 #define	PRINT_MASK_ATTA		0x00000001
329 #define	PRINT_MASK_OPEN 	0x00000002
330 #define	PRINT_MASK_CLOSE	0x00000004
331 #define	PRINT_MASK_EVENTS	0x00000008
332 #define	PRINT_MASK_PM		0x00000010
333 #define	PRINT_MASK_ALL		0xFFFFFFFF
334 
335 /*
336  * Define states local to hid driver
337  */
338 #define	USB_DEV_HID_POWER_CHANGE 0x80
339 
340 /* define for retrying control requests */
341 #define	HID_RETRY	10
342 
343 #ifdef __cplusplus
344 }
345 #endif
346 
347 #endif	/* _SYS_USB_HIDVAR_H */
348