[usb_gadget p01] Functions for encoding HID descriptors.

tools/usb_gadget/hid_descriptors.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.
+
+
+"""Utility functions for constructing HID report descriptors.
+"""
+
+import struct
+
+import hid_constants
+
+
+def ReportDescriptor(*items):
+  return ''.join(items)
+
+
+def _PackItem(tag, typ, value=0, force_length=0):
+  """Pack a multibyte value.
+
+  See Device Class Definition for Human Interface Devices (HID) Version 1.11
+  section 5.8.
+
+  Args:
+    tag: Item tag.
+    typ: Item type.
+    value: Item value.
+    force_length: Force packing to a specific width.
+
+  Returns:
+    Packed string.
+  """
+  if value == 0 and force_length <= 0:
+    return struct.pack('<B', tag << 4 | typ << 2 | 0)
+  elif value <= 0xff and force_length <= 1:
+    return struct.pack('<BB', tag << 4 | typ << 2 | 1, value)
+  elif value <= 0xffff and force_length <= 2:
+    return struct.pack('<BH', tag << 4 | typ << 2 | 2, value)
+  elif value <= 0xffffffff and force_length <= 4:
+    return struct.pack('<BI', tag << 4 | typ << 2 | 3, value)
+  else:
+    raise NotImplementedError('Long items are not implemented.')
+
+
+def _DefineItem(name, tag, typ):
+  """Create a function which encodes a HID item.
+
+  Args:
+    name: Function name.
+    tag: Item tag.
+    typ: Item type.
+
+  Returns:
+    A function which encodes a HID item of the given type.
+  """
+  assert tag >= 0 and tag <= 0xF
+  assert typ >= 0 and typ <= 3
+
+  def EncodeItem(value=0, force_length=0):
+    return _PackItem(tag, typ, value, force_length)
+
+  EncodeItem.__name__ = name
+  return EncodeItem
+
+
+def _DefineMainItem(name, tag):
+  """Create a function which encodes a HID Main item.
+
+  See Device Class Definition for Human Interface Devices (HID) Version 1.11
+  section 6.2.2.4.
+
+  Args:
+    name: Function name.
+    tag: Item tag.
+
+  Returns:
+    A function which encodes a HID item of the given type.
+
+  Raises:
+    ValueError: If the tag value is out of range.
+  """
+  assert tag >= 0 and tag <= 0xF
+
+  def EncodeMainItem(*properties):
+    value = 0
+    for bit, is_set in properties:
+      if is_set:
+        value |= 1 << bit
+    return _PackItem(tag, hid_constants.Scope.MAIN, value, force_length=1)
+
+  EncodeMainItem.__name__ = name
+  return EncodeMainItem
+
+Input = _DefineMainItem('Input', 8)
+Output = _DefineMainItem('Output', 9)
+Feature = _DefineMainItem('Feature', 11)
+
+# Input, Output and Feature Item Properties
+#
+# See Device Class Definition for Human Interface Devices (HID) Version 1.11
+# section 6.2.2.5.
+Data = (0, False)
+Constant = (0, True)
+Array = (1, False)
+Variable = (1, True)
+Absolute = (2, False)
+Relative = (2, True)
+NoWrap = (3, False)
+Wrap = (3, True)
+Linear = (4, False)
+NonLinear = (4, True)
+PreferredState = (5, False)
+NoPreferred = (5, True)
+NoNullPosition = (6, False)
+NullState = (6, True)
+NonVolatile = (7, False)
+Volatile = (7, True)
+BitField = (8, False)
+BufferedBytes = (8, True)
+
+
+def Collection(typ, *items):
+  start = struct.pack('<BB', 0xA1, typ)
+  end = struct.pack('<B', 0xC0)
+  return start + ''.join(items) + end
+
+# Global Items
+#
+# See Device Class Definition for Human Interface Devices (HID) Version 1.11
+# section 6.2.2.7.
+UsagePage = _DefineItem('UsagePage', 0, hid_constants.Scope.GLOBAL)
+LogicalMinimum = _DefineItem('LogicalMinimum', 1, hid_constants.Scope.GLOBAL)
+LogicalMaximum = _DefineItem('LogicalMaximum', 2, hid_constants.Scope.GLOBAL)
+PhysicalMinimum = _DefineItem('PhysicalMinimum', 3, hid_constants.Scope.GLOBAL)
+PhysicalMaximum = _DefineItem('PhysicalMaximum', 4, hid_constants.Scope.GLOBAL)
+UnitExponent = _DefineItem('UnitExponent', 5, hid_constants.Scope.GLOBAL)
+Unit = _DefineItem('Unit', 6, hid_constants.Scope.GLOBAL)
+ReportSize = _DefineItem('ReportSize', 7, hid_constants.Scope.GLOBAL)
+ReportID = _DefineItem('ReportID', 8, hid_constants.Scope.GLOBAL)
+ReportCount = _DefineItem('ReportCount', 9, hid_constants.Scope.GLOBAL)
+Push = _DefineItem('Push', 10, hid_constants.Scope.GLOBAL)
+Pop = _DefineItem('Pop', 11, hid_constants.Scope.GLOBAL)
+
+# Local Items
+#
+# See Device Class Definition for Human Interface Devices (HID) Version 1.11
+# section 6.2.2.8.
+Usage = _DefineItem('Usage', 0, hid_constants.Scope.LOCAL)
+UsageMinimum = _DefineItem('UsageMinimum', 1, hid_constants.Scope.LOCAL)
+UsageMaximum = _DefineItem('UsageMaximum', 2, hid_constants.Scope.LOCAL)
+DesignatorIndex = _DefineItem('DesignatorIndex', 3, hid_constants.Scope.LOCAL)
+DesignatorMinimum = _DefineItem('DesignatorMinimum', 4,
+                                hid_constants.Scope.LOCAL)
+DesignatorMaximum = _DefineItem('DesignatorMaximum', 5,
+                                hid_constants.Scope.LOCAL)
+StringIndex = _DefineItem('StringIndex', 7, hid_constants.Scope.LOCAL)
+StringMinimum = _DefineItem('StringMinimum', 8, hid_constants.Scope.LOCAL)
+StringMaximum = _DefineItem('StringMaximum', 9, hid_constants.Scope.LOCAL)
+Delimiter = _DefineItem('Delimiter', 10, hid_constants.Scope.LOCAL)