87b18fc15f7949c716ebd9b9cd0a7b982faf9e5d
[mirror_edk2.git] / MdePkg / Include / Library / UefiUsbLib.h
1 /** @file
2 Provides most usb APIs to support the Hid requests defined in Usb Hid 1.1 spec
3 and the standard requests defined in Usb 1.1 spec.
4
5 Copyright (c) 2006 - 2008, 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 /**
23 Get the descriptor of the specified USB HID interface.
24
25 Submit a USB get HID descriptor request for the USB device specified by UsbIo
26 and Interface and return the HID descriptor in HidDescriptor.
27 If UsbIo is NULL, then ASSERT().
28 If HidDescriptor is NULL, then ASSERT().
29
30 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
31 @param Interface The index of the HID interface on the USB target.
32 @param HidDescriptor Pointer to the USB HID descriptor that was retrieved from
33 the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR
34 is defined in the MDE Package Industry Standard include file Usb.h.
35
36 @retval EFI_SUCCESS The request executed successfully.
37 @retval EFI_TIMEOUT A timeout occurred executing the request.
38 @retval EFI_DEVICE_ERROR The request failed due to a device error.
39
40 **/
41 EFI_STATUS
42 EFIAPI
43 UsbGetHidDescriptor (
44 IN EFI_USB_IO_PROTOCOL *UsbIo,
45 IN UINT8 Interface,
46 OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor
47 );
48
49
50 /**
51 Get the report descriptor of the specified USB HID interface.
52
53 Submit a USB get HID report descriptor request for the USB device specified by
54 UsbIo and Interface and return the report descriptor in DescriptorBuffer.
55 If UsbIo is NULL, then ASSERT().
56 If DescriptorBuffer is NULL, then ASSERT().
57
58 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
59 @param Interface The index of the report interface on the USB target.
60 @param DescriptorLength The size, in bytes, of DescriptorBuffer.
61 @param DescriptorBuffer A pointer to the buffer to store the report class descriptor.
62
63 @retval EFI_SUCCESS The request executed successfully.
64 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
65 buffer specified by DescriptorLength and DescriptorBuffer
66 is not large enough to hold the result of the request.
67 @retval EFI_TIMEOUT A timeout occurred executing the request.
68 @retval EFI_DEVICE_ERROR The request failed due to a device error.
69
70 **/
71 EFI_STATUS
72 EFIAPI
73 UsbGetReportDescriptor (
74 IN EFI_USB_IO_PROTOCOL *UsbIo,
75 IN UINT8 Interface,
76 IN UINT16 DescriptorLength,
77 OUT UINT8 *DescriptorBuffer
78 );
79
80 /**
81 Get the HID protocol of the specified USB HID interface.
82
83 Submit a USB get HID protocol request for the USB device specified by UsbIo
84 and Interface and return the protocol retrieved in Protocol.
85 If UsbIo is NULL, then ASSERT().
86 If Protocol is NULL, then ASSERT().
87
88 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
89 @param Interface The index of the report interface on the USB target.
90 @param Protocol A pointer to the protocol for the specified USB target.
91
92 @retval EFI_SUCCESS The request executed successfully.
93 @retval EFI_TIMEOUT A timeout occurred executing the request.
94 @retval EFI_DEVICE_ERROR The request failed due to a device error.
95
96 **/
97 EFI_STATUS
98 EFIAPI
99 UsbGetProtocolRequest (
100 IN EFI_USB_IO_PROTOCOL *UsbIo,
101 IN UINT8 Interface,
102 OUT UINT8 *Protocol
103 );
104
105 /**
106 Set the HID protocol of the specified USB HID interface.
107
108 Submit a USB set HID protocol request for the USB device specified by UsbIo
109 and Interface and set the protocol to the value specified by Protocol.
110 If UsbIo is NULL, then ASSERT().
111
112 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
113 @param Interface The index of the report interface on the USB target.
114 @param Protocol The protocol value to set for the specified USB target.
115
116 @retval EFI_SUCCESS The request executed successfully.
117 @retval EFI_TIMEOUT A timeout occurred executing the request.
118 @retval EFI_DEVICE_ERROR The request failed due to a device error.
119
120 **/
121 EFI_STATUS
122 EFIAPI
123 UsbSetProtocolRequest (
124 IN EFI_USB_IO_PROTOCOL *UsbIo,
125 IN UINT8 Interface,
126 IN UINT8 Protocol
127 );
128
129 /**
130 Set the idle rate of the specified USB HID report.
131
132 Submit a USB set HID report idle request for the USB device specified by UsbIo,
133 Interface, and ReportId, and set the idle rate to the value specified by Duration.
134 If UsbIo is NULL, then ASSERT().
135
136 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
137 @param Interface The index of the report interface on the USB target.
138 @param ReportId The identifier of the report to retrieve.
139 @param Duration The idle rate to set for the specified USB target.
140
141 @retval EFI_SUCCESS The request executed successfully.
142 @retval EFI_TIMEOUT A timeout occurred executing the request.
143 @retval EFI_DEVICE_ERROR The request failed due to a device error.
144
145 **/
146 EFI_STATUS
147 EFIAPI
148 UsbSetIdleRequest (
149 IN EFI_USB_IO_PROTOCOL *UsbIo,
150 IN UINT8 Interface,
151 IN UINT8 ReportId,
152 IN UINT8 Duration
153 );
154
155 /**
156 Get the idle rate of the specified USB HID report.
157
158 Submit a USB get HID report idle request for the USB device specified by UsbIo,
159 Interface, and ReportId, and return the ide rate in Duration.
160 If UsbIo is NULL, then ASSERT().
161 If Duration is NULL, then ASSERT().
162
163 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
164 @param Interface The index of the report interface on the USB target.
165 @param ReportId The identifier of the report to retrieve.
166 @param Duration A pointer to the idle rate retrieved from the specified USB target.
167
168 @retval EFI_SUCCESS The request executed successfully.
169 @retval EFI_TIMEOUT A timeout occurred executing the request.
170 @retval EFI_DEVICE_ERROR The request failed due to a device error.
171
172 **/
173 EFI_STATUS
174 EFIAPI
175 UsbGetIdleRequest (
176 IN EFI_USB_IO_PROTOCOL *UsbIo,
177 IN UINT8 Interface,
178 IN UINT8 ReportId,
179 OUT UINT8 *Duration
180 );
181
182 /**
183 Set the report descriptor of the specified USB HID interface.
184
185 Submit a USB set HID report request for the USB device specified by UsbIo,
186 Interface, ReportId, and ReportType, and set the report descriptor using the
187 buffer specified by ReportLength and Report.
188 If UsbIo is NULL, then ASSERT().
189 If Report is NULL, then ASSERT().
190
191 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
192 @param Interface The index of the report interface on the USB target.
193 @param ReportId The identifier of the report to retrieve.
194 @param ReportType The type of report to retrieve.
195 @param ReportLength The size, in bytes, of Report.
196 @param Report A pointer to the report descriptor buffer to set.
197
198 @retval EFI_SUCCESS The request executed successfully.
199 @retval EFI_TIMEOUT A timeout occurred executing the request.
200 @retval EFI_DEVICE_ERROR The request failed due to a device error.
201
202 **/
203 EFI_STATUS
204 EFIAPI
205 UsbSetReportRequest (
206 IN EFI_USB_IO_PROTOCOL *UsbIo,
207 IN UINT8 Interface,
208 IN UINT8 ReportId,
209 IN UINT8 ReportType,
210 IN UINT16 ReportLen,
211 IN UINT8 *Report
212 );
213
214 /**
215 Get the report descriptor of the specified USB HID interface.
216
217 Submit a USB get HID report request for the USB device specified by UsbIo,
218 Interface, ReportId, and ReportType, and return the report in the buffer
219 specified by Report.
220 If UsbIo is NULL, then ASSERT().
221 If Report is NULL, then ASSERT().
222
223 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
224 @param Interface The index of the report interface on the USB target.
225 @param ReportId The identifier of the report to retrieve.
226 @param ReportType The type of report to retrieve.
227 @param ReportLength The size, in bytes, of Report.
228 @param Report A pointer to the buffer to store the report descriptor.
229
230 @retval EFI_SUCCESS The request executed successfully.
231 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
232 buffer specified by ReportLength and Report is not
233 large enough to hold the result of the request.
234 @retval EFI_TIMEOUT A timeout occurred executing the request.
235 @retval EFI_DEVICE_ERROR The request failed due to a device error.
236
237 **/
238 EFI_STATUS
239 EFIAPI
240 UsbGetReportRequest (
241 IN EFI_USB_IO_PROTOCOL *UsbIo,
242 IN UINT8 Interface,
243 IN UINT8 ReportId,
244 IN UINT8 ReportType,
245 IN UINT16 ReportLen,
246 OUT UINT8 *Report
247 );
248
249 /**
250 Get the descriptor of the specified USB device.
251
252 Submit a USB get descriptor request for the USB device specified by UsbIo, Value,
253 and Index, and return the descriptor in the buffer specified by Descriptor.
254 The status of the transfer is returned in Status.
255 If UsbIo is NULL, then ASSERT().
256 If Descriptor is NULL, then ASSERT().
257 If Status is NULL, then ASSERT().
258
259 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
260 @param Value The device request value.
261 @param Index The device request index.
262 @param DescriptorLength The size, in bytes, of Descriptor.
263 @param Descriptor A pointer to the descriptor buffer to get.
264 @param Status A pointer to the status of the transfer.
265
266 @retval EFI_SUCCESS The request executed successfully.
267 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
268 buffer specified by DescriptorLength and Descriptor
269 is not large enough to hold the result of the request.
270 @retval EFI_TIMEOUT A timeout occurred executing the request.
271 @retval EFI_DEVICE_ERROR The request failed due to a device error. The transfer
272 status is returned in Status.
273
274 **/
275 EFI_STATUS
276 EFIAPI
277 UsbGetDescriptor (
278 IN EFI_USB_IO_PROTOCOL *UsbIo,
279 IN UINT16 Value,
280 IN UINT16 Index,
281 IN UINT16 DescriptorLength,
282 OUT VOID *Descriptor,
283 OUT UINT32 *Status
284 );
285
286 /**
287 Set the descriptor of the specified USB device.
288
289 Submit a USB set descriptor request for the USB device specified by UsbIo,
290 Value, and Index, and set the descriptor using the buffer specified by DesriptorLength
291 and Descriptor. The status of the transfer is returned in Status.
292 If UsbIo is NULL, then ASSERT().
293 If Descriptor is NULL, then ASSERT().
294 If Status is NULL, then ASSERT().
295
296 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
297 @param Value The device request value.
298 @param Index The device request index.
299 @param DescriptorLength The size, in bytes, of Descriptor.
300 @param Descriptor A pointer to the descriptor buffer to set.
301 @param Status A pointer to the status of the transfer.
302
303 @retval EFI_SUCCESS The request executed successfully.
304 @retval EFI_TIMEOUT A timeout occurred executing the request.
305 @retval EFI_DEVICE_ERROR The request failed due to a device error.
306 The transfer status is returned in Status.
307
308 **/
309 EFI_STATUS
310 EFIAPI
311 UsbSetDescriptor (
312 IN EFI_USB_IO_PROTOCOL *UsbIo,
313 IN UINT16 Value,
314 IN UINT16 Index,
315 IN UINT16 DescriptorLength,
316 IN VOID *Descriptor,
317 OUT UINT32 *Status
318 );
319
320 /**
321 Get the interface setting of the specified USB device.
322
323 Submit a USB get interface request for the USB device specified by UsbIo,
324 and Interface, and place the result in the buffer specified by AlternateSetting.
325 The status of the transfer is returned in Status.
326 If UsbIo is NULL, then ASSERT().
327 If AlternateSetting is NULL, then ASSERT().
328 If Status is NULL, then ASSERT().
329
330 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
331 @param Interface The interface index value.
332 @param AlternateSetting A pointer to the alternate setting to be retrieved.
333 @param Status A pointer to the status of the transfer.
334
335 @retval EFI_SUCCESS The request executed successfully.
336 @retval EFI_TIMEOUT A timeout occurred executing the request.
337 @retval EFI_DEVICE_ERROR The request failed due to a device error.
338 The transfer status is returned in Status.
339
340 **/
341 EFI_STATUS
342 EFIAPI
343 UsbGetInterface (
344 IN EFI_USB_IO_PROTOCOL *UsbIo,
345 IN UINT16 Interface,
346 OUT UINT16 *AlternateSetting,
347 OUT UINT32 *Status
348 );
349
350 /**
351 Set the interface setting of the specified USB device.
352
353 Submit a USB set interface request for the USB device specified by UsbIo, and
354 Interface, and set the alternate setting to the value specified by AlternateSetting.
355 The status of the transfer is returned in Status.
356 If UsbIo is NULL, then ASSERT().
357 If Status is NULL, then ASSERT().
358
359 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
360 @param Interface The interface index value.
361 @param AlternateSetting The alternate setting to be set.
362 @param Status A pointer to the status of the transfer.
363
364 @retval EFI_SUCCESS The request executed successfully.
365 @retval EFI_TIMEOUT A timeout occurred executing the request.
366 @retval EFI_SUCCESS The request failed due to a device error.
367 The transfer status is returned in Status.
368
369 **/
370 EFI_STATUS
371 EFIAPI
372 UsbSetInterface (
373 IN EFI_USB_IO_PROTOCOL *UsbIo,
374 IN UINT16 Interface,
375 IN UINT16 AlternateSetting,
376 OUT UINT32 *Status
377 );
378
379 /**
380 Get the device configuration.
381
382 Submit a USB get configuration request for the USB device specified by UsbIo
383 and place the result in the buffer specified by ConfigurationValue. The status
384 of the transfer is returned in Status.
385 If UsbIo is NULL, then ASSERT().
386 If ConfigurationValue is NULL, then ASSERT().
387 If Status is NULL, then ASSERT().
388
389 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
390 @param ConfigurationValue A pointer to the device configuration to be retrieved.
391 @param Status A pointer to the status of the transfer.
392
393 @retval EFI_SUCCESS The request executed successfully.
394 @retval EFI_TIMEOUT A timeout occurred executing the request.
395 @retval EFI_DEVICE_ERROR The request failed due to a device error.
396 The transfer status is returned in Status.
397
398 **/
399 EFI_STATUS
400 EFIAPI
401 UsbGetConfiguration (
402 IN EFI_USB_IO_PROTOCOL *UsbIo,
403 OUT UINT16 *ConfigurationValue,
404 OUT UINT32 *Status
405 );
406
407 /**
408 Set the device configuration.
409
410 Submit a USB set configuration request for the USB device specified by UsbIo
411 and set the device configuration to the value specified by ConfigurationValue.
412 The status of the transfer is returned in Status.
413 If UsbIo is NULL, then ASSERT().
414 If Status is NULL, then ASSERT().
415
416 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
417 @param ConfigurationValue The device configuration value to be set.
418 @param Status A pointer to the status of the transfer.
419
420 @retval EFI_SUCCESS The request executed successfully.
421 @retval EFI_TIMEOUT A timeout occurred executing the request.
422 @retval EFI_DEVICE_ERROR The request failed due to a device error.
423 The transfer status is returned in Status.
424
425 **/
426 EFI_STATUS
427 EFIAPI
428 UsbSetConfiguration (
429 IN EFI_USB_IO_PROTOCOL *UsbIo,
430 IN UINT16 ConfigurationValue,
431 OUT UINT32 *Status
432 );
433
434 /**
435 Set the specified feature of the specified device.
436
437 Submit a USB set device feature request for the USB device specified by UsbIo,
438 Recipient, and Target to the value specified by Value. The status of the
439 transfer is returned in Status.
440 If UsbIo is NULL, then ASSERT().
441 If Status is NULL, then ASSERT().
442
443 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
444 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint).
445 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry
446 Standard include file Usb.h.
447 @param Value The value of the feature to be set.
448 @param Target The index of the device to be set.
449 @param Status A pointer to the status of the transfer.
450
451 @retval EFI_SUCCESS The request executed successfully.
452 @retval EFI_TIMEOUT A timeout occurred executing the request.
453 @retval EFI_DEVICE_ERROR The request failed due to a device error.
454 The transfer status is returned in Status.
455
456 **/
457 EFI_STATUS
458 EFIAPI
459 UsbSetFeature (
460 IN EFI_USB_IO_PROTOCOL *UsbIo,
461 IN USB_TYPES_DEFINITION Recipient,
462 IN UINT16 Value,
463 IN UINT16 Target,
464 OUT UINT32 *Status
465 );
466
467 /**
468 Clear the specified feature of the specified device.
469
470 Submit a USB clear device feature request for the USB device specified by UsbIo,
471 Recipient, and Target to the value specified by Value. The status of the transfer
472 is returned in Status.
473 If UsbIo is NULL, then ASSERT().
474 If Status is NULL, then ASSERT().
475
476 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
477 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint).
478 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard
479 include file Usb.h.
480 @param Value The value of the feature to be cleared.
481 @param Target The index of the device to be cleared.
482 @param Status A pointer to the status of the transfer.
483
484 @retval EFI_SUCCESS The request executed successfully.
485 @retval EFI_TIMEOUT A timeout occurred executing the request.
486 @retval EFI_DEVICE_ERROR The request failed due to a device error.
487 The transfer status is returned in Status.
488
489 **/
490 EFI_STATUS
491 EFIAPI
492 UsbClearFeature (
493 IN EFI_USB_IO_PROTOCOL *UsbIo,
494 IN USB_TYPES_DEFINITION Recipient,
495 IN UINT16 Value,
496 IN UINT16 Target,
497 OUT UINT32 *Status
498 );
499
500 /**
501 Get the status of the specified device.
502
503 Submit a USB device get status request for the USB device specified by UsbIo,
504 Recipient, and Target and place the result in the buffer specified by DeviceStatus.
505 The status of the transfer is returned in Status.
506 If UsbIo is NULL, then ASSERT().
507 If DeviceStatus is NULL, then ASSERT().
508 If Status is NULL, then ASSERT().
509
510 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
511 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint).
512 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard
513 include file Usb.h.
514 @param Target The index of the device to be get the status of.
515 @param DeviceStatus A pointer to the device status to be retrieved.
516 @param Status A pointer to the status of the transfer.
517
518 @retval EFI_SUCCESS The request executed successfully.
519 @retval EFI_TIMEOUT A timeout occurred executing the request.
520 @retval EFI_DEVICE_ERROR The request failed due to a device error.
521 The transfer status is returned in Status.
522
523 **/
524 EFI_STATUS
525 EFIAPI
526 UsbGetStatus (
527 IN EFI_USB_IO_PROTOCOL *UsbIo,
528 IN USB_TYPES_DEFINITION Recipient,
529 IN UINT16 Target,
530 OUT UINT16 *DeviceStatus,
531 OUT UINT32 *Status
532 );
533
534 /**
535 Clear halt feature of the specified usb endpoint.
536
537 Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint.
538 If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND.
539 If the endpoint descriptor is found, then clear the halt feature of this USB endpoint.
540 The status of the transfer is returned in Status.
541 If UsbIo is NULL, then ASSERT().
542 If Status is NULL, then ASSERT().
543
544 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
545 @param Endpoint The endpoint address.
546 @param Status A pointer to the status of the transfer.
547
548 @retval EFI_SUCCESS The request executed successfully.
549 @retval EFI_TIMEOUT A timeout occurred executing the request.
550 @retval EFI_DEVICE_ERROR The request failed due to a device error.
551 The transfer status is returned in Status.
552 @retval EFI_NOT_FOUND The specified USB endpoint descriptor can not be found
553
554 **/
555 EFI_STATUS
556 EFIAPI
557 UsbClearEndpointHalt (
558 IN EFI_USB_IO_PROTOCOL *UsbIo,
559 IN UINT8 Endpoint,
560 OUT UINT32 *Status
561 );
562
563 #endif