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
32extern "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 */
129typedef 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
135typedef 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
168typedef struct hid_state {
169	dev_info_t		*hid_dip;	/* per-device info handle */
170	kmutex_t		hid_mutex;	/* for general locking */
171	int			hid_instance;	/* instance number */
172
173	/* Attach/detach flags */
174	int			hid_attach_flags;
175
176	/* device state flag */
177	int			hid_dev_state;
178
179	/* outstanding requests on the default pipe */
180	int			hid_default_pipe_req;
181
182	hid_power_t		*hid_pm;	/* ptr to power struct */
183
184	usb_client_dev_data_t	*hid_dev_data;	/* ptr to usb reg struct */
185
186	usb_dev_descr_t		*hid_dev_descr;	/* device descriptor. */
187
188	/* hid driver is attached to this interface */
189	int			hid_interfaceno;
190
191	usb_if_descr_t		hid_if_descr;		/* interface descr */
192	usb_hid_descr_t		hid_hid_descr;		/* hid descriptor */
193	usb_ep_xdescr_t		hid_ep_intr_xdescr;	/* ep extended desc */
194	hidparser_handle_t	hid_report_descr;	/* report descr */
195
196	usb_pipe_handle_t	hid_default_pipe;	/* default pipe */
197	usb_pipe_handle_t	hid_interrupt_pipe;	/* intr pipe handle */
198
199	int			hid_packet_size;	/* data packet size */
200
201	/* Pipe policy for the interrupt pipe is saved here */
202	usb_pipe_policy_t	hid_intr_pipe_policy;
203
204	/*
205	 * This field is only used if the device provides polled input
206	 * This is state information for the usba layer.
207	 */
208	usb_console_info_t	hid_polled_console_info;
209
210	/*
211	 * This is the buffer that the raw characters are stored in.
212	 * for polled mode.
213	 */
214	uchar_t			*hid_polled_raw_buf;
215
216	/* handle for outputting messages */
217	usb_log_handle_t	hid_log_handle;
218
219	queue_t			*hid_internal_rq;
220	queue_t			*hid_external_rq;
221	/* which one of the above 2 streams gets the input */
222	queue_t			*hid_inuse_rq;
223	int			hid_internal_flag;	/* see below */
224	int			hid_external_flag;	/* see below */
225} hid_state_t;
226
227/* warlock directives, stable data */
228_NOTE(MUTEX_PROTECTS_DATA(hid_state_t::hid_mutex, hid_state_t))
229_NOTE(MUTEX_PROTECTS_DATA(hid_state_t::hid_mutex, hid_power_t))
230_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dip))
231_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_pm))
232_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_data))
233_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_instance))
234_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_interrupt_pipe))
235_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_ep_intr_descr))
236_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_default_pipe))
237_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_log_handle))
238_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_if_descr))
239_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_data))
240_NOTE(DATA_READABLE_WITHOUT_LOCK(hid_state_t::hid_dev_descr))
241_NOTE(SCHEME_PROTECTS_DATA("stable data", usb_ep_descr))
242
243
244/*
245 * The hid_polled_console_info field is a handle from usba.  The
246 * handle is used when the kernel is in the single thread mode
247 * so the field is tagged with this note.
248 */
249_NOTE(SCHEME_PROTECTS_DATA("unique per call",
250				hid_state_t::hid_polled_console_info))
251
252/*
253 * structure for argument for callback routine for async
254 * data transfer through default pipe.
255 */
256typedef struct hid_default_pipe_argument {
257	/* Pointer to the write queue from which the message comes from */
258	queue_t		*hid_default_pipe_arg_queue;
259
260	/* Message to be sent up to the stream */
261	struct iocblk	hid_default_pipe_arg_mctlmsg;
262
263	/* Pointer to the original mblk_t received from hid_wput() */
264	mblk_t		*hid_default_pipe_arg_mblk;
265
266	/* Request that caused this callback to happen */
267	uchar_t		hid_default_pipe_arg_bRequest;
268
269} hid_default_pipe_arg_t;
270
271/*
272 * An instance of this structure is created per command down to the
273 * device.  The control callback is not executed until the call is
274 * made into usba, so there is no danger of a callback happening when
275 * the fields of the structure are being set.
276 */
277_NOTE(SCHEME_PROTECTS_DATA("unique per call", hid_default_pipe_arg_t))
278
279/*
280 * An instance of this structure is created per command down to the
281 * device.  The callback is not executed until the call is
282 * made into usba, so there is no danger of a callback happening when
283 * the fields of the structure are being set.
284 */
285
286/* Value for hid_[internal|external]_flag */
287#define	HID_STREAMS_OPEN	0x00000001	/* Streams are open */
288#define	HID_STREAMS_DISMANTLING	0x00000002	/* In hid_close() */
289
290#define	HID_STREAMS_FLAG(q, hidp) ((q) == (hidp)->hid_internal_rq ? \
291	(hidp)->hid_internal_flag : (hidp)->hid_external_flag)
292
293#define	HID_IS_OPEN(hidp)	(((hidp)->hid_internal_flag == \
294	HID_STREAMS_OPEN) || ((hidp)->hid_external_flag == HID_STREAMS_OPEN))
295
296#define	HID_BAD_DESCR		0x01		/* Bad hid report descriptor */
297
298#define	HID_MINOR_NAME_LEN	20	/* Max length of minor_name string */
299
300/* hid_close will wait 60 secons for callbacks to be over */
301#define	HID_CLOSE_WAIT_TIMEOUT	10
302
303/* define a timeout for draining requests on the default control pipe */
304#define	HID_DEFAULT_PIPE_DRAIN_TIMEOUT	5
305
306/* To support PM on SUN mice of later revisions */
307#define	HID_SUN_MOUSE_VENDOR_ID	0x0430
308#define	HID_SUN_MOUSE_PROD_ID	0x0100
309#define	HID_SUN_MOUSE_BCDDEVICE	0x0105	/* and later revisions */
310
311
312/*
313 * Debug message Masks
314 */
315#define	PRINT_MASK_ATTA		0x00000001
316#define	PRINT_MASK_OPEN 	0x00000002
317#define	PRINT_MASK_CLOSE	0x00000004
318#define	PRINT_MASK_EVENTS	0x00000008
319#define	PRINT_MASK_PM		0x00000010
320#define	PRINT_MASK_ALL		0xFFFFFFFF
321
322/*
323 * Define states local to hid driver
324 */
325#define	USB_DEV_HID_POWER_CHANGE 0x80
326
327/* define for retrying control requests */
328#define	HID_RETRY	10
329
330#ifdef __cplusplus
331}
332#endif
333
334#endif	/* _SYS_USB_HIDVAR_H */
335