3 The library provides the USB Standard Device Requests defined
4 in Usb specification 9.4 section.
6 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
7 This program and the accompanying materials are
8 licensed and made available under the terms and conditions of
9 the BSD License which accompanies this distribution. The full
10 text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php.
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #include "UefiUsbLibInternal.h"
22 Get the descriptor of the specified USB device.
24 Submit a USB get descriptor request for the USB device specified by UsbIo, Value,
25 and Index, and return the descriptor in the buffer specified by Descriptor.
26 The status of the transfer is returned in Status.
27 If UsbIo is NULL, then ASSERT().
28 If Descriptor is NULL, then ASSERT().
29 If Status is NULL, then ASSERT().
31 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
32 @param Value The device request value.
33 @param Index The device request index.
34 @param DescriptorLength The size, in bytes, of Descriptor.
35 @param Descriptor A pointer to the descriptor buffer to get.
36 @param Status A pointer to the status of the transfer.
38 @retval EFI_SUCCESS The request executed successfully.
39 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
40 buffer specified by DescriptorLength and Descriptor
41 is not large enough to hold the result of the request.
42 @retval EFI_TIMEOUT A timeout occurred executing the request.
43 @retval EFI_DEVICE_ERROR The request failed due to a device error. The transfer
44 status is returned in Status.
50 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
53 IN UINT16 DescriptorLength
,
58 EFI_USB_DEVICE_REQUEST DevReq
;
60 ASSERT (UsbIo
!= NULL
);
61 ASSERT (Descriptor
!= NULL
);
62 ASSERT (Status
!= NULL
);
64 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
66 DevReq
.RequestType
= USB_DEV_GET_DESCRIPTOR_REQ_TYPE
;
67 DevReq
.Request
= USB_REQ_GET_DESCRIPTOR
;
70 DevReq
.Length
= DescriptorLength
;
72 return UsbIo
->UsbControlTransfer (
76 PcdGet32 (PcdUsbTransferTimeoutValue
),
85 Set the descriptor of the specified USB device.
87 Submit a USB set descriptor request for the USB device specified by UsbIo,
88 Value, and Index, and set the descriptor using the buffer specified by DesriptorLength
89 and Descriptor. The status of the transfer is returned in Status.
90 If UsbIo is NULL, then ASSERT().
91 If Descriptor is NULL, then ASSERT().
92 If Status is NULL, then ASSERT().
94 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
95 @param Value The device request value.
96 @param Index The device request index.
97 @param DescriptorLength The size, in bytes, of Descriptor.
98 @param Descriptor A pointer to the descriptor buffer to set.
99 @param Status A pointer to the status of the transfer.
101 @retval EFI_SUCCESS The request executed successfully.
102 @retval EFI_TIMEOUT A timeout occurred executing the request.
103 @retval EFI_DEVICE_ERROR The request failed due to a device error.
104 The transfer status is returned in Status.
110 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
113 IN UINT16 DescriptorLength
,
118 EFI_USB_DEVICE_REQUEST DevReq
;
120 ASSERT (UsbIo
!= NULL
);
121 ASSERT (Descriptor
!= NULL
);
122 ASSERT (Status
!= NULL
);
124 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
126 DevReq
.RequestType
= USB_DEV_SET_DESCRIPTOR_REQ_TYPE
;
127 DevReq
.Request
= USB_REQ_SET_DESCRIPTOR
;
128 DevReq
.Value
= Value
;
129 DevReq
.Index
= Index
;
130 DevReq
.Length
= DescriptorLength
;
132 return UsbIo
->UsbControlTransfer (
136 PcdGet32 (PcdUsbTransferTimeoutValue
),
145 Get the interface setting of the specified USB device.
147 Submit a USB get interface request for the USB device specified by UsbIo,
148 and Interface, and place the result in the buffer specified by AlternateSetting.
149 The status of the transfer is returned in Status.
150 If UsbIo is NULL, then ASSERT().
151 If AlternateSetting is NULL, then ASSERT().
152 If Status is NULL, then ASSERT().
154 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
155 @param Interface The interface index value.
156 @param AlternateSetting A pointer to the alternate setting to be retrieved.
157 @param Status A pointer to the status of the transfer.
159 @retval EFI_SUCCESS The request executed successfully.
160 @retval EFI_TIMEOUT A timeout occurred executing the request.
161 @retval EFI_DEVICE_ERROR The request failed due to a device error.
162 The transfer status is returned in Status.
168 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
170 OUT UINT16
*AlternateSetting
,
174 EFI_USB_DEVICE_REQUEST DevReq
;
176 ASSERT (UsbIo
!= NULL
);
177 ASSERT (AlternateSetting
!= NULL
);
178 ASSERT (Status
!= NULL
);
180 *AlternateSetting
= 0;
182 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
184 DevReq
.RequestType
= USB_DEV_GET_INTERFACE_REQ_TYPE
;
185 DevReq
.Request
= USB_REQ_GET_INTERFACE
;
186 DevReq
.Index
= Interface
;
189 return UsbIo
->UsbControlTransfer (
193 PcdGet32 (PcdUsbTransferTimeoutValue
),
202 Set the interface setting of the specified USB device.
204 Submit a USB set interface request for the USB device specified by UsbIo, and
205 Interface, and set the alternate setting to the value specified by AlternateSetting.
206 The status of the transfer is returned in Status.
207 If UsbIo is NULL, then ASSERT().
208 If Status is NULL, then ASSERT().
210 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
211 @param Interface The interface index value.
212 @param AlternateSetting The alternate setting to be set.
213 @param Status A pointer to the status of the transfer.
215 @retval EFI_SUCCESS The request executed successfully.
216 @retval EFI_TIMEOUT A timeout occurred executing the request.
217 @retval EFI_SUCCESS The request failed due to a device error.
218 The transfer status is returned in Status.
224 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
226 IN UINT16 AlternateSetting
,
230 EFI_USB_DEVICE_REQUEST DevReq
;
232 ASSERT (UsbIo
!= NULL
);
233 ASSERT (Status
!= NULL
);
235 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
237 DevReq
.RequestType
= USB_DEV_SET_INTERFACE_REQ_TYPE
;
238 DevReq
.Request
= USB_REQ_SET_INTERFACE
;
239 DevReq
.Value
= AlternateSetting
;
240 DevReq
.Index
= Interface
;
242 return UsbIo
->UsbControlTransfer (
246 PcdGet32 (PcdUsbTransferTimeoutValue
),
255 Get the device configuration.
257 Submit a USB get configuration request for the USB device specified by UsbIo
258 and place the result in the buffer specified by ConfigurationValue. The status
259 of the transfer is returned in Status.
260 If UsbIo is NULL, then ASSERT().
261 If ConfigurationValue is NULL, then ASSERT().
262 If Status is NULL, then ASSERT().
264 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
265 @param ConfigurationValue A pointer to the device configuration to be retrieved.
266 @param Status A pointer to the status of the transfer.
268 @retval EFI_SUCCESS The request executed successfully.
269 @retval EFI_TIMEOUT A timeout occurred executing the request.
270 @retval EFI_DEVICE_ERROR The request failed due to a device error.
271 The transfer status is returned in Status.
276 UsbGetConfiguration (
277 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
278 OUT UINT16
*ConfigurationValue
,
282 EFI_USB_DEVICE_REQUEST DevReq
;
284 ASSERT (UsbIo
!= NULL
);
285 ASSERT (ConfigurationValue
!= NULL
);
286 ASSERT (Status
!= NULL
);
288 *ConfigurationValue
= 0;
290 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
292 DevReq
.RequestType
= USB_DEV_GET_CONFIGURATION_REQ_TYPE
;
293 DevReq
.Request
= USB_REQ_GET_CONFIG
;
296 return UsbIo
->UsbControlTransfer (
300 PcdGet32 (PcdUsbTransferTimeoutValue
),
309 Set the device configuration.
311 Submit a USB set configuration request for the USB device specified by UsbIo
312 and set the device configuration to the value specified by ConfigurationValue.
313 The status of the transfer is returned in Status.
314 If UsbIo is NULL, then ASSERT().
315 If Status is NULL, then ASSERT().
317 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
318 @param ConfigurationValue The device configuration value to be set.
319 @param Status A pointer to the status of the transfer.
321 @retval EFI_SUCCESS The request executed successfully.
322 @retval EFI_TIMEOUT A timeout occurred executing the request.
323 @retval EFI_DEVICE_ERROR The request failed due to a device error.
324 The transfer status is returned in Status.
329 UsbSetConfiguration (
330 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
331 IN UINT16 ConfigurationValue
,
335 EFI_USB_DEVICE_REQUEST DevReq
;
337 ASSERT (UsbIo
!= NULL
);
338 ASSERT (Status
!= NULL
);
340 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
342 DevReq
.RequestType
= USB_DEV_SET_CONFIGURATION_REQ_TYPE
;
343 DevReq
.Request
= USB_REQ_SET_CONFIG
;
344 DevReq
.Value
= ConfigurationValue
;
346 return UsbIo
->UsbControlTransfer (
350 PcdGet32 (PcdUsbTransferTimeoutValue
),
359 Set the specified feature of the specified device.
361 Submit a USB set device feature request for the USB device specified by UsbIo,
362 Recipient, and Target to the value specified by Value. The status of the
363 transfer is returned in Status.
364 If UsbIo is NULL, then ASSERT().
365 If Status is NULL, then ASSERT().
367 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
368 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint).
369 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry
370 Standard include file Usb.h.
371 @param Value The value of the feature to be set.
372 @param Target The index of the device to be set.
373 @param Status A pointer to the status of the transfer.
375 @retval EFI_SUCCESS The request executed successfully.
376 @retval EFI_TIMEOUT A timeout occurred executing the request.
377 @retval EFI_DEVICE_ERROR The request failed due to a device error.
378 The transfer status is returned in Status.
384 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
385 IN USB_TYPES_DEFINITION Recipient
,
391 EFI_USB_DEVICE_REQUEST DevReq
;
393 ASSERT (UsbIo
!= NULL
);
394 ASSERT (Status
!= NULL
);
396 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
400 case USB_TARGET_DEVICE
:
401 DevReq
.RequestType
= USB_DEV_SET_FEATURE_REQ_TYPE_D
;
404 case USB_TARGET_INTERFACE
:
405 DevReq
.RequestType
= USB_DEV_SET_FEATURE_REQ_TYPE_I
;
408 case USB_TARGET_ENDPOINT
:
409 DevReq
.RequestType
= USB_DEV_SET_FEATURE_REQ_TYPE_E
;
416 // Fill device request, see USB1.1 spec
418 DevReq
.Request
= USB_REQ_SET_FEATURE
;
419 DevReq
.Value
= Value
;
420 DevReq
.Index
= Target
;
423 return UsbIo
->UsbControlTransfer (
427 PcdGet32 (PcdUsbTransferTimeoutValue
),
436 Clear the specified feature of the specified device.
438 Submit a USB clear device feature request for the USB device specified by UsbIo,
439 Recipient, and Target to the value specified by Value. The status of the transfer
440 is returned in Status.
441 If UsbIo is NULL, then ASSERT().
442 If Status is NULL, then ASSERT().
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 Standard
448 @param Value The value of the feature to be cleared.
449 @param Target The index of the device to be cleared.
450 @param Status A pointer to the status of the transfer.
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.
461 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
462 IN USB_TYPES_DEFINITION Recipient
,
468 EFI_USB_DEVICE_REQUEST DevReq
;
470 ASSERT (UsbIo
!= NULL
);
471 ASSERT (Status
!= NULL
);
474 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
478 case USB_TARGET_DEVICE
:
479 DevReq
.RequestType
= USB_DEV_CLEAR_FEATURE_REQ_TYPE_D
;
482 case USB_TARGET_INTERFACE
:
483 DevReq
.RequestType
= USB_DEV_CLEAR_FEATURE_REQ_TYPE_I
;
486 case USB_TARGET_ENDPOINT
:
487 DevReq
.RequestType
= USB_DEV_CLEAR_FEATURE_REQ_TYPE_E
;
494 // Fill device request, see USB1.1 spec
496 DevReq
.Request
= USB_REQ_CLEAR_FEATURE
;
497 DevReq
.Value
= Value
;
498 DevReq
.Index
= Target
;
501 return UsbIo
->UsbControlTransfer (
505 PcdGet32 (PcdUsbTransferTimeoutValue
),
514 Get the status of the specified device.
516 Submit a USB device get status request for the USB device specified by UsbIo,
517 Recipient, and Target and place the result in the buffer specified by DeviceStatus.
518 The status of the transfer is returned in Status.
519 If UsbIo is NULL, then ASSERT().
520 If DeviceStatus is NULL, then ASSERT().
521 If Status is NULL, then ASSERT().
523 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
524 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint).
525 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard
527 @param Target The index of the device to be get the status of.
528 @param DeviceStatus A pointer to the device status to be retrieved.
529 @param Status A pointer to the status of the transfer.
531 @retval EFI_SUCCESS The request executed successfully.
532 @retval EFI_TIMEOUT A timeout occurred executing the request.
533 @retval EFI_DEVICE_ERROR The request failed due to a device error.
534 The transfer status is returned in Status.
540 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
541 IN USB_TYPES_DEFINITION Recipient
,
543 OUT UINT16
*DeviceStatus
,
547 EFI_USB_DEVICE_REQUEST DevReq
;
549 ASSERT (UsbIo
!= NULL
);
550 ASSERT (DeviceStatus
!= NULL
);
551 ASSERT (Status
!= NULL
);
553 ZeroMem (&DevReq
, sizeof (EFI_USB_DEVICE_REQUEST
));
557 case USB_TARGET_DEVICE
:
558 DevReq
.RequestType
= USB_DEV_GET_STATUS_REQ_TYPE_D
;
561 case USB_TARGET_INTERFACE
:
562 DevReq
.RequestType
= USB_DEV_GET_STATUS_REQ_TYPE_I
;
565 case USB_TARGET_ENDPOINT
:
566 DevReq
.RequestType
= USB_DEV_GET_STATUS_REQ_TYPE_E
;
573 // Fill device request, see USB1.1 spec
575 DevReq
.Request
= USB_REQ_GET_STATUS
;
577 DevReq
.Index
= Target
;
580 return UsbIo
->UsbControlTransfer (
584 PcdGet32 (PcdUsbTransferTimeoutValue
),
593 Clear halt feature of the specified usb endpoint.
595 Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint.
596 If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND.
597 If the endpoint descriptor is found, then clear the halt feature of this USB endpoint.
598 The status of the transfer is returned in Status.
599 If UsbIo is NULL, then ASSERT().
600 If Status is NULL, then ASSERT().
602 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
603 @param Endpoint The endpoint address.
604 @param Status A pointer to the status of the transfer.
606 @retval EFI_SUCCESS The request executed successfully.
607 @retval EFI_TIMEOUT A timeout occurred executing the request.
608 @retval EFI_DEVICE_ERROR The request failed due to a device error.
609 The transfer status is returned in Status.
610 @retval EFI_NOT_FOUND The specified USB endpoint descriptor can not be found
615 UsbClearEndpointHalt (
616 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
622 EFI_USB_ENDPOINT_DESCRIPTOR EndpointDescriptor
;
623 EFI_USB_INTERFACE_DESCRIPTOR InterfaceDescriptor
;
626 ASSERT (UsbIo
!= NULL
);
627 ASSERT (Status
!= NULL
);
629 ZeroMem (&EndpointDescriptor
, sizeof (EFI_USB_ENDPOINT_DESCRIPTOR
));
631 // First search the endpoint descriptor for that endpoint addr
633 Result
= UsbIo
->UsbGetInterfaceDescriptor (
637 if (EFI_ERROR (Result
)) {
641 for (Index
= 0; Index
< InterfaceDescriptor
.NumEndpoints
; Index
++) {
642 Result
= UsbIo
->UsbGetEndpointDescriptor (
647 if (EFI_ERROR (Result
)) {
651 if (EndpointDescriptor
.EndpointAddress
== Endpoint
) {
656 if (Index
== InterfaceDescriptor
.NumEndpoints
) {
660 return EFI_NOT_FOUND
;
663 Result
= UsbClearFeature (
666 USB_FEATURE_ENDPOINT_HALT
,
667 EndpointDescriptor
.EndpointAddress
,