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