EFI USB IO PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides services to manage and communicate with USB devices.

Contents

GUID

#define EFI_USB_IO_PROTOCOL_GUID \
  {0x2B2F68D6,0x0CD2,0x44cf,0x8E,0x8B,0xBB,0xA2,0x0B,0x1B,0x5B,0x75}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(UsbIo)

extern EFI_GUID gEfiUsbIoProtocolGuid;
typedef struct _EFI_USB_IO_PROTOCOL {
  EFI_USB_IO_CONTROL_TRANSFER            UsbControlTransfer;
  EFI_USB_IO_BULK_TRANSFER               UsbBulkTransfer;
  EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER    UsbAsyncInterruptTransfer;
  EFI_USB_IO_SYNC_INTERRPUT_TRANSFER     UsbSyncInterruptTransfer;
  EFI_USB_IO_ISOCHRONOUS_TRANSFER        UsbIsochronousTransfer;
  EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER  UsbAsyncIsochronousTransfer;
  EFI_USB_IO_GET_DEVICE_DESCRIPTOR       UsbGetDeviceDescriptor;
  EFI_USB_IO_GET_CONFIG_DESCRIPTOR       UsbGetConfigDescriptor;
  EFI_USB_IO_GET_INTERFACE_DESCRIPTOR    UsbGetInterfaceDescriptor;
  EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR     UsbGetEndpointDescriptor;
  EFI_USB_IO_GET_STRING_DESCRIPTOR       UsbGetStringDescriptor;
  EFI_USB_IO_GET_SUPPORTED_LANGUAGES     UsbGetSupportedLanguages;
  EFI_USB_IO_PORT_RESET                  UsbPortReset;
} EFI_USB_IO_PROTOCOL;

Members

Member Description
UsbControl Transfer Accesses the USB Device through USB Control Transfer Pipe.
UsbBulkTransfer Accesses the USB Device through USB Bulk Transfer Pipe.
UsbAsyncInterruptTransfer Non-block USB interrupt transfer.
UsbSyncInterruptTransfer Accesses the USB Device through USB Synchronous Interrupt Transfer Pipe.
UsbIsochronousTransfer Accesses the USB Device through USB Isochronous Transfer Pipe.
UsbAsyncIsochronousTransfer Nonblock USB isochronous transfer.
UsbGetDeviceDescriptor Retrieves the device descriptor of a USB device.
UsbGetConfigDescriptor Retrieves the activated configuration descriptor of a USB device.
UsbGetInterfaceDescriptor Retrieves the interface descriptor of a USB Controller.
UsbGetEndpointDescriptor Retrieves the endpoint descriptor of a USB Controller.
UsbGetStringDescriptor Retrieves the string descriptor inside a USB Device.
UsbGetSupportedLanguages Retrieves the array of languages that the USB device supports.
UsbPortReset Resets and reconfigures the USB controller.

Description

The EFI_USB_IO_PROTOCOL provides four basic transfers types described in the USB 1.1 Specification. These include control transfer, interrupt transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL also provides some basic USB device/controller management and configuration interfaces. A USB device driver uses the services of this protocol to manage USB devices.

UsbControlTransfer()

This function is used to manage a USB device with a control transfer pipe. A control transfer is typically used to perform device initialization and configuration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (
  IN     EFI_USB_IO_PROTOCOL     *This,
  IN     EFI_USB_DEVICE_REQUEST  *Request,
  IN     EFI_USB_DATA_DIRECTION  Direction,
  IN     UINT32                  Timeout,
  IN OUT VOID                    *Data OPTIONAL,
  IN     UINTN                   DataLength OPTIONAL,
  OUT    UINT32                  *Status
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
Request A pointer to the USB device request that will be sent to the USB device.
Direction Indicates the data direction.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
Timeout Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
DataLength The size, in bytes, of the data buffer specified by Data.
Status A pointer to the result of the USB transfer.
#define EFI_USB_NOERROR        0x0000
#define EFI_USB_ERR_NOTEXECUTE 0x0001
#define EFI_USB_ERR_STALL      0x0002
#define EFI_USB_ERR_BUFFER     0x0004
#define EFI_USB_ERR_BABBLE     0x0008
#define EFI_USB_ERR_NAK        0x0010
#define EFI_USB_ERR_CRC        0x0020
#define EFI_USB_ERR_TIMEOUT    0x0040
#define EFI_USB_ERR_BITSTUFF   0x0080
#define EFI_USB_ERR_SYSTEM     0x0100

Description
This function allows a USB device driver to communicate with the USB device through a Control Transfer. There are three control transfer types according to the data phase. If the Direction parameter is EfiUsbNoData, Data is NULL, and DataLength is 0, then no data phase exists for the control transfer. If the Direction parameter is EfiUsbDataOut, then Data specifies the data to be transmitted to the device, and DataLength specifies the number of bytes to transfer to the device. In this case there is an OUT DATA stage followed by a SETUP stage. If the Direction parameter is EfiUsbDataIn, then Data specifies the data that is received from the device, and DataLength specifies the number of bytes to receive from the device. In this case there is an IN DATA stage followed by a SETUP stage. After the USB transfer has completed successfully, EFI_SUCCESS is returned. If the transfer cannot be completed due to timeout, then EFI_TIMEOUT is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR is returned and the detailed status code is returned in Status.

Status Code Returned

Status Code Description
EFI_SUCCESS The control transfer has been successfully executed.
EFI_INVALID_PARAMETER The parameter Direction is not valid.
EFI_INVALID_PARAMETER Request is NULL.
EFI_INVALID_PARAMETER Status is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
EFI_TIMEOUT The control transfer fails due to timeout.
EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.

UsbBulkTransfer()

This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are typically used to transfer large amounts of data to/from USB devices.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (
  IN     EFI_USB_IO_PROTOCOL *This,
  IN     UINT8               DeviceEndpoint,
  IN OUT VOID                *Data,
  IN OUT UINTN               *DataLength,
  IN     UINTN               Timeout,
  OUT    UINT32              *Status
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpoint The destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number “1” stands for an IN endpoint, and “0” stands for an OUT endpoint.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLength On input, the size, in bytes, of the data buffer specified by Data. On output, the number of bytes that were actually transferred.
Timeout Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Status This parameter indicates the USB transfer status.

Description
This function allows a USB device driver to communicate with the USB device through Bulk Transfer. The transfer direction is determined by the endpoint direction. If the USB transfer is successful, then EFI_SUCCESS is returned. If USB transfer cannot be completed within the Timeout frame, EFI_TIMEOUT is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR is returned and the detailed status code will be returned in the Status parameter.

Status Code Returned

Status Code Description
EFI_SUCCESS The bulk transfer has been successfully executed.
EFI_INVALID_PARAMETER If DeviceEndpoint is not valid.
EFI_INVALID_PARAMETER Data is NULL.
EFI_INVALID_PARAMETER DataLength is NULL.
EFI_INVALID_PARAMETER Status is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
EFI_TIMEOUT The bulk transfer cannot be completed within Timeout timeframe.
EFI_DEVICE_ERROR The transfer failed other than timeout, and the transfer status is returned in Status.

UsbAsyncInterruptTransfer()

This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous Interrupt Transfer is typically used to query a device’s status at a fixed rate. For example, keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at a fixed rate.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER) (
  IN EFI_USB_IO_PROTOCOL             *This,
  IN UINT8                           DeviceEndpoint,
  IN BOOLEAN                         IsNewTransfer,
  IN UINTN                           PollingInterval OPTIONAL,
  IN UINTN                           DataLength OPTIONAL,
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,
  IN VOID                            *Context OPTIONAL
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpoint The destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not an INTERRUPT endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number “1” stands for an IN endpoint, and “0” stands for an OUT endpoint.
IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If FALSE, the interrupt transfer is deleted from the device’s interrupt transfer queue. If TRUE, and an interrupt transfer exists for the target end point, then EFI_INVALID_PARAMETER is returned.
PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. This parameter is required when IsNewTransfer is TRUE. The value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. The units are in milliseconds.
DataLength Specifies the length, in bytes, of the data to be received from the USB device. This parameter is only required when IsNewTransfer is TRUE.
Context Data passed to the InterruptCallback function. This is an optional parameter and may be NULL.
InterruptCallback The Callback function. This function is called if the asynchronous interrupt transfer is completed. This parameter is required when IsNewTransfer is TRUE.

Description
This function allows a USB device driver to communicate with a USB device with an Interrupt Transfer. Asynchronous Interrupt transfer is different than the other four transfer types because it is a nonblocking transfer. The interrupt endpoint is queried at a fixed rate, and the data transfer direction is always in the direction from the USB device towards the system.

If IsNewTransfer is TRUE, then an interrupt transfer is started at a fixed rate. The rate is specified by PollingInterval, the size of the receive buffer is specified by DataLength, and the callback function is specified by InterruptCallback. If IsNewTransfer is TRUE, and an interrupt transfer exists for the target end point, then EFI_INVALID_PARAMETER is returned.

If IsNewTransfer is FALSE, then the interrupt transfer is canceled.

Status Code Returned

Status Code Description
EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
EFI_DEVICE_ERROR The asynchronous USB transfer request failed. When an interrupt transfer exists for the target end point and a new transfer is requested, EFI_INVALID_PARAMETER is returned.

UsbSyncInterruptTransfer()

This function is used to manage a USB device with an interrupt transfer pipe. The difference between UsbAsyncInterruptTransfer() and UsbSyncInterruptTransfer() is that the Synchronous interrupt transfer will only be executed one time. Once it returns, regardless of its status, the interrupt request will be deleted in the system.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (
  IN     EFI_USB_IO_PROTOCOL *This,
  IN     UINT8               DeviceEndpoint,
  IN OUT VOID                *Data,
  IN OUT UINTN               *DataLength,
  IN     UINTN               Timeout,
  OUT    UINT32              *Status
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpoint The destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not an INTERRUPT endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number “1” stands for an IN endpoint, and “0” stands for an OUT endpoint.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLength On input, then size, in bytes, of the buffer Data. On output, the amount of data actually transferred.
Timeout The time out, in seconds, for this transfer. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
Status This parameter indicates the USB transfer status.

Description
This function allows a USB device driver to communicate with a USB device through a synchronous interrupt transfer. The UsbSyncInterruptTransfer() differs from UsbAsyncInterruptTransfer() described in the previous section in that it is a blocking transfer request. The caller must wait for the function return, either successfully or unsuccessfully.

Status Code Returned

Status Code Description
EFI_SUCCESS The sync interrupt transfer has been successfully executed.
EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
EFI_INVALID_PARAMETER Data is NULL.
EFI_INVALID_PARAMETER DataLength is NULL.
EFI_INVALID_PARAMETER Status is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
EFI_TIMEOUT The transfer cannot be completed within Timeout timeframe.
EFI_DEVICE_ERROR The transfer failed other than timeout, and the transfer status is returned in Status.

UsbIsochronousTransfer()

This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous transfer is typically used to transfer streaming data.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_USB_IO_ISOCHRONOUS_TRANSFER) (
  IN     EFI_USB_IO_PROTOCOL *This,
  IN     UINT8               DeviceEndpoint,
  IN OUT VOID                *Data,
  IN     UINTN               DataLength,
  OUT    UINT32              *Status
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpoint The destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not an ISOCHRONOUS endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number “1” stands for an IN endpoint, and “0” stands for an OUT endpoint.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLength The size, in bytes, of the data buffer specified by Data.
Status This parameter indicates the USB transfer status.

Description
This function allows a USB device driver to communicate with a USB device with an Isochronous Transfer. The type of transfer is different than the other types because the USB Bus Driver will not attempt to perform error recovery if transfer fails. If the USB transfer is completed successfully, then EFI_SUCCESS is returned. The isochronous transfer is designed to be completed within 1 USB frame time, if it cannot be completed, EFI_TIMEOUT is returned. If the transfer fails due to other reasons, then EFI_DEVICE_ERROR is returned and the detailed error status is returned in Status. If the data length exceeds the maximum payload per USB frame time, then it is this function’s responsibility to divide the data into a set of smaller packets that fit into a USB frame time. If all the packets are transferred successfully, then EFI_SUCCESS is returned.

Status Code Returned

Status Code Description
EFI_SUCCESS The isochronous transfer has been successfully executed.
EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
EFI_TIMEOUT The transfer cannot be completed within the 1 USB frame time.
EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status is returned in Status.
EFI_UNSUPPORTED The implementation doesn’t support an Isochronous transfer function.

UsbAsyncIsochronousTransfer()

This function is used to manage a USB device with an isochronous transfer pipe. An asynchronous Isochronous transfer is a nonblocking USB isochronous transfer.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (
  IN     EFI_USB_IO_PROTOCOL             *This,
  IN     UINT8                           DeviceEndpoint,
  IN OUT VOID                            *Data,
  IN     UINTN                           DataLength,
  IN     EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
  IN     VOID                            *Context OPTIONAL
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpoint The destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not an ISOCHRONOUS endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number “1” stands for an IN endpoint, and “0” stands for an OUT endpoint.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLength Specifies the length, in bytes, of the data to be sent to or received from the USB device.
Context Data passed to the IsochronousCallback() function. This is an optional parameter and may be NULL.
IsochronousCallback The IsochronousCallback() function. This function is called if the requested isochronous transfer is completed. See the “Related Definitions” section of the UsbAsyncInterruptTransfer() function description.

Description
This is an asynchronous type of USB isochronous transfer. If the caller submits a USB isochronous transfer request through this function, this function will return immediately. When the isochronous transfer completes, the IsochronousCallback() function will be triggered, the caller can know the transfer results. If the transfer is successful, the caller can get the data received or sent in this callback function.

Status Code Returned

Status Code Description
EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted to the system.
EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
EFI_UNSUPPORTED The implementation doesn’t support an asynchronous Isochronous transfer function.

UsbGetDeviceDescriptor()

Retrieves the USB Device Descriptor.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (
  IN  EFI_USB_IO_PROTOCOL       *This,
  OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.

Description
This function is used to retrieve information about USB devices. This information includes the device class, subclass, and the number of configurations the USB device supports. If DeviceDescriptor is NULL, then EFI_INVALID_PARAMETER is returned. If the USB device descriptor is not found, then EFI_NOT_FOUND is returned. Otherwise, the device descriptor is returned in DeviceDescriptor, and EFI_SUCCESS is returned.

Status Code Returned

Status Code Description
EFI_SUCCESS The device descriptor was retrieved successfully.
EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.

UsbGetConfigDescriptor()

Retrieves the USB Device Configuration Descriptor.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (
  IN  EFI_USB_IO_PROTOCOL       *This,
  OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration Descriptor.

Description
This function is used to retrieve the active configuration that the USB device is currently using. If ConfigurationDescriptor is NULL, then EFI_INVALID_PARAMETER is returned. If the USB controller does not contain an active configuration, then EFI_NOT_FOUND is returned. Otherwise, the active configuration is returned in ConfigurationDescriptor, and EFI_SUCCESS is returned.

Status Code Returned

Status Code Description
EFI_SUCCESS The active configuration descriptor was retrieved successfully.
EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not be configured.

UsbGetInterfaceDescriptor()

Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface within a USB device is equivalently to a USB Controller within the current configuration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (
  IN  EFI_USB_IO_PROTOCOL          *This,
  OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within the configuration setting.

Description
This function is used to retrieve the interface descriptor for the USB controller. If InterfaceDescriptor is NULL, then EFI_INVALID_PARAMETER is returned. If the USB controller does not contain an interface descriptor, then EFI_NOT_FOUND is returned. Otherwise, the interface descriptor is returned in InterfaceDescriptor, and EFI_SUCCESS is returned.

Status Code Returned

Parameters Description
EFI_SUCCESS The interface descriptor retrieved successfully.
EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be correctly configured.

UsbGetEndpointDescriptor()

Retrieves an Endpoint Descriptor within a USB Controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR) (
  IN  EFI_USB_IO_PROTOCOL          *This,
  IN  UINT8                            EndpointIndex,
  OUT EFI_USB_ENDPOINT_DESCRIPTOR  *EndpointDescriptor
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
EndpointIndex Indicates which endpoint descriptor to retrieve. The valid range is 0..15.
EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of a USB controller.

Description
This function is used to retrieve an endpoint descriptor within a USB controller. If EndpointIndex is not in the range 0..15, then EFI_INVALID_PARAMETER is returned. If EndpointDescriptor is NULL, then EFI_INVALID_PARAMETER is returned. If the endpoint specified by EndpointIndex does not exist within the USB controller, then EFI_NOT_FOUND is returned. Otherwise, the endpoint descriptor is returned in EndpointDescriptor, and EFI_SUCCESS is returned.

Status Code Returned

Status Code Description
EFI_SUCCESS The endpoint descriptor was retrieved successfully.
EFI_INVALID_PARAMETER EndpointIndex is not valid.
EFI_INVALID_PARAMETER EndpointDescriptor is NULL.
EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be correctly configured.

UsbGetStringDescriptor()

Retrieves a Unicode string stored in a USB Device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (
  IN  EFI_USB_IO_PROTOCOL  *This,
  IN  UINT16               LangID,
  IN  UINT8                StringID,
  OUT CHAR16               **String
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
LangID The Language ID for the string being retrieved. See the UsbGetSupportedLanguages() function description for a more detailed description.
StringID The ID of the string being retrieved.
String A pointer to a buffer allocated by this function with AllocatePool() to store the string. If this function returns EFI_SUCCESS, it stores the string the caller wants to get. The caller should release the string buffer with FreePool() after the string is not used any more.

Description
This function is used to retrieve strings stored in a USB device. Strings are stored in a Unicode format. The string to retrieve is identified by a language and an identifier. The language is specified by LangID, and the identifier is specified by StringID. If the string is found, it is returned in String, and EFI_SUCCESS is returned. If the string cannot be found, then EFI_NOT_FOUND is returned. The string buffer is allocated by this function with AllocatePool(). The caller is responsible for calling FreePool() for String when it is no longer required.

Status Code Returned

Status Code Description
EFI_SUCCESS The string was retrieved successfully.
EFI_NOT_FOUND The string specified by LangID and StringID was not found.
EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.

UsbGetSupportedLanguages()

Retrieves all the language ID codes that the USB device supports.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGES) (
  IN  EFI_USB_IO_PROTOCOL  *This,
  OUT UINT16               **LangIDTable,
  OUT UINT16               *TableSize
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.
LangIDTable Language ID for the string the caller wants to get. This is a 16-bit ID defined by Microsoft. This buffer pointer is allocated and maintained by the USB Bus Driver, the caller should not modify its contents.
TableSize The size, in bytes, of the table LangIDTable.

Description
Retrieves all the language ID codes that the USB device supports.

Status Code Returned

Status Code Description
EFI_SUCCESS The support languages were retrieved successfully.

UsbPortReset()

Resets and reconfigures the USB controller. This function will work for all USB devices except USB Hub Controllers.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB_IO_PORT_RESET) (
  IN EFI_USB_IO_PROTOCOL *This
  );

Parameters

Parameters Description
This A pointer to the EFI_USB_IO_PROTOCOL instance.

Description
This function provides a reset mechanism by sending a RESET signal from the parent hub port. A reconfiguration process will happen (that includes setting the address and setting the configuration). This reset function does not change the bus topology. A USB hub controller cannot be reset using this function, because it would impact the downstream USB devices. So if the controller is a USB hub controller, then EFI_INVALID_PARAMETER is returned.

Status Code Returned

Status Code Description
EFI_SUCCESS The USB controller was reset.
EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
EFI_DEVICE_ERROR An error occurred during the reconfiguration process.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools