hid-sensor.txt 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. HID Sensors Framework
  2. ======================
  3. HID sensor framework provides necessary interfaces to implement sensor drivers,
  4. which are connected to a sensor hub. The sensor hub is a HID device and it provides
  5. a report descriptor conforming to HID 1.12 sensor usage tables.
  6. Description from the HID 1.12 "HID Sensor Usages" specification:
  7. "Standardization of HID usages for sensors would allow (but not require) sensor
  8. hardware vendors to provide a consistent Plug And Play interface at the USB boundary,
  9. thereby enabling some operating systems to incorporate common device drivers that
  10. could be reused between vendors, alleviating any need for the vendors to provide
  11. the drivers themselves."
  12. This specification describes many usage IDs, which describe the type of sensor
  13. and also the individual data fields. Each sensor can have variable number of
  14. data fields. The length and order is specified in the report descriptor. For
  15. example a part of report descriptor can look like:
  16. INPUT(1)[INPUT]
  17. ..
  18. Field(2)
  19. Physical(0020.0073)
  20. Usage(1)
  21. 0020.045f
  22. Logical Minimum(-32767)
  23. Logical Maximum(32767)
  24. Report Size(8)
  25. Report Count(1)
  26. Report Offset(16)
  27. Flags(Variable Absolute)
  28. ..
  29. ..
  30. The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
  31. This accelerometer-3D has some fields. Here for example field 2 is motion intensity
  32. (0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The
  33. order of fields and length of each field is important as the input event raw
  34. data will use this format.
  35. Implementation
  36. =================
  37. This specification defines many different types of sensors with different sets of
  38. data fields. It is difficult to have a common input event to user space applications,
  39. for different sensors. For example an accelerometer can send X,Y and Z data, whereas
  40. an ambient light sensor can send illumination data.
  41. So the implementation has two parts:
  42. - Core hid driver
  43. - Individual sensor processing part (sensor drivers)
  44. Core driver
  45. -----------
  46. The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
  47. report descriptors and identifies all the sensors present. It adds an MFD device
  48. with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
  49. For example
  50. HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
  51. So if any driver with this name is inserted, then the probe routine for that
  52. function will be called. So an accelerometer processing driver can register
  53. with this name and will be probed if there is an accelerometer-3D detected.
  54. The core driver provides a set of APIs which can be used by the processing
  55. drivers to register and get events for that usage id. Also it provides parsing
  56. functions, which get and set each input/feature/output report.
  57. Individual sensor processing part (sensor drivers)
  58. -----------
  59. The processing driver will use an interface provided by the core driver to parse
  60. the report and get the indexes of the fields and also can get events. This driver
  61. can use IIO interface to use the standard ABI defined for a type of sensor.
  62. Core driver Interface
  63. =====================
  64. Callback structure:
  65. Each processing driver can use this structure to set some callbacks.
  66. int (*suspend)(..): Callback when HID suspend is received
  67. int (*resume)(..): Callback when HID resume is received
  68. int (*capture_sample)(..): Capture a sample for one of its data fields
  69. int (*send_event)(..): One complete event is received which can have
  70. multiple data fields.
  71. Registration functions:
  72. int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
  73. u32 usage_id,
  74. struct hid_sensor_hub_callbacks *usage_callback):
  75. Registers callbacks for an usage id. The callback functions are not allowed
  76. to sleep.
  77. int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
  78. u32 usage_id):
  79. Removes callbacks for an usage id.
  80. Parsing function:
  81. int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
  82. u8 type,
  83. u32 usage_id, u32 attr_usage_id,
  84. struct hid_sensor_hub_attribute_info *info);
  85. A processing driver can look for some field of interest and check if it exists
  86. in a report descriptor. If it exists it will store necessary information
  87. so that fields can be set or get individually.
  88. These indexes avoid searching every time and getting field index to get or set.
  89. Set Feature report
  90. int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
  91. u32 field_index, s32 value);
  92. This interface is used to set a value for a field in feature report. For example
  93. if there is a field report_interval, which is parsed by a call to
  94. sensor_hub_input_get_attribute_info before, then it can directly set that individual
  95. field.
  96. int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
  97. u32 field_index, s32 *value);
  98. This interface is used to get a value for a field in input report. For example
  99. if there is a field report_interval, which is parsed by a call to
  100. sensor_hub_input_get_attribute_info before, then it can directly get that individual
  101. field value.
  102. int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
  103. u32 usage_id,
  104. u32 attr_usage_id, u32 report_id);
  105. This is used to get a particular field value through input reports. For example
  106. accelerometer wants to poll X axis value, then it can call this function with
  107. the usage id of X axis. HID sensors can provide events, so this is not necessary
  108. to poll for any field. If there is some new sample, the core driver will call
  109. registered callback function to process the sample.