[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbMassStorageDxe / UsbMassBot.h

/** @file\r
  Definition for the USB mass storage Bulk-Only Transport protocol,\r
  based on the "Universal Serial Bus Mass Storage Class Bulk-Only\r
  Transport" Revision 1.0, September 31, 1999.\r
\r
Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\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 _EFI_USBMASS_BOT_H_\r
#define _EFI_USBMASS_BOT_H_\r
\r
extern USB_MASS_TRANSPORT mUsbBotTransport;\r
\r
//\r
// Usb Bulk-Only class specfic request\r
//\r
#define USB_BOT_RESET_REQUEST    0xFF       ///< Bulk-Only Mass Storage Reset\r
#define USB_BOT_GETLUN_REQUEST   0xFE       ///< Get Max Lun\r
#define USB_BOT_CBW_SIGNATURE    0x43425355 ///< dCBWSignature, tag the packet as CBW\r
#define USB_BOT_CSW_SIGNATURE    0x53425355 ///< dCSWSignature, tag the packet as CSW\r
#define USB_BOT_MAX_LUN          0x0F       ///< Lun number is from 0 to 15\r
#define USB_BOT_MAX_CMDLEN       16         ///< Maxium number of command from command set\r
\r
//\r
// Usb BOT command block status values\r
//\r
#define USB_BOT_COMMAND_OK       0x00 ///< Command passed, good status\r
#define USB_BOT_COMMAND_FAILED   0x01 ///< Command failed\r
#define USB_BOT_COMMAND_ERROR    0x02 ///< Phase error, need to reset the device\r
\r
//\r
// Usb Bot retry to get CSW, refers to specification[BOT10-5.3, it says 2 times]\r
//\r
#define USB_BOT_RECV_CSW_RETRY   3\r
\r
//\r
// Usb Bot wait device reset complete, set by experience\r
//  \r
#define USB_BOT_RESET_DEVICE_STALL  (100 * USB_MASS_1_MILLISECOND)\r
\r
//\r
// Usb Bot transport timeout, set by experience\r
//\r
#define USB_BOT_SEND_CBW_TIMEOUT     (3 * USB_MASS_1_SECOND)\r
#define USB_BOT_RECV_CSW_TIMEOUT     (3 * USB_MASS_1_SECOND)\r
#define USB_BOT_RESET_DEVICE_TIMEOUT (3 * USB_MASS_1_SECOND)\r
\r
#pragma pack(1)\r
///\r
/// The CBW (Command Block Wrapper) structures used by the USB BOT protocol.\r
///\r
typedef struct {\r
  UINT32              Signature;\r
  UINT32              Tag;\r
  UINT32              DataLen;  ///< Length of data between CBW and CSW\r
  UINT8               Flag;     ///< Bit 7, 0 ~ Data-Out, 1 ~ Data-In\r
  UINT8               Lun;      ///< Lun number. Bits 0~3 are used\r
  UINT8               CmdLen;   ///< Length of the command. Bits 0~4 are used\r
  UINT8               CmdBlock[USB_BOT_MAX_CMDLEN];\r
} USB_BOT_CBW;\r
\r
///\r
/// The and CSW (Command Status Wrapper) structures used by the USB BOT protocol.\r
///\r
typedef struct {\r
  UINT32              Signature;\r
  UINT32              Tag;\r
  UINT32              DataResidue;\r
  UINT8               CmdStatus;\r
} USB_BOT_CSW;\r
#pragma pack()\r
\r
typedef struct {\r
  //\r
  // Put Interface at the first field to make it easy to distinguish BOT/CBI Protocol instance\r
  //\r
  EFI_USB_INTERFACE_DESCRIPTOR  Interface;\r
  EFI_USB_ENDPOINT_DESCRIPTOR   *BulkInEndpoint;\r
  EFI_USB_ENDPOINT_DESCRIPTOR   *BulkOutEndpoint;\r
  UINT32                        CbwTag;\r
  EFI_USB_IO_PROTOCOL           *UsbIo;\r
} USB_BOT_PROTOCOL;\r
\r
/**\r
  Initializes USB BOT protocol.\r
\r
  This function initializes the USB mass storage class BOT protocol.\r
  It will save its context which is a USB_BOT_PROTOCOL structure\r
  in the Context if Context isn't NULL.\r
\r
  @param  UsbIo                 The USB I/O Protocol instance\r
  @param  Context               The buffer to save the context to\r
\r
  @retval EFI_SUCCESS           The device is successfully initialized.\r
  @retval EFI_UNSUPPORTED       The transport protocol doesn't support the device.\r
  @retval Other                 The USB BOT initialization fails.\r
\r
**/\r
EFI_STATUS\r
UsbBotInit (\r
  IN  EFI_USB_IO_PROTOCOL       *UsbIo,\r
  OUT VOID                      **Context OPTIONAL\r
  );\r
\r
/**\r
  Call the USB Mass Storage Class BOT protocol to issue\r
  the command/data/status circle to execute the commands.\r
\r
  @param  Context               The context of the BOT protocol, that is,\r
                                USB_BOT_PROTOCOL\r
  @param  Cmd                   The high level command\r
  @param  CmdLen                The command length\r
  @param  DataDir               The direction of the data transfer\r
  @param  Data                  The buffer to hold data\r
  @param  DataLen               The length of the data\r
  @param  Lun                   The number of logic unit\r
  @param  Timeout               The time to wait command\r
  @param  CmdStatus             The result of high level command execution\r
\r
  @retval EFI_SUCCESS           The command is executed successfully.\r
  @retval Other                 Failed to execute command\r
\r
**/\r
EFI_STATUS\r
UsbBotExecCommand (\r
  IN  VOID                    *Context,\r
  IN  VOID                    *Cmd,\r
  IN  UINT8                   CmdLen,\r
  IN  EFI_USB_DATA_DIRECTION  DataDir,\r
  IN  VOID                    *Data,\r
  IN  UINT32                  DataLen,\r
  IN  UINT8                   Lun,\r
  IN  UINT32                  Timeout,\r
  OUT UINT32                  *CmdStatus\r
  );\r
\r
/**\r
  Reset the USB mass storage device by BOT protocol.\r
\r
  @param  Context               The context of the BOT protocol, that is,\r
                                USB_BOT_PROTOCOL.\r
  @param  ExtendedVerification  If FALSE, just issue Bulk-Only Mass Storage Reset request.\r
                                If TRUE, additionally reset parent hub port.\r
\r
  @retval EFI_SUCCESS           The device is reset.\r
  @retval Others                Failed to reset the device..\r
\r
**/\r
EFI_STATUS\r
UsbBotResetDevice (\r
  IN  VOID                    *Context,\r
  IN  BOOLEAN                 ExtendedVerification\r
  );\r
\r
/**\r
  Get the max LUN (Logical Unit Number) of USB mass storage device.\r
\r
  @param  Context          The context of the BOT protocol, that is, USB_BOT_PROTOCOL\r
  @param  MaxLun           Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and\r
                           LUN1 in all.)\r
\r
  @retval EFI_SUCCESS      Max LUN is got successfully.\r
  @retval Others           Fail to execute this request.\r
\r
**/\r
EFI_STATUS\r
UsbBotGetMaxLun (\r
  IN  VOID                    *Context,\r
  OUT UINT8                   *MaxLun\r
  );\r
\r
/**\r
  Clean up the resource used by this BOT protocol.\r
\r
  @param  Context         The context of the BOT protocol, that is, USB_BOT_PROTOCOL.\r
\r
  @retval EFI_SUCCESS     The resource is cleaned up.\r
\r
**/\r
EFI_STATUS\r
UsbBotCleanUp (\r
  IN  VOID                    *Context\r
  );\r
\r
#endif\r
Commit	Line	Data
e237e7ae	1	/** @file\r
d80ed2a7	2	Definition for the USB mass storage Bulk-Only Transport protocol,\r
	3	based on the "Universal Serial Bus Mass Storage Class Bulk-Only\r
	4	Transport" Revision 1.0, September 31, 1999.\r
cc5166ff	5	\r
39840c50	6	Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR>\r
cd5ebaa0	7	This program and the accompanying materials\r
e237e7ae	8	are licensed and made available under the terms and conditions of the BSD License\r
	9	which accompanies this distribution. The full text of the license may be found at\r
	10	http://opensource.org/licenses/bsd-license.php\r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	14	\r
e237e7ae	15	**/\r
	16	\r
	17	#ifndef _EFI_USBMASS_BOT_H_\r
	18	#define _EFI_USBMASS_BOT_H_\r
	19	\r
d80ed2a7	20	extern USB_MASS_TRANSPORT mUsbBotTransport;\r
d80ed2a7	21	\r
1ccdbf2a	22	//\r
	23	// Usb Bulk-Only class specfic request\r
	24	//\r
	25	#define USB_BOT_RESET_REQUEST 0xFF ///< Bulk-Only Mass Storage Reset\r
	26	#define USB_BOT_GETLUN_REQUEST 0xFE ///< Get Max Lun\r
	27	#define USB_BOT_CBW_SIGNATURE 0x43425355 ///< dCBWSignature, tag the packet as CBW\r
	28	#define USB_BOT_CSW_SIGNATURE 0x53425355 ///< dCSWSignature, tag the packet as CSW\r
	29	#define USB_BOT_MAX_LUN 0x0F ///< Lun number is from 0 to 15\r
	30	#define USB_BOT_MAX_CMDLEN 16 ///< Maxium number of command from command set\r
e237e7ae	31	\r
1ccdbf2a	32	//\r
	33	// Usb BOT command block status values\r
	34	//\r
	35	#define USB_BOT_COMMAND_OK 0x00 ///< Command passed, good status\r
	36	#define USB_BOT_COMMAND_FAILED 0x01 ///< Command failed\r
	37	#define USB_BOT_COMMAND_ERROR 0x02 ///< Phase error, need to reset the device\r
e237e7ae	38	\r
1ccdbf2a	39	//\r
	40	// Usb Bot retry to get CSW, refers to specification[BOT10-5.3, it says 2 times]\r
	41	//\r
	42	#define USB_BOT_RECV_CSW_RETRY 3\r
e237e7ae	43	\r
1ccdbf2a	44	//\r
	45	// Usb Bot wait device reset complete, set by experience\r
	46	// \r
	47	#define USB_BOT_RESET_DEVICE_STALL (100 * USB_MASS_1_MILLISECOND)\r
	48	\r
	49	//\r
	50	// Usb Bot transport timeout, set by experience\r
	51	//\r
	52	#define USB_BOT_SEND_CBW_TIMEOUT (3 * USB_MASS_1_SECOND)\r
	53	#define USB_BOT_RECV_CSW_TIMEOUT (3 * USB_MASS_1_SECOND)\r
	54	#define USB_BOT_RESET_DEVICE_TIMEOUT (3 * USB_MASS_1_SECOND)\r
e237e7ae	55	\r
e237e7ae	56	#pragma pack(1)\r
d80ed2a7	57	///\r
	58	/// The CBW (Command Block Wrapper) structures used by the USB BOT protocol.\r
	59	///\r
e237e7ae	60	typedef struct {\r
	61	UINT32 Signature;\r
	62	UINT32 Tag;\r
d80ed2a7	63	UINT32 DataLen; ///< Length of data between CBW and CSW\r
	64	UINT8 Flag; ///< Bit 7, 0 ~ Data-Out, 1 ~ Data-In\r
	65	UINT8 Lun; ///< Lun number. Bits 0~3 are used\r
	66	UINT8 CmdLen; ///< Length of the command. Bits 0~4 are used\r
e237e7ae	67	UINT8 CmdBlock[USB_BOT_MAX_CMDLEN];\r
	68	} USB_BOT_CBW;\r
	69	\r
d80ed2a7	70	///\r
	71	/// The and CSW (Command Status Wrapper) structures used by the USB BOT protocol.\r
	72	///\r
e237e7ae	73	typedef struct {\r
	74	UINT32 Signature;\r
	75	UINT32 Tag;\r
	76	UINT32 DataResidue;\r
	77	UINT8 CmdStatus;\r
	78	} USB_BOT_CSW;\r
	79	#pragma pack()\r
	80	\r
e237e7ae	81	typedef struct {\r
d80ed2a7	82	//\r
	83	// Put Interface at the first field to make it easy to distinguish BOT/CBI Protocol instance\r
	84	//\r
e237e7ae	85	EFI_USB_INTERFACE_DESCRIPTOR Interface;\r
	86	EFI_USB_ENDPOINT_DESCRIPTOR *BulkInEndpoint;\r
	87	EFI_USB_ENDPOINT_DESCRIPTOR *BulkOutEndpoint;\r
	88	UINT32 CbwTag;\r
	89	EFI_USB_IO_PROTOCOL *UsbIo;\r
	90	} USB_BOT_PROTOCOL;\r
	91	\r
d80ed2a7	92	/**\r
	93	Initializes USB BOT protocol.\r
	94	\r
	95	This function initializes the USB mass storage class BOT protocol.\r
	96	It will save its context which is a USB_BOT_PROTOCOL structure\r
	97	in the Context if Context isn't NULL.\r
	98	\r
	99	@param UsbIo The USB I/O Protocol instance\r
	100	@param Context The buffer to save the context to\r
	101	\r
	102	@retval EFI_SUCCESS The device is successfully initialized.\r
	103	@retval EFI_UNSUPPORTED The transport protocol doesn't support the device.\r
	104	@retval Other The USB BOT initialization fails.\r
	105	\r
	106	**/\r
	107	EFI_STATUS\r
	108	UsbBotInit (\r
	109	IN EFI_USB_IO_PROTOCOL *UsbIo,\r
	110	OUT VOID **Context OPTIONAL\r
	111	);\r
	112	\r
	113	/**\r
	114	Call the USB Mass Storage Class BOT protocol to issue\r
	115	the command/data/status circle to execute the commands.\r
	116	\r
	117	@param Context The context of the BOT protocol, that is,\r
	118	USB_BOT_PROTOCOL\r
	119	@param Cmd The high level command\r
	120	@param CmdLen The command length\r
	121	@param DataDir The direction of the data transfer\r
	122	@param Data The buffer to hold data\r
	123	@param DataLen The length of the data\r
	124	@param Lun The number of logic unit\r
	125	@param Timeout The time to wait command\r
	126	@param CmdStatus The result of high level command execution\r
	127	\r
	128	@retval EFI_SUCCESS The command is executed successfully.\r
ed356b9e	129	@retval Other Failed to execute command\r
d80ed2a7	130	\r
	131	**/\r
	132	EFI_STATUS\r
	133	UsbBotExecCommand (\r
	134	IN VOID *Context,\r
	135	IN VOID *Cmd,\r
	136	IN UINT8 CmdLen,\r
	137	IN EFI_USB_DATA_DIRECTION DataDir,\r
	138	IN VOID *Data,\r
	139	IN UINT32 DataLen,\r
	140	IN UINT8 Lun,\r
	141	IN UINT32 Timeout,\r
	142	OUT UINT32 *CmdStatus\r
	143	);\r
	144	\r
	145	/**\r
	146	Reset the USB mass storage device by BOT protocol.\r
	147	\r
	148	@param Context The context of the BOT protocol, that is,\r
	149	USB_BOT_PROTOCOL.\r
	150	@param ExtendedVerification If FALSE, just issue Bulk-Only Mass Storage Reset request.\r
	151	If TRUE, additionally reset parent hub port.\r
	152	\r
	153	@retval EFI_SUCCESS The device is reset.\r
	154	@retval Others Failed to reset the device..\r
	155	\r
	156	**/\r
	157	EFI_STATUS\r
	158	UsbBotResetDevice (\r
	159	IN VOID *Context,\r
	160	IN BOOLEAN ExtendedVerification\r
	161	);\r
	162	\r
	163	/**\r
	164	Get the max LUN (Logical Unit Number) of USB mass storage device.\r
	165	\r
	166	@param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL\r
	167	@param MaxLun Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and\r
	168	LUN1 in all.)\r
	169	\r
	170	@retval EFI_SUCCESS Max LUN is got successfully.\r
	171	@retval Others Fail to execute this request.\r
	172	\r
	173	**/\r
	174	EFI_STATUS\r
	175	UsbBotGetMaxLun (\r
	176	IN VOID *Context,\r
	177	OUT UINT8 *MaxLun\r
	178	);\r
	179	\r
	180	/**\r
	181	Clean up the resource used by this BOT protocol.\r
	182	\r
	183	@param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL.\r
	184	\r
	185	@retval EFI_SUCCESS The resource is cleaned up.\r
	186	\r
	187	**/\r
	188	EFI_STATUS\r
	189	UsbBotCleanUp (\r
	190	IN VOID *Context\r
	191	);\r
	192	\r
e237e7ae	193	#endif\r