1 /** @file 2 Helper functions to parse HID report descriptor and items. 3 4 Copyright (c) 2004 - 2010, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #include "UsbMouse.h" 16 17 18 /** 19 Get next HID item from report descriptor. 20 21 This function retrieves next HID item from report descriptor, according to 22 the start position. 23 According to USB HID Specification, An item is piece of information 24 about the device. All items have a one-byte prefix that contains 25 the item tag, item type, and item size. 26 There are two basic types of items: short items and long items. 27 If the item is a short item, its optional data size may be 0, 1, 2, or 4 bytes. 28 Only short item is supported here. 29 30 @param StartPos Start position of the HID item to get. 31 @param EndPos End position of the range to get the the next HID item. 32 @param HidItem Buffer for the HID Item to return. 33 34 @return Pointer to end of the HID item returned. 35 NULL if no HID item retrieved. 36 37 **/ 38 UINT8 * 39 GetNextHidItem ( 40 IN UINT8 *StartPos, 41 IN UINT8 *EndPos, 42 OUT HID_ITEM *HidItem 43 ) 44 { 45 UINT8 Temp; 46 47 if (EndPos <= StartPos) { 48 return NULL; 49 } 50 51 Temp = *StartPos; 52 StartPos++; 53 54 // 55 // Bit format of prefix byte: 56 // Bits 0-1: Size 57 // Bits 2-3: Type 58 // Bits 4-7: Tag 59 // 60 HidItem->Type = BitFieldRead8 (Temp, 2, 3); 61 HidItem->Tag = BitFieldRead8 (Temp, 4, 7); 62 63 if (HidItem->Tag == HID_ITEM_TAG_LONG) { 64 // 65 // Long Items are not supported, although we try to parse it. 66 // 67 HidItem->Format = HID_ITEM_FORMAT_LONG; 68 69 if ((EndPos - StartPos) >= 2) { 70 HidItem->Size = *StartPos++; 71 HidItem->Tag = *StartPos++; 72 73 if ((EndPos - StartPos) >= HidItem->Size) { 74 HidItem->Data.LongData = StartPos; 75 StartPos += HidItem->Size; 76 return StartPos; 77 } 78 } 79 } else { 80 HidItem->Format = HID_ITEM_FORMAT_SHORT; 81 HidItem->Size = BitFieldRead8 (Temp, 0, 1); 82 83 switch (HidItem->Size) { 84 case 0: 85 // 86 // No data 87 // 88 return StartPos; 89 90 case 1: 91 // 92 // 1-byte data 93 // 94 if ((EndPos - StartPos) >= 1) { 95 HidItem->Data.Uint8 = *StartPos++; 96 return StartPos; 97 } 98 99 case 2: 100 // 101 // 2-byte data 102 // 103 if ((EndPos - StartPos) >= 2) { 104 CopyMem (&HidItem->Data.Uint16, StartPos, sizeof (UINT16)); 105 StartPos += 2; 106 return StartPos; 107 } 108 109 case 3: 110 // 111 // 4-byte data, adjust size 112 // 113 HidItem->Size = 4; 114 if ((EndPos - StartPos) >= 4) { 115 CopyMem (&HidItem->Data.Uint32, StartPos, sizeof (UINT32)); 116 StartPos += 4; 117 return StartPos; 118 } 119 } 120 } 121 122 return NULL; 123 } 124 125 126 /** 127 Get data from HID item. 128 129 This function retrieves data from HID item. 130 It only supports short items, which has 4 types of data: 131 0, 1, 2, or 4 bytes. 132 133 @param HidItem Pointer to the HID item. 134 135 @return The data of HID item. 136 137 **/ 138 UINT32 139 GetItemData ( 140 IN HID_ITEM *HidItem 141 ) 142 { 143 // 144 // Get data from HID item. 145 // 146 switch (HidItem->Size) { 147 case 1: 148 return HidItem->Data.Uint8; 149 case 2: 150 return HidItem->Data.Uint16; 151 case 4: 152 return HidItem->Data.Uint32; 153 } 154 return 0; 155 } 156 157 /** 158 Parse HID item from report descriptor. 159 160 There are three item types: Main, Global, and Local. 161 This function parses these types of HID items according 162 to tag info. 163 164 @param UsbMouse The instance of USB_MOUSE_DEV 165 @param HidItem The HID item to parse 166 167 **/ 168 VOID 169 ParseHidItem ( 170 IN USB_MOUSE_DEV *UsbMouse, 171 IN HID_ITEM *HidItem 172 ) 173 { 174 UINT8 Data; 175 176 switch (HidItem->Type) { 177 178 case HID_ITEM_TYPE_MAIN: 179 // 180 // we don't care any main items, just skip 181 // 182 return; 183 184 case HID_ITEM_TYPE_GLOBAL: 185 // 186 // For global items, we only care Usage Page tag for Button Page here 187 // 188 if (HidItem->Tag == HID_GLOBAL_ITEM_TAG_USAGE_PAGE) { 189 Data = (UINT8) GetItemData (HidItem); 190 if (Data == 0x09) { 191 // 192 // Button Page 193 // 194 UsbMouse->PrivateData.ButtonDetected = TRUE; 195 } 196 } 197 return; 198 199 case HID_ITEM_TYPE_LOCAL: 200 if (HidItem->Size == 0) { 201 // 202 // No expected data for local item 203 // 204 return ; 205 } 206 207 Data = (UINT8) GetItemData (HidItem); 208 209 switch (HidItem->Tag) { 210 case HID_LOCAL_ITEM_TAG_USAGE_MINIMUM: 211 if (UsbMouse->PrivateData.ButtonDetected) { 212 UsbMouse->PrivateData.ButtonMinIndex = Data; 213 } 214 return ; 215 216 case HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM: 217 { 218 if (UsbMouse->PrivateData.ButtonDetected) { 219 UsbMouse->PrivateData.ButtonMaxIndex = Data; 220 } 221 return ; 222 } 223 224 default: 225 return; 226 } 227 } 228 } 229 230 231 /** 232 Parse Mouse Report Descriptor. 233 234 According to USB HID Specification, report descriptors are 235 composed of pieces of information. Each piece of information 236 is called an Item. This function retrieves each item from 237 the report descriptor and updates USB_MOUSE_DEV. 238 239 @param UsbMouse The instance of USB_MOUSE_DEV 240 @param ReportDescriptor Report descriptor to parse 241 @param ReportSize Report descriptor size 242 243 @retval EFI_SUCCESS Report descriptor successfully parsed. 244 @retval EFI_UNSUPPORTED Report descriptor contains long item. 245 246 **/ 247 EFI_STATUS 248 ParseMouseReportDescriptor ( 249 OUT USB_MOUSE_DEV *UsbMouse, 250 IN UINT8 *ReportDescriptor, 251 IN UINTN ReportSize 252 ) 253 { 254 UINT8 *DescriptorEnd; 255 UINT8 *Ptr; 256 HID_ITEM HidItem; 257 258 DescriptorEnd = ReportDescriptor + ReportSize; 259 260 Ptr = GetNextHidItem (ReportDescriptor, DescriptorEnd, &HidItem); 261 while (Ptr != NULL) { 262 if (HidItem.Format != HID_ITEM_FORMAT_SHORT) { 263 // 264 // Long Item is not supported at current HID revision 265 // 266 return EFI_UNSUPPORTED; 267 } 268 269 ParseHidItem (UsbMouse, &HidItem); 270 271 Ptr = GetNextHidItem (Ptr, DescriptorEnd, &HidItem); 272 } 273 274 UsbMouse->NumberOfButtons = (UINT8) (UsbMouse->PrivateData.ButtonMaxIndex - UsbMouse->PrivateData.ButtonMinIndex + 1); 275 UsbMouse->XLogicMax = 127; 276 UsbMouse->YLogicMax = 127; 277 UsbMouse->XLogicMin = -127; 278 UsbMouse->YLogicMin = -127; 279 280 return EFI_SUCCESS; 281 } 282