1438328c9bdc2450fa7a2d0088c088b37751f651
[mirror_edk2.git] / MdePkg / Include / Library / UsbLib.h
1 /** @file
2 Common Dxe Libarary for USB
3
4 Copyright (c) 2006, Intel Corporation<BR>
5 All rights reserved. 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
16 #ifndef __USB_DXE_LIB_H__
17 #define __USB_DXE_LIB_H__
18
19 #include <Protocol/UsbIo.h>
20
21 //
22 // Standard device request and request type
23 // By [Spec-USB20/Chapter-9.4]
24 //
25 #define USB_DEV_GET_STATUS 0x00
26 #define USB_DEV_GET_STATUS_REQ_TYPE_D 0x80 // Receiver : Device
27 #define USB_DEV_GET_STATUS_REQ_TYPE_I 0x81 // Receiver : Interface
28 #define USB_DEV_GET_STATUS_REQ_TYPE_E 0x82 // Receiver : Endpoint
29
30 #define USB_DEV_CLEAR_FEATURE 0x01
31 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device
32 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface
33 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint
34
35 #define USB_DEV_SET_FEATURE 0x03
36 #define USB_DEV_SET_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device
37 #define USB_DEV_SET_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface
38 #define USB_DEV_SET_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint
39
40 #define USB_DEV_SET_ADDRESS 0x05
41 #define USB_DEV_SET_ADDRESS_REQ_TYPE 0x00
42
43 #define USB_DEV_GET_DESCRIPTOR 0x06
44 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE 0x80
45
46 #define USB_DEV_SET_DESCRIPTOR 0x07
47 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE 0x00
48
49 #define USB_DEV_GET_CONFIGURATION 0x08
50 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE 0x80
51
52 #define USB_DEV_SET_CONFIGURATION 0x09
53 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE 0x00
54
55 #define USB_DEV_GET_INTERFACE 0x0A
56 #define USB_DEV_GET_INTERFACE_REQ_TYPE 0x81
57
58 #define USB_DEV_SET_INTERFACE 0x0B
59 #define USB_DEV_SET_INTERFACE_REQ_TYPE 0x01
60
61 #define USB_DEV_SYNCH_FRAME 0x0C
62 #define USB_DEV_SYNCH_FRAME_REQ_TYPE 0x82
63
64 //
65 // define the timeout time as 3ms
66 //
67 #define TIMEOUT_VALUE 3 * 1000
68
69 //
70 // HID constants definition, see HID rev1.0
71 //
72 //
73 // HID report item format
74 //
75 #define HID_ITEM_FORMAT_SHORT 0
76 #define HID_ITEM_FORMAT_LONG 1
77
78 //
79 // Special tag indicating long items
80 //
81 #define HID_ITEM_TAG_LONG 15
82
83 //
84 // HID report descriptor item type (prefix bit 2,3)
85 //
86 #define HID_ITEM_TYPE_MAIN 0
87 #define HID_ITEM_TYPE_GLOBAL 1
88 #define HID_ITEM_TYPE_LOCAL 2
89 #define HID_ITEM_TYPE_RESERVED 3
90
91 //
92 // HID report descriptor main item tags
93 //
94 #define HID_MAIN_ITEM_TAG_INPUT 8
95 #define HID_MAIN_ITEM_TAG_OUTPUT 9
96 #define HID_MAIN_ITEM_TAG_FEATURE 11
97 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION 10
98 #define HID_MAIN_ITEM_TAG_END_COLLECTION 12
99
100 //
101 // HID report descriptor main item contents
102 //
103 #define HID_MAIN_ITEM_CONSTANT 0x001
104 #define HID_MAIN_ITEM_VARIABLE 0x002
105 #define HID_MAIN_ITEM_RELATIVE 0x004
106 #define HID_MAIN_ITEM_WRAP 0x008
107 #define HID_MAIN_ITEM_NONLINEAR 0x010
108 #define HID_MAIN_ITEM_NO_PREFERRED 0x020
109 #define HID_MAIN_ITEM_NULL_STATE 0x040
110 #define HID_MAIN_ITEM_VOLATILE 0x080
111 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100
112
113 //
114 // HID report descriptor collection item types
115 //
116 #define HID_COLLECTION_PHYSICAL 0
117 #define HID_COLLECTION_APPLICATION 1
118 #define HID_COLLECTION_LOGICAL 2
119
120 //
121 // HID report descriptor global item tags
122 //
123 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE 0
124 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM 1
125 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM 2
126 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM 3
127 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM 4
128 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT 5
129 #define HID_GLOBAL_ITEM_TAG_UNIT 6
130 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE 7
131 #define HID_GLOBAL_ITEM_TAG_REPORT_ID 8
132 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT 9
133 #define HID_GLOBAL_ITEM_TAG_PUSH 10
134 #define HID_GLOBAL_ITEM_TAG_POP 11
135
136 //
137 // HID report descriptor local item tags
138 //
139 #define HID_LOCAL_ITEM_TAG_USAGE 0
140 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM 1
141 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM 2
142 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX 3
143 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4
144 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5
145 #define HID_LOCAL_ITEM_TAG_STRING_INDEX 7
146 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM 8
147 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM 9
148 #define HID_LOCAL_ITEM_TAG_DELIMITER 10
149
150 //
151 // HID usage tables
152 //
153 #define HID_USAGE_PAGE 0xffff0000
154
155 #define HID_UP_GENDESK 0x00010000
156 #define HID_UP_KEYBOARD 0x00070000
157 #define HID_UP_LED 0x00080000
158 #define HID_UP_BUTTON 0x00090000
159 #define HID_UP_CONSUMER 0x000c0000
160 #define HID_UP_DIGITIZER 0x000d0000
161 #define HID_UP_PID 0x000f0000
162
163 #define HID_USAGE 0x0000ffff
164
165 #define HID_GD_POINTER 0x00010001
166 #define HID_GD_MOUSE 0x00010002
167 #define HID_GD_JOYSTICK 0x00010004
168 #define HID_GD_GAMEPAD 0x00010005
169 #define HID_GD_HATSWITCH 0x00010039
170
171 //
172 // HID report types
173 //
174 #define HID_INPUT_REPORT 1
175 #define HID_OUTPUT_REPORT 2
176 #define HID_FEATURE_REPORT 3
177
178 //
179 // HID device quirks.
180 //
181 #define HID_QUIRK_INVERT 0x01
182 #define HID_QUIRK_NOTOUCH 0x02
183
184 //
185 // HID class protocol request
186 //
187 #define EFI_USB_GET_REPORT_REQUEST 0x01
188 #define EFI_USB_GET_IDLE_REQUEST 0x02
189 #define EFI_USB_GET_PROTOCOL_REQUEST 0x03
190 #define EFI_USB_SET_REPORT_REQUEST 0x09
191 #define EFI_USB_SET_IDLE_REQUEST 0x0a
192 #define EFI_USB_SET_PROTOCOL_REQUEST 0x0b
193
194 #pragma pack(1)
195 //
196 // Descriptor header for Report/Physical Descriptors
197 //
198 typedef struct hid_class_descriptor {
199 UINT8 DescriptorType;
200 UINT16 DescriptorLength;
201 } EFI_USB_HID_CLASS_DESCRIPTOR;
202
203 typedef struct hid_descriptor {
204 UINT8 Length;
205 UINT8 DescriptorType;
206 UINT16 BcdHID;
207 UINT8 CountryCode;
208 UINT8 NumDescriptors;
209 EFI_USB_HID_CLASS_DESCRIPTOR HidClassDesc[1];
210 } EFI_USB_HID_DESCRIPTOR;
211
212 #pragma pack()
213
214 EFI_STATUS
215 UsbGetHidDescriptor (
216 IN EFI_USB_IO_PROTOCOL *UsbIo,
217 IN UINT8 InterfaceNum,
218 OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor
219 );
220
221 EFI_STATUS
222 UsbGetReportDescriptor (
223 IN EFI_USB_IO_PROTOCOL *UsbIo,
224 IN UINT8 InterfaceNum,
225 IN UINT16 DescriptorSize,
226 OUT UINT8 *DescriptorBuffer
227 );
228
229 EFI_STATUS
230 UsbGetProtocolRequest (
231 IN EFI_USB_IO_PROTOCOL *UsbIo,
232 IN UINT8 Interface,
233 IN UINT8 *Protocol
234 );
235
236 EFI_STATUS
237 UsbSetProtocolRequest (
238 IN EFI_USB_IO_PROTOCOL *UsbIo,
239 IN UINT8 Interface,
240 IN UINT8 Protocol
241 );
242
243 EFI_STATUS
244 UsbSetIdleRequest (
245 IN EFI_USB_IO_PROTOCOL *UsbIo,
246 IN UINT8 Interface,
247 IN UINT8 ReportId,
248 IN UINT8 Duration
249 );
250
251 EFI_STATUS
252 UsbGetIdleRequest (
253 IN EFI_USB_IO_PROTOCOL *UsbIo,
254 IN UINT8 Interface,
255 IN UINT8 ReportId,
256 OUT UINT8 *Duration
257 );
258
259 EFI_STATUS
260 UsbSetReportRequest (
261 IN EFI_USB_IO_PROTOCOL *UsbIo,
262 IN UINT8 Interface,
263 IN UINT8 ReportId,
264 IN UINT8 ReportType,
265 IN UINT16 ReportLen,
266 IN UINT8 *Report
267 );
268
269 EFI_STATUS
270 UsbGetReportRequest (
271 IN EFI_USB_IO_PROTOCOL *UsbIo,
272 IN UINT8 Interface,
273 IN UINT8 ReportId,
274 IN UINT8 ReportType,
275 IN UINT16 ReportLen,
276 IN UINT8 *Report
277 );
278
279 typedef enum {
280 EfiUsbEndpointHalt,
281 EfiUsbDeviceRemoteWakeup
282 } EFI_USB_STANDARD_FEATURE_SELECTOR;
283
284 EFI_STATUS
285 UsbGetDescriptor (
286 IN EFI_USB_IO_PROTOCOL *UsbIo,
287 IN UINT16 Value,
288 IN UINT16 Index,
289 IN UINT16 DescriptorLength,
290 OUT VOID *Descriptor,
291 OUT UINT32 *Status
292 );
293
294 EFI_STATUS
295 UsbSetDescriptor (
296 IN EFI_USB_IO_PROTOCOL *UsbIo,
297 IN UINT16 Value,
298 IN UINT16 Index,
299 IN UINT16 DescriptorLength,
300 IN VOID *Descriptor,
301 OUT UINT32 *Status
302 );
303
304 EFI_STATUS
305 UsbGetInterface (
306 IN EFI_USB_IO_PROTOCOL *UsbIo,
307 IN UINT16 Index,
308 OUT UINT8 *AltSetting,
309 OUT UINT32 *Status
310 );
311
312 EFI_STATUS
313 UsbSetInterface (
314 IN EFI_USB_IO_PROTOCOL *UsbIo,
315 IN UINT16 InterfaceNo,
316 IN UINT16 AltSetting,
317 OUT UINT32 *Status
318 );
319
320 EFI_STATUS
321 UsbGetConfiguration (
322 IN EFI_USB_IO_PROTOCOL *UsbIo,
323 OUT UINT8 *ConfigValue,
324 OUT UINT32 *Status
325 );
326
327 EFI_STATUS
328 UsbSetConfiguration (
329 IN EFI_USB_IO_PROTOCOL *UsbIo,
330 IN UINT16 Value,
331 OUT UINT32 *Status
332 );
333
334 EFI_STATUS
335 UsbSetFeature (
336 IN EFI_USB_IO_PROTOCOL *UsbIo,
337 IN UINTN Recipient,
338 IN UINT16 Value,
339 IN UINT16 Target,
340 OUT UINT32 *Status
341 );
342
343 EFI_STATUS
344 UsbClearFeature (
345 IN EFI_USB_IO_PROTOCOL *UsbIo,
346 IN UINTN Recipient,
347 IN UINT16 Value,
348 IN UINT16 Target,
349 OUT UINT32 *Status
350 );
351
352 EFI_STATUS
353 UsbGetStatus (
354 IN EFI_USB_IO_PROTOCOL *UsbIo,
355 IN UINTN Recipient,
356 IN UINT16 Target,
357 OUT UINT16 *DevStatus,
358 OUT UINT32 *Status
359 );
360
361 EFI_STATUS
362 UsbGetHubDescriptor (
363 IN EFI_USB_IO_PROTOCOL *UsbIo,
364 IN UINT16 Value,
365 IN UINT16 Index,
366 IN UINT16 DescriptorLength,
367 OUT VOID *Descriptor,
368 OUT UINT32 *Status
369 );
370
371 //
372 // Clear endpoint stall
373 //
374 EFI_STATUS
375 UsbClearEndpointHalt (
376 IN EFI_USB_IO_PROTOCOL *UsbIo,
377 IN UINT8 EndpointNo,
378 OUT UINT32 *Status
379 );
380
381 #endif