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