/** @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
- 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
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\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
0x3e745226, 0x9818, 0x45b6, {0xa2, 0xac, 0xd7, 0xcd, 0xe, 0x8b, 0xa2, 0xbc } \\r
}\r
\r
-//\r
-// Forward reference for pure ANSI compatability\r
-//\r
+///\r
+/// Forward reference for pure ANSI compatability\r
+///\r
typedef struct _EFI_USB2_HC_PROTOCOL EFI_USB2_HC_PROTOCOL;\r
\r
\r
typedef struct {\r
- UINT16 PortStatus;\r
- UINT16 PortChangeStatus;\r
+ UINT16 PortStatus; ///< Contains current port status bitmap.\r
+ UINT16 PortChangeStatus; ///< Contains current port status change bitmap.\r
} EFI_USB_PORT_STATUS;\r
\r
-//\r
-// Constant value for Port Status & Port Change Status\r
-//\r
+///\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_SUSPEND 0x0004\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
+///\r
#define USB_PORT_STAT_C_CONNECTION 0x0001\r
#define USB_PORT_STAT_C_ENABLE 0x0002\r
#define USB_PORT_STAT_C_SUSPEND 0x0004\r
#define USB_PORT_STAT_C_RESET 0x0010\r
\r
\r
-//\r
-// Usb port features\r
-//\r
+///\r
+/// Usb port features value\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
EfiUsbPortEnable = 1,\r
EfiUsbPortSuspend = 2,\r
EfiUsbPortResetChange = 20\r
} EFI_USB_PORT_FEATURE;\r
\r
-\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_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;\r
- UINT8 TranslatorPortNumber;\r
+ UINT8 TranslatorHubAddress; ///< device address\r
+ UINT8 TranslatorPortNumber; ///< the port number of the hub that device is connected to.\r
} EFI_USB2_HC_TRANSACTION_TRANSLATOR;\r
\r
//\r
OUT UINT8 *MaxSpeed,\r
OUT UINT8 *PortNumber,\r
OUT UINT8 *Is64BitCapable\r
- )\r
-;\r
+ );\r
\r
#define EFI_USB_HC_RESET_GLOBAL 0x0001\r
#define EFI_USB_HC_RESET_HOST_CONTROLLER 0x0002\r
(EFIAPI *EFI_USB2_HC_PROTOCOL_RESET)(\r
IN EFI_USB2_HC_PROTOCOL *This,\r
IN UINT16 Attributes\r
- )\r
-;\r
+ );\r
\r
/**\r
-\r
- @param EfiUsbHcStateHalt The host controller is in halt\r
- state. No USB transactions can occur\r
- while in this state. The host\r
- controller can enter this state for\r
- three reasons: 1) After host\r
- controller hardware reset. 2)\r
- Explicitly set by software. 3)\r
- Triggered by a fatal error such as\r
- consistency check failure.\r
-\r
-\r
- @param EfiUsbHcStateOperational The host controller is in an\r
- operational state. When in\r
- this state, the host\r
- controller can execute bus\r
- traffic. This state must be\r
- explicitly set to enable the\r
- USB bus traffic.\r
-\r
-\r
- @param EfiUsbHcStateSuspend The host controller is in the\r
- suspend state. No USB\r
- transactions can occur while in\r
- this state. The host controller\r
- enters this state for the\r
- following reasons: 1) Explicitly\r
- set by software. 2) Triggered\r
- when there is no bus traffic for\r
- 3 microseconds.\r
-\r
+ Enumration value for status of USB HC.\r
**/\r
typedef enum {\r
- EfiUsbHcStateHalt,\r
- EfiUsbHcStateOperational,\r
- EfiUsbHcStateSuspend,\r
- EfiUsbHcStateMaximum\r
+ EfiUsbHcStateHalt, ///< The host controller is in halt\r
+ ///< state. No USB transactions can occur\r
+ ///< while in this state. The host\r
+ ///< controller can enter this state for\r
+ ///< three reasons: 1) After host\r
+ ///< controller hardware reset. 2)\r
+ ///< Explicitly set by software. 3)\r
+ ///< Triggered by a fatal error such as\r
+ ///< consistency check failure.\r
+\r
+ EfiUsbHcStateOperational, ///< The host controller is in an\r
+ ///< operational state. When in\r
+ ///< this state, the host\r
+ ///< controller can execute bus\r
+ ///< traffic. This state must be\r
+ ///< explicitly set to enable the\r
+ ///< USB bus traffic.\r
+\r
+ EfiUsbHcStateSuspend, ///< The host controller is in the\r
+ ///< suspend state. No USB\r
+ ///< transactions can occur while in\r
+ ///< this state. The host controller\r
+ ///< enters this state for the\r
+ ///< following reasons: 1) Explicitly\r
+ ///< set by software. 2) Triggered\r
+ ///< when there is no bus traffic for\r
+ ///< 3 microseconds.\r
+\r
+ EfiUsbHcStateMaximum ///< Maximum value for enumration value of HC status.\r
} EFI_USB_HC_STATE;\r
\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
\r
/**\r
Sets the USB host controller to a specific state.\r
(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_STATE)(\r
IN EFI_USB2_HC_PROTOCOL *This,\r
IN EFI_USB_HC_STATE State\r
- )\r
-;\r
+ );\r
\r
/**\r
Submits control transfer to a target USB device.\r
IN UINTN TimeOut,\r
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
OUT UINT32 *TransferResult\r
- )\r
-;\r
+ );\r
\r
#define EFI_USB_MAX_BULK_BUFFER_NUM 10\r
\r
IN UINTN TimeOut,\r
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
OUT UINT32 *TransferResult\r
- )\r
-;\r
+ );\r
\r
/**\r
Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.\r
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator OPTIONAL,\r
IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL,\r
IN VOID *Context OPTIONAL\r
- )\r
-;\r
+ );\r
\r
/**\r
Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.\r
IN UINTN TimeOut,\r
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
OUT UINT32 *TransferResult\r
- )\r
-;\r
+ );\r
\r
#define EFI_USB_MAX_ISO_BUFFER_NUM 7\r
#define EFI_USB_MAX_ISO_BUFFER_NUM1 2\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
IN UINTN DataLength,\r
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
OUT UINT32 *TransferResult\r
- )\r
-;\r
+ );\r
\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
IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,\r
IN VOID *Context OPTIONAL\r
- )\r
-;\r
+ );\r
\r
/**\r
Retrieves the current status of a USB root hub port.\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
Sets a feature for the specified root hub port.\r
IN EFI_USB2_HC_PROTOCOL *This,\r
IN UINT8 PortNumber,\r
IN EFI_USB_PORT_FEATURE PortFeature\r
- )\r
-;\r
+ );\r
\r
/**\r
Clears a feature for the specified root hub port.\r
IN EFI_USB2_HC_PROTOCOL *This,\r
IN UINT8 PortNumber,\r
IN EFI_USB_PORT_FEATURE PortFeature\r
- )\r
-;\r
-\r
-/** \r
- @par Protocol Description:\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
- @param GetCapability\r
- Retrieves the capabilities of the USB host controller. \r
-\r
- @param Reset\r
- Software reset of USB. \r
-\r
- @param GetState\r
- Retrieves the current state of the USB host controller. \r
-\r
- @param SetState\r
- Sets the USB host controller to a specific state. \r
-\r
- @param ControlTransfer\r
- Submits a control transfer to a target USB device. \r
-\r
- @param BulkTransfer\r
- Submits a bulk transfer to a bulk endpoint of a USB device. \r
-\r
- @param AsyncInterruptTransfer\r
- Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. \r
-\r
- @param SyncInterruptTransfer\r
- Submits a synchronous interrupt transfer to an interrupt endpoint of a USB device. \r
-\r
- @param IsochronousTransfer\r
- Submits isochronous transfer to an isochronous endpoint of a USB device. \r
-\r
- @param AsyncIsochronousTransfer\r
- Submits nonblocking USB isochronous transfer. \r
-\r
- @param GetRootHubPortStatus\r
- Retrieves the status of the specified root hub port. \r
-\r
- @param SetRootHubPortFeature\r
- Sets the feature for the specified root hub port. \r
-\r
- @param ClearRootHubPortFeature\r
- Clears the feature for the specified root hub port. \r
-\r
- @param MajorRevision\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
- @param MinorRevision\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
+ );\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
+/// instance, and an EFI_USB2_HC_PROTOCOL instance.\r
+///\r
struct _EFI_USB2_HC_PROTOCOL {\r
EFI_USB2_HC_PROTOCOL_GET_CAPABILITY GetCapability;\r
EFI_USB2_HC_PROTOCOL_RESET Reset;\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
+ /// 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
+ ///\r
UINT16 MinorRevision;\r
};\r
\r
projects / mirror_edk2.git / blobdiff