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