Library/PackageCache/com.unity.inputsystem@1.6.1/InputSystem/Plugins/HID/HIDParser.cs

using System;
using System.Collections.Generic;

////TODO: array support
////TODO: delimiter support
////TODO: designator support

#pragma warning disable CS0649
namespace UnityEngine.InputSystem.HID
{
    /// <summary>
    /// Turns binary HID descriptors into <see cref="HID.HIDDeviceDescriptor"/> instances.
    /// </summary>
    /// <remarks>
    /// For information about the format, see the <a href="http://www.usb.org/developers/hidpage/HID1_11.pdf">
    /// Device Class Definition for Human Interface Devices</a> section 6.2.2.
    /// </remarks>
    internal static class HIDParser
    {
        /// <summary>
        /// Parse a HID report descriptor as defined by section 6.2.2 of the
        /// <a href="http://www.usb.org/developers/hidpage/HID1_11.pdf">HID
        /// specification</a> and add the elements and collections from the
        /// descriptor to the given <paramref name="deviceDescriptor"/>.
        /// </summary>
        /// <param name="buffer">Buffer containing raw HID report descriptor.</param>
        /// <param name="deviceDescriptor">HID device descriptor to complete with the information
        /// from the report descriptor. Elements and collections will get added to this descriptor.</param>
        /// <returns>True if the report descriptor was successfully parsed.</returns>
        /// <remarks>
        /// Will also set <see cref="HID.HIDDeviceDescriptor.inputReportSize"/>,
        /// <see cref="HID.HIDDeviceDescriptor.outputReportSize"/>, and
        /// <see cref="HID.HIDDeviceDescriptor.featureReportSize"/>.
        /// </remarks>
        public static unsafe bool ParseReportDescriptor(byte[] buffer, ref HID.HIDDeviceDescriptor deviceDescriptor)
        {
            if (buffer == null)
                throw new ArgumentNullException(nameof(buffer));

            fixed(byte* bufferPtr = buffer)
            {
                return ParseReportDescriptor(bufferPtr, buffer.Length, ref deviceDescriptor);
            }
        }

        public unsafe static bool ParseReportDescriptor(byte* bufferPtr, int bufferLength, ref HID.HIDDeviceDescriptor deviceDescriptor)
        {
            // Item state.
            var localItemState = new HIDItemStateLocal();
            var globalItemState = new HIDItemStateGlobal();

            // Lists where we accumulate the data from the HID items.
            var reports = new List<HIDReportData>();
            var elements = new List<HID.HIDElementDescriptor>();
            var collections = new List<HID.HIDCollectionDescriptor>();
            var currentCollection = -1;

            // Parse the linear list of items.
            var endPtr = bufferPtr + bufferLength;
            var currentPtr = bufferPtr;
            while (currentPtr < endPtr)
            {
                var firstByte = *currentPtr;

                ////TODO
                if (firstByte == 0xFE)
                    throw new NotImplementedException("long item support");

                // Read item header.
                var itemSize = (byte)(firstByte & 0x3);
                var itemTypeAndTag = (byte)(firstByte & 0xFC);
                ++currentPtr;

                // Process item.
                switch (itemTypeAndTag)
                {
                    // ------------ Global Items --------------
                    // These set item state permanently until it is reset.

                    // Usage Page
                    case (int)HIDItemTypeAndTag.UsagePage:
                        globalItemState.usagePage = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Report Count
                    case (int)HIDItemTypeAndTag.ReportCount:
                        globalItemState.reportCount = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Report Size
                    case (int)HIDItemTypeAndTag.ReportSize:
                        globalItemState.reportSize = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Report ID
                    case (int)HIDItemTypeAndTag.ReportID:
                        globalItemState.reportId = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Logical Minimum
                    case (int)HIDItemTypeAndTag.LogicalMinimum:
                        globalItemState.logicalMinimum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Logical Maximum
                    case (int)HIDItemTypeAndTag.LogicalMaximum:
                        globalItemState.logicalMaximum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Physical Minimum
                    case (int)HIDItemTypeAndTag.PhysicalMinimum:
                        globalItemState.physicalMinimum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Physical Maximum
                    case (int)HIDItemTypeAndTag.PhysicalMaximum:
                        globalItemState.physicalMaximum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Unit Exponent
                    case (int)HIDItemTypeAndTag.UnitExponent:
                        globalItemState.unitExponent = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Unit
                    case (int)HIDItemTypeAndTag.Unit:
                        globalItemState.unit = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // ------------ Local Items --------------
                    // These set the state for the very next elements to be generated.

                    // Usage
                    case (int)HIDItemTypeAndTag.Usage:
                        localItemState.SetUsage(ReadData(itemSize, currentPtr, endPtr));
                        break;

                    // Usage Minimum
                    case (int)HIDItemTypeAndTag.UsageMinimum:
                        localItemState.usageMinimum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // Usage Maximum
                    case (int)HIDItemTypeAndTag.UsageMaximum:
                        localItemState.usageMaximum = ReadData(itemSize, currentPtr, endPtr);
                        break;

                    // ------------ Main Items --------------
                    // These emit things into the descriptor based on the local and global item state.

                    // Collection
                    case (int)HIDItemTypeAndTag.Collection:

                        // Start new collection.
                        var parentCollection = currentCollection;
                        currentCollection = collections.Count;
                        collections.Add(new HID.HIDCollectionDescriptor
                        {
                            type = (HID.HIDCollectionType)ReadData(itemSize, currentPtr, endPtr),
                            parent = parentCollection,
                            usagePage = globalItemState.GetUsagePage(0, ref localItemState),
                            usage = localItemState.GetUsage(0),
                            firstChild = elements.Count
                        });

                        HIDItemStateLocal.Reset(ref localItemState);
                        break;

                    // EndCollection
                    case (int)HIDItemTypeAndTag.EndCollection:
                        if (currentCollection == -1)
                            return false;

                        // Close collection.
                        var collection = collections[currentCollection];
                        collection.childCount = elements.Count - collection.firstChild;
                        collections[currentCollection] = collection;

                        // Switch back to parent collection (if any).
                        currentCollection = collection.parent;

                        HIDItemStateLocal.Reset(ref localItemState);
                        break;

                    // Input/Output/Feature
                    case (int)HIDItemTypeAndTag.Input:
                    case (int)HIDItemTypeAndTag.Output:
                    case (int)HIDItemTypeAndTag.Feature:

                        // Determine report type.
                        var reportType = itemTypeAndTag == (int)HIDItemTypeAndTag.Input
                            ? HID.HIDReportType.Input
                            : itemTypeAndTag == (int)HIDItemTypeAndTag.Output
                            ? HID.HIDReportType.Output
                            : HID.HIDReportType.Feature;

                        // Find report.
                        var reportIndex = HIDReportData.FindOrAddReport(globalItemState.reportId, reportType, reports);
                        var report = reports[reportIndex];

                        // If we have a report ID, then reports start with an 8 byte report ID.
                        // Shift our offsets accordingly.
                        if (report.currentBitOffset == 0 && globalItemState.reportId.HasValue)
                            report.currentBitOffset = 8;

                        // Add elements to report.
                        var reportCount = globalItemState.reportCount.GetValueOrDefault(1);
                        var flags = ReadData(itemSize, currentPtr, endPtr);
                        for (var i = 0; i < reportCount; ++i)
                        {
                            var element = new HID.HIDElementDescriptor
                            {
                                usage = localItemState.GetUsage(i) & 0xFFFF, // Mask off usage page, if set.
                                usagePage = globalItemState.GetUsagePage(i, ref localItemState),
                                reportType = reportType,
                                reportSizeInBits = globalItemState.reportSize.GetValueOrDefault(8),
                                reportOffsetInBits = report.currentBitOffset,
                                reportId = globalItemState.reportId.GetValueOrDefault(1),
                                flags = (HID.HIDElementFlags)flags,
                                logicalMin = globalItemState.logicalMinimum.GetValueOrDefault(0),
                                logicalMax = globalItemState.logicalMaximum.GetValueOrDefault(0),
                                physicalMin = globalItemState.GetPhysicalMin(),
                                physicalMax = globalItemState.GetPhysicalMax(),
                                unitExponent = globalItemState.unitExponent.GetValueOrDefault(0),
                                unit = globalItemState.unit.GetValueOrDefault(0),
                            };
                            report.currentBitOffset += element.reportSizeInBits;
                            elements.Add(element);
                        }
                        reports[reportIndex] = report;

                        HIDItemStateLocal.Reset(ref localItemState);
                        break;
                }

                if (itemSize == 3)
                    currentPtr += 4;
                else
                    currentPtr += itemSize;
            }

            deviceDescriptor.elements = elements.ToArray();
            deviceDescriptor.collections = collections.ToArray();

            // Set usage and usage page on device descriptor to what's
            // on the toplevel application collection.
            foreach (var collection in collections)
            {
                if (collection.parent == -1 && collection.type == HID.HIDCollectionType.Application)
                {
                    deviceDescriptor.usage = collection.usage;
                    deviceDescriptor.usagePage = collection.usagePage;
                    break;
                }
            }

            return true;
        }

        private unsafe static int ReadData(int itemSize, byte* currentPtr, byte* endPtr)
        {
            if (itemSize == 0)
                return 0;

            // Read byte.
            if (itemSize == 1)
            {
                if (currentPtr >= endPtr)
                    return 0;
                return *currentPtr;
            }

            // Read short.
            if (itemSize == 2)
            {
                if (currentPtr + 2 >= endPtr)
                    return 0;
                var data1 = *currentPtr;
                var data2 = *(currentPtr + 1);
                return (data2 << 8) | data1;
            }

            // Read int.
            if (itemSize == 3) // Item size 3 means 4 bytes!
            {
                if (currentPtr + 4 >= endPtr)
                    return 0;

                var data1 = *currentPtr;
                var data2 = *(currentPtr + 1);
                var data3 = *(currentPtr + 2);
                var data4 = *(currentPtr + 3);

                return (data4 << 24) | (data3 << 24) | (data2 << 8) | data1;
            }

            Debug.Assert(false, "Should not reach here");
            return 0;
        }

        private struct HIDReportData
        {
            public int reportId;
            public HID.HIDReportType reportType;
            public int currentBitOffset;

            public static int FindOrAddReport(int? reportId, HID.HIDReportType reportType, List<HIDReportData> reports)
            {
                var id = 1;
                if (reportId.HasValue)
                    id = reportId.Value;

                for (var i = 0; i < reports.Count; ++i)
                {
                    if (reports[i].reportId == id && reports[i].reportType == reportType)
                        return i;
                }

                reports.Add(new HIDReportData
                {
                    reportId = id,
                    reportType = reportType
                });

                return reports.Count - 1;
            }
        }

        // All types and tags with size bits (low order two bits) masked out (i.e. being 0).
        private enum HIDItemTypeAndTag
        {
            Input = 0x80,
            Output = 0x90,
            Feature = 0xB0,
            Collection = 0xA0,
            EndCollection = 0xC0,
            UsagePage = 0x04,
            LogicalMinimum = 0x14,
            LogicalMaximum = 0x24,
            PhysicalMinimum = 0x34,
            PhysicalMaximum = 0x44,
            UnitExponent = 0x54,
            Unit = 0x64,
            ReportSize = 0x74,
            ReportID = 0x84,
            ReportCount = 0x94,
            Push = 0xA4,
            Pop = 0xB4,
            Usage = 0x08,
            UsageMinimum = 0x18,
            UsageMaximum = 0x28,
            DesignatorIndex = 0x38,
            DesignatorMinimum = 0x48,
            DesignatorMaximum = 0x58,
            StringIndex = 0x78,
            StringMinimum = 0x88,
            StringMaximum = 0x98,
            Delimiter = 0xA8,
        }

        // State that needs to be defined for each main item separately.
        // See section 6.2.2.8
        private struct HIDItemStateLocal
        {
            public int? usage;
            public int? usageMinimum;
            public int? usageMaximum;
            public int? designatorIndex;
            public int? designatorMinimum;
            public int? designatorMaximum;
            public int? stringIndex;
            public int? stringMinimum;
            public int? stringMaximum;

            public List<int> usageList;

            // Wipe state but preserve usageList allocation.
            public static void Reset(ref HIDItemStateLocal state)
            {
                var usageList = state.usageList;
                state = new HIDItemStateLocal();
                if (usageList != null)
                {
                    usageList.Clear();
                    state.usageList = usageList;
                }
            }

            // Usage can be set repeatedly to provide an enumeration of usages.
            public void SetUsage(int value)
            {
                if (usage.HasValue)
                {
                    if (usageList == null)
                        usageList = new List<int>();
                    usageList.Add(usage.Value);
                }
                usage = value;
            }

            // Get usage for Nth element in [0-reportCount] list.
            public int GetUsage(int index)
            {
                // If we have minimum and maximum usage, interpolate between that.
                if (usageMinimum.HasValue && usageMaximum.HasValue)
                {
                    var min = usageMinimum.Value;
                    var max = usageMaximum.Value;

                    var range = max - min;
                    if (range < 0)
                        return 0;
                    if (index >= range)
                        return max;
                    return min + index;
                }

                // If we have a list of usages, index into that.
                if (usageList != null && usageList.Count > 0)
                {
                    var usageCount = usageList.Count;
                    if (index >= usageCount)
                        return usage.Value;

                    return usageList[index];
                }

                if (usage.HasValue)
                    return usage.Value;

                ////TODO: min/max

                return 0;
            }
        }

        // State that is carried over from main item to main item.
        // See section 6.2.2.7
        private struct HIDItemStateGlobal
        {
            public int? usagePage;
            public int? logicalMinimum;
            public int? logicalMaximum;
            public int? physicalMinimum;
            public int? physicalMaximum;
            public int? unitExponent;
            public int? unit;
            public int? reportSize;
            public int? reportCount;
            public int? reportId;

            public HID.UsagePage GetUsagePage(int index, ref HIDItemStateLocal localItemState)
            {
                if (!usagePage.HasValue)
                {
                    var usage = localItemState.GetUsage(index);
                    return (HID.UsagePage)(usage >> 16);
                }

                return (HID.UsagePage)usagePage.Value;
            }

            public int GetPhysicalMin()
            {
                if (physicalMinimum == null || physicalMaximum == null ||
                    (physicalMinimum.Value == 0 && physicalMaximum.Value == 0))
                    return logicalMinimum.GetValueOrDefault(0);
                return physicalMinimum.Value;
            }

            public int GetPhysicalMax()
            {
                if (physicalMinimum == null || physicalMaximum == null ||
                    (physicalMinimum.Value == 0 && physicalMaximum.Value == 0))
                    return logicalMaximum.GetValueOrDefault(0);
                return physicalMaximum.Value;
            }
        }
    }
}