usb_gadget: Base USB HID gadget implementation.

tools/usb_gadget/hid_gadget.py

+# Copyright 2014 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+"""Human Interface Device gadget module.
+
+This gadget emulates a USB Human Interface Device. Multiple logical components
+of a device can be composed together as separate "features" where each has its
+own Report ID and will be called upon to answer get/set input/output/feature
+report requests as necessary.
+"""
+
+import math
+import struct
+import uuid
+
+import gadget
+import hid_constants
+import usb_constants
+import usb_descriptors
+
+
+class HidGadget(gadget.Gadget):
+  """Generic HID gadget.
+  """
+
+  def __init__(self, report_desc, features, vendor_id, product_id,
+               packet_size=64, interval_ms=10, out_endpoint=True,
+               device_version=0x0100):
+    """Create a HID gadget.
+
+    Args:
+      report_desc: HID report descriptor.
+      features: Map between Report IDs and HidFeature objects to handle them.
+      vendor_id: Device Vendor ID.
+      product_id: Device Product ID.
+      packet_size: Maximum interrupt packet size.
+      interval_ms: Interrupt transfer interval in milliseconds.
+      out_endpoint: Should this device have an interrupt OUT endpoint?
+      device_version: Device version number.
+
+    Raises:
+      ValueError: If any of the parameters are out of range.
+    """
+    device_desc = usb_descriptors.DeviceDescriptor(
+        idVendor=vendor_id,
+        idProduct=product_id,
+        bcdUSB=0x0200,
+        iManufacturer=1,
+        iProduct=2,
+        iSerialNumber=3,
+        bcdDevice=device_version)
+
+    fs_config_desc = usb_descriptors.ConfigurationDescriptor(
+        bmAttributes=0x80,
+        MaxPower=50)
+    fs_interface_desc = usb_descriptors.InterfaceDescriptor(
+        bInterfaceNumber=0,
+        bInterfaceClass=usb_constants.DeviceClass.HID,
+        bInterfaceSubClass=0,  # Non-bootable.
+        bInterfaceProtocol=0,  # None.
+    )
+    fs_config_desc.AddInterface(fs_interface_desc)
+
+    hs_config_desc = usb_descriptors.ConfigurationDescriptor(
+        bmAttributes=0x80,
+        MaxPower=50)
+    hs_interface_desc = usb_descriptors.InterfaceDescriptor(
+        bInterfaceNumber=0,
+        bInterfaceClass=usb_constants.DeviceClass.HID,
+        bInterfaceSubClass=0,  # Non-bootable.
+        bInterfaceProtocol=0,  # None.
+    )
+    hs_config_desc.AddInterface(hs_interface_desc)
+
+    hid_desc = usb_descriptors.HidDescriptor()
+    hid_desc.AddDescriptor(hid_constants.DescriptorType.REPORT,
+                           len(report_desc))
+    fs_interface_desc.Add(hid_desc)
+    hs_interface_desc.Add(hid_desc)
+
+    fs_interval = math.ceil(math.log(interval_ms, 2)) + 1
+    if fs_interval < 1 or fs_interval > 16:
+      raise ValueError('Full speed interval out of range: {} ({} ms)'
+                       .format(fs_interval, interval_ms))
+
+    fs_interface_desc.AddEndpoint(usb_descriptors.EndpointDescriptor(
+        bEndpointAddress=0x81,
+        bmAttributes=usb_constants.TransferType.INTERRUPT,
+        wMaxPacketSize=packet_size,
+        bInterval=fs_interval
+    ))
+
+    hs_interval = math.ceil(math.log(interval_ms, 2)) + 4
+    if hs_interval < 1 or hs_interval > 16:
+      raise ValueError('High speed interval out of range: {} ({} ms)'
+                       .format(hs_interval, interval_ms))
+
+    hs_interface_desc.AddEndpoint(usb_descriptors.EndpointDescriptor(
+        bEndpointAddress=0x81,
+        bmAttributes=usb_constants.TransferType.INTERRUPT,
+        wMaxPacketSize=packet_size,
+        bInterval=hs_interval
+    ))
+
+    if out_endpoint:
+      fs_interface_desc.AddEndpoint(usb_descriptors.EndpointDescriptor(
+          bEndpointAddress=0x01,
+          bmAttributes=usb_constants.TransferType.INTERRUPT,
+          wMaxPacketSize=packet_size,
+          bInterval=fs_interval
+      ))
+      hs_interface_desc.AddEndpoint(usb_descriptors.EndpointDescriptor(
+          bEndpointAddress=0x01,
+          bmAttributes=usb_constants.TransferType.INTERRUPT,
+          wMaxPacketSize=packet_size,
+          bInterval=hs_interval
+      ))
+
+    super(HidGadget, self).__init__(device_desc, fs_config_desc, hs_config_desc)
+    self.AddStringDescriptor(3, '{:06X}'.format(uuid.getnode()))
+    self._report_desc = report_desc
+    self._features = features
+
+  def Connected(self, chip, speed):
+    super(HidGadget, self).Connected(chip, speed)
+    for report_id, feature in self._features.iteritems():
+      feature.Connected(self, report_id)
+
+  def Disconnected(self):
+    super(HidGadget, self).Disconnected()
+    for feature in self._features.itervalues():
+      feature.Disconnected()
+
+  def GetDescriptor(self, recipient, typ, index, lang, length):
+    if recipient == usb_constants.Recipient.INTERFACE:
+      if typ == hid_constants.DescriptorType.REPORT:
+        if index == 0:
+          return self._report_desc[:length]
+
+    return super(HidGadget, self).GetDescriptor(recipient, typ, index, lang,
+                                                length)
+
+  def ClassControlRead(self, recipient, request, value, index, length):
+    """Handle class-specific control requests.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 7.2.
+
+    Args:
+      recipient: Request recipient (device, interface, endpoint, etc.)
+      request: bRequest field of the setup packet.
+      value: wValue field of the setup packet.
+      index: wIndex field of the setup packet.
+      length: Maximum amount of data the host expects the device to return.
+
+    Returns:
+      A buffer to return to the USB host with len <= length on success or
+      None to stall the pipe.
+    """
+    if recipient != usb_constants.Recipient.INTERFACE:
+      return None
+    if index != 0:
+      return None
+
+    if request == hid_constants.Request.GET_REPORT:
+      report_type, report_id = value >> 8, value & 0xFF
+      print ('GetReport(type={}, id={}, length={})'
+             .format(report_type, report_id, length))
+      return self.GetReport(report_type, report_id, length)
+
+  def ClassControlWrite(self, recipient, request, value, index, data):
+    """Handle class-specific control requests.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 7.2.
+
+    Args:
+      recipient: Request recipient (device, interface, endpoint, etc.)
+      request: bRequest field of the setup packet.
+      value: wValue field of the setup packet.
+      index: wIndex field of the setup packet.
+      data: Data stage of the request.
+
+    Returns:
+      True on success, None to stall the pipe.
+    """
+    if recipient != usb_constants.Recipient.INTERFACE:
+      return None
+    if index != 0:
+      return None
+
+    if request == hid_constants.Request.SET_REPORT:
+      report_type, report_id = value >> 8, value & 0xFF
+      print('SetReport(type={}, id={}, length={})'
+            .format(report_type, report_id, len(data)))
+      return self.SetReport(report_type, report_id, data)
+    elif request == hid_constants.Request.SET_IDLE:
+      duration, report_id = value >> 8, value & 0xFF
+      print('SetIdle(duration={}, report={})'
+            .format(duration, report_id))
+      return True
+
+  def GetReport(self, report_type, report_id, length):
+    """Handle GET_REPORT requests.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 7.2.1.
+
+    Args:
+      report_type: Requested report type.
+      report_id: Requested report ID.
+      length: Maximum amount of data the host expects the device to return.
+
+    Returns:
+      A buffer to return to the USB host with len <= length on success or
+      None to stall the pipe.
+    """
+    feature = self._features.get(report_id, None)
+    if feature is None:
+      return None
+
+    if report_type == hid_constants.ReportType.INPUT:
+      return feature.GetInputReport()[:length]
+    elif report_type == hid_constants.ReportType.OUTPUT:
+      return feature.GetOutputReport()[:length]
+    elif report_type == hid_constants.ReportType.FEATURE:
+      return feature.GetFeatureReport()[:length]
+
+  def SetReport(self, report_type, report_id, data):
+    """Handle SET_REPORT requests.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 7.2.2.
+
+    Args:
+      report_type: Report type.
+      report_id: Report ID.
+      data: Report data.
+
+    Returns:
+      True on success, None to stall the pipe.
+    """
+    feature = self._features.get(report_id, None)
+    if feature is None:
+      return None
+
+    if report_type == hid_constants.ReportType.INPUT:
+      return feature.SetInputReport(data)
+    elif report_type == hid_constants.ReportType.OUTPUT:
+      return feature.SetOutputReport(data)
+    elif report_type == hid_constants.ReportType.FEATURE:
+      return feature.SetFeatureReport(data)
+
+  def SendReport(self, report_id, data):
+    """Send a HID report.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 8.
+
+    Args:
+      report_id: Report ID associated with the data.
+      data: Contents of the report.
+    """
+    if report_id == 0:
+      self.SendPacket(0x81, data)
+    else:
+      self.SendPacket(0x81, struct.pack('B', report_id) + data)
+
+  def ReceivePacket(self, endpoint, data):
+    """Dispatch a report to the appropriate feature.
+
+    See Device Class Definition for Human Interface Devices (HID) Version 1.11
+    section 8.
+
+    Args:
+      endpoint: Incoming endpoint (must be the Interrupt OUT pipe).
+      data: Interrupt packet data.
+    """
+    assert endpoint == 0x01
+
+    if 0 in self._features:
+      self._features[0].SetOutputReport(data)
+    elif len(data) >= 1:
+      report_id, = struct.unpack('B', data[0])
+      feature = self._features.get(report_id, None)
+      if feature is None or feature.SetOutputReport(data[1:]) is None:
+        self.HaltEndpoint(endpoint)
+
+
+class HidFeature(object):
+  """Represents a component of a HID gadget.
+
+  A "feature" produces and consumes reports with a particular Report ID. For
+  example a keyboard, mouse or vendor specific functionality.
+  """
+
+  def __init__(self):
+    self._gadget = None
+    self._report_id = None
+
+  def Connected(self, my_gadget, report_id):
+    self._gadget = my_gadget
+    self._report_id = report_id
+
+  def Disconnected(self):
+    self._gadget = None
+    self._report_id = None
+
+  def IsConnected(self):
+    return self._gadget is not None
+
+  def SendReport(self, data):
+    """Send a report with this feature's Report ID.
+
+    Args:
+      data: Report to send. If necessary the Report ID will be added.
+
+    Raises:
+      RuntimeError: If a report cannot be sent at this time.
+    """
+    if not self.IsConnected():
+      raise RuntimeError('Device is not connected.')
+    self._gadget.SendReport(self._report_id, data)
+
+  def SetInputReport(self, data):
+    """Handle an input report sent from the host.
+
+    This function is called when a SET_REPORT(input) command for this class's
+    Report ID is received. It should be overridden by a subclass.
+
+    Args:
+      data: Contents of the input report.
+    """
+    pass  # pragma: no cover
+
+  def SetOutputReport(self, data):
+    """Handle an feature report sent from the host.
+
+    This function is called when a SET_REPORT(output) command or interrupt OUT
+    transfer is received with this class's Report ID. It should be overridden
+    by a subclass.
+
+    Args:
+      data: Contents of the output report.
+    """
+    pass  # pragma: no cover
+
+  def SetFeatureReport(self, data):
+    """Handle an feature report sent from the host.
+
+    This function is called when a SET_REPORT(feature) command for this class's
+    Report ID is received. It should be overridden by a subclass.
+
+    Args:
+      data: Contents of the feature report.
+    """
+    pass  # pragma: no cover
+
+  def GetInputReport(self):
+    """Handle a input report request from the host.
+
+    This function is called when a GET_REPORT(input) command for this class's
+    Report ID is received. It should be overridden by a subclass.
+
+    Returns:
+      The input report or None to stall the pipe.
+    """
+    pass  # pragma: no cover
+
+  def GetOutputReport(self):
+    """Handle a output report request from the host.
+
+    This function is called when a GET_REPORT(output) command for this class's
+    Report ID is received. It should be overridden by a subclass.
+
+    Returns:
+      The output report or None to stall the pipe.
+    """
+    pass  # pragma: no cover
+
+  def GetFeatureReport(self):
+    """Handle a feature report request from the host.
+
+    This function is called when a GET_REPORT(feature) command for this class's
+    Report ID is received. It should be overridden by a subclass.
+
+    Returns:
+      The feature report or None to stall the pipe.
+    """
+    pass  # pragma: no cover