MdePkg/Include/Protocol/UsbIo.h - device/linaro/bootloader/edk2 - Git at Google

 /** @file
   EFI Usb I/O Protocol as defined in UEFI specification.
   This protocol is used by code, typically drivers, running in the EFI
   boot services environment to access USB devices like USB keyboards,
   mice and mass storage devices. In particular, functions for managing devices
   on USB buses are defined here.

   Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
   This program and the accompanying materials
   are licensed and made available under the terms and conditions of the BSD License
   which accompanies this distribution.  The full text of the license may be found at
   http://opensource.org/licenses/bsd-license.php

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 **/

 #ifndef __USB_IO_H__
 #define __USB_IO_H__

 #include <IndustryStandard/Usb.h>

 //
 // Global ID for the USB I/O Protocol
 //
 #define EFI_USB_IO_PROTOCOL_GUID \
   { \
     0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
   }

 typedef struct _EFI_USB_IO_PROTOCOL   EFI_USB_IO_PROTOCOL;

 //
 // Related Definition for EFI USB I/O protocol
 //

 //
 // USB standard descriptors and reqeust
 //
 typedef USB_DEVICE_REQUEST        EFI_USB_DEVICE_REQUEST;
 typedef USB_DEVICE_DESCRIPTOR     EFI_USB_DEVICE_DESCRIPTOR;
 typedef USB_CONFIG_DESCRIPTOR     EFI_USB_CONFIG_DESCRIPTOR;
 typedef USB_INTERFACE_DESCRIPTOR  EFI_USB_INTERFACE_DESCRIPTOR;
 typedef USB_ENDPOINT_DESCRIPTOR   EFI_USB_ENDPOINT_DESCRIPTOR;

 ///
 /// USB data transfer direction
 ///
 typedef enum {
   EfiUsbDataIn,
   EfiUsbDataOut,
   EfiUsbNoData
 } EFI_USB_DATA_DIRECTION;

 //
 // USB Transfer Results
 //
 #define EFI_USB_NOERROR             0x00
 #define EFI_USB_ERR_NOTEXECUTE      0x01
 #define EFI_USB_ERR_STALL           0x02
 #define EFI_USB_ERR_BUFFER          0x04
 #define EFI_USB_ERR_BABBLE          0x08
 #define EFI_USB_ERR_NAK             0x10
 #define EFI_USB_ERR_CRC             0x20
 #define EFI_USB_ERR_TIMEOUT         0x40
 #define EFI_USB_ERR_BITSTUFF        0x80
 #define EFI_USB_ERR_SYSTEM          0x100

 /**
   Async USB transfer callback routine.

   @param  Data                  Data received or sent via the USB Asynchronous Transfer, if the
                                 transfer completed successfully.
   @param  DataLength            The length of Data received or sent via the Asynchronous
                                 Transfer, if transfer successfully completes.
   @param  Context               Data passed from UsbAsyncInterruptTransfer() request.
   @param  Status                Indicates the result of the asynchronous transfer.

   @retval EFI_SUCCESS           The asynchronous USB transfer request has been successfully executed.
   @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)(
   IN VOID         *Data,
   IN UINTN        DataLength,
   IN VOID         *Context,
   IN UINT32       Status
   );

 //
 // Prototype for EFI USB I/O protocol
 //


 /**
   This function is used to manage a USB device with a control transfer pipe. A control transfer is
   typically used to perform device initialization and configuration.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  Request               A pointer to the USB device request that will be sent to the USB
                                 device.
   @param  Direction             Indicates the data direction.
   @param  Timeout               Indicating the transfer should be completed within this time frame.
                                 The units are in milliseconds.
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
                                 device or received from USB device.
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.
   @param  Status                A pointer to the result of the USB transfer.

   @retval EFI_SUCCESS           The control transfer has been successfully executed.
   @retval EFI_DEVICE_ERROR      The transfer failed. The transfer status is returned in Status.
   @retval EFI_INVALID_PARAMETE  One or more parameters are invalid.
   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
   @retval EFI_TIMEOUT           The control transfer fails due to timeout.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_CONTROL_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL                        *This,
   IN EFI_USB_DEVICE_REQUEST                     *Request,
   IN EFI_USB_DATA_DIRECTION                     Direction,
   IN UINT32                                     Timeout,
   IN OUT VOID                                   *Data OPTIONAL,
   IN UINTN                                      DataLength  OPTIONAL,
   OUT UINT32                                    *Status
   );

 /**
   This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
   typically used to transfer large amounts of data to/from USB devices.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceEndpoint        The destination USB device endpoint to which the
                                 device request is being sent. DeviceEndpoint must
                                 be between 0x01 and 0x0F or between 0x81 and 0x8F,
                                 otherwise EFI_INVALID_PARAMETER is returned. If
                                 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
                                 is returned. The MSB of this parameter indicates
                                 the endpoint direction. The number "1" stands for
                                 an IN endpoint, and "0" stands for an OUT endpoint.
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
                                 device or received from USB device.
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.
                                 On input, the size, in bytes, of the data buffer specified by Data.
                                 On output, the number of bytes that were actually transferred.
   @param  Timeout               Indicating the transfer should be completed within this time frame.
                                 The units are in milliseconds. If Timeout is 0, then the
                                 caller must wait for the function to be completed until
                                 EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
   @param  Status                This parameter indicates the USB transfer status.

   @retval EFI_SUCCESS           The bulk transfer has been successfully executed.
   @retval EFI_DEVICE_ERROR      The transfer failed. The transfer status is returned in Status.
   @retval EFI_INVALID_PARAMETE  One or more parameters are invalid.
   @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.
   @retval EFI_TIMEOUT           The control transfer fails due to timeout.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_BULK_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL            *This,
   IN UINT8                          DeviceEndpoint,
   IN OUT VOID                       *Data,
   IN OUT UINTN                      *DataLength,
   IN UINTN                          Timeout,
   OUT UINT32                        *Status
   );

 /**
   This function is used to manage a USB device with an interrupt transfer pipe. 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.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceEndpoint        The destination USB device endpoint to which the
                                 device request is being sent. DeviceEndpoint must
                                 be between 0x01 and 0x0F or between 0x81 and 0x8F,
                                 otherwise EFI_INVALID_PARAMETER is returned. If
                                 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
                                 is returned. The MSB of this parameter indicates
                                 the endpoint direction. The number "1" stands for
                                 an IN endpoint, and "0" stands for an OUT endpoint.
   @param  IsNewTransfer         If TRUE, a new transfer will be submitted to USB controller. If
                                 FALSE, the interrupt transfer is deleted from the device's interrupt
                                 transfer queue.
   @param  PollingInterval       Indicates the periodic rate, in milliseconds, that the transfer is to be
                                 executed.This parameter is required when IsNewTransfer is TRUE. The
                                 value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.
                                 The units are in milliseconds.
   @param  DataLength            Specifies the length, in bytes, of the data to be received from the
                                 USB device. This parameter is only required when IsNewTransfer is TRUE.
   @param  InterruptCallback     The Callback function. This function is called if the asynchronous
                                 interrupt transfer is completed. This parameter is required
                                 when IsNewTransfer is TRUE.
   @param  Context               Data passed to the InterruptCallback function. This is an optional
                                 parameter and may be NULL.

   @retval EFI_SUCCESS           The asynchronous USB transfer request transfer has been successfully executed.
   @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL                                 *This,
   IN UINT8                                               DeviceEndpoint,
   IN BOOLEAN                                             IsNewTransfer,
   IN UINTN                                               PollingInterval    OPTIONAL,
   IN UINTN                                               DataLength         OPTIONAL,
   IN EFI_ASYNC_USB_TRANSFER_CALLBACK                     InterruptCallBack  OPTIONAL,
   IN VOID                                                *Context OPTIONAL
   );

 /**
   This function is used to manage a USB device with an interrupt transfer pipe.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceEndpoint        The destination USB device endpoint to which the
                                 device request is being sent. DeviceEndpoint must
                                 be between 0x01 and 0x0F or between 0x81 and 0x8F,
                                 otherwise EFI_INVALID_PARAMETER is returned. If
                                 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
                                 is returned. The MSB of this parameter indicates
                                 the endpoint direction. The number "1" stands for
                                 an IN endpoint, and "0" stands for an OUT endpoint.
   @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, then size, in bytes, of the buffer Data. On output, the
                                 amount of data actually transferred.
   @param  Timeout               The time out, in seconds, for this transfer. If Timeout is 0,
                                 then the caller must wait for the function to be completed
                                 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the
                                 transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
   @param  Status                This parameter indicates the USB transfer status.

   @retval EFI_SUCCESS           The sync interrupt transfer has been successfully executed.
   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
   @retval EFI_DEVICE_ERROR      The sync interrupt transfer request failed.
   @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.
   @retval EFI_TIMEOUT           The transfer fails due to timeout.
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL            *This,
   IN     UINT8                      DeviceEndpoint,
   IN OUT VOID                       *Data,
   IN OUT UINTN                      *DataLength,
   IN     UINTN                      Timeout,
   OUT    UINT32                     *Status
   );

 /**
   This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
   transfer is typically used to transfer streaming data.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceEndpoint        The destination USB device endpoint to which the
                                 device request is being sent. DeviceEndpoint must
                                 be between 0x01 and 0x0F or between 0x81 and 0x8F,
                                 otherwise EFI_INVALID_PARAMETER is returned. If
                                 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
                                 is returned. The MSB of this parameter indicates
                                 the endpoint direction. The number "1" stands for
                                 an IN endpoint, and "0" stands for an OUT endpoint.
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
                                 device or received from USB device.
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.
   @param  Status                This parameter indicates the USB transfer status.

   @retval EFI_SUCCESS           The isochronous transfer has been successfully executed.
   @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
   @retval EFI_DEVICE_ERROR      The transfer failed due to the reason other than timeout, The error status
                                 is returned in Status.
   @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.
   @retval EFI_TIMEOUT           The transfer fails due to timeout.
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL            *This,
   IN     UINT8                      DeviceEndpoint,
   IN OUT VOID                       *Data,
   IN     UINTN                      DataLength,
   OUT    UINT32                     *Status
   );

 /**
   This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
   transfer is typically used to transfer streaming data.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceEndpoint        The destination USB device endpoint to which the
                                 device request is being sent. DeviceEndpoint must
                                 be between 0x01 and 0x0F or between 0x81 and 0x8F,
                                 otherwise EFI_INVALID_PARAMETER is returned. If
                                 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
                                 is returned. The MSB of this parameter indicates
                                 the endpoint direction. The number "1" stands for
                                 an IN endpoint, and "0" stands for an OUT endpoint.
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
                                 device or received from USB device.
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.
                                 This is an optional parameter and may be NULL.
   @param  IsochronousCallback   The IsochronousCallback() function.This function is
                                 called if the requested isochronous transfer is completed.
   @param  Context               Data passed to the IsochronousCallback() function.

   @retval EFI_SUCCESS           The asynchronous isochronous transfer has been successfully submitted
                                 to the system.
   @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
   @retval EFI_OUT_OF_RESOURCES  The request could not be submitted due to a lack of resources.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)(
   IN EFI_USB_IO_PROTOCOL              *This,
   IN UINT8                            DeviceEndpoint,
   IN OUT VOID                         *Data,
   IN     UINTN                        DataLength,
   IN EFI_ASYNC_USB_TRANSFER_CALLBACK  IsochronousCallBack,
   IN VOID                             *Context OPTIONAL
   );

 /**
   Resets and reconfigures the USB controller. This function will work for all USB devices except
   USB Hub Controllers.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

   @retval EFI_SUCCESS           The USB controller was reset.
   @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
   @retval EFI_DEVICE_ERROR      An error occurred during the reconfiguration process.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_PORT_RESET)(
   IN EFI_USB_IO_PROTOCOL    *This
   );

 /**
   Retrieves the USB Device Descriptor.

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  DeviceDescriptor      A pointer to the caller allocated USB Device Descriptor.

   @retval EFI_SUCCESS           The device descriptor was retrieved successfully.
   @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
   @retval EFI_NOT_FOUND         The device descriptor was not found. The device may not be configured.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)(
   IN EFI_USB_IO_PROTOCOL            *This,
   OUT EFI_USB_DEVICE_DESCRIPTOR     *DeviceDescriptor
   );

 /**
   Retrieves the USB Device Descriptor.

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
                                   Descriptor.
   @retval EFI_SUCCESS             The active configuration descriptor was retrieved successfully.
   @retval EFI_INVALID_PARAMETER   ConfigurationDescriptor is NULL.
   @retval EFI_NOT_FOUND           An active configuration descriptor cannot be found. The device may not
                                   be configured.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)(
   IN EFI_USB_IO_PROTOCOL            *This,
   OUT EFI_USB_CONFIG_DESCRIPTOR     *ConfigurationDescriptor
   );

 /**
   Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
   within a USB device is equivalently to a USB Controller within the current configuration.

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  InterfaceDescriptor     A pointer to the caller allocated USB Interface Descriptor within
                                   the configuration setting.
   @retval EFI_SUCCESS             The interface descriptor retrieved successfully.
   @retval EFI_INVALID_PARAMETER   InterfaceDescriptor is NULL.
   @retval EFI_NOT_FOUND           The interface descriptor cannot be found. The device may not be
                                   correctly configured.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)(
   IN EFI_USB_IO_PROTOCOL            *This,
   OUT EFI_USB_INTERFACE_DESCRIPTOR  *InterfaceDescriptor
   );

 /**
   Retrieves an Endpoint Descriptor within a USB Controller.

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  EndpointIndex           Indicates which endpoint descriptor to retrieve.
   @param  EndpointDescriptor      A pointer to the caller allocated USB Endpoint Descriptor of
                                   a USB controller.

   @retval EFI_SUCCESS             The endpoint descriptor was retrieved successfully.
   @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
   @retval EFI_NOT_FOUND           The endpoint descriptor cannot be found. The device may not be
                                   correctly configured.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)(
   IN EFI_USB_IO_PROTOCOL            *This,
   IN  UINT8                         EndpointIndex,
   OUT EFI_USB_ENDPOINT_DESCRIPTOR   *EndpointDescriptor
   );

 /**
   Retrieves a string stored in a USB Device.

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  LangID                  The Language ID for the string being retrieved.
   @param  StringID                The ID of the string being retrieved.
   @param  String                  A pointer to a buffer allocated by this function with
                                   AllocatePool() to store the string.If this function
                                   returns EFI_SUCCESS, it stores the string the caller
                                   wants to get. The caller should release the string
                                   buffer with FreePool() after the string is not used any more.

   @retval EFI_SUCCESS             The string was retrieved successfully.
   @retval EFI_NOT_FOUND           The string specified by LangID and StringID was not found.
   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to allocate the return buffer String.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)(
   IN EFI_USB_IO_PROTOCOL            *This,
   IN  UINT16                        LangID,
   IN  UINT8                         StringID,
   OUT CHAR16                        **String
   );

 /**
   Retrieves all the language ID codes that the USB device supports.

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
   @param  LangIDTable             Language ID for the string the caller wants to get.
                                   This is a 16-bit ID defined by Microsoft. This
                                   buffer pointer is allocated and maintained by
                                   the USB Bus Driver, the caller should not modify
                                   its contents.
   @param  TableSize               The size, in bytes, of the table LangIDTable.

   @retval EFI_SUCCESS             The support languages were retrieved successfully.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)(
   IN EFI_USB_IO_PROTOCOL            *This,
   OUT UINT16                        **LangIDTable,
   OUT UINT16                        *TableSize
   );

 ///
 /// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
 /// in the USB 1.1 Specification. These include control transfer, interrupt
 /// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
 /// also provides some basic USB device/controller management and configuration
 /// interfaces. A USB device driver uses the services of this protocol to manage USB devices.
 ///
 struct _EFI_USB_IO_PROTOCOL {
   //
   // IO transfer
   //
   EFI_USB_IO_CONTROL_TRANSFER           UsbControlTransfer;
   EFI_USB_IO_BULK_TRANSFER              UsbBulkTransfer;
   EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER   UsbAsyncInterruptTransfer;
   EFI_USB_IO_SYNC_INTERRUPT_TRANSFER    UsbSyncInterruptTransfer;
   EFI_USB_IO_ISOCHRONOUS_TRANSFER       UsbIsochronousTransfer;
   EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;

   //
   // Common device request
   //
   EFI_USB_IO_GET_DEVICE_DESCRIPTOR      UsbGetDeviceDescriptor;
   EFI_USB_IO_GET_CONFIG_DESCRIPTOR      UsbGetConfigDescriptor;
   EFI_USB_IO_GET_INTERFACE_DESCRIPTOR   UsbGetInterfaceDescriptor;
   EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR    UsbGetEndpointDescriptor;
   EFI_USB_IO_GET_STRING_DESCRIPTOR      UsbGetStringDescriptor;
   EFI_USB_IO_GET_SUPPORTED_LANGUAGE     UsbGetSupportedLanguages;

   //
   // Reset controller's parent port
   //
   EFI_USB_IO_PORT_RESET                 UsbPortReset;
 };

 extern EFI_GUID gEfiUsbIoProtocolGuid;

 #endif
	/** @file
	EFI Usb I/O Protocol as defined in UEFI specification.
	This protocol is used by code, typically drivers, running in the EFI
	boot services environment to access USB devices like USB keyboards,
	mice and mass storage devices. In particular, functions for managing devices
	on USB buses are defined here.

	Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
	This program and the accompanying materials
	are licensed and made available under the terms and conditions of the BSD License
	which accompanies this distribution. The full text of the license may be found at
	http://opensource.org/licenses/bsd-license.php

	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

	**/

	#ifndef __USB_IO_H__
	#define __USB_IO_H__

	#include <IndustryStandard/Usb.h>

	//
	// Global ID for the USB I/O Protocol
	//
	#define EFI_USB_IO_PROTOCOL_GUID \
	{ \
	0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
	}

	typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;

	//
	// Related Definition for EFI USB I/O protocol
	//

	//
	// USB standard descriptors and reqeust
	//
	typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST;
	typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR;
	typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR;
	typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR;
	typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR;

	///
	/// USB data transfer direction
	///
	typedef enum {
	EfiUsbDataIn,
	EfiUsbDataOut,
	EfiUsbNoData
	} EFI_USB_DATA_DIRECTION;

	//
	// USB Transfer Results
	//
	#define EFI_USB_NOERROR 0x00
	#define EFI_USB_ERR_NOTEXECUTE 0x01
	#define EFI_USB_ERR_STALL 0x02
	#define EFI_USB_ERR_BUFFER 0x04
	#define EFI_USB_ERR_BABBLE 0x08
	#define EFI_USB_ERR_NAK 0x10
	#define EFI_USB_ERR_CRC 0x20
	#define EFI_USB_ERR_TIMEOUT 0x40
	#define EFI_USB_ERR_BITSTUFF 0x80
	#define EFI_USB_ERR_SYSTEM 0x100

	/**
	Async USB transfer callback routine.

	@param Data Data received or sent via the USB Asynchronous Transfer, if the
	transfer completed successfully.
	@param DataLength The length of Data received or sent via the Asynchronous
	Transfer, if transfer successfully completes.
	@param Context Data passed from UsbAsyncInterruptTransfer() request.
	@param Status Indicates the result of the asynchronous transfer.

	@retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
	@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)(
	IN VOID *Data,
	IN UINTN DataLength,
	IN VOID *Context,
	IN UINT32 Status
	);

	//
	// Prototype for EFI USB I/O protocol
	//


	/**
	This function is used to manage a USB device with a control transfer pipe. A control transfer is
	typically used to perform device initialization and configuration.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param Request A pointer to the USB device request that will be sent to the USB
	device.
	@param Direction Indicates the data direction.
	@param Timeout Indicating the transfer should be completed within this time frame.
	The units are in milliseconds.
	@param Data A pointer to the buffer of data that will be transmitted to USB
	device or received from USB device.
	@param DataLength The size, in bytes, of the data buffer specified by Data.
	@param Status A pointer to the result of the USB transfer.

	@retval EFI_SUCCESS The control transfer has been successfully executed.
	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.
	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
	@retval EFI_TIMEOUT The control transfer fails due to timeout.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN EFI_USB_DEVICE_REQUEST *Request,
	IN EFI_USB_DATA_DIRECTION Direction,
	IN UINT32 Timeout,
	IN OUT VOID *Data OPTIONAL,
	IN UINTN DataLength OPTIONAL,
	OUT UINT32 *Status
	);

	/**
	This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
	typically used to transfer large amounts of data to/from USB devices.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceEndpoint The destination USB device endpoint to which the
	device request is being sent. DeviceEndpoint must
	be between 0x01 and 0x0F or between 0x81 and 0x8F,
	otherwise EFI_INVALID_PARAMETER is returned. If
	the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
	is returned. The MSB of this parameter indicates
	the endpoint direction. The number "1" stands for
	an IN endpoint, and "0" stands for an OUT endpoint.
	@param Data A pointer to the buffer of data that will be transmitted to USB
	device or received from USB device.
	@param DataLength The size, in bytes, of the data buffer specified by Data.
	On input, the size, in bytes, of the data buffer specified by Data.
	On output, the number of bytes that were actually transferred.
	@param Timeout Indicating the transfer should be completed within this time frame.
	The units are in milliseconds. If Timeout is 0, then the
	caller must wait for the function to be completed until
	EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
	@param Status This parameter indicates the USB transfer status.

	@retval EFI_SUCCESS The bulk transfer has been successfully executed.
	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.
	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
	@retval EFI_TIMEOUT The control transfer fails due to timeout.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_BULK_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 DeviceEndpoint,
	IN OUT VOID *Data,
	IN OUT UINTN *DataLength,
	IN UINTN Timeout,
	OUT UINT32 *Status
	);

	/**
	This function is used to manage a USB device with an interrupt transfer pipe. 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.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceEndpoint The destination USB device endpoint to which the
	device request is being sent. DeviceEndpoint must
	be between 0x01 and 0x0F or between 0x81 and 0x8F,
	otherwise EFI_INVALID_PARAMETER is returned. If
	the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
	is returned. The MSB of this parameter indicates
	the endpoint direction. The number "1" stands for
	an IN endpoint, and "0" stands for an OUT endpoint.
	@param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
	FALSE, the interrupt transfer is deleted from the device's interrupt
	transfer queue.
	@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
	executed.This parameter is required when IsNewTransfer is TRUE. The
	value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.
	The units are in milliseconds.
	@param DataLength Specifies the length, in bytes, of the data to be received from the
	USB device. This parameter is only required when IsNewTransfer is TRUE.
	@param InterruptCallback The Callback function. This function is called if the asynchronous
	interrupt transfer is completed. This parameter is required
	when IsNewTransfer is TRUE.
	@param Context Data passed to the InterruptCallback function. This is an optional
	parameter and may be NULL.

	@retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
	@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 DeviceEndpoint,
	IN BOOLEAN IsNewTransfer,
	IN UINTN PollingInterval OPTIONAL,
	IN UINTN DataLength OPTIONAL,
	IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,
	IN VOID *Context OPTIONAL
	);

	/**
	This function is used to manage a USB device with an interrupt transfer pipe.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceEndpoint The destination USB device endpoint to which the
	device request is being sent. DeviceEndpoint must
	be between 0x01 and 0x0F or between 0x81 and 0x8F,
	otherwise EFI_INVALID_PARAMETER is returned. If
	the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
	is returned. The MSB of this parameter indicates
	the endpoint direction. The number "1" stands for
	an IN endpoint, and "0" stands for an OUT endpoint.
	@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, then size, in bytes, of the buffer Data. On output, the
	amount of data actually transferred.
	@param Timeout The time out, in seconds, for this transfer. If Timeout is 0,
	then the caller must wait for the function to be completed
	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the
	transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
	@param Status This parameter indicates the USB transfer status.

	@retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
	@retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
	@retval EFI_TIMEOUT The transfer fails due to timeout.
	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 DeviceEndpoint,
	IN OUT VOID *Data,
	IN OUT UINTN *DataLength,
	IN UINTN Timeout,
	OUT UINT32 *Status
	);

	/**
	This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
	transfer is typically used to transfer streaming data.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceEndpoint The destination USB device endpoint to which the
	device request is being sent. DeviceEndpoint must
	be between 0x01 and 0x0F or between 0x81 and 0x8F,
	otherwise EFI_INVALID_PARAMETER is returned. If
	the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
	is returned. The MSB of this parameter indicates
	the endpoint direction. The number "1" stands for
	an IN endpoint, and "0" stands for an OUT endpoint.
	@param Data A pointer to the buffer of data that will be transmitted to USB
	device or received from USB device.
	@param DataLength The size, in bytes, of the data buffer specified by Data.
	@param Status This parameter indicates the USB transfer status.

	@retval EFI_SUCCESS The isochronous transfer has been successfully executed.
	@retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
	@retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
	is returned in Status.
	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
	@retval EFI_TIMEOUT The transfer fails due to timeout.
	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 DeviceEndpoint,
	IN OUT VOID *Data,
	IN UINTN DataLength,
	OUT UINT32 *Status
	);

	/**
	This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
	transfer is typically used to transfer streaming data.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceEndpoint The destination USB device endpoint to which the
	device request is being sent. DeviceEndpoint must
	be between 0x01 and 0x0F or between 0x81 and 0x8F,
	otherwise EFI_INVALID_PARAMETER is returned. If
	the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
	is returned. The MSB of this parameter indicates
	the endpoint direction. The number "1" stands for
	an IN endpoint, and "0" stands for an OUT endpoint.
	@param Data A pointer to the buffer of data that will be transmitted to USB
	device or received from USB device.
	@param DataLength The size, in bytes, of the data buffer specified by Data.
	This is an optional parameter and may be NULL.
	@param IsochronousCallback The IsochronousCallback() function.This function is
	called if the requested isochronous transfer is completed.
	@param Context Data passed to the IsochronousCallback() function.

	@retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
	to the system.
	@retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 DeviceEndpoint,
	IN OUT VOID *Data,
	IN UINTN DataLength,
	IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
	IN VOID *Context OPTIONAL
	);

	/**
	Resets and reconfigures the USB controller. This function will work for all USB devices except
	USB Hub Controllers.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.

	@retval EFI_SUCCESS The USB controller was reset.
	@retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
	@retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_PORT_RESET)(
	IN EFI_USB_IO_PROTOCOL *This
	);

	/**
	Retrieves the USB Device Descriptor.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.

	@retval EFI_SUCCESS The device descriptor was retrieved successfully.
	@retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
	@retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)(
	IN EFI_USB_IO_PROTOCOL *This,
	OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor
	);

	/**
	Retrieves the USB Device Descriptor.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
	Descriptor.
	@retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
	@retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
	@retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
	be configured.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)(
	IN EFI_USB_IO_PROTOCOL *This,
	OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor
	);

	/**
	Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
	within a USB device is equivalently to a USB Controller within the current configuration.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
	the configuration setting.
	@retval EFI_SUCCESS The interface descriptor retrieved successfully.
	@retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
	@retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
	correctly configured.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)(
	IN EFI_USB_IO_PROTOCOL *This,
	OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor
	);

	/**
	Retrieves an Endpoint Descriptor within a USB Controller.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param EndpointIndex Indicates which endpoint descriptor to retrieve.
	@param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
	a USB controller.

	@retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
	@retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
	correctly configured.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT8 EndpointIndex,
	OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor
	);

	/**
	Retrieves a string stored in a USB Device.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param LangID The Language ID for the string being retrieved.
	@param StringID The ID of the string being retrieved.
	@param String A pointer to a buffer allocated by this function with
	AllocatePool() to store the string.If this function
	returns EFI_SUCCESS, it stores the string the caller
	wants to get. The caller should release the string
	buffer with FreePool() after the string is not used any more.

	@retval EFI_SUCCESS The string was retrieved successfully.
	@retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
	@retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)(
	IN EFI_USB_IO_PROTOCOL *This,
	IN UINT16 LangID,
	IN UINT8 StringID,
	OUT CHAR16 **String
	);

	/**
	Retrieves all the language ID codes that the USB device supports.

	@param This A pointer to the EFI_USB_IO_PROTOCOL instance.
	@param LangIDTable Language ID for the string the caller wants to get.
	This is a 16-bit ID defined by Microsoft. This
	buffer pointer is allocated and maintained by
	the USB Bus Driver, the caller should not modify
	its contents.
	@param TableSize The size, in bytes, of the table LangIDTable.

	@retval EFI_SUCCESS The support languages were retrieved successfully.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)(
	IN EFI_USB_IO_PROTOCOL *This,
	OUT UINT16 **LangIDTable,
	OUT UINT16 *TableSize
	);

	///
	/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
	/// in the USB 1.1 Specification. These include control transfer, interrupt
	/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
	/// also provides some basic USB device/controller management and configuration
	/// interfaces. A USB device driver uses the services of this protocol to manage USB devices.
	///
	struct _EFI_USB_IO_PROTOCOL {
	//
	// IO transfer
	//
	EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;
	EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;
	EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;
	EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;
	EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;
	EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;

	//
	// Common device request
	//
	EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;
	EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;
	EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;
	EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;
	EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;
	EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;

	//
	// Reset controller's parent port
	//
	EFI_USB_IO_PORT_RESET UsbPortReset;
	};

	extern EFI_GUID gEfiUsbIoProtocolGuid;

	#endif