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