[mirror_edk2.git] / MdePkg / Include / Protocol / UsbIo.h

/** @file\r
  EFI Usb I/O Protocol\r
\r
  Copyright (c) 2006, 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
\r
**/\r
\r
#ifndef __USB_IO_H__\r
#define __USB_IO_H__\r
\r
#include <IndustryStandard/Usb.h>\r
\r
//\r
// Global ID for the USB I/O Protocol\r
//\r
#define EFI_USB_IO_PROTOCOL_GUID \\r
  { \\r
    0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \\r
  }\r
\r
typedef struct _EFI_USB_IO_PROTOCOL   EFI_USB_IO_PROTOCOL;\r
\r
//\r
// Related Definition for EFI USB I/O protocol\r
//\r
\r
//\r
// USB standard descriptors and reqeust\r
//\r
typedef USB_DEVICE_REQUEST        EFI_USB_DEVICE_REQUEST;\r
typedef USB_DEVICE_DESCRIPTOR     EFI_USB_DEVICE_DESCRIPTOR;\r
typedef USB_CONFIG_DESCRIPTOR     EFI_USB_CONFIG_DESCRIPTOR;\r
typedef USB_INTERFACE_DESCRIPTOR  EFI_USB_INTERFACE_DESCRIPTOR;\r
typedef USB_ENDPOINT_DESCRIPTOR   EFI_USB_ENDPOINT_DESCRIPTOR;\r
\r
//\r
// USB data transfer direction\r
//\r
typedef enum {\r
  EfiUsbDataIn,\r
  EfiUsbDataOut,\r
  EfiUsbNoData\r
} EFI_USB_DATA_DIRECTION;\r
\r
//\r
// USB Transfer Results\r
//\r
#define EFI_USB_NOERROR             0x00\r
#define EFI_USB_ERR_NOTEXECUTE      0x01\r
#define EFI_USB_ERR_STALL           0x02\r
#define EFI_USB_ERR_BUFFER          0x04\r
#define EFI_USB_ERR_BABBLE          0x08\r
#define EFI_USB_ERR_NAK             0x10\r
#define EFI_USB_ERR_CRC             0x20\r
#define EFI_USB_ERR_TIMEOUT         0x40\r
#define EFI_USB_ERR_BITSTUFF        0x80\r
#define EFI_USB_ERR_SYSTEM          0x100\r
\r
/**\r
  Async USB transfer callback routine.\r
\r
  @param  Data                  Data received or sent via the USB Asynchronous Transfer, if the\r
                                transfer completed successfully.\r
  @param  DataLength            The length of Data received or sent via the Asynchronous\r
                                Transfer, if transfer successfully completes.\r
  @param  Context               Data passed from UsbAsyncInterruptTransfer() request.\r
  @param  Status                Indicates the result of the asynchronous transfer.\r
\r
  @retval EFI_SUCCESS           The asynchronous USB transfer request has been successfully executed.\r
  @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (\r
  IN VOID         *Data,\r
  IN UINTN        DataLength,\r
  IN VOID         *Context,\r
  IN UINT32       Status\r
  );\r
\r
//\r
// Prototype for EFI USB I/O protocol\r
//\r
\r
\r
/**\r
  This function is used to manage a USB device with a control transfer pipe. A control transfer is\r
  typically used to perform device initialization and configuration.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  Request               A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  Direction             Indicates the data direction.\r
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                device or received from USB device.\r
  @param  Timeout               Indicating the transfer should be completed within this time frame.\r
                                The units are in milliseconds.\r
  @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
  @param  Status                A pointer to the result of the USB transfer.\r
\r
  @retval EFI_SUCCESS           The control transfer has been successfully executed.\r
  @retval EFI_DEVICE_ERROR      The transfer failed. The transfer status is returned in Status.\r
  @retval EFI_INVALID_PARAMETE  One or more parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
  @retval EFI_TIMEOUT           The control transfer fails due to timeout.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL                        *This,\r
  IN EFI_USB_DEVICE_REQUEST                     *Request,\r
  IN EFI_USB_DATA_DIRECTION                     Direction,\r
  IN UINT32                                     Timeout,\r
  IN OUT VOID                                   *Data OPTIONAL,\r
  IN UINTN                                      DataLength  OPTIONAL,\r
  OUT UINT32                                    *Status\r
  );\r
\r
/**\r
  This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are\r
  typically used to transfer large amounts of data to/from USB devices.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                device or received from USB device.\r
  @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
  @param  Timeout               Indicating the transfer should be completed within this time frame.\r
                                The units are in milliseconds.\r
  @param  Status                This parameter indicates the USB transfer status.\r
\r
  @retval EFI_SUCCESS           The bulk transfer has been successfully executed.\r
  @retval EFI_DEVICE_ERROR      The transfer failed. The transfer status is returned in Status.\r
  @retval EFI_INVALID_PARAMETE  One or more parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.\r
  @retval EFI_TIMEOUT           The control transfer fails due to timeout.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  IN UINT8                          DeviceEndpoint,\r
  IN OUT VOID                       *Data,\r
  IN OUT UINTN                      *DataLength,\r
  IN UINTN                          Timeout,\r
  OUT UINT32                        *Status\r
  );\r
\r
/**\r
  This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous\r
  Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,\r
  keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at\r
  a fixed rate.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  IsNewTransfer         If TRUE, a new transfer will be submitted to USB controller. If\r
                                FALSE, the interrupt transfer is deleted from the device's interrupt\r
                                transfer queue.\r
  @param  PollingInterval       Indicates the periodic rate, in milliseconds, that the transfer is to be\r
                                executed.\r
  @param  DataLength            Specifies the length, in bytes, of the data to be received from the\r
                                USB device.\r
  @param  Context               Data passed to the InterruptCallback function.\r
  @param  InterruptCallback     The Callback function. This function is called if the asynchronous\r
                                interrupt transfer is completed.\r
\r
  @retval EFI_SUCCESS           The asynchronous USB transfer request transfer has been successfully executed.\r
  @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL                                 *This,\r
  IN UINT8                                               DeviceEndpoint,\r
  IN BOOLEAN                                             IsNewTransfer,\r
  IN UINTN                                               PollingInterval    OPTIONAL,\r
  IN UINTN                                               DataLength         OPTIONAL,\r
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK                     InterruptCallBack  OPTIONAL,\r
  IN VOID                                                *Context OPTIONAL\r
  );\r
\r
/**\r
  This function is used to manage a USB device with an interrupt transfer pipe.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                device or received from USB device.\r
  @param  DataLength            On input, then size, in bytes, of the buffer Data. On output, the\r
                                amount of data actually transferred.\r
  @param  Timeout               The time out, in seconds, for this transfer.\r
  @param  Status                This parameter indicates the USB transfer status.\r
\r
  @retval EFI_SUCCESS           The sync interrupt transfer has been successfully executed.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
  @retval EFI_DEVICE_ERROR      The sync interrupt transfer request failed.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.\r
  @retval EFI_TIMEOUT           The transfer fails due to timeout.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  IN     UINT8                      DeviceEndpoint,\r
  IN OUT VOID                       *Data,\r
  IN OUT UINTN                      *DataLength,\r
  IN     UINTN                      Timeout,\r
  OUT    UINT32                     *Status\r
  );\r
\r
/**\r
  This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
  transfer is typically used to transfer streaming data.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                device or received from USB device.\r
  @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
  @param  Status                This parameter indicates the USB transfer status.\r
\r
  @retval EFI_SUCCESS           The isochronous transfer has been successfully executed.\r
  @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
  @retval EFI_DEVICE_ERROR      The transfer failed due to the reason other than timeout, The error status\r
                                is returned in Status.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.\r
  @retval EFI_TIMEOUT           The transfer fails due to timeout.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  IN     UINT8                      DeviceEndpoint,\r
  IN OUT VOID                       *Data,\r
  IN     UINTN                      DataLength,\r
  OUT    UINT32                     *Status\r
  );\r
\r
/**\r
  This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
  transfer is typically used to transfer streaming data.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
                                device.\r
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                device or received from USB device.\r
  @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
  @param  Context               Data passed to the IsochronousCallback() function.\r
  @param  IsochronousCallback   The IsochronousCallback() function.\r
\r
  @retval EFI_SUCCESS           The asynchronous isochronous transfer has been successfully submitted\r
                                to the system.\r
  @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (\r
  IN EFI_USB_IO_PROTOCOL              *This,\r
  IN UINT8                            DeviceEndpoint,\r
  IN OUT VOID                         *Data,\r
  IN     UINTN                        DataLength,\r
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK  IsochronousCallBack,\r
  IN VOID                             *Context OPTIONAL\r
  );\r
\r
/**\r
  Resets and reconfigures the USB controller. This function will work for all USB devices except\r
  USB Hub Controllers.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
\r
  @retval EFI_SUCCESS           The USB controller was reset.\r
  @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.\r
  @retval EFI_DEVICE_ERROR      An error occurred during the reconfiguration process.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_PORT_RESET) (\r
  IN EFI_USB_IO_PROTOCOL    *This\r
  );\r
\r
/**\r
  Retrieves the USB Device Descriptor.\r
\r
  @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  DeviceDescriptor      A pointer to the caller allocated USB Device Descriptor.\r
\r
  @retval EFI_SUCCESS           The device descriptor was retrieved successfully.\r
  @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.\r
  @retval EFI_NOT_FOUND         The device descriptor was not found. The device may not be configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  OUT EFI_USB_DEVICE_DESCRIPTOR     *DeviceDescriptor\r
  );\r
\r
/**\r
  Retrieves the USB Device Descriptor.\r
\r
  @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration\r
                                  Descriptor.\r
  @retval EFI_SUCCESS             The active configuration descriptor was retrieved successfully.\r
  @retval EFI_INVALID_PARAMETER   ConfigurationDescriptor is NULL.\r
  @retval EFI_NOT_FOUND           An active configuration descriptor cannot be found. The device may not\r
                                  be configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  OUT EFI_USB_CONFIG_DESCRIPTOR     *ConfigurationDescriptor\r
  );\r
\r
/**\r
  Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface\r
  within a USB device is equivalently to a USB Controller within the current configuration.\r
\r
  @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  InterfaceDescriptor     A pointer to the caller allocated USB Interface Descriptor within\r
                                  the configuration setting.\r
  @retval EFI_SUCCESS             The interface descriptor retrieved successfully.\r
  @retval EFI_INVALID_PARAMETER   InterfaceDescriptor is NULL.\r
  @retval EFI_NOT_FOUND           The interface descriptor cannot be found. The device may not be\r
                                  correctly configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  OUT EFI_USB_INTERFACE_DESCRIPTOR  *InterfaceDescriptor\r
  );\r
\r
/**\r
  Retrieves an Endpoint Descriptor within a USB Controller.\r
\r
  @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  EndpointIndex           Indicates which endpoint descriptor to retrieve.\r
  @param  EndpointDescriptor      A pointer to the caller allocated USB Endpoint Descriptor of\r
                                  a USB controller.\r
\r
  @retval EFI_SUCCESS             The endpoint descriptor was retrieved successfully.\r
  @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.\r
  @retval EFI_NOT_FOUND           The endpoint descriptor cannot be found. The device may not be\r
                                  correctly configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  IN  UINT8                         EndpointIndex,\r
  OUT EFI_USB_ENDPOINT_DESCRIPTOR   *EndpointDescriptor\r
  );\r
\r
/**\r
  Retrieves a Unicode string stored in a USB Device.\r
\r
  @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  LangID                  The Language ID for the string being retrieved.\r
  @param  StringID                The ID of the string being retrieved.\r
  @param  String                  A pointer to a buffer allocated by this function with\r
                                  AllocatePool() to store the string.\r
\r
  @retval EFI_SUCCESS             The string was retrieved successfully.\r
  @retval EFI_NOT_FOUND           The string specified by LangID and StringID was not found.\r
  @retval EFI_OUT_OF_RESOURCES    There are not enough resources to allocate the return buffer String.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  IN  UINT16                        LangID,\r
  IN  UINT8                         StringID,\r
  OUT CHAR16                        **String\r
  );\r
\r
/**\r
  Retrieves all the language ID codes that the USB device supports.\r
\r
  @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
  @param  LangIDTable             Language ID for the string the caller wants to get.\r
  @param  TableSize               The size, in bytes, of the table LangIDTable.\r
\r
  @retval EFI_SUCCESS             The support languages were retrieved successfully.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE) (\r
  IN EFI_USB_IO_PROTOCOL            *This,\r
  OUT UINT16                        **LangIDTable,\r
  OUT UINT16                        *TableSize\r
  );\r
\r
//\r
//  Protocol Interface Structure\r
//\r
struct _EFI_USB_IO_PROTOCOL {\r
  //\r
  // IO transfer\r
  //\r
  EFI_USB_IO_CONTROL_TRANSFER           UsbControlTransfer;\r
  EFI_USB_IO_BULK_TRANSFER              UsbBulkTransfer;\r
  EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER   UsbAsyncInterruptTransfer;\r
  EFI_USB_IO_SYNC_INTERRUPT_TRANSFER    UsbSyncInterruptTransfer;\r
  EFI_USB_IO_ISOCHRONOUS_TRANSFER       UsbIsochronousTransfer;\r
  EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;\r
\r
  //\r
  // Common device request\r
  //\r
  EFI_USB_IO_GET_DEVICE_DESCRIPTOR      UsbGetDeviceDescriptor;\r
  EFI_USB_IO_GET_CONFIG_DESCRIPTOR      UsbGetConfigDescriptor;\r
  EFI_USB_IO_GET_INTERFACE_DESCRIPTOR   UsbGetInterfaceDescriptor;\r
  EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR    UsbGetEndpointDescriptor;\r
  EFI_USB_IO_GET_STRING_DESCRIPTOR      UsbGetStringDescriptor;\r
  EFI_USB_IO_GET_SUPPORTED_LANGUAGE     UsbGetSupportedLanguages;\r
\r
  //\r
  // Reset controller's parent port\r
  //\r
  EFI_USB_IO_PORT_RESET                 UsbPortReset;\r
};\r
\r
extern EFI_GUID gEfiUsbIoProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	EFI Usb I/O Protocol\r
	3	\r
e3c6b3d9	4	Copyright (c) 2006, Intel Corporation\r
	5	All rights reserved. This program and the accompanying materials\r
	6	are licensed and made available under the terms and conditions of the BSD License\r
	7	which accompanies this distribution. The full text of the license may be found at\r
	8	http://opensource.org/licenses/bsd-license.php\r
d1f95000	9	\r
e3c6b3d9	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
e3c6b3d9	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
d1f95000	12	\r
d1f95000	13	**/\r
	14	\r
	15	#ifndef __USB_IO_H__\r
	16	#define __USB_IO_H__\r
	17	\r
	18	#include <IndustryStandard/Usb.h>\r
	19	\r
	20	//\r
	21	// Global ID for the USB I/O Protocol\r
	22	//\r
	23	#define EFI_USB_IO_PROTOCOL_GUID \\r
	24	{ \\r
	25	0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \\r
	26	}\r
	27	\r
	28	typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;\r
	29	\r
e3c6b3d9	30	//\r
	31	// Related Definition for EFI USB I/O protocol\r
	32	//\r
	33	\r
	34	//\r
	35	// USB standard descriptors and reqeust\r
	36	//\r
	37	typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST;\r
	38	typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR;\r
	39	typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR;\r
	40	typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR;\r
	41	typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR;\r
	42	\r
	43	//\r
	44	// USB data transfer direction\r
	45	//\r
	46	typedef enum {\r
	47	EfiUsbDataIn,\r
	48	EfiUsbDataOut,\r
	49	EfiUsbNoData\r
	50	} EFI_USB_DATA_DIRECTION;\r
	51	\r
	52	//\r
	53	// USB Transfer Results\r
	54	//\r
	55	#define EFI_USB_NOERROR 0x00\r
	56	#define EFI_USB_ERR_NOTEXECUTE 0x01\r
	57	#define EFI_USB_ERR_STALL 0x02\r
	58	#define EFI_USB_ERR_BUFFER 0x04\r
	59	#define EFI_USB_ERR_BABBLE 0x08\r
	60	#define EFI_USB_ERR_NAK 0x10\r
	61	#define EFI_USB_ERR_CRC 0x20\r
	62	#define EFI_USB_ERR_TIMEOUT 0x40\r
	63	#define EFI_USB_ERR_BITSTUFF 0x80\r
	64	#define EFI_USB_ERR_SYSTEM 0x100\r
	65	\r
	66	/**\r
d1f95000	67	Async USB transfer callback routine.\r
e3c6b3d9	68	\r
d1f95000	69	@param Data Data received or sent via the USB Asynchronous Transfer, if the\r
e3c6b3d9	70	transfer completed successfully.\r
d1f95000	71	@param DataLength The length of Data received or sent via the Asynchronous\r
e3c6b3d9	72	Transfer, if transfer successfully completes.\r
d1f95000	73	@param Context Data passed from UsbAsyncInterruptTransfer() request.\r
d1f95000	74	@param Status Indicates the result of the asynchronous transfer.\r
e3c6b3d9	75	\r
e3c6b3d9	76	@retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.\r
d1f95000	77	@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.\r
e3c6b3d9	78	\r
d1f95000	79	**/\r
	80	typedef\r
	81	EFI_STATUS\r
	82	(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (\r
	83	IN VOID *Data,\r
	84	IN UINTN DataLength,\r
	85	IN VOID *Context,\r
	86	IN UINT32 Status\r
	87	);\r
	88	\r
	89	//\r
	90	// Prototype for EFI USB I/O protocol\r
	91	//\r
	92	\r
	93	\r
e3c6b3d9	94	/**\r
d1f95000	95	This function is used to manage a USB device with a control transfer pipe. A control transfer is\r
e3c6b3d9	96	typically used to perform device initialization and configuration.\r
	97	\r
	98	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	99	@param Request A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	100	device.\r
d1f95000	101	@param Direction Indicates the data direction.\r
d1f95000	102	@param Data A pointer to the buffer of data that will be transmitted to USB\r
e3c6b3d9	103	device or received from USB device.\r
d1f95000	104	@param Timeout Indicating the transfer should be completed within this time frame.\r
e3c6b3d9	105	The units are in milliseconds.\r
d1f95000	106	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
d1f95000	107	@param Status A pointer to the result of the USB transfer.\r
e3c6b3d9	108	\r
d1f95000	109	@retval EFI_SUCCESS The control transfer has been successfully executed.\r
	110	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
	111	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
	112	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
	113	@retval EFI_TIMEOUT The control transfer fails due to timeout.\r
e3c6b3d9	114	\r
d1f95000	115	**/\r
	116	typedef\r
	117	EFI_STATUS\r
	118	(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (\r
	119	IN EFI_USB_IO_PROTOCOL *This,\r
	120	IN EFI_USB_DEVICE_REQUEST *Request,\r
	121	IN EFI_USB_DATA_DIRECTION Direction,\r
	122	IN UINT32 Timeout,\r
	123	IN OUT VOID *Data OPTIONAL,\r
	124	IN UINTN DataLength OPTIONAL,\r
	125	OUT UINT32 *Status\r
	126	);\r
	127	\r
e3c6b3d9	128	/**\r
d1f95000	129	This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are\r
d1f95000	130	typically used to transfer large amounts of data to/from USB devices.\r
e3c6b3d9	131	\r
e3c6b3d9	132	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	133	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	134	device.\r
d1f95000	135	@param Data A pointer to the buffer of data that will be transmitted to USB\r
e3c6b3d9	136	device or received from USB device.\r
d1f95000	137	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
d1f95000	138	@param Timeout Indicating the transfer should be completed within this time frame.\r
e3c6b3d9	139	The units are in milliseconds.\r
d1f95000	140	@param Status This parameter indicates the USB transfer status.\r
e3c6b3d9	141	\r
d1f95000	142	@retval EFI_SUCCESS The bulk transfer has been successfully executed.\r
	143	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
	144	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
	145	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
	146	@retval EFI_TIMEOUT The control transfer fails due to timeout.\r
e3c6b3d9	147	\r
d1f95000	148	**/\r
	149	typedef\r
	150	EFI_STATUS\r
	151	(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (\r
	152	IN EFI_USB_IO_PROTOCOL *This,\r
	153	IN UINT8 DeviceEndpoint,\r
	154	IN OUT VOID *Data,\r
	155	IN OUT UINTN *DataLength,\r
	156	IN UINTN Timeout,\r
	157	OUT UINT32 *Status\r
	158	);\r
	159	\r
e3c6b3d9	160	/**\r
	161	This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous\r
	162	Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,\r
d1f95000	163	keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at\r
e3c6b3d9	164	a fixed rate.\r
	165	\r
	166	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	167	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	168	device.\r
e3c6b3d9	169	@param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If\r
d1f95000	170	FALSE, the interrupt transfer is deleted from the device's interrupt\r
e3c6b3d9	171	transfer queue.\r
	172	@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be\r
	173	executed.\r
d1f95000	174	@param DataLength Specifies the length, in bytes, of the data to be received from the\r
e3c6b3d9	175	USB device.\r
d1f95000	176	@param Context Data passed to the InterruptCallback function.\r
	177	@param InterruptCallback The Callback function. This function is called if the asynchronous\r
	178	interrupt transfer is completed.\r
e3c6b3d9	179	\r
d1f95000	180	@retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.\r
e3c6b3d9	181	@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.\r
e3c6b3d9	182	\r
d1f95000	183	**/\r
	184	typedef\r
	185	EFI_STATUS\r
	186	(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER) (\r
	187	IN EFI_USB_IO_PROTOCOL *This,\r
	188	IN UINT8 DeviceEndpoint,\r
	189	IN BOOLEAN IsNewTransfer,\r
	190	IN UINTN PollingInterval OPTIONAL,\r
	191	IN UINTN DataLength OPTIONAL,\r
	192	IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,\r
	193	IN VOID *Context OPTIONAL\r
	194	);\r
	195	\r
e3c6b3d9	196	/**\r
d1f95000	197	This function is used to manage a USB device with an interrupt transfer pipe.\r
e3c6b3d9	198	\r
e3c6b3d9	199	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	200	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	201	device.\r
d1f95000	202	@param Data A pointer to the buffer of data that will be transmitted to USB\r
e3c6b3d9	203	device or received from USB device.\r
d1f95000	204	@param DataLength On input, then size, in bytes, of the buffer Data. On output, the\r
e3c6b3d9	205	amount of data actually transferred.\r
d1f95000	206	@param Timeout The time out, in seconds, for this transfer.\r
e3c6b3d9	207	@param Status This parameter indicates the USB transfer status.\r
e3c6b3d9	208	\r
d1f95000	209	@retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.\r
d1f95000	210	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
e3c6b3d9	211	@retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.\r
d1f95000	212	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
e3c6b3d9	213	@retval EFI_TIMEOUT The transfer fails due to timeout.\r
d1f95000	214	**/\r
	215	typedef\r
	216	EFI_STATUS\r
	217	(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (\r
	218	IN EFI_USB_IO_PROTOCOL *This,\r
	219	IN UINT8 DeviceEndpoint,\r
	220	IN OUT VOID *Data,\r
	221	IN OUT UINTN *DataLength,\r
	222	IN UINTN Timeout,\r
	223	OUT UINT32 *Status\r
	224	);\r
	225	\r
e3c6b3d9	226	/**\r
d1f95000	227	This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
d1f95000	228	transfer is typically used to transfer streaming data.\r
e3c6b3d9	229	\r
e3c6b3d9	230	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	231	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	232	device.\r
d1f95000	233	@param Data A pointer to the buffer of data that will be transmitted to USB\r
e3c6b3d9	234	device or received from USB device.\r
	235	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
	236	@param Status This parameter indicates the USB transfer status.\r
	237	\r
d1f95000	238	@retval EFI_SUCCESS The isochronous transfer has been successfully executed.\r
	239	@retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
	240	@retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status\r
e3c6b3d9	241	is returned in Status.\r
d1f95000	242	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
e3c6b3d9	243	@retval EFI_TIMEOUT The transfer fails due to timeout.\r
d1f95000	244	**/\r
	245	typedef\r
	246	EFI_STATUS\r
	247	(EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER) (\r
	248	IN EFI_USB_IO_PROTOCOL *This,\r
	249	IN UINT8 DeviceEndpoint,\r
	250	IN OUT VOID *Data,\r
	251	IN UINTN DataLength,\r
	252	OUT UINT32 *Status\r
	253	);\r
	254	\r
e3c6b3d9	255	/**\r
d1f95000	256	This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
e3c6b3d9	257	transfer is typically used to transfer streaming data.\r
	258	\r
	259	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	260	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
e3c6b3d9	261	device.\r
d1f95000	262	@param Data A pointer to the buffer of data that will be transmitted to USB\r
e3c6b3d9	263	device or received from USB device.\r
e3c6b3d9	264	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
d1f95000	265	@param Context Data passed to the IsochronousCallback() function.\r
d1f95000	266	@param IsochronousCallback The IsochronousCallback() function.\r
e3c6b3d9	267	\r
d1f95000	268	@retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted\r
	269	to the system.\r
	270	@retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
	271	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
e3c6b3d9	272	\r
d1f95000	273	**/\r
	274	typedef\r
	275	EFI_STATUS\r
	276	(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (\r
	277	IN EFI_USB_IO_PROTOCOL *This,\r
	278	IN UINT8 DeviceEndpoint,\r
	279	IN OUT VOID *Data,\r
	280	IN UINTN DataLength,\r
	281	IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,\r
	282	IN VOID *Context OPTIONAL\r
	283	);\r
	284	\r
e3c6b3d9	285	/**\r
d1f95000	286	Resets and reconfigures the USB controller. This function will work for all USB devices except\r
e3c6b3d9	287	USB Hub Controllers.\r
	288	\r
	289	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
	290	\r
	291	@retval EFI_SUCCESS The USB controller was reset.\r
d1f95000	292	@retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.\r
d1f95000	293	@retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.\r
e3c6b3d9	294	\r
d1f95000	295	**/\r
	296	typedef\r
	297	EFI_STATUS\r
	298	(EFIAPI *EFI_USB_IO_PORT_RESET) (\r
	299	IN EFI_USB_IO_PROTOCOL *This\r
	300	);\r
	301	\r
e3c6b3d9	302	/**\r
d1f95000	303	Retrieves the USB Device Descriptor.\r
e3c6b3d9	304	\r
e3c6b3d9	305	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	306	@param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.\r
e3c6b3d9	307	\r
d1f95000	308	@retval EFI_SUCCESS The device descriptor was retrieved successfully.\r
	309	@retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.\r
	310	@retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.\r
e3c6b3d9	311	\r
d1f95000	312	**/\r
	313	typedef\r
	314	EFI_STATUS\r
	315	(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (\r
	316	IN EFI_USB_IO_PROTOCOL *This,\r
	317	OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor\r
	318	);\r
	319	\r
e3c6b3d9	320	/**\r
d1f95000	321	Retrieves the USB Device Descriptor.\r
e3c6b3d9	322	\r
e3c6b3d9	323	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	324	@param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration\r
e3c6b3d9	325	Descriptor.\r
d1f95000	326	@retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.\r
	327	@retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.\r
	328	@retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not\r
e3c6b3d9	329	be configured.\r
e3c6b3d9	330	\r
d1f95000	331	**/\r
	332	typedef\r
	333	EFI_STATUS\r
	334	(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (\r
	335	IN EFI_USB_IO_PROTOCOL *This,\r
	336	OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor\r
	337	);\r
	338	\r
e3c6b3d9	339	/**\r
d1f95000	340	Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface\r
e3c6b3d9	341	within a USB device is equivalently to a USB Controller within the current configuration.\r
	342	\r
	343	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	344	@param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within\r
e3c6b3d9	345	the configuration setting.\r
d1f95000	346	@retval EFI_SUCCESS The interface descriptor retrieved successfully.\r
	347	@retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.\r
	348	@retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be\r
e3c6b3d9	349	correctly configured.\r
e3c6b3d9	350	\r
d1f95000	351	**/\r
	352	typedef\r
	353	EFI_STATUS\r
	354	(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (\r
	355	IN EFI_USB_IO_PROTOCOL *This,\r
	356	OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor\r
	357	);\r
	358	\r
e3c6b3d9	359	/**\r
d1f95000	360	Retrieves an Endpoint Descriptor within a USB Controller.\r
e3c6b3d9	361	\r
e3c6b3d9	362	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	363	@param EndpointIndex Indicates which endpoint descriptor to retrieve.\r
d1f95000	364	@param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of\r
e3c6b3d9	365	a USB controller.\r
e3c6b3d9	366	\r
d1f95000	367	@retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.\r
	368	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
	369	@retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be\r
e3c6b3d9	370	correctly configured.\r
e3c6b3d9	371	\r
d1f95000	372	**/\r
	373	typedef\r
	374	EFI_STATUS\r
	375	(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR) (\r
	376	IN EFI_USB_IO_PROTOCOL *This,\r
	377	IN UINT8 EndpointIndex,\r
	378	OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor\r
	379	);\r
	380	\r
e3c6b3d9	381	/**\r
d1f95000	382	Retrieves a Unicode string stored in a USB Device.\r
e3c6b3d9	383	\r
e3c6b3d9	384	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	385	@param LangID The Language ID for the string being retrieved.\r
e3c6b3d9	386	@param StringID The ID of the string being retrieved.\r
e3c6b3d9	387	@param String A pointer to a buffer allocated by this function with\r
d1f95000	388	AllocatePool() to store the string.\r
e3c6b3d9	389	\r
	390	@retval EFI_SUCCESS The string was retrieved successfully.\r
	391	@retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.\r
d1f95000	392	@retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.\r
e3c6b3d9	393	\r
d1f95000	394	**/\r
	395	typedef\r
	396	EFI_STATUS\r
	397	(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (\r
	398	IN EFI_USB_IO_PROTOCOL *This,\r
	399	IN UINT16 LangID,\r
	400	IN UINT8 StringID,\r
	401	OUT CHAR16 **String\r
	402	);\r
	403	\r
e3c6b3d9	404	/**\r
d1f95000	405	Retrieves all the language ID codes that the USB device supports.\r
e3c6b3d9	406	\r
e3c6b3d9	407	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
d1f95000	408	@param LangIDTable Language ID for the string the caller wants to get.\r
d1f95000	409	@param TableSize The size, in bytes, of the table LangIDTable.\r
e3c6b3d9	410	\r
	411	@retval EFI_SUCCESS The support languages were retrieved successfully.\r
	412	\r
d1f95000	413	**/\r
	414	typedef\r
	415	EFI_STATUS\r
	416	(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE) (\r
	417	IN EFI_USB_IO_PROTOCOL *This,\r
	418	OUT UINT16 **LangIDTable,\r
	419	OUT UINT16 *TableSize\r
	420	);\r
	421	\r
	422	//\r
	423	// Protocol Interface Structure\r
	424	//\r
	425	struct _EFI_USB_IO_PROTOCOL {\r
	426	//\r
	427	// IO transfer\r
	428	//\r
	429	EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;\r
	430	EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;\r
	431	EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;\r
	432	EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;\r
	433	EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;\r
	434	EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;\r
	435	\r
	436	//\r
	437	// Common device request\r
	438	//\r
	439	EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;\r
	440	EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;\r
	441	EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;\r
	442	EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;\r
	443	EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;\r
	444	EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;\r
	445	\r
	446	//\r
	447	// Reset controller's parent port\r
	448	//\r
	449	EFI_USB_IO_PORT_RESET UsbPortReset;\r
	450	};\r
	451	\r
	452	extern EFI_GUID gEfiUsbIoProtocolGuid;\r
	453	\r
	454	#endif\r