[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
  Module Name:  UsbIo.h\r
\r
**/\r
\r
#ifndef __USB_IO_H__\r
#define __USB_IO_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
  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
Commit	Line	Data
878ddf1f	1	/** @file\r
	2	EFI Usb I/O Protocol\r
	3	\r
	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
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
	13	Module Name: UsbIo.h\r
	14	\r
	15	**/\r
	16	\r
	17	#ifndef __USB_IO_H__\r
	18	#define __USB_IO_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
	30	/** \r
	31	Async USB transfer callback routine.\r
	32	\r
	33	@param Data Data received or sent via the USB Asynchronous Transfer, if the\r
	34	transfer completed successfully. \r
	35	@param DataLength The length of Data received or sent via the Asynchronous\r
	36	Transfer, if transfer successfully completes. \r
	37	@param Context Data passed from UsbAsyncInterruptTransfer() request.\r
	38	@param Status Indicates the result of the asynchronous transfer.\r
	39	\r
	40	@retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. \r
	41	@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.\r
	42	\r
	43	**/\r
	44	typedef\r
	45	EFI_STATUS\r
	46	(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (\r
	47	IN VOID *Data,\r
	48	IN UINTN DataLength,\r
	49	IN VOID *Context,\r
	50	IN UINT32 Status\r
	51	);\r
	52	\r
	53	//\r
	54	// Prototype for EFI USB I/O protocol\r
	55	//\r
	56	\r
	57	\r
	58	/** \r
	59	This function is used to manage a USB device with a control transfer pipe. A control transfer is\r
	60	typically used to perform device initialization and configuration. \r
	61	\r
	62	@param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
	63	@param Request A pointer to the USB device request that will be sent to the USB\r
	64	device. \r
65	@param Direction Indicates the data direction.\r
66	@param Data A pointer to the buffer of data that will be transmitted to USB\r
67	device or received from USB device. \r
68	@param Timeout Indicating the transfer should be completed within this time frame.\r
69	The units are in milliseconds. \r
70	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
71	@param Status A pointer to the result of the USB transfer.\r
72	\r
73	@retval EFI_SUCCESS The control transfer has been successfully executed.\r
74	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
75	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
76	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
77	@retval EFI_TIMEOUT The control transfer fails due to timeout.\r
78	\r
79	**/\r
80	typedef\r
81	EFI_STATUS\r
82	(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (\r
83	IN EFI_USB_IO_PROTOCOL *This,\r
84	IN EFI_USB_DEVICE_REQUEST *Request,\r
85	IN EFI_USB_DATA_DIRECTION Direction,\r
86	IN UINT32 Timeout,\r
87	IN OUT VOID *Data OPTIONAL,\r
88	IN UINTN DataLength OPTIONAL,\r
89	OUT UINT32 *Status\r
90	);\r
91	\r
92	/** \r
93	This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are\r
94	typically used to transfer large amounts of data to/from USB devices.\r
95	\r
96	@param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
97	@param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
98	device. \r
99	@param Data A pointer to the buffer of data that will be transmitted to USB\r
100	device or received from USB device. \r
101	@param DataLength The size, in bytes, of the data buffer specified by Data.\r
102	@param Timeout Indicating the transfer should be completed within this time frame.\r
103	The units are in milliseconds. \r
104	@param Status This parameter indicates the USB transfer status.\r
105	\r
106	@retval EFI_SUCCESS The bulk transfer has been successfully executed.\r
107	@retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
108	@retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
109	@retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
110	@retval EFI_TIMEOUT The control transfer fails due to timeout.\r
111	\r
112	**/\r
113	typedef\r
114	EFI_STATUS\r
115	(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (\r
116	IN EFI_USB_IO_PROTOCOL *This,\r
117	IN UINT8 DeviceEndpoint,\r
118	IN OUT VOID *Data,\r
119	IN OUT UINTN *DataLength,\r
120	IN UINTN Timeout,\r
121	OUT UINT32 *Status\r
122	);\r
123	\r
124	/** \r
125	This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous \r
126