| // Copyright 2017 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef HID_PARSER_PARSER_H_ |
| #define HID_PARSER_PARSER_H_ |
| |
| #include <stdint.h> |
| #include <stdlib.h> |
| |
| namespace hid { |
| |
| // The hid report descriptor parser consists of a single function |
| // ParseReportDescriptor() that takes as input a USB report descriptor |
| // byte stream and on success returns a heap-allocated DeviceDescriptor |
| // structure. When not needed it can be freed via FreeDeviceDescriptor(). |
| // |
| // The DeviceDescriptor data is organized at the first level by the |
| // three arrays which correspond to the feature fields for the input, |
| // output, and feature reports. Input, ouput, and feature reports each |
| // have their own length and fields: they are logically connected only |
| // because they share a report_id. The arrays of report features are of |
| // length {type}_count. Eg: the input_fields array has input_size ReportField |
| // structures. |
| // |
| // report[0].input_fields ---> ReportField |
| // +report_id |
| // +field_type == kInput |
| // +attr |
| // +col -------> Collection |
| // +type |
| // +parent ---> Collection |
| // |
| // The structure describes all the information returned by the device; |
| // no information present in the original stream is lost. |
| // |
| // The attr field of the ReportField contains all information to parse |
| // a report sent by the device. The ExtractUint functions will use the |
| // offset in the attribute to extract the necessary data. |
| // |
| // An example will enlighten. Assume |report| array as follows, |
| // with most fields omitted for brevity: |
| // |
| // report[0] |
| // .input_fields---> [0] report_id: 1 |
| // usage button,1 |
| // flags data,var |
| // bit_sz 1 |
| // // For descriptors that have more than 1 report, |
| // // the first 8 bits are always the report id |
| // offset 8 |
| // |
| // [1] report_id: 1 |
| // usage button,2 |
| // flags data,var |
| // bit_sz 1 |
| // offset 9 |
| // |
| // [2] report_id: 1 |
| // usage button,none |
| // flags const |
| // bit_sz 6 |
| // offset 10 |
| // report[1] |
| // .input_fields---> [3] report_id: 3 |
| // usage desktop,X |
| // flags data,var |
| // bit_sz 8 |
| // offset 8 |
| // |
| // [4] report_id: 3 |
| // usage desktop,Y |
| // flags data,var |
| // bit_sz 8 |
| // offset 16 |
| // report[2] |
| // .input_fields---> [5] report_id: 4 |
| // usage desktop,wheel |
| // flags data,var |
| // bit_sz 5 |
| // offset 8 |
| // |
| // [6] report_id: 4 |
| // usage desktop,none |
| // flags const |
| // bit_sz 3 |
| // offset 13 |
| // |
| // Now given the following report stream, with byte-order |
| // left to right: |
| // |
| // 03 b4 67 01 02 04 13 03 b5 6a |
| // ------>--------->-----------> |
| // |
| // Can be parsed as the following 4 reports: |
| // |
| // - 03 is report id, so Node [3] and Node [4] are in play |
| // b4 is X-coord/desktop (8-bits) |
| // 67 is Y-coord/desktop (8-bits) |
| // |
| // - 01 is report id, so Node [0], Node [1] and Node [3] are in play |
| // 02 is split into bits |
| // 0 is 1/button (1-bit) |
| // 1 is 2/button (1-bit) |
| // 0 is none/button (7-bit) padding |
| // |
| // - 04 is report id, so Node [5] and Node [6] are in play |
| // 13 is split into bits |
| // 13 is desktop/wheel (5-bit) |
| // 0 is desktop/none (3-bit) padding |
| // |
| // - 03 is report id, so Node [3] and Node [4] are in play |
| // b5 is X-coord/desktop (8-bits) |
| // 6a is Y-coord/desktop (8-bits) |
| // |
| // |
| // Input, Output, and Feature reports are all sent over unique channels, which |
| // is how they are distingushed. This is important because they can share the |
| // same report id. |
| |
| // Logical minimum and maximum per hid spec. |
| struct MinMax { |
| int64_t min; |
| int64_t max; |
| }; |
| |
| // Physical units descriptor. |
| struct Unit { |
| uint32_t type; |
| int32_t exp; |
| }; |
| |
| // Describes the semantic meaning of fields. See the "HID Usage tables" |
| // document from usb.org. |
| struct Usage { |
| uint16_t page; |
| uint32_t usage; |
| }; |
| |
| enum class CollectionType : uint32_t { |
| kPhysical, |
| kApplication, |
| kLogical, |
| kReport, |
| kNamedArray, |
| kUsageSwitch, |
| kUsageModifier, |
| kReserved, |
| kVendor |
| }; |
| |
| enum NodeType : uint32_t { |
| kInput, |
| kOutput, |
| kFeature |
| }; |
| |
| enum FieldTypeFlags : uint32_t { |
| // Indicates if field can be modfied. Constant often means is padding. |
| kData = 1 << 0, |
| kConstant = 1 << 1, |
| // The field is either an array or scalar. If it is an array only |
| // the kData|kConstant and kAbsolute|kRelative flags are valid. |
| kArray = 1 << 2, |
| kScalar = 1 << 3, |
| // Value is absolute wrt to a fixed origin or not. |
| kAbsolute = 1 << 4, |
| kRelative = 1 << 5, |
| // Whether the data rolls over wrt to the logical min/max. |
| kNoWrap = 1 << 6, |
| kWrap = 1 << 7, |
| // Data has been pre-processed, for example dead-zone. |
| kLinear = 1 << 8, |
| kNonLinear = 1 << 9, |
| // Value returns to a preset value when the user is not interacting with control. |
| kPreferredState = 1 << 10, |
| kNoPreferred = 1 << 11, |
| // If the control can enter a state when it does not report data. |
| kNoNullPosition = 1 << 12, |
| kNullState = 1 << 13, |
| // Output-only: can the value be modified without host interaction. |
| kNonVolatile = 1 << 14, |
| kVolatile = 1 << 15, |
| // Data is a fixed size stream. |
| kBitField = 1 << 16, |
| kBufferedBytes = 1 << 17, |
| }; |
| |
| // TODO(cpu): consider repurposing the kData| kArray | kNonLinear to indicate |
| // an array field which requires a lookup table. See adafruit trinket report id 4 |
| // for an example of this case. |
| |
| struct Collection { |
| CollectionType type; |
| Usage usage; |
| Collection* parent; // Enclosing collection or null. |
| }; |
| |
| struct Attributes { |
| Usage usage; |
| Unit unit; |
| MinMax logc_mm; |
| MinMax phys_mm; |
| uint8_t bit_sz; |
| uint32_t offset; |
| }; |
| |
| struct ReportField { |
| uint8_t report_id; |
| Attributes attr; |
| NodeType type; |
| uint32_t flags; |
| Collection* col; |
| }; |
| |
| struct ReportDescriptor { |
| uint8_t report_id; |
| |
| // The byte size includes the 1 byte for the report ID if the report ID is |
| // not equal to zero. |
| size_t input_byte_sz; |
| size_t input_count; |
| ReportField* input_fields; |
| |
| size_t output_byte_sz; |
| size_t output_count; |
| ReportField* output_fields; |
| |
| size_t feature_byte_sz; |
| size_t feature_count; |
| ReportField* feature_fields; |
| }; |
| |
| struct DeviceDescriptor { |
| size_t rep_count; |
| ReportDescriptor report[]; |
| }; |
| |
| enum ParseResult : uint32_t { |
| kParseOk = 0, |
| kParseNoMemory = 1, |
| kParseMoreNeeded = 2, |
| kParseUnsuported = 3, |
| kParseInvalidTag = 4, |
| kParseInvalidItemType = 5, |
| kParseInvalidItemValue = 6, |
| kParseUsageLimit = 7, |
| kParseInvalidRange = 8, |
| kParseOverflow = 9, |
| kParseLeftovers = 10, |
| kParseUnexpectedCol = 11, |
| kParseUnexectedItem = 12, |
| kParseInvalidUsage = 13, |
| kParseMissingUsage = 14, |
| kParserMissingPage = 15, |
| kParserUnexpectedPop = 16, |
| kParserInvalidID = 17 |
| }; |
| |
| ParseResult ParseReportDescriptor( |
| const uint8_t* rpt_desc, size_t desc_len, |
| DeviceDescriptor** dev_desc); |
| |
| void FreeDeviceDescriptor(DeviceDescriptor* dev_desc); |
| |
| Collection* GetAppCollection(const ReportField* field); |
| |
| // Helper for creating Usage constants. |
| template <typename P, typename U> |
| constexpr Usage USAGE(P page, U usage) { |
| return Usage{static_cast<uint16_t>(page), static_cast<uint32_t>(usage)}; |
| } |
| |
| } // namespace hid |
| |
| inline bool operator==(hid::Usage a, hid::Usage b) { |
| return (a.page == b.page) && (a.usage == b.usage); |
| } |
| |
| inline bool operator!=(hid::Usage a, hid::Usage b) { |
| return (a.page != b.page) || (a.usage != b.usage); |
| } |
| |
| inline bool operator==(hid::MinMax a, hid::MinMax b) { |
| return (a.min == b.min) && (a.max == b.max); |
| } |
| |
| #endif // HID_PARSER_PARSER_H_ |
