| /** @file |
| EFI_USB_HC_PROTOCOL as defined in EFI 1.10. |
| |
| The USB Host Controller Protocol is used by code, typically USB bus drivers, |
| running in the EFI boot services environment, to perform data transactions |
| over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. |
| |
| Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| **/ |
| |
| #ifndef _USB_HOSTCONTROLLER_H_ |
| #define _USB_HOSTCONTROLLER_H_ |
| |
| #include <Protocol/Usb2HostController.h> |
| |
| #define EFI_USB_HC_PROTOCOL_GUID \ |
| { \ |
| 0xf5089266, 0x1aa0, 0x4953, {0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 } \ |
| } |
| |
| /// |
| /// Forward reference for pure ANSI compatability |
| /// |
| typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL; |
| |
| // |
| // Protocol definitions |
| // |
| |
| /** |
| Provides software reset for the USB host controller. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param Attributes A bit mask of the reset operation to perform. |
| |
| @retval EFI_SUCCESS The reset operation succeeded. |
| @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported |
| by the host controller hardware. |
| @retval EFI_INVALID_PARAMETER Attributes is not valid. |
| @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_RESET)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT16 Attributes |
| ); |
| |
| /** |
| Retrieves current state of the USB host controller. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param State A pointer to the EFI_USB_HC_STATE data structure that |
| indicates current state of the USB host controller. |
| |
| @retval EFI_SUCCESS The state information of the host controller was returned in State. |
| @retval EFI_INVALID_PARAMETER State is NULL. |
| @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's |
| current state. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_GET_STATE)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| OUT EFI_USB_HC_STATE *State |
| ); |
| |
| /** |
| Sets the USB host controller to a specific state. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param State Indicates the state of the host controller that will be set. |
| |
| @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by |
| State. |
| @retval EFI_INVALID_PARAMETER State is NULL. |
| @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_SET_STATE)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN EFI_USB_HC_STATE State |
| ); |
| |
| /** |
| Submits control transfer to a target USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param IsSlowDevice Indicates whether the target device is slow device or full-speed |
| device. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer endpoint is capable of sending or receiving. |
| @param Request A pointer to the USB device request that will be sent to the USB |
| device. |
| @param TransferDirection Specifies the data direction for the transfer. There are three |
| values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. |
| @param Data A pointer to the buffer of data that will be transmitted to USB |
| device or received from USB device. |
| @param DataLength On input, indicates the size, in bytes, of the data buffer specified |
| by Data. On output, indicates the amount of data actually |
| transferred. |
| @param TimeOut Indicates the maximum time, in milliseconds, which the transfer |
| is allowed to complete. |
| @param TransferResult A pointer to the detailed result information generated by this |
| control transfer. |
| |
| @retval EFI_SUCCESS The control transfer was completed successfully. |
| @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| @retval EFI_TIMEOUT The control transfer failed due to timeout. |
| @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN BOOLEAN IsSlowDevice, |
| IN UINT8 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, |
| OUT UINT32 *TransferResult |
| ); |
| |
| /** |
| Submits bulk transfer to a bulk endpoint of a USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param 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. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer endpoint is capable of sending or receiving. |
| @param Data A pointer to the buffer of data that will be transmitted to USB |
| device or received from USB device. |
| @param DataLength On input, indicates the size, in bytes, of the data buffer specified |
| by Data. On output, indicates the amount of data actually |
| transferred. |
| @param DataToggle A pointer to the data toggle value. |
| @param TimeOut Indicates the maximum time, in milliseconds, which the transfer |
| is allowed to complete. |
| @param TransferResult A pointer to the detailed result information of the bulk transfer. |
| |
| @retval EFI_SUCCESS The bulk transfer was completed successfully. |
| @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| @retval EFI_TIMEOUT The bulk transfer failed due to timeout. |
| @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_BULK_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN UINT8 EndPointAddress, |
| IN UINT8 MaximumPacketLength, |
| IN OUT VOID *Data, |
| IN OUT UINTN *DataLength, |
| IN OUT UINT8 *DataToggle, |
| IN UINTN TimeOut, |
| OUT UINT32 *TransferResult |
| ); |
| |
| /** |
| Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param 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. |
| @param IsSlowDevice Indicates whether the target device is slow device or full-speed |
| device. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer endpoint is capable of sending or receiving. |
| @param 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. |
| @param 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. |
| @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous |
| interrupt transfer is polled. |
| @param 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. |
| @param CallBackFunction The Callback function. This function is called at the rate specified by |
| PollingInterval. This parameter is only required when IsNewTransfer is TRUE. |
| @param Context The context that is passed to the CallBackFunction. |
| |
| @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully |
| submitted or canceled. |
| @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| @retval EFI_TIMEOUT The bulk transfer failed due to timeout. |
| @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN UINT8 EndPointAddress, |
| IN BOOLEAN IsSlowDevice, |
| IN UINT8 MaxiumPacketLength, |
| 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 |
| ); |
| |
| /** |
| Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param 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. |
| @param IsSlowDevice Indicates whether the target device is slow device or full-speed |
| device. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer endpoint is capable of sending or receiving. |
| @param Data A pointer to the buffer of data that will be transmitted to USB |
| device or received from USB device. asynchronous interrupt pipe is canceled. |
| @param DataLength On input, the size, in bytes, of the data buffer specified by Data. |
| On output, the number of bytes transferred. |
| @param 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. |
| @param TimeOut Indicates the maximum time, in milliseconds, which the transfer |
| is allowed to complete. |
| @param TransferResult A pointer to the detailed result information from the synchronous |
| interrupt transfer. |
| |
| @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully. |
| @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout. |
| @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN UINT8 EndPointAddress, |
| IN BOOLEAN IsSlowDevice, |
| IN UINT8 MaximumPacketLength, |
| IN OUT VOID *Data, |
| IN OUT UINTN *DataLength, |
| IN OUT UINT8 *DataToggle, |
| IN UINTN TimeOut, |
| OUT UINT32 *TransferResult |
| ); |
| |
| /** |
| Submits isochronous transfer to an isochronous endpoint of a USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param 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. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer endpoint is capable of sending or receiving. |
| @param Data A pointer to the buffer of data that will be transmitted to USB |
| device or received from USB device. asynchronous interrupt pipe is canceled. |
| @param DataLength Specifies the length, in bytes, of the data to be sent to or received |
| from the USB device. |
| @param TransferResult A pointer to the detailed result information from the isochronous |
| transfer. |
| |
| @retval EFI_SUCCESS The isochronous transfer was completed successfully. |
| @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| @retval EFI_TIMEOUT The isochronous transfer failed due to timeout. |
| @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN UINT8 EndPointAddress, |
| IN UINT8 MaximumPacketLength, |
| IN OUT VOID *Data, |
| IN UINTN DataLength, |
| OUT UINT32 *TransferResult |
| ); |
| |
| /** |
| Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param DeviceAddress Represents the address of the target device on the USB, which is |
| assigned during USB enumeration. |
| @param 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. |
| @param MaximumPacketLength Indicates the maximum packet size that the default control |
| transfer 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 perframe data payloads. The pipe may, on an ongoing basis, |
| actually use less bandwidth than that reserved. |
| @param Data A pointer to the buffer of data that will be transmitted to USB |
| device or received from USB device. asynchronous interrupt pipe is canceled. |
| @param DataLength Specifies the length, in bytes, of the data to be sent to or received |
| from the USB device. |
| @param IsochronousCallback The Callback function.This function is called if the requested |
| isochronous transfer is completed. |
| @param Context Data passed to the IsochronousCallback function. This is |
| an optional parameter and may be NULL. |
| |
| @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully. |
| @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources. |
| @retval EFI_INVALID_PARAMETER Some parameters are invalid. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 DeviceAddress, |
| IN UINT8 EndPointAddress, |
| IN UINT8 MaximumPacketLength, |
| IN OUT VOID *Data, |
| IN UINTN DataLength, |
| IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, |
| IN VOID *Context OPTIONAL |
| ); |
| |
| /** |
| Retrieves the number of root hub ports. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param PortNumber A pointer to the number of the root hub ports. |
| |
| @retval EFI_SUCCESS The port number was retrieved successfully. |
| @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number. |
| @retval EFI_INVALID_PARAMETER PortNumber is NULL. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| OUT UINT8 *PortNumber |
| ); |
| |
| /** |
| Retrieves the current status of a USB root hub port. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param 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. |
| @param PortStatus A pointer to the current port status bits and port status change bits. |
| |
| @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber |
| was returned in PortStatus. |
| @retval EFI_INVALID_PARAMETER PortNumber is invalid. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 PortNumber, |
| OUT EFI_USB_PORT_STATUS *PortStatus |
| ); |
| |
| /** |
| Sets a feature for the specified root hub port. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param 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. |
| @param PortFeature Indicates the feature selector associated with the feature set |
| request. |
| |
| @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB |
| root hub port specified by PortNumber. |
| @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 PortNumber, |
| IN EFI_USB_PORT_FEATURE PortFeature |
| ); |
| |
| /** |
| Clears a feature for the specified root hub port. |
| |
| @param This A pointer to the EFI_USB_HC_PROTOCOL instance. |
| @param 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. |
| @param PortFeature Indicates the feature selector associated with the feature clear |
| request. |
| |
| @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB |
| root hub port specified by PortNumber. |
| @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)( |
| IN EFI_USB_HC_PROTOCOL *This, |
| IN UINT8 PortNumber, |
| IN EFI_USB_PORT_FEATURE PortFeature |
| ); |
| |
| |
| /// |
| /// The EFI_USB_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_USB_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_USB_HC_PROTOCOL instance. |
| /// |
| struct _EFI_USB_HC_PROTOCOL { |
| EFI_USB_HC_PROTOCOL_RESET Reset; |
| EFI_USB_HC_PROTOCOL_GET_STATE GetState; |
| EFI_USB_HC_PROTOCOL_SET_STATE SetState; |
| EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer; |
| EFI_USB_HC_PROTOCOL_BULK_TRANSFER BulkTransfer; |
| EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer; |
| EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer; |
| EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer; |
| EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer; |
| EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; |
| EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; |
| EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; |
| EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; |
| /// |
| /// 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. |
| /// |
| UINT16 MajorRevision; |
| /// |
| /// 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. |
| /// |
| UINT16 MinorRevision; |
| }; |
| |
| extern EFI_GUID gEfiUsbHcProtocolGuid; |
| |
| #endif |