1 # Copyright 2014 The Chromium Authors. All rights reserved. 2 # Use of this source code is governed by a BSD-style license that can be 3 # found in the LICENSE file. 4 5 """Generic USB gadget functionality. 6 """ 7 8 import struct 9 10 import usb_constants 11 12 13 class Gadget(object): 14 """Basic functionality for a USB device. 15 16 Implements standard control requests assuming that a subclass will handle 17 class- or vendor-specific requests. 18 """ 19 20 def __init__(self, device_desc, fs_config_desc, hs_config_desc): 21 """Create a USB gadget device. 22 23 Args: 24 device_desc: USB device descriptor. 25 fs_config_desc: Low/full-speed device descriptor. 26 hs_config_desc: High-speed device descriptor. 27 """ 28 self._speed = usb_constants.Speed.UNKNOWN 29 self._chip = None 30 self._device_desc = device_desc 31 self._fs_config_desc = fs_config_desc 32 self._hs_config_desc = hs_config_desc 33 # dict mapping language codes to a dict mapping indexes to strings 34 self._strings = {} 35 # dict mapping interface numbers to a set of endpoint addresses 36 self._active_endpoints = {} 37 38 def GetDeviceDescriptor(self): 39 return self._device_desc 40 41 def GetFullSpeedConfigurationDescriptor(self): 42 return self._fs_config_desc 43 44 def GetHighSpeedConfigurationDescriptor(self): 45 return self._hs_config_desc 46 47 def GetConfigurationDescriptor(self): 48 if self._speed == usb_constants.Speed.FULL: 49 return self._fs_config_desc 50 elif self._speed == usb_constants.Speed.HIGH: 51 return self._hs_config_desc 52 else: 53 raise RuntimeError('Device is not connected.') 54 55 def GetSpeed(self): 56 return self._speed 57 58 def AddStringDescriptor(self, index, value, lang=0x0409): 59 """Add a string descriptor to this device. 60 61 Args: 62 index: String descriptor index (matches 'i' fields in descriptors). 63 value: The string. 64 lang: Language code (default: English). 65 66 Raises: 67 ValueError: The index or language code is invalid. 68 """ 69 if index < 1 or index > 255: 70 raise ValueError('String descriptor index out of range.') 71 if lang < 0 or lang > 0xffff: 72 raise ValueError('String descriptor language code out of range.') 73 74 lang_strings = self._strings.setdefault(lang, {}) 75 lang_strings[index] = value 76 77 def Connected(self, chip, speed): 78 """The device has been connected to a USB host. 79 80 Args: 81 chip: USB controller. 82 speed: Connection speed. 83 """ 84 self._speed = speed 85 self._chip = chip 86 87 def Disconnected(self): 88 """The device has been disconnected from the USB host.""" 89 self._speed = usb_constants.Speed.UNKNOWN 90 self._chip = None 91 self._active_endpoints.clear() 92 93 def IsConnected(self): 94 return self._chip is not None 95 96 def ControlRead(self, request_type, request, value, index, length): 97 """Handle a read on the control pipe (endpoint zero). 98 99 Args: 100 request_type: bmRequestType field of the setup packet. 101 request: bRequest field of the setup packet. 102 value: wValue field of the setup packet. 103 index: wIndex field of the setup packet. 104 length: Maximum amount of data the host expects the device to return. 105 106 Returns: 107 A buffer to return to the USB host with len <= length on success or 108 None to stall the pipe. 109 """ 110 assert request_type & usb_constants.Dir.IN 111 typ = request_type & usb_constants.Type.MASK 112 recipient = request_type & usb_constants.Recipient.MASK 113 if typ == usb_constants.Type.STANDARD: 114 return self.StandardControlRead( 115 recipient, request, value, index, length) 116 elif typ == usb_constants.Type.CLASS: 117 return self.ClassControlRead( 118 recipient, request, value, index, length) 119 elif typ == usb_constants.Type.VENDOR: 120 return self.VendorControlRead( 121 recipient, request, value, index, length) 122 123 def ControlWrite(self, request_type, request, value, index, data): 124 """Handle a write to the control pipe (endpoint zero). 125 126 Args: 127 request_type: bmRequestType field of the setup packet. 128 request: bRequest field of the setup packet. 129 value: wValue field of the setup packet. 130 index: wIndex field of the setup packet. 131 data: Data stage of the request. 132 133 Returns: 134 True on success, None to stall the pipe. 135 """ 136 assert not request_type & usb_constants.Dir.IN 137 typ = request_type & usb_constants.Type.MASK 138 recipient = request_type & usb_constants.Recipient.MASK 139 if typ == usb_constants.Type.STANDARD: 140 return self.StandardControlWrite( 141 recipient, request, value, index, data) 142 elif typ == usb_constants.Type.CLASS: 143 return self.ClassControlWrite( 144 recipient, request, value, index, data) 145 elif typ == usb_constants.Type.VENDOR: 146 return self.VendorControlWrite( 147 recipient, request, value, index, data) 148 149 def SendPacket(self, endpoint, data): 150 """Send a data packet on the given endpoint. 151 152 Args: 153 endpoint: Endpoint address. 154 data: Data buffer. 155 156 Raises: 157 ValueError: If the endpoint address is not valid. 158 RuntimeError: If the device is not connected. 159 """ 160 if self._chip is None: 161 raise RuntimeError('Device is not connected.') 162 if not endpoint & usb_constants.Dir.IN: 163 raise ValueError('Cannot write to non-input endpoint.') 164 self._chip.SendPacket(endpoint, data) 165 166 def ReceivePacket(self, endpoint, data): 167 """Handle an incoming data packet on one of the device's active endpoints. 168 169 This method should be overridden by a subclass implementing endpoint-based 170 data transfers. 171 172 Args: 173 endpoint: Endpoint address. 174 data: Data buffer. 175 """ 176 pass 177 178 def HaltEndpoint(self, endpoint): 179 """Signals a STALL condition to the host on the given endpoint. 180 181 Args: 182 endpoint: Endpoint address. 183 """ 184 self._chip.HaltEndpoint(endpoint) 185 186 def StandardControlRead(self, recipient, request, value, index, length): 187 """Handle standard control transfers. 188 189 Args: 190 recipient: Request recipient (device, interface, endpoint, etc.) 191 request: bRequest field of the setup packet. 192 value: wValue field of the setup packet. 193 index: wIndex field of the setup packet. 194 length: Maximum amount of data the host expects the device to return. 195 196 Returns: 197 A buffer to return to the USB host with len <= length on success or 198 None to stall the pipe. 199 """ 200 if request == usb_constants.Request.GET_DESCRIPTOR: 201 desc_type = value >> 8 202 desc_index = value & 0xff 203 desc_lang = index 204 205 print 'GetDescriptor(recipient={}, type={}, index={}, lang={})'.format( 206 recipient, desc_type, desc_index, desc_lang) 207 208 return self.GetDescriptor(recipient, desc_type, desc_index, desc_lang, 209 length) 210 211 def GetDescriptor(self, recipient, typ, index, lang, length): 212 """Handle a standard GET_DESCRIPTOR request. 213 214 See Universal Serial Bus Specification Revision 2.0 section 9.4.3. 215 216 Args: 217 recipient: Request recipient (device, interface, endpoint, etc.) 218 typ: Descriptor type. 219 index: Descriptor index. 220 lang: Descriptor language code. 221 length: Maximum amount of data the host expects the device to return. 222 223 Returns: 224 The value of the descriptor or None to stall the pipe. 225 """ 226 if recipient == usb_constants.Recipient.DEVICE: 227 if typ == usb_constants.DescriptorType.STRING: 228 return self.GetStringDescriptor(index, lang, length) 229 230 def ClassControlRead(self, recipient, request, value, index, length): 231 """Handle class-specific control transfers. 232 233 This function should be overridden by a subclass implementing a particular 234 device class. 235 236 Args: 237 recipient: Request recipient (device, interface, endpoint, etc.) 238 request: bRequest field of the setup packet. 239 value: wValue field of the setup packet. 240 index: wIndex field of the setup packet. 241 length: Maximum amount of data the host expects the device to return. 242 243 Returns: 244 A buffer to return to the USB host with len <= length on success or 245 None to stall the pipe. 246 """ 247 _ = recipient, request, value, index, length 248 return None 249 250 def VendorControlRead(self, recipient, request, value, index, length): 251 """Handle vendor-specific control transfers. 252 253 This function should be overridden by a subclass if implementing a device 254 that responds to vendor-specific requests. 255 256 Args: 257 recipient: Request recipient (device, interface, endpoint, etc.) 258 request: bRequest field of the setup packet. 259 value: wValue field of the setup packet. 260 index: wIndex field of the setup packet. 261 length: Maximum amount of data the host expects the device to return. 262 263 Returns: 264 A buffer to return to the USB host with len <= length on success or 265 None to stall the pipe. 266 """ 267 _ = recipient, request, value, index, length 268 return None 269 270 def StandardControlWrite(self, recipient, request, value, index, data): 271 """Handle standard control transfers. 272 273 Args: 274 recipient: Request recipient (device, interface, endpoint, etc.) 275 request: bRequest field of the setup packet. 276 value: wValue field of the setup packet. 277 index: wIndex field of the setup packet. 278 data: Data stage of the request. 279 280 Returns: 281 True on success, None to stall the pipe. 282 """ 283 _ = data 284 285 if request == usb_constants.Request.SET_CONFIGURATION: 286 if recipient == usb_constants.Recipient.DEVICE: 287 return self.SetConfiguration(value) 288 elif request == usb_constants.Request.SET_INTERFACE: 289 if recipient == usb_constants.Recipient.INTERFACE: 290 return self.SetInterface(index, value) 291 292 def ClassControlWrite(self, recipient, request, value, index, data): 293 """Handle class-specific control transfers. 294 295 This function should be overridden by a subclass implementing a particular 296 device class. 297 298 Args: 299 recipient: Request recipient (device, interface, endpoint, etc.) 300 request: bRequest field of the setup packet. 301 value: wValue field of the setup packet. 302 index: wIndex field of the setup packet. 303 data: Data stage of the request. 304 305 Returns: 306 True on success, None to stall the pipe. 307 """ 308 _ = recipient, request, value, index, data 309 return None 310 311 def VendorControlWrite(self, recipient, request, value, index, data): 312 """Handle vendor-specific control transfers. 313 314 This function should be overridden by a subclass if implementing a device 315 that responds to vendor-specific requests. 316 317 Args: 318 recipient: Request recipient (device, interface, endpoint, etc.) 319 request: bRequest field of the setup packet. 320 value: wValue field of the setup packet. 321 index: wIndex field of the setup packet. 322 data: Data stage of the request. 323 324 Returns: 325 True on success, None to stall the pipe. 326 """ 327 _ = recipient, request, value, index, data 328 return None 329 330 def GetStringDescriptor(self, index, lang, length): 331 """Handle a GET_DESCRIPTOR(String) request from the host. 332 333 Descriptor index 0 returns the set of languages supported by the device. 334 All other indices return the string descriptors registered with those 335 indices. 336 337 See Universal Serial Bus Specification Revision 2.0 section 9.6.7. 338 339 Args: 340 index: Descriptor index. 341 lang: Descriptor language code. 342 length: Maximum amount of data the host expects the device to return. 343 344 Returns: 345 The string descriptor or None to stall the pipe if the descriptor is not 346 found. 347 """ 348 if index == 0: 349 length = 2 + len(self._strings) * 2 350 header = struct.pack('<BB', length, usb_constants.DescriptorType.STRING) 351 lang_codes = [struct.pack('<H', lang) 352 for lang in self._strings.iterkeys()] 353 buf = header + ''.join(lang_codes) 354 assert len(buf) == length 355 return buf[:length] 356 elif lang not in self._strings: 357 return None 358 elif index not in self._strings[lang]: 359 return None 360 else: 361 string = self._strings[lang][index].encode('UTF-16LE') 362 header = struct.pack( 363 '<BB', 2 + len(string), usb_constants.DescriptorType.STRING) 364 buf = header + string 365 return buf[:length] 366 367 def SetConfiguration(self, index): 368 """Handle a SET_CONFIGURATION request from the host. 369 370 See Universal Serial Bus Specification Revision 2.0 section 9.4.7. 371 372 Args: 373 index: Configuration index selected. 374 375 Returns: 376 True on success, None on error to stall the pipe. 377 """ 378 print 'SetConfiguration({})'.format(index) 379 380 for endpoint_addrs in self._active_endpoints.values(): 381 for endpoint_addr in endpoint_addrs: 382 self._chip.StopEndpoint(endpoint_addr) 383 endpoint_addrs.clear() 384 385 if index == 0: 386 # SET_CONFIGRATION(0) puts the device into the Address state which 387 # Windows does before suspending the port. 388 return True 389 elif index != 1: 390 return None 391 392 config_desc = self.GetConfigurationDescriptor() 393 for interface_desc in config_desc.GetInterfaces(): 394 if interface_desc.bAlternateSetting != 0: 395 continue 396 endpoint_addrs = self._active_endpoints.setdefault( 397 interface_desc.bInterfaceNumber, set()) 398 for endpoint_desc in interface_desc.GetEndpoints(): 399 self._chip.StartEndpoint(endpoint_desc) 400 endpoint_addrs.add(endpoint_desc.bEndpointAddress) 401 return True 402 403 def SetInterface(self, interface, alt_setting): 404 """Handle a SET_INTERFACE request from the host. 405 406 See Universal Serial Bus Specification Revision 2.0 section 9.4.10. 407 408 Args: 409 interface: Interface number to configure. 410 alt_setting: Alternate setting to select. 411 412 Returns: 413 True on success, None on error to stall the pipe. 414 """ 415 print 'SetInterface({}, {})'.format(interface, alt_setting) 416 417 config_desc = self.GetConfigurationDescriptor() 418 interface_desc = None 419 for interface_option in config_desc.GetInterfaces(): 420 if (interface_option.bInterfaceNumber == interface and 421 interface_option.bAlternateSetting == alt_setting): 422 interface_desc = interface_option 423 if interface_desc is None: 424 return None 425 426 endpoint_addrs = self._active_endpoints.setdefault(interface, set()) 427 for endpoint_addr in endpoint_addrs: 428 self._chip.StopEndpoint(endpoint_addr) 429 for endpoint_desc in interface_desc.GetEndpoints(): 430 self._chip.StartEndpoint(endpoint_desc) 431 endpoint_addrs.add(endpoint_desc.bEndpointAddress) 432 return True 433
