291eccbe3652bc86c9f8ab385d42c5343f6474a8
[people/mcb30/edk2.git] / edk2 / MdePkg / Include / Library / UsbLib.h
1 /** @file\r
2    Common Dxe Libarary  for USB\r
3    Add Constants & structure definitions for Usb HID\r
4 \r
5   Copyright (c) 2006, Intel Corporation<BR>\r
6   All rights reserved. This program and the accompanying materials\r
7   are licensed and made available under the terms and conditions of the BSD License\r
8   which accompanies this distribution.  The full text of the license may be found at\r
9   http://opensource.org/licenses/bsd-license.php\r
10 \r
11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
13 \r
14 **/\r
15 \r
16 \r
17 #ifndef __USB_DXE_LIB_H__\r
18 #define __USB_DXE_LIB_H__\r
19 \r
20 #include <Protocol/UsbIo.h>\r
21 //\r
22 // define the timeout time as 3ms\r
23 //\r
24 #define TIMEOUT_VALUE 3 * 1000\r
25 \r
26 //\r
27 // HID constants definition, see HID rev1.0\r
28 //\r
29 //\r
30 // HID report item format\r
31 //\r
32 #define HID_ITEM_FORMAT_SHORT 0\r
33 #define HID_ITEM_FORMAT_LONG  1\r
34 \r
35 //\r
36 // Special tag indicating long items\r
37 //\r
38 #define HID_ITEM_TAG_LONG 15\r
39 \r
40 //\r
41 // HID report descriptor item type (prefix bit 2,3)\r
42 //\r
43 #define HID_ITEM_TYPE_MAIN      0\r
44 #define HID_ITEM_TYPE_GLOBAL    1\r
45 #define HID_ITEM_TYPE_LOCAL     2\r
46 #define HID_ITEM_TYPE_RESERVED  3\r
47 \r
48 //\r
49 // HID report descriptor main item tags\r
50 //\r
51 #define HID_MAIN_ITEM_TAG_INPUT             8\r
52 #define HID_MAIN_ITEM_TAG_OUTPUT            9\r
53 #define HID_MAIN_ITEM_TAG_FEATURE           11\r
54 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION  10\r
55 #define HID_MAIN_ITEM_TAG_END_COLLECTION    12\r
56 \r
57 //\r
58 // HID report descriptor main item contents\r
59 //\r
60 #define HID_MAIN_ITEM_CONSTANT      0x001\r
61 #define HID_MAIN_ITEM_VARIABLE      0x002\r
62 #define HID_MAIN_ITEM_RELATIVE      0x004\r
63 #define HID_MAIN_ITEM_WRAP          0x008\r
64 #define HID_MAIN_ITEM_NONLINEAR     0x010\r
65 #define HID_MAIN_ITEM_NO_PREFERRED  0x020\r
66 #define HID_MAIN_ITEM_NULL_STATE    0x040\r
67 #define HID_MAIN_ITEM_VOLATILE      0x080\r
68 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100\r
69 \r
70 //\r
71 // HID report descriptor collection item types\r
72 //\r
73 #define HID_COLLECTION_PHYSICAL     0\r
74 #define HID_COLLECTION_APPLICATION  1\r
75 #define HID_COLLECTION_LOGICAL      2\r
76 \r
77 //\r
78 // HID report descriptor global item tags\r
79 //\r
80 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE        0\r
81 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM   1\r
82 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM   2\r
83 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM  3\r
84 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM  4\r
85 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT     5\r
86 #define HID_GLOBAL_ITEM_TAG_UNIT              6\r
87 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE       7\r
88 #define HID_GLOBAL_ITEM_TAG_REPORT_ID         8\r
89 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT      9\r
90 #define HID_GLOBAL_ITEM_TAG_PUSH              10\r
91 #define HID_GLOBAL_ITEM_TAG_POP               11\r
92 \r
93 //\r
94 // HID report descriptor local item tags\r
95 //\r
96 #define HID_LOCAL_ITEM_TAG_USAGE              0\r
97 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM      1\r
98 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM      2\r
99 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX   3\r
100 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4\r
101 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5\r
102 #define HID_LOCAL_ITEM_TAG_STRING_INDEX       7\r
103 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM     8\r
104 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM     9\r
105 #define HID_LOCAL_ITEM_TAG_DELIMITER          10\r
106 \r
107 //\r
108 // HID usage tables\r
109 //\r
110 #define HID_USAGE_PAGE    0xffff0000\r
111 \r
112 #define HID_UP_GENDESK    0x00010000\r
113 #define HID_UP_KEYBOARD   0x00070000\r
114 #define HID_UP_LED        0x00080000\r
115 #define HID_UP_BUTTON     0x00090000\r
116 #define HID_UP_CONSUMER   0x000c0000\r
117 #define HID_UP_DIGITIZER  0x000d0000\r
118 #define HID_UP_PID        0x000f0000\r
119 \r
120 #define HID_USAGE         0x0000ffff\r
121 \r
122 #define HID_GD_POINTER    0x00010001\r
123 #define HID_GD_MOUSE      0x00010002\r
124 #define HID_GD_JOYSTICK   0x00010004\r
125 #define HID_GD_GAMEPAD    0x00010005\r
126 #define HID_GD_HATSWITCH  0x00010039\r
127 \r
128 //\r
129 // HID report types\r
130 //\r
131 #define HID_INPUT_REPORT    1\r
132 #define HID_OUTPUT_REPORT   2\r
133 #define HID_FEATURE_REPORT  3\r
134 \r
135 //\r
136 // HID device quirks.\r
137 //\r
138 #define HID_QUIRK_INVERT  0x01\r
139 #define HID_QUIRK_NOTOUCH 0x02\r
140 \r
141 //\r
142 // HID class protocol request\r
143 //\r
144 #define EFI_USB_GET_REPORT_REQUEST    0x01\r
145 #define EFI_USB_GET_IDLE_REQUEST      0x02\r
146 #define EFI_USB_GET_PROTOCOL_REQUEST  0x03\r
147 #define EFI_USB_SET_REPORT_REQUEST    0x09\r
148 #define EFI_USB_SET_IDLE_REQUEST      0x0a\r
149 #define EFI_USB_SET_PROTOCOL_REQUEST  0x0b\r
150 \r
151 #pragma pack(1)\r
152 //\r
153 // Descriptor header for Report/Physical Descriptors\r
154 //\r
155 typedef struct hid_class_descriptor {\r
156   UINT8   DescriptorType;\r
157   UINT16  DescriptorLength;\r
158 } EFI_USB_HID_CLASS_DESCRIPTOR;\r
159 \r
160 typedef struct hid_descriptor {\r
161   UINT8                         Length;\r
162   UINT8                         DescriptorType;\r
163   UINT16                        BcdHID;\r
164   UINT8                         CountryCode;\r
165   UINT8                         NumDescriptors;\r
166   EFI_USB_HID_CLASS_DESCRIPTOR  HidClassDesc[1];\r
167 } EFI_USB_HID_DESCRIPTOR;\r
168 \r
169 #pragma pack()\r
170 \r
171 EFI_STATUS\r
172 UsbGetHidDescriptor (\r
173   IN  EFI_USB_IO_PROTOCOL        *UsbIo,\r
174   IN  UINT8                      InterfaceNum,\r
175   OUT EFI_USB_HID_DESCRIPTOR     *HidDescriptor\r
176   );\r
177 \r
178 EFI_STATUS\r
179 UsbGetReportDescriptor (\r
180   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
181   IN  UINT8                   InterfaceNum,\r
182   IN  UINT16                  DescriptorSize,\r
183   OUT UINT8                   *DescriptorBuffer\r
184   );\r
185 \r
186 EFI_STATUS\r
187 UsbGetProtocolRequest (\r
188   IN EFI_USB_IO_PROTOCOL     *UsbIo,\r
189   IN UINT8                   Interface,\r
190   IN UINT8                   *Protocol\r
191   );\r
192 \r
193 EFI_STATUS\r
194 UsbSetProtocolRequest (\r
195   IN EFI_USB_IO_PROTOCOL     *UsbIo,\r
196   IN UINT8                   Interface,\r
197   IN UINT8                   Protocol\r
198   );\r
199 \r
200 EFI_STATUS\r
201 UsbSetIdleRequest (\r
202   IN EFI_USB_IO_PROTOCOL     *UsbIo,\r
203   IN UINT8                   Interface,\r
204   IN UINT8                   ReportId,\r
205   IN UINT8                   Duration\r
206   );\r
207 \r
208 EFI_STATUS\r
209 UsbGetIdleRequest (\r
210   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
211   IN  UINT8                   Interface,\r
212   IN  UINT8                   ReportId,\r
213   OUT UINT8                   *Duration\r
214   );\r
215 \r
216 EFI_STATUS\r
217 UsbSetReportRequest (\r
218   IN EFI_USB_IO_PROTOCOL     *UsbIo,\r
219   IN UINT8                   Interface,\r
220   IN UINT8                   ReportId,\r
221   IN UINT8                   ReportType,\r
222   IN UINT16                  ReportLen,\r
223   IN UINT8                   *Report\r
224   );\r
225 \r
226 EFI_STATUS\r
227 UsbGetReportRequest (\r
228   IN EFI_USB_IO_PROTOCOL     *UsbIo,\r
229   IN UINT8                   Interface,\r
230   IN UINT8                   ReportId,\r
231   IN UINT8                   ReportType,\r
232   IN UINT16                  ReportLen,\r
233   IN UINT8                   *Report\r
234   );\r
235 \r
236 //\r
237 // Get Device Descriptor\r
238 //\r
239 EFI_STATUS\r
240 UsbGetDescriptor (\r
241   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
242   IN  UINT16                  Value,\r
243   IN  UINT16                  Index,\r
244   IN  UINT16                  DescriptorLength,\r
245   OUT VOID                    *Descriptor,\r
246   OUT UINT32                  *Status\r
247   );\r
248 \r
249 //\r
250 // Set Device Descriptor\r
251 //\r
252 EFI_STATUS\r
253 UsbSetDescriptor (\r
254   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
255   IN  UINT16                  Value,\r
256   IN  UINT16                  Index,\r
257   IN  UINT16                  DescriptorLength,\r
258   IN  VOID                    *Descriptor,\r
259   OUT UINT32                  *Status\r
260   );\r
261 \r
262 //\r
263 // Get device Interface\r
264 //\r
265 EFI_STATUS\r
266 UsbGetDeviceInterface (\r
267   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
268   IN  UINT16                  Index,\r
269   OUT UINT8                   *AltSetting,\r
270   OUT UINT32                  *Status\r
271   );\r
272 \r
273 //\r
274 // Set device interface\r
275 //\r
276 EFI_STATUS\r
277 UsbSetDeviceInterface (\r
278   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
279   IN  UINT16                  InterfaceNo,\r
280   IN  UINT16                  AltSetting,\r
281   OUT UINT32                  *Status\r
282   );\r
283 \r
284 //\r
285 // Get device configuration\r
286 //\r
287 EFI_STATUS\r
288 UsbGetDeviceConfiguration (\r
289   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
290   OUT UINT8                   *ConfigValue,\r
291   OUT UINT32                  *Status\r
292   );\r
293 \r
294 //\r
295 // Set device configuration\r
296 //\r
297 EFI_STATUS\r
298 UsbSetDeviceConfiguration (\r
299   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
300   IN  UINT16                  Value,\r
301   OUT UINT32                  *Status\r
302   );\r
303 \r
304 //\r
305 //  Set Device Feature\r
306 //\r
307 EFI_STATUS\r
308 UsbSetDeviceFeature (\r
309   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
310   IN  EFI_USB_RECIPIENT       Recipient,\r
311   IN  UINT16                  Value,\r
312   IN  UINT16                  Target,\r
313   OUT UINT32                  *Status\r
314   );\r
315 \r
316 //\r
317 // Clear Device Feature\r
318 //\r
319 EFI_STATUS\r
320 UsbClearDeviceFeature (\r
321   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
322   IN  EFI_USB_RECIPIENT       Recipient,\r
323   IN  UINT16                  Value,\r
324   IN  UINT16                  Target,\r
325   OUT UINT32                  *Status\r
326   );\r
327 \r
328 //\r
329 //  Get Device Status\r
330 //\r
331 EFI_STATUS\r
332 UsbGetDeviceStatus (\r
333   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
334   IN  EFI_USB_RECIPIENT       Recipient,\r
335   IN  UINT16                  Target,\r
336   OUT UINT16                  *DevStatus,\r
337   OUT UINT32                  *Status\r
338   );\r
339 \r
340 //\r
341 // The following APIs are not basic library, but they are common used.\r
342 //\r
343 //\r
344 // Usb Get String\r
345 //\r
346 EFI_STATUS\r
347 UsbGetString (\r
348   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
349   IN  UINT16                  LangID,\r
350   IN  UINT8                   Index,\r
351   IN  VOID                    *Buf,\r
352   IN  UINTN                   BufSize,\r
353   OUT UINT32                  *Status\r
354   );\r
355 \r
356 //\r
357 // Clear endpoint stall\r
358 //\r
359 EFI_STATUS\r
360 UsbClearEndpointHalt (\r
361   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
362   IN  UINT8                   EndpointNo,\r
363   OUT UINT32                  *Status\r
364   );\r
365 \r
366 #endif\r