tools/usb_gadget/composite_gadget.py

   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 """A composite USB gadget is built from multiple USB features.
   6 """
   7
   8 import gadget
   9 import usb_constants
  10 import usb_descriptors
  11
  12
  13 class CompositeGadget(gadget.Gadget):
  14   """Basic functionality for a composite USB device.
  15
  16   Composes multiple USB features into a single device.
  17   """
  18
  19   def __init__(self, device_desc, features):
  20     """Create a USB gadget device.
  21
  22     Args:
  23       device_desc: USB device descriptor.
  24       features: USB device features.
  25     """
  26     # dicts mapping interface numbers to features for FS and HS configurations
  27     self._fs_interface_feature_map = {}
  28     self._hs_interface_feature_map = {}
  29
  30     fs_config_desc = usb_descriptors.ConfigurationDescriptor(
  31         bmAttributes=0x80,
  32         MaxPower=50)
  33     hs_config_desc = usb_descriptors.ConfigurationDescriptor(
  34         bmAttributes=0x80,
  35         MaxPower=50)
  36     for feature in features:
  37       for fs_interface in feature.GetFullSpeedInterfaces():
  38         fs_config_desc.AddInterface(fs_interface)
  39         self._fs_interface_feature_map[fs_interface.bInterfaceNumber] = feature
  40       for hs_interface in feature.GetHighSpeedInterfaces():
  41         hs_config_desc.AddInterface(hs_interface)
  42         self._hs_interface_feature_map[hs_interface.bInterfaceNumber] = feature
  43
  44     super(CompositeGadget, self).__init__(
  45         device_desc, fs_config_desc, hs_config_desc)
  46     self._features = features
  47
  48   def Connected(self, chip, speed):
  49     super(CompositeGadget, self).Connected(chip, speed)
  50     for feature in self._features:
  51       feature.Connected(self)
  52
  53   def Disconnected(self):
  54     super(CompositeGadget, self).Disconnected()
  55     for feature in self._features:
  56       feature.Disconnected()
  57
  58   def _GetInterfaceFeatureMap(self):
  59     if self.GetSpeed() == usb_constants.Speed.FULL:
  60       return self._fs_interface_feature_map
  61     elif self.GetSpeed() == usb_constants.Speed.HIGH:
  62       return self._hs_interface_feature_map
  63     else:
  64       raise RuntimeError('Device is not connected.')
  65
  66   def ReceivePacket(self, endpoint, data):
  67     interface = self.GetInterfaceForEndpoint(endpoint)
  68     feature = self._GetInterfaceFeatureMap()[interface]
  69     feature.ReceivePacket(endpoint, data)
  70
  71   def _GetFeatureForIndex(self, recipient, index):
  72     interface = None
  73     if recipient == usb_constants.Recipient.INTERFACE:
  74       interface = index
  75     elif recipient == usb_constants.Recipient.ENDPOINT:
  76       interface = self.GetInterfaceForEndpoint(index)
  77
  78     if interface is not None:
  79       return self._GetInterfaceFeatureMap().get(interface)
  80     return None
  81
  82   def StandardControlRead(self, recipient, request, value, index, length):
  83     response = super(CompositeGadget, self).StandardControlRead(
  84         recipient, request, value, index, length)
  85     if response is not None:
  86       return response
  87
  88     feature = self._GetFeatureForIndex(recipient, index)
  89     if feature:
  90       return feature.StandardControlRead(
  91           recipient, request, value, index, length)
  92
  93   def StandardControlWrite(self, recipient, request, value, index, data):
  94     response = super(CompositeGadget, self).StandardControlWrite(
  95         recipient, request, value, index, data)
  96     if response is not None:
  97       return response
  98
  99     feature = self._GetFeatureForIndex(recipient, index)
 100     if feature:
 101       return feature.StandardControlWrite(
 102           recipient, request, value, index, data)
 103
 104   def ClassControlRead(self, recipient, request, value, index, length):
 105     response = super(CompositeGadget, self).ClassControlRead(
 106         recipient, request, value, index, length)
 107     if response is not None:
 108       return response
 109
 110     feature = self._GetFeatureForIndex(recipient, index)
 111     if feature:
 112       return feature.ClassControlRead(recipient, request, value, index, length)
 113
 114   def ClassControlWrite(self, recipient, request, value, index, data):
 115     response = super(CompositeGadget, self).ClassControlWrite(
 116         recipient, request, value, index, data)
 117     if response is not None:
 118       return response
 119
 120     feature = self._GetFeatureForIndex(recipient, index)
 121     if feature:
 122       return feature.ClassControlWrite(recipient, request, value, index, data)
 123
 124   def VendorControlRead(self, recipient, request, value, index, length):
 125     response = super(CompositeGadget, self).VendorControlRead(
 126         recipient, request, value, index, length)
 127     if response is not None:
 128       return response
 129
 130     feature = self._GetFeatureForIndex(recipient, index)
 131     if feature:
 132       return feature.VendorControlRead(recipient, request, value, index, length)
 133
 134   def VendorControlWrite(self, recipient, request, value, index, data):
 135     response = super(CompositeGadget, self).VendorControlWrite(
 136         recipient, request, value, index, data)
 137     if response is not None:
 138       return response
 139
 140     feature = self._GetFeatureForIndex(recipient, index)
 141     if feature:
 142       return feature.VendorControlWrite(recipient, request, value, index, data)
 143
 144
 145 class CompositeFeature(object):
 146   def __init__(self, fs_interface_descs, hs_interface_descs):
 147     self._gadget = None
 148     self._fs_interface_descs = fs_interface_descs
 149     self._hs_interface_descs = hs_interface_descs
 150
 151   def GetFullSpeedInterfaces(self):
 152     return self._fs_interface_descs
 153
 154   def GetHighSpeedInterfaces(self):
 155     return self._hs_interface_descs
 156
 157   def Connected(self, my_gadget):
 158     self._gadget = my_gadget
 159
 160   def Disconnected(self):
 161     self._gadget = None
 162
 163   def IsConnected(self):
 164     return self._gadget is not None
 165
 166   def SendPacket(self, endpoint, data):
 167     if self._gadget is None:
 168       raise RuntimeError('Device is not connected.')
 169     self._gadget.SendPacket(endpoint, data)
 170
 171   def HaltEndpoint(self, endpoint):
 172     if self._gadget is None:
 173       raise RuntimeError('Device is not connected.')
 174     self._gadget.HaltEndpoint(endpoint)
 175
 176   def GetDescriptor(self, recipient, typ, index, lang, length):
 177     _ = recipient, typ, index, lang, length
 178     return None
 179
 180   def StandardControlRead(self, recipient, request, value, index, length):
 181     """Handle standard USB control transfers.
 182
 183     Args:
 184       recipient: Request recipient (interface or endpoint)
 185       request: bRequest field of the setup packet.
 186       value: wValue field of the setup packet.
 187       index: wIndex field of the setup packet.
 188       length: Maximum amount of data the host expects the device to return.
 189
 190     Returns:
 191       A buffer to return to the USB host with len <= length on success or
 192       None to stall the pipe.
 193     """
 194     _ = recipient, request, value, index, length
 195     return None
 196
 197   def ClassControlRead(self, recipient, request, value, index, length):
 198     """Handle class-specific control transfers.
 199
 200     Args:
 201       recipient: Request recipient (interface or endpoint)
 202       request: bRequest field of the setup packet.
 203       value: wValue field of the setup packet.
 204       index: wIndex field of the setup packet.
 205       length: Maximum amount of data the host expects the device to return.
 206
 207     Returns:
 208       A buffer to return to the USB host with len <= length on success or
 209       None to stall the pipe.
 210     """
 211     _ = recipient, request, value, index, length
 212     return None
 213
 214   def VendorControlRead(self, recipient, request, value, index, length):
 215     """Handle vendor-specific control transfers.
 216
 217     Args:
 218       recipient: Request recipient (interface or endpoint)
 219       request: bRequest field of the setup packet.
 220       value: wValue field of the setup packet.
 221       index: wIndex field of the setup packet.
 222       length: Maximum amount of data the host expects the device to return.
 223
 224     Returns:
 225       A buffer to return to the USB host with len <= length on success or
 226       None to stall the pipe.
 227     """
 228     _ = recipient, request, value, index, length
 229     return None
 230
 231   def StandardControlWrite(self, recipient, request, value, index, data):
 232     """Handle standard USB control transfers.
 233
 234     Args:
 235       recipient: Request recipient (interface or endpoint)
 236       request: bRequest field of the setup packet.
 237       value: wValue field of the setup packet.
 238       index: wIndex field of the setup packet.
 239       data: Data stage of the request.
 240
 241     Returns:
 242       True on success, None to stall the pipe.
 243     """
 244     _ = recipient, request, value, index, data
 245     return None
 246
 247   def ClassControlWrite(self, recipient, request, value, index, data):
 248     """Handle class-specific control transfers.
 249
 250     Args:
 251       recipient: Request recipient (interface or endpoint)
 252       request: bRequest field of the setup packet.
 253       value: wValue field of the setup packet.
 254       index: wIndex field of the setup packet.
 255       data: Data stage of the request.
 256
 257     Returns:
 258       True on success, None to stall the pipe.
 259     """
 260     _ = recipient, request, value, index, data
 261     return None
 262
 263   def VendorControlWrite(self, recipient, request, value, index, data):
 264     """Handle vendor-specific control transfers.
 265
 266     Args:
 267       recipient: Request recipient (interface or endpoint)
 268       request: bRequest field of the setup packet.
 269       value: wValue field of the setup packet.
 270       index: wIndex field of the setup packet.
 271       data: Data stage of the request.
 272
 273     Returns:
 274       True on success, None to stall the pipe.
 275     """
 276     _ = recipient, request, value, index, data
 277     return None