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