EFI USB2 HC PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides basic USB host controller management, basic data transactions over USB bus, and USB root hub access.

Contents

GUID

#define EFI_USB2_HC_PROTOCOL_GUID \
  {0x3e745226,0x9818,0x45b6,0xa2,0xac,0xd7,0xcd,0xe,0x8b,0xa2,0xbc}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(UsbHostController)

extern EFI_GUID gEfiUsb2HcProtocolGuid;
typedef struct _EFI_USB2_HC_PROTOCOL {
  EFI_USB2_HC_PROTOCOL_GET_CAPABILITY              GetCapability;
  EFI_USB2_HC_PROTOCOL_RESET                       Reset;
  EFI_USB2_HC_PROTOCOL_GET_STATE                   GetState;
  EFI_USB2_HC_PROTOCOL_SET_STATE                   SetState;
  EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER            ControlTransfer;
  EFI_USB2_HC_PROTOCOL_BULK_TRANSFER               BulkTransfer;
  EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER    AsyncInterruptTransfer;
  EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER     SyncInterruptTransfer;
  EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER        IsochronousTransfer;
  EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER  AsyncIsochronousTransfer;
  EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
  EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
  EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
  UINT16                                           MajorRevision;
  UINT16                                           MinorRevision;
} EFI_USB2_HC_PROTOCOL;

Members

Member Description
GetCapability Retrieves the capabilities of the USB host controller.
Reset Software reset of USB.
GetState Retrieves the current state of the USB host controller.
SetState Sets the USB host controller to a specific state.
ControlTransfer Submits a control transfer to a target USB device.
BulkTransfer Submits a bulk transfer to a bulk endpoint of a USB device.
AsyncInterruptTransfer Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
SyncInterruptTransfer Submits a synchronous interrupt transfer to an interrupt endpoint of a USB device.
IsochronousTransfer Submits isochronous transfer to an isochronous endpoint of a USB device.
AsyncIsochronousTransfer Submits nonblocking USB isochronous transfer.
GetRootHubPortStatus Retrieves the status of the specified root hub port.
SetRootHubPortFeature Sets the feature for the specified root hub port.
ClearRootHubPortFeature Clears the feature for the specified root hub port.
MajorRevision The major revision number of the USB host controller. The revision information indicates the release of the Universal Serial Bus Specification with which the host controller is compliant.
MinorRevision The minor revision number of the USB host controller. The revision information indicates the release of the Universal Serial Bus Specification with which the host controller is compliant.

Description

The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic data transactions over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL instance that is associated with the USB bus to be managed. A device handle for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB2_HC_PROTOCOL instance.

GetCapability()

Retrieves the Host Controller capabilities.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_CAPABILITY) (
  IN  EFI_USB2_HC_PROTOCOL *This,
  OUT UINT8                *MaxSpeed,
  OUT UINT8                *PortNumber,
  OUT UINT8                *Is64BitCapable
  );
#define EFI_USB_SPEED_FULL 0x0000
#define EFI_USB_SPEED_LOW  0x0001
#define EFI_USB_SPEED_HIGH 0x0002

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
MaxSpeed Host controller data transfer speed.
Speed Description
EFI_USB_SPEED_LOW Low speed USB device; data bandwidth is up to 1 Mb/s. Supported by USB 1.1 OHCI and UHCI host controllers.
EFI_USB_SPEED_FULL Full speed USB device; data bandwidth is up to 12 Mb/s. Supported by USB 1.1 OHCI and UHCI host controllers.
EFI_USB_SPEED_HIGH High speed USB device; data bandwidth is up to 480 Mb/s. Supported by USB 2.0 EHCI host controllers.
PortNumber Number of the root hub ports.
Is64BitCapable TRUE if controller supports 64-bit memory addressing, FALSE otherwise.

Description
This function is used to retrieve the host controller capabilities. MaxSpeed indicates the maximum data transfer speed the controller is capable of; this information is needed for the subsequent transfers. PortNumber is the number of root hub ports, it is required by the USB bus driver to perform bus enumeration. Is64BitCapable indicates that controller is capable of 64-bit memory access so that the host controller software can use memory blocks above 4 GB for the data transfers.


Status Codes Returned

Status Code Description
EFI_SUCCESS The host controller capabilities were retrieved successfully.
EFI_INVALID_PARAMETER MaxSpeed or PortNumber or Is64BitCapable is NULL.
EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the capabilities.

Reset()

Provides software reset for the USB host controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_RESET) (
  IN EFI_USB2_HC_PROTOCOL  *This,
  IN UINT16                Attributes
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
Attributes A bit mask of the reset operation to perform.
#define EFI_USB_HC_RESET_GLOBAL 0x0001
#define EFI_USB_HC_RESET_HOST_CONTROLLER 0x0002
#define EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG 0x0004
#define EFI_USB_HC_RESET_HOST_WITH_DEBUG 0x0008
EFI_USB_HC_RESET_GLOBAL If this bit is set, a global reset signal will be sent to the USB bus. This resets all of the USB bus logic, including the USB host controller hardware and all the devices attached on the USB bus.
EFI_USB_HC_RESET_HOST_CONTROLLER If this bit is set, the USB host controller hardware will be reset. No reset signal will be sent to the USB bus.
EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG If this bit is set, then a global reset signal will be sent to the USB bus. This resets all of the USB bus logic, including the USB host controller and all of the devices attached on the USB bus. If this is an EHCI controller and the debug port has been configured, then this will still reset the host controller.
EFI_USB_HC_RESET_HOST_WITH_DEBUG If this bit is set, the USB host controller hardware will be reset. If this is an EHCI controller and the debug port has been configured, then this will still reset the host controller.

Description
This function provides a software mechanism to reset a USB host controller. The type of reset is specified by the Attributes parameter. If the type of reset specified by Attributes is not valid, then EFI_INVALID_PARAMETER is returned. If the reset operation is completed, then EFI_SUCCESS is returned. If the type of reset specified by Attributes is not currently supported by the host controller hardware, EFI_UNSUPPORTD is returned. If a device error occurs during the reset operation, then EFI_DEVICE_ERROR is returned.

Note: For EHCI controllers, the EFI_USB_HC_RESET_GLOBAL and EFI_USB_HC_RESET_HOST_CONTROLLER types of reset do not actually reset the bus if the debug port has been configured. In these cases, the function will return EFI_ACCESS_DENIED.

Status Codes Returned

Status Code Description
EFI_SUCCESS The reset operation succeeded.
EFI_INVALID_PARAMETER Attributes is not valid.
EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported by the host controller hardware.
EFI_ACCESS_DENIED Reset operation is rejected due to the debug port being configured and active; only EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG or EFI_USB_HC_RESET_HOST_WITH_DEBUG reset Attributes can be used to perform reset operation for this host controller.
EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation.

GetState()

Retrieves current state of the USB host controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_STATE) (
  IN  EFI_USB2_HC_PROTOCOL *This,
  OUT EFI_USB_HC_STATE     *State
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
State A pointer to the EFI_USB_HC_STATE data structure that indicates current state of the USB host controller.

Description
This function is used to retrieve the USB host controller’s current state. The USB Host Controller Protocol publishes three states for USB host controller, as defined in “Related Definitions” below. If State is NULL, then EFI_INVALID_PARAMETER is returned. If a device error occurs while attempting to retrieve the USB host controllers current state, then EFI_DEVICE_ERROR is returned. Otherwise, the USB host controller’s current state is returned in State, and EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The state information of the host controller was returned in State.
EFI_INVALID_PARAMETER State is NULL.
EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller’s current state.

SetState()

Sets the USB host controller to a specific state.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_STATE) (
  IN EFI_USB2_HC_PROTOCOL *This,
  IN EFI_USB_HC_STATE     State
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
State Indicates the state of the host controller that will be set.

Description
This function is used to explicitly set a USB host controller’s state. There are three states defined for the USB host controller. These are the halt state, the operational state and the suspend state.

If the state specified by State is not valid, then EFI_INVALID_PARAMETER is returned. If a device error occurs while attempting to place the USB host controller into the state specified by State, then EFI_DEVICE_ERROR is returned. If the USB host controller is successfully placed in the state specified by State, then EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The USB host controller was successfully placed in the state specified by State.
EFI_INVALID_PARAMETER State is invalid.
EFI_DEVICE_ERROR Failed to set the state specified by State due to device error.

ControlTransfer()

Submits control transfer to a target USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL                *This,
  IN     UINT8                               DeviceAddress,
  IN     UINT8                               DeviceSpeed,
  IN     UINTN                               MaximumPacketLength,
  IN     EFI_USB_DEVICE_REQUEST              *Request,
  IN     EFI_USB_DATA_DIRECTION              TransferDirection,
  IN OUT VOID                                *Data OPTIONAL,
  IN OUT UINTN                               *DataLength OPTIONAL,
  IN     UINTN                               TimeOut,
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
  OUT    UINT32                              *TransferResult
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
DeviceSpeed Indicates device speed. See “Related Definitions” in GetCapability() for a list of the supported values.
MaximumPacketLength Indicates the maximum packet size that the default control transfer endpoint is capable of sending or receiving.
Request A pointer to the USB device request that will be sent to the USB device. Refer to Section 2.5.1 14.2 of EFI 1.1 USB Driver Model, version 0.7.
TransferDirection Specifies the data direction for the transfer. There are three values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. Refer to Section 2.5.1 of EFI1.1 USB Driver Model, version 0.7 14.2.
Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLength On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually transferred.
Translator A pointer to the transaction translator data. See “Description” for the detailed information of this data structure.
TimeOut Indicates the maximum time, in milliseconds, which the transfer is allowed to complete.
TransferResult A pointer to the detailed result information generated by this control transfer. Refer to Section 2.5.1 of EFI1.1 USB Driver Model, version 0.7 14.2.

Description
This function is used to submit a control transfer to a target USB device specified by DeviceAddress. Control transfers are intended to support configuration/command/status type communication flows between host and USB device.

There are three control transfer types according to the data phase. If the TransferDirection parameter is EfiUsbNoData, Data is NULL, and DataLength is 0, then no data phase is present in the control transfer. If the TransferDirection 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 TransferDirection parameter is EfiUsbDataIn, then Data specifies the data to be 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.

Translator is necessary to perform split transactions on low-speed or full-speed devices connected to a high-speed hub. Such transaction require the device connection information: device address and the port number of the hub that device is connected to. This information is passed through the fields of EFI_USB2_HC_TRANSACTION_TRANSLATOR structure. See “Related Definitions” for the structure field names. Translator is passed as NULL for the USB1.1 host controllers transfers or when the transfer is requested for high-speed device connected to USB2.0 controller.

If the control transfer has completed successfully, then EFI_SUCCESS is returned. If the transfer cannot be completed within the timeout specified by 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 error code will be returned in the TransferResult parameter.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • TransferDirection is invalid.
  • TransferDirection, Data, and DataLength do not match one of the three control transfer types described above.
  • Request pointer is NULL.
  • MaximumPacketLength is not valid. If DeviceSpeed is EFI_USB_SPEED_LOW, then MaximumPacketLength must be 8. If IsSlowDevice is FALSE EFI_USB_SPEED_FULL or EFI_USB_SPEED_HIGH, then MaximumPacketLength must be 8, 16, 32, or 64.
  • TransferResult pointer is NULL.
  • Translator is NULL while the requested transfer requires split transaction. The conditions of the split transactions are described above in “Description” section.

Status Codes Returned

Status Code Description
EFI_SUCCESS The control transfer was completed successfully.
EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above.
EFI_TIMEOUT The control transfer failed due to timeout.
EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. Caller should check TransferResult for detailed error information.

BulkTransfer()

Submits bulk transfer to a bulk endpoint of a USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_BULK_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL                *This,
  IN     UINT8                               DeviceAddress,
  IN     UINT8                               EndPointAddress,
  IN     UINT8                               DeviceSpeed,
  IN     UINTN                               MaximumPacketLength,
  IN     UINT8                               DataBuffersNumber,
  IN OUT VOID                                **Data,
  IN OUT UINTN                               *DataLength,
  IN OUT UINT8                               *DataToggle,
  IN     UINTN                               TimeOut,
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
  OUT    UINT32                              *TransferResult
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is 0). It is the caller’s responsibility to make sure that the EndPointAddress represents a bulk endpoint.
DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL and EFI_USB_SPEED_HIGH.
MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving.
DataBuffersNumber Number of data buffers prepared for the transfer.
Data Array of pointers to the buffers of data that will be transmitted to USB device or received from USB device.
DataLength When input, indicates the size, in bytes, of the data buffers specified by Data. When output, indicates the actually transferred data size.
DataToggle A pointer to the data toggle value. On input, it indicates the initial data toggle value the bulk transfer should adopt; on output, it is updated to indicate the data toggle value of the subsequent bulk transfer.
Translator A pointer to the transaction translator data. See ControlTransfer() “Description” for the detailed information of this data structure.
TimeOut Indicates the maximum time, in milliseconds, which the transfer is allowed to complete.
TransferResult A pointer to the detailed result information of the bulk transfer. Refer to Section 2.5.1 of EFI1.1 USB Driver Model, version 0.7 14.2.

Description
This function is used to submit bulk transfer to a target endpoint of a USB device. The target endpoint is specified by DeviceAddress and EndpointAddress. Bulk transfers are designed to support devices that need to communicate relatively large amounts of data at highly variable times where the transfer can use any available bandwidth. Bulk transfers can be used only by full-speed and high-speed devices.

High-speed bulk transfers can be performed using multiple data buffers. The number of buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For full-speed bulk transfers this value is ignored.

Data represents a list of pointers to the data buffers. For full-speed bulk transfers only the data pointed by Data[0] shall be used. For high-speed transfers depending on DataLength there several data buffers can be used. The total number of buffers must not exceed EFI_USB_MAX_BULK_BUFFER_NUM. See “Related Definitions” for the EFI_USB_MAX_BULK_BUFFER_NUM value.

The data transfer direction is determined by the endpoint direction that is encoded in the EndPointAddress parameter. Refer to USB Specification, Revision 2.0 on the Endpoint Address encoding.

The DataToggle parameter is used to track target endpoint’s data sequence toggle bits. The USB provides a mechanism to guarantee data packet synchronization between data transmitter and receiver across multiple transactions. The data packet synchronization is achieved with the data sequence toggle bits and the DATA0/DATA1 PIDs. A bulk endpoint’s toggle sequence is initialized to DATA0 when the endpoint experiences a configuration event. It toggles between DATA0 and DATA1 in each successive data transfer. It is host’s responsibility to track the bulk endpoint’s data toggle sequence and set the correct value for each data packet. The input DataToggle value points to the data toggle value for the first data packet of this bulk transfer; the output DataToggle value points to the data toggle value for the last successfully transferred data packet of this bulk transfer. The caller should record the data toggle value for use in subsequent bulk transfers to the same endpoint.

If the bulk transfer is successful, then EFI_SUCCESS is returned. If USB transfer cannot be completed within the timeout specified by 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 TransferResult.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • Data is NULL.
  • DataLength is 0.
  • DeviceSpeed is not valid; the legal values are EFI_USB_SPEED_FULL or EFI_USB_SPEED_HIGH.
  • MaximumPacketLength is not valid. The legal value of this parameter is 64 or less for fullspeed and 512 or less for high-speed transaction.
  • DataToggle points to a value other than 0 and 1.
  • TransferResult is NULL.

Status Codes Returned

Status Code Description
EFI_SUCCESS The bulk transfer was completed successfully.
EFI_OUT_OF_RESOURCES The bulk transfer could not be submitted due to lack of resource.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above.
EFI_TIMEOUT The bulk transfer failed due to timeout.
EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. Caller should check TransferResult for detailed error information.

AsyncInterruptTransfer()

Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL            *This,
  IN     UINT8                           DeviceAddress,
  IN     UINT8                           EndPointAddress,
  IN     UINT8                           DeviceSpeed,
  IN     UINTN                           MaximumPacketLength,
  IN     BOOLEAN                         IsNewTransfer,
  IN OUT UINT8                           *DataToggle,
  IN     UINTN                           PollingInterval OPTIONAL,
  IN     UINTN                           DataLength OPTIONAL,
  IN     EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL,
  IN     VOID                            *Context OPTIONAL
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller’s responsibility to make sure that the EndPointAddress represents an interrupt endpoint.
DeviceSpeed Indicates device speed.
MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving.
IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host and the target interrupt endpoint. If FALSE, the specified asynchronous interrupt pipe is canceled. If TRUE, and an interrupt transfer exists for the target end point, then EFI_INVALID_PARAMETER is returned.
DataToggle A pointer to the data toggle value. On input, it is valid when IsNewTransfer is TRUE, and it indicates the initial data toggle value the asynchronous interrupt transfer should adopt. On output, it is valid when IsNewTransfer is FALSE, and it is updated to indicate the data toggle value of the subsequent asynchronous interrupt transfer.
PollingInterval Indicates the interval, in milliseconds, that the asynchronous interrupt transfer is polled. This parameter is required when IsNewTransfer is TRUE.
DataLength Indicates the length of data to be received at the rate specified by PollingInterval from the target asynchronous interrupt endpoint. This parameter is only required when IsNewTransfer is TRUE.
CallBackFunction The Callback function. This function is called at the rate specified by PollingInterval. This parameter is only required when IsNewTransfer is TRUE.
Context The context that is passed to the CallBackFunction. This is an optional parameter and may be NULL.

Description
This function is used to submit asynchronous interrupt transfer to a target endpoint of a USB device. The target endpoint is specified by DeviceAddress and EndpointAddress. In the USB Specification, Revision 2.0, interrupt transfer is one of the four USB transfer types. In the EFI_USB2_HC_PROTOCOL, interrupt transfer is divided further into synchronous interrupt transfer and asynchronous interrupt transfer.

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. The asynchronous interrupt transfer is intended to support the interrupt transfer type of “submit once, execute periodically.” Unless an explicit request is made, the asychronous transfer will never retire.

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 CallBackFunction. Context specifies an optional context that is passed to the CallBackFunction each time it is called. The CallBackFunction is intended to provide a means for the host to periodically process interrupt transfer data.

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.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • Data transfer direction indicated by EndPointAddress is other than EfiUsbDataIn.
  • IsNewTransfer is TRUE and DataLength is 0.
  • IsNewTransfer is TRUE and DataToggle points to a value other than 0 and 1.
  • IsNewTransfer is TRUE and PollingInterval is not in the range 1..255.
  • IsNewTransfer requested where an interrupt transfer exists for the target end point.

Status Codes Returned

Status Code Description
EFI_SUCCESS The asynchronous interrupt transfer request has been successfully submitted or canceled.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above. When an interrupt transfer exists for the target end point and a new transfer is requested, EFI_INVALID_PARAMETER is returned.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

SyncInterruptTransfer()

Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL  *This,
  IN     UINT8                     DeviceAddress,
  IN     UINT8                     EndPointAddress,
  IN     UINT8                     DeviceSpeed,
  IN     UINTN                     MaximumPacketLength,
  IN OUT VOID                      *Data,
  IN OUT UINTN                     *DataLength,
  IN OUT UINT8                     *DataToggle,
  IN     UINTN                     TimeOut,
  OUT    UINT32                    *TransferResult
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller’s responsibility to make sure that the EndPointAddress represents an interrupt endpoint.
DeviceSpeed Indicates device speed.
MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving.
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 transferred.
DataToggle A pointer to the data toggle value. On input, it indicates the initial data toggle value the synchronous interrupt transfer should adopt; on output, it is updated to indicate the data toggle value of the subsequent synchronous interrupt transfer.
TimeOut Indicates the maximum time, in milliseconds, which the transfer is allowed to complete.
TransferResult A pointer to the detailed result information from the synchronous interrupt transfer.

Description
This function is used to submit a synchronous interrupt transfer to a target endpoint of a USB device. The target endpoint is specified by DeviceAddress and EndpointAddress. In the USB Specification, Revision2.0, interrupt transfer is one of the four USB transfer types. In the EFI_USB2_HC_PROTOCOL, interrupt transfer is divided further into synchronous interrupt transfer and asynchronous interrupt transfer.

The synchronous interrupt transfer is designed to retrieve small amounts of data from a USB device through an interrupt endpoint. A synchronous interrupt transfer is only executed once for each request. This is the most significant difference from the asynchronous interrupt transfer.

If the synchronous interrupt transfer is successful, then EFI_SUCCESS is returned. If the USB transfer cannot be completed within the timeout specified by 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 TransferResult.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • Data transfer direction indicated by EndPointAddress is not EfiUsbDataIn.
  • Data is NULL.
  • DataLength is 0.
  • MaximumPacketLength is not valid. The legal value of this parameter should be 3072 or less for high-speed device, 64 or less for a full-speed device; for a slow device, it is limited to 8 or less. For the full-speed device, it should be 8, 16, 32, or 64; for the slow device, it is limited to 8.
  • DataToggle points to a value other than 0 and 1.
  • TransferResult is NULL.

Status Codes Returned

Status Code Description
EFI_SUCCESS The synchronous interrupt transfer was completed successfully.
EFI_OUT_OF_RESOURCES The synchronous interrupt transfer could not be submitted due to lack of resource.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above.
EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout.
EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. Caller should check TransferResult for detailed error information.

IsochronousTransfer()

Submits isochronous transfer to an isochronous endpoint of a USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL            *This,
  IN     UINT8                               DeviceAddress,
  IN     UINT8                               EndPointAddress,
  IN     UINT8                               DeviceSpeed,
  IN     UINTN                               MaximumPacketLength,
  IN     UINT8                               DataBuffersNumber,
  IN OUT VOID                                *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
  IN     UINTN                               DataLength,
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
  OUT    UINT32                              *TransferResult
  );
#define EFI_USB_MAX_ISO_BUFFER_NUM  7
#define EFI_USB_MAX_ISO_BUFFER_NUM1 2

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is 0). It is the caller’s responsibility to make sure that the EndPointAddress represents an isochronous endpoint.
DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL and EFI_USB_SPEED_HIGH.
MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving. For isochronous endpoints, this value is used to reserve the bus time in the schedule, required for the per-frame data payloads. The pipe may, on an ongoing basis, actually use less bandwidth than that reserved.
DataBuffersNumber Number of data buffers prepared for the transfer.
Data Array of pointers to the buffers 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.
Translator A pointer to the transaction translator data.
TransferResult A pointer to the detail result information of the isochronous transfer.

Description
This function is used to submit isochronous transfer to a target endpoint of a USB device. The target endpoint is specified by DeviceAddress and EndpointAddress. Isochronous transfers are used when working with isochronous date. It provides periodic, continuous communication between the host and a device. Isochronous transfers can be used only by full-speed and high-speed devices.

High-speed isochronous transfers can be performed using multiple data buffers. The number of buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For full-speed isochronous transfers this value is ignored.

Data represents a list of pointers to the data buffers. For full-speed isochronous transfers only the data pointed by Data[0] shall be used. For high-speed isochronous transfers and for the split transactions depending on DataLength there several data buffers can be used. For the high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM. For split transactions performed on full-speed device by high-speed host controller the total number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1 See “Related Definitions” for the EFI_USB_MAX_ISO_BUFFER_NUM and EFI_USB_MAX_ISO_BUFFER_NUM1 values.

If the isochronous transfer is successful, then EFI_SUCCESS is returned. The isochronous transfer is designed to be completed within one USB frame time, if it cannot be completed, 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 TransferResult.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • Data is NULL.
  • DataLength is 0.
  • MaximumPacketLength is larger than 1023.
  • TransferResult is NULL.

Status Codes Returned

Status Code Description
EFI_SUCCESS The isochronous transfer was completed successfully.
EFI_OUT_OF_RESOURCES The isochronous transfer could not be submitted due to lack of resource.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above.
EFI_TIMEOUT The isochronous transfer cannot be completed within the one USB frame time.
EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. Caller should check TransferResult for detailed error information.
EFI_UNSUPPORTED The implementation doesn’t support an Isochronous transfer function.

AsyncIsochronousTransfer()

Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER) (
  IN     EFI_USB2_HC_PROTOCOL                *This,
  IN     UINT8                               DeviceAddress,
  IN     UINT8                               EndPointAddress,
  IN     UINT8                               DeviceSpeed,
  IN     UINTN                               MaximumPacketLength,
  IN     UINT8                               DataBuffersNumber,
  IN OUT VOID                                *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
  IN     UINTN                               DataLength,
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
  IN     EFI_ASYNC_USB_TRANSFER_CALLBACK     IsochronousCallBack,
  IN     VOID                                *Context OPTIONAL
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration.
EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller’s responsibility to make sure that the EndPointAddress represents an isochronous endpoint.
DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL and EFI_USB_SPEED_HIGH.
MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving. For isochronous endpoints, this value is used to reserve the bus time in the schedule, required for the per-frame data payloads. The pipe may, on an ongoing basis, actually use less bandwidth than that reserved.
DataBuffersNumber Number of data buffers prepared for the transfer.
Data Array of pointers to the buffers 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.
Translator A pointer to the transaction translator data.
IsochronousCallback The Callback function. This function is called if the requested isochronous transfer is completed.
Context Data passed to the IsochronousCallback function. This is an optional parameter and may be NULL.

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.

The target endpoint is specified by DeviceAddress and EndpointAddress. Isochronous transfers are used when working with isochronous date. It provides periodic, continuous communication between the host and a device. Isochronous transfers can be used only by full-speed and high-speed devices.

High-speed isochronous transfers can be performed using multiple data buffers. The number of buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For full-speed isochronous transfers this value is ignored.

Data represents a list of pointers to the data buffers. For full-speed isochronous transfers only the data pointed by Data[0] shall be used. For high-speed isochronous transfers and for the split transactions depending on DataLength there several data buffers can be used. For the high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM. For split transactions performed on full-speed device by high-speed host controller the total number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1 See “Related Definitions” in IsochronousTransfer() section for the EFI_USB_MAX_ISO_BUFFER_NUM and EFI_USB_MAX_ISO_BUFFER_NUM1 values.

EFI_INVALID_PARAMETER is returned if one of the following conditions is satisfied:

  • Data is NULL.
  • DataLength is 0.
  • MaximumPacketLength is larger than 1023.

Status Codes Returned

Status Code Description
EFI_SUCCESS The asynchronous isochronous transfer was completed successfully.
EFI_OUT_OF_RESOURCES The asynchronous isochronous transfer could not be submitted due to lack of resource.
EFI_INVALID_PARAMETER Some parameters are invalid. The possible invalid parameters are described in “Description” above.
EFI_UNSUPPORTED The implementation doesn’t support Isochronous transfer function

GetRootHubPortStatus()

Retrieves the current status of a USB root hub port.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS) (
  IN  EFI_USB2_HC_PROTOCOL *This,
  IN  UINT8                PortNumber,
  OUT EFI_USB_PORT_STATUS  *PortStatus
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
PortNumber Specifies the root hub port from which the status is to be retrieved. This value is zero based. For example, if a root hub has two ports, then the first port is numbered 0, and the second port is numbered 1.
PortStatus A pointer to the current port status bits and port status change bits.


Description
This function is used to retrieve the status of the root hub port specified by PortNumber.

EFI_USB_PORT_STATUS describes the port status of a specified USB port. This data structure is designed to be common to both a USB root hub port and a USB hub port.

The number of root hub ports attached to the USB host controller can be determined with the function GetRootHubPortStatus(). If PortNumber is greater than or equal to the number of ports returned by GetRootHubPortNumber(), then EFI_INVALID_PARAMETER is returned. Otherwise, the status of the USB root hub port is returned in PortStatus, and EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The status of the USB root hub port specified by PortNumber was returned in PortStatus.
EFI_INVALID_PARAMETER PortNumber is invalid.

SetRootHubPortFeature()

Sets a feature for the specified root hub port.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE) (
  IN EFI_USB2_HC_PROTOCOL  *This,
  IN UINT8                 PortNumber,
  IN EFI_USB_PORT_FEATURE  PortFeature
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
PortNumber Specifies the root hub port whose feature is requested to be set. This value is zero based. For example, if a root hub has two ports, then the first port is number 0, and the second port is numbered 1.
PortFeature Indicates the feature selector associated with the feature set request.

Description
This function sets the feature specified by PortFeature for the USB root hub port specified by PortNumber. Setting a feature enables that feature or starts a process associated with that feature.

The number of root hub ports attached to the USB host controller can be determined with the function GetRootHubPortStatus(). If PortNumber is greater than or equal to the number of ports returned by GetRootHubPortNumber(), then EFI_INVALID_PARAMETER is returned. If PortFeature is not EfiUsbPortEnable, EfiUsbPortSuspend, EfiUsbPortReset nor EfiUsbPortPower, then EFI_INVALID_PARAMETER is returned.

Status Codes Returned

Status Cod Description
EFI_SUCCESS The feature specified by PortFeature was set for the USB root hub port specified by PortNumber.
EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.

ClearRootHubPortFeature()

Clears a feature for the specified root hub port.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE) (
  IN EFI_USB2_HC_PROTOCOL  *This
  IN UINT8                 PortNumber,
  IN EFI_USB_PORT_FEATURE  PortFeature
  );

Parameters

Parameter Description
This A pointer to the EFI_USB2_HC_PROTOCOL instance.
PortNumber Specifies the root hub port whose feature is requested to be cleared. This value is zero-based. For example, if a root hub has two ports, then the first port is number 0, and the second port is numbered 1.
PortFeature Indicates the feature selector associated with the feature clear request.

Description
This function clears the feature specified by PortFeature for the USB root hub port specified by PortNumber. Clearing a feature disables that feature or stops a process associated with that feature.

The number of root hub ports attached to the USB host controller can be determined with the function GetRootHubPortStatus(). If PortNumber is greater than or equal to the number of ports returned by GetRootHubPortNumber(), then EFI_INVALID_PARAMETER is returned. If PortFeature is not EfiUsbPortEnable, EfiUsbPortSuspend, EfiUsbPortPower, EfiUsbPortConnectChange, EfiUsbPortResetChange, EfiUsbPortEnableChange, EfiUsbPortSuspendChange, or EfiUsbPortOverCurrentChange, then EFI_INVALID_PARAMETER is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The feature specified by PortFeature was cleared for the USB root hub port specified by PortNumber.
EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.

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

Personal tools