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 "UsbMouseAbsolutePointer.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 *
GetNextHidItem(IN UINT8 * StartPos,IN UINT8 * EndPos,OUT HID_ITEM * HidItem)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
GetItemData(IN HID_ITEM * HidItem)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_ABSOLUTE_POINTER_DEV
165 @param HidItem The HID item to parse
166
167 **/
168 VOID
ParseHidItem(IN USB_MOUSE_ABSOLUTE_POINTER_DEV * UsbMouse,IN HID_ITEM * HidItem)169 ParseHidItem (
170 IN USB_MOUSE_ABSOLUTE_POINTER_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_ABSOLUTE_POINTER_DEV.
238
239 @param UsbMouseAbsolutePointer The instance of USB_MOUSE_ABSOLUTE_POINTER_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
ParseMouseReportDescriptor(OUT USB_MOUSE_ABSOLUTE_POINTER_DEV * UsbMouseAbsolutePointer,IN UINT8 * ReportDescriptor,IN UINTN ReportSize)248 ParseMouseReportDescriptor (
249 OUT USB_MOUSE_ABSOLUTE_POINTER_DEV *UsbMouseAbsolutePointer,
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 (UsbMouseAbsolutePointer, &HidItem);
270
271 Ptr = GetNextHidItem (Ptr, DescriptorEnd, &HidItem);
272 }
273
274 UsbMouseAbsolutePointer->NumberOfButtons = (UINT8) (UsbMouseAbsolutePointer->PrivateData.ButtonMaxIndex - UsbMouseAbsolutePointer->PrivateData.ButtonMinIndex + 1);
275 UsbMouseAbsolutePointer->XLogicMax = 1023;
276 UsbMouseAbsolutePointer->YLogicMax = 1023;
277 UsbMouseAbsolutePointer->XLogicMin = -1023;
278 UsbMouseAbsolutePointer->YLogicMin = -1023;
279
280 return EFI_SUCCESS;
281 }
282