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