/** @file\r
EFI_USB2_HC_PROTOCOL as defined in UEFI 2.0.\r
- The USB Host Controller Protocol is used by code, typically USB bus drivers, \r
- running in the EFI boot services environment, to perform data transactions over \r
+ The USB Host Controller Protocol is used by code, typically USB bus drivers,\r
+ running in the EFI boot services environment, to perform data transactions over\r
a USB bus. In addition, it provides an abstraction for the root hub of the USB bus.\r
\r
- Copyright (c) 2006 - 2008, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution. The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
#ifndef _USB2_HOSTCONTROLLER_H_\r
#define _USB2_HOSTCONTROLLER_H_\r
\r
-#include <IndustryStandard/Usb.h>\r
#include <Protocol/UsbIo.h>\r
\r
#define EFI_USB2_HC_PROTOCOL_GUID \\r
} EFI_USB_PORT_STATUS;\r
\r
///\r
-/// EFI_USB_PORT_STATUS.PortStatus bit definition \r
+/// EFI_USB_PORT_STATUS.PortStatus bit definition\r
///\r
#define USB_PORT_STAT_CONNECTION 0x0001\r
#define USB_PORT_STAT_ENABLE 0x0002\r
#define USB_PORT_STAT_POWER 0x0100\r
#define USB_PORT_STAT_LOW_SPEED 0x0200\r
#define USB_PORT_STAT_HIGH_SPEED 0x0400\r
-#define USB_PORT_STAT_OWNER 0x0800\r
+#define USB_PORT_STAT_SUPER_SPEED 0x0800\r
+#define USB_PORT_STAT_OWNER 0x2000\r
\r
///\r
-/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition \r
+/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition\r
///\r
#define USB_PORT_STAT_C_CONNECTION 0x0001\r
#define USB_PORT_STAT_C_ENABLE 0x0002\r
\r
///\r
/// Usb port features value\r
-/// Each value indicates its bit index in the port status and status change bitmaps, \r
+/// Each value indicates its bit index in the port status and status change bitmaps,\r
/// if combines these two bitmaps into a 32-bit bitmap.\r
///\r
typedef enum {\r
#define EFI_USB_SPEED_FULL 0x0000 ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC.\r
#define EFI_USB_SPEED_LOW 0x0001 ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC.\r
#define EFI_USB_SPEED_HIGH 0x0002 ///< 480 Mb/s, USB 2.0 EHCI HC.\r
+#define EFI_USB_SPEED_SUPER 0x0003 ///< 4.8 Gb/s, USB 3.0 XHCI HC.\r
\r
typedef struct {\r
UINT8 TranslatorHubAddress; ///< device address\r
///< Explicitly set by software. 3)\r
///< Triggered by a fatal error such as\r
///< consistency check failure.\r
- \r
+\r
EfiUsbHcStateOperational, ///< The host controller is in an\r
///< operational state. When in\r
///< this state, the host\r
///< traffic. This state must be\r
///< explicitly set to enable the\r
///< USB bus traffic.\r
- \r
+\r
EfiUsbHcStateSuspend, ///< The host controller is in the\r
///< suspend state. No USB\r
///< transactions can occur while in\r
///< set by software. 2) Triggered\r
///< when there is no bus traffic for\r
///< 3 microseconds.\r
- \r
+\r
EfiUsbHcStateMaximum ///< Maximum value for enumration value of HC status.\r
} EFI_USB_HC_STATE;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_STATE)(\r
- IN CONST EFI_USB2_HC_PROTOCOL *This,\r
+ IN EFI_USB2_HC_PROTOCOL *This,\r
OUT EFI_USB_HC_STATE *State\r
);\r
\r
/**\r
Submits isochronous transfer to an isochronous endpoint of a USB device.\r
\r
+ This function is used to submit isochronous transfer to a target endpoint of a USB device.\r
+ The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers are\r
+ used when working with isochronous date. It provides periodic, continuous communication between\r
+ the host and a device. Isochronous transfers can beused only by full-speed, high-speed, and\r
+ super-speed devices.\r
+\r
+ High-speed isochronous transfers can be performed using multiple data buffers. The number of\r
+ buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For\r
+ full-speed isochronous transfers this value is ignored.\r
+\r
+ Data represents a list of pointers to the data buffers. For full-speed isochronous transfers\r
+ only the data pointed by Data[0]shall be used. For high-speed isochronous transfers and for\r
+ the split transactions depending on DataLengththere several data buffers canbe used. For the\r
+ high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.\r
+\r
+ For split transactions performed on full-speed device by high-speed host controller the total\r
+ number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.\r
+ If the isochronous transfer is successful, then EFI_SUCCESSis returned. The isochronous transfer\r
+ is designed to be completed within one USB frame time, if it cannot be completed, EFI_TIMEOUT\r
+ is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR\r
+ is returned and the detailed status code will be returned in TransferResult.\r
+\r
+ EFI_INVALID_PARAMETERis returned if one of the following conditionsis satisfied:\r
+ - Data is NULL.\r
+ - DataLength is 0.\r
+ - DeviceSpeed is not one of the supported values listed above.\r
+ - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed devices,\r
+ and 1024 or less for high-speed and super-speed devices.\r
+ - TransferResult is NULL.\r
+\r
@param This A pointer to the EFI_USB2_HC_PROTOCOL instance.\r
@param DeviceAddress Represents the address of the target device on the USB.\r
@param EndPointAddress The combination of an endpoint number and an endpoint direction of the\r
target USB device.\r
- @param DeviceSpeed Indicates device speed.\r
+ @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL,\r
+ EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.\r
@param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of\r
sending or receiving.\r
@param DataBuffersNumber Number of data buffers prepared for the transfer.\r
/**\r
Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.\r
\r
+ This is an asynchronous type of USB isochronous transfer. If the caller submits a USB\r
+ isochronous transfer request through this function, this function will return immediately.\r
+\r
+ When the isochronous transfer completes, the IsochronousCallbackfunction will be triggered,\r
+ the caller can know the transfer results. If the transfer is successful, the caller can get\r
+ the data received or sent in this callback function.\r
+\r
+ The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers\r
+ are used when working with isochronous date. It provides periodic, continuous communication\r
+ between the host and a device. Isochronous transfers can be used only by full-speed, high-speed,\r
+ and super-speed devices.\r
+\r
+ High-speed isochronous transfers can be performed using multiple data buffers. The number of\r
+ buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For\r
+ full-speed isochronous transfers this value is ignored.\r
+\r
+ Data represents a list of pointers to the data buffers. For full-speed isochronous transfers\r
+ only the data pointed by Data[0] shall be used. For high-speed isochronous transfers and for\r
+ the split transactions depending on DataLength there several data buffers can be used. For\r
+ the high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.\r
+\r
+ For split transactions performed on full-speed device by high-speed host controller the total\r
+ number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.\r
+\r
+ EFI_INVALID_PARAMETER is returned if one of the following conditionsis satisfied:\r
+ - Data is NULL.\r
+ - DataLength is 0.\r
+ - DeviceSpeed is not one of the supported values listed above.\r
+ - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed\r
+ devices and 1024 or less for high-speed and super-speed devices.\r
+\r
@param This A pointer to the EFI_USB2_HC_PROTOCOL instance.\r
@param DeviceAddress Represents the address of the target device on the USB.\r
@param EndPointAddress The combination of an endpoint number and an endpoint direction of the\r
target USB device.\r
- @param DeviceSpeed Indicates device speed.\r
+ @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL,\r
+ EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.\r
@param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of\r
sending or receiving.\r
@param DataBuffersNumber Number of data buffers prepared for the transfer.\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)(\r
- IN CONST EFI_USB2_HC_PROTOCOL *This,\r
- IN CONST UINT8 PortNumber,\r
+ IN EFI_USB2_HC_PROTOCOL *This,\r
+ IN UINT8 PortNumber,\r
OUT EFI_USB_PORT_STATUS *PortStatus\r
);\r
\r
);\r
\r
///\r
-/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic \r
-/// data transactions over a USB bus, and USB root hub access. A device driver \r
-/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL \r
-/// instance that is associated with the USB bus to be managed. A device handle \r
-/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL \r
+/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic\r
+/// data transactions over a USB bus, and USB root hub access. A device driver\r
+/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL\r
+/// instance that is associated with the USB bus to be managed. A device handle\r
+/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL\r
/// instance, and an EFI_USB2_HC_PROTOCOL instance.\r
///\r
struct _EFI_USB2_HC_PROTOCOL {\r
EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus;\r
EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature;\r
EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature;\r
- \r
+\r
///\r
- /// The major revision number of the USB host controller. The revision information \r
- /// indicates the release of the Universal Serial Bus Specification with which the \r
+ /// The major revision number of the USB host controller. The revision information\r
+ /// indicates the release of the Universal Serial Bus Specification with which the\r
/// host controller is compliant.\r
///\r
UINT16 MajorRevision;\r
\r
///\r
- /// The minor revision number of the USB host controller. The revision information \r
- /// indicates the release of the Universal Serial Bus Specification with which the \r
- /// host controller is compliant. \r
+ /// The minor revision number of the USB host controller. The revision information\r
+ /// indicates the release of the Universal Serial Bus Specification with which the\r
+ /// host controller is compliant.\r
///\r
UINT16 MinorRevision;\r
};\r
projects / mirror_edk2.git / blobdiff