2 Implementation of the USB mass storage Bulk-Only Transport protocol,
3 according to USB Mass Storage Class Bulk-Only Transport, Revision 1.0.
5 Copyright (c) 2007 - 2008, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #include "UsbMassBoot.h"
17 #include "UsbMassBot.h"
20 // Definition of USB BOT Transport Protocol
22 USB_MASS_TRANSPORT mUsbBotTransport
= {
32 Initializes USB BOT protocol.
34 This function initializes the USB mass storage class BOT protocol.
35 It will save its context which is a USB_BOT_PROTOCOL structure
36 in the Context if Context isn't NULL.
38 @param UsbIo The USB I/O Protocol instance
39 @param Context The buffer to save the context to
41 @retval EFI_SUCCESS The device is successfully initialized.
42 @retval EFI_UNSUPPORTED The transport protocol doesn't support the device.
43 @retval Other The USB BOT initialization fails.
48 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
49 OUT VOID
**Context OPTIONAL
52 USB_BOT_PROTOCOL
*UsbBot
;
53 EFI_USB_INTERFACE_DESCRIPTOR
*Interface
;
54 EFI_USB_ENDPOINT_DESCRIPTOR EndPoint
;
59 // Allocate the BOT context for USB_BOT_PROTOCOL and two endpoint descriptors.
61 UsbBot
= AllocateZeroPool (sizeof (USB_BOT_PROTOCOL
) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR
));
62 ASSERT (UsbBot
!= NULL
);
64 UsbBot
->UsbIo
= UsbIo
;
67 // Get the interface descriptor and validate that it
68 // is a USB Mass Storage BOT interface.
70 Status
= UsbIo
->UsbGetInterfaceDescriptor (UsbIo
, &UsbBot
->Interface
);
72 if (EFI_ERROR (Status
)) {
76 Interface
= &UsbBot
->Interface
;
78 if (Interface
->InterfaceProtocol
!= USB_MASS_STORE_BOT
) {
79 Status
= EFI_UNSUPPORTED
;
84 // Locate and save the first bulk-in and bulk-out endpoint
86 for (Index
= 0; Index
< Interface
->NumEndpoints
; Index
++) {
87 Status
= UsbIo
->UsbGetEndpointDescriptor (UsbIo
, Index
, &EndPoint
);
89 if (EFI_ERROR (Status
) || !USB_IS_BULK_ENDPOINT (EndPoint
.Attributes
)) {
93 if (USB_IS_IN_ENDPOINT (EndPoint
.EndpointAddress
) &&
94 (UsbBot
->BulkInEndpoint
== NULL
)) {
96 UsbBot
->BulkInEndpoint
= (EFI_USB_ENDPOINT_DESCRIPTOR
*) (UsbBot
+ 1);
97 CopyMem(UsbBot
->BulkInEndpoint
, &EndPoint
, sizeof (EndPoint
));
100 if (USB_IS_OUT_ENDPOINT (EndPoint
.EndpointAddress
) &&
101 (UsbBot
->BulkOutEndpoint
== NULL
)) {
103 UsbBot
->BulkOutEndpoint
= (EFI_USB_ENDPOINT_DESCRIPTOR
*) (UsbBot
+ 1) + 1;
104 CopyMem (UsbBot
->BulkOutEndpoint
, &EndPoint
, sizeof(EndPoint
));
109 // If bulk-in or bulk-out endpoint is not found, report error.
111 if ((UsbBot
->BulkInEndpoint
== NULL
) || (UsbBot
->BulkOutEndpoint
== NULL
)) {
112 Status
= EFI_UNSUPPORTED
;
117 // The USB BOT protocol uses CBWTag to match the CBW and CSW.
119 UsbBot
->CbwTag
= 0x01;
121 if (Context
!= NULL
) {
135 Send the command to the device using Bulk-Out endpoint.
137 This function sends the command to the device using Bulk-Out endpoint.
138 BOT transfer is composed of three phases: Command, Data, and Status.
139 This is the Command phase.
141 @param UsbBot The USB BOT device
142 @param Cmd The command to transfer to device
143 @param CmdLen The length of the command
144 @param DataDir The direction of the data
145 @param TransLen The expected length of the data
146 @param Lun The number of logic unit
148 @retval EFI_SUCCESS The command is sent to the device.
149 @retval EFI_NOT_READY The device return NAK to the transfer
150 @retval Others Failed to send the command to device
155 IN USB_BOT_PROTOCOL
*UsbBot
,
158 IN EFI_USB_DATA_DIRECTION DataDir
,
169 ASSERT ((CmdLen
> 0) && (CmdLen
<= USB_BOT_MAX_CMDLEN
));
172 // Fill in the Command Block Wrapper.
174 Cbw
.Signature
= USB_BOT_CBW_SIGNATURE
;
175 Cbw
.Tag
= UsbBot
->CbwTag
;
176 Cbw
.DataLen
= TransLen
;
177 Cbw
.Flag
= (UINT8
) ((DataDir
== EfiUsbDataIn
) ? BIT7
: 0);
181 ZeroMem (Cbw
.CmdBlock
, USB_BOT_MAX_CMDLEN
);
182 CopyMem (Cbw
.CmdBlock
, Cmd
, CmdLen
);
185 DataLen
= sizeof (USB_BOT_CBW
);
186 Timeout
= USB_BOT_SEND_CBW_TIMEOUT
/ USB_MASS_1_MILLISECOND
;
189 // Use USB I/O Protocol to send the Command Block Wrapper to the device.
191 Status
= UsbBot
->UsbIo
->UsbBulkTransfer (
193 UsbBot
->BulkOutEndpoint
->EndpointAddress
,
199 if (EFI_ERROR (Status
)) {
200 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
) && DataDir
== EfiUsbDataOut
) {
202 // Respond to Bulk-Out endpoint stall with a Reset Recovery,
203 // according to section 5.3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
205 UsbBotResetDevice (UsbBot
, FALSE
);
206 } else if (USB_IS_ERROR (Result
, EFI_USB_ERR_NAK
)) {
207 Status
= EFI_NOT_READY
;
216 Transfer the data between the device and host.
218 This function transfers the data between the device and host.
219 BOT transfer is composed of three phases: Command, Data, and Status.
220 This is the Data phase.
222 @param UsbBot The USB BOT device
223 @param DataDir The direction of the data
224 @param Data The buffer to hold data
225 @param TransLen The expected length of the data
226 @param Timeout The time to wait the command to complete
228 @retval EFI_SUCCESS The data is transferred
229 @retval EFI_SUCCESS No data to transfer
230 @retval EFI_NOT_READY The device return NAK to the transfer
231 @retval Others Failed to transfer data
236 IN USB_BOT_PROTOCOL
*UsbBot
,
237 IN EFI_USB_DATA_DIRECTION DataDir
,
239 IN OUT UINTN
*TransLen
,
243 EFI_USB_ENDPOINT_DESCRIPTOR
*Endpoint
;
248 // If no data to transfer, just return EFI_SUCCESS.
250 if ((DataDir
== EfiUsbNoData
) || (*TransLen
== 0)) {
255 // Select the endpoint then issue the transfer
257 if (DataDir
== EfiUsbDataIn
) {
258 Endpoint
= UsbBot
->BulkInEndpoint
;
260 Endpoint
= UsbBot
->BulkOutEndpoint
;
264 Timeout
= Timeout
/ USB_MASS_1_MILLISECOND
;
266 Status
= UsbBot
->UsbIo
->UsbBulkTransfer (
268 Endpoint
->EndpointAddress
,
274 if (EFI_ERROR (Status
)) {
275 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
)) {
276 DEBUG ((EFI_D_INFO
, "UsbBotDataTransfer: (%r)\n", Status
));
277 DEBUG ((EFI_D_INFO
, "UsbBotDataTransfer: DataIn Stall\n"));
278 UsbClearEndpointStall (UsbBot
->UsbIo
, Endpoint
->EndpointAddress
);
279 } else if (USB_IS_ERROR (Result
, EFI_USB_ERR_NAK
)) {
280 Status
= EFI_NOT_READY
;
282 DEBUG ((EFI_D_ERROR
, "UsbBotDataTransfer: (%r)\n", Status
));
284 if(Status
== EFI_TIMEOUT
){
285 UsbBotResetDevice(UsbBot
, FALSE
);
294 Get the command execution status from device.
296 This function gets the command execution status from device.
297 BOT transfer is composed of three phases: Command, Data, and Status.
298 This is the Status phase.
300 This function returns the transfer status of the BOT's CSW status,
301 and returns the high level command execution result in Result. So
302 even if EFI_SUCCESS is returned, the command may still have failed.
304 @param UsbBot The USB BOT device.
305 @param TransLen The expected length of the data.
306 @param CmdStatus The result of the command execution.
308 @retval EFI_SUCCESS Command execute result is retrieved and in the Result.
309 @retval Other Error occurred when trying to get status.
314 IN USB_BOT_PROTOCOL
*UsbBot
,
324 EFI_USB_IO_PROTOCOL
*UsbIo
;
328 *CmdStatus
= USB_BOT_COMMAND_ERROR
;
329 Status
= EFI_DEVICE_ERROR
;
330 Endpoint
= UsbBot
->BulkInEndpoint
->EndpointAddress
;
331 UsbIo
= UsbBot
->UsbIo
;
332 Timeout
= USB_BOT_RECV_CSW_TIMEOUT
/ USB_MASS_1_MILLISECOND
;
334 for (Index
= 0; Index
< USB_BOT_RECV_CSW_RETRY
; Index
++) {
336 // Attemp to the read Command Status Wrapper from bulk in endpoint
338 ZeroMem (&Csw
, sizeof (USB_BOT_CSW
));
340 Len
= sizeof (USB_BOT_CSW
);
341 Status
= UsbIo
->UsbBulkTransfer (
349 if (EFI_ERROR(Status
)) {
350 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
)) {
351 UsbClearEndpointStall (UsbIo
, Endpoint
);
356 if (Csw
.Signature
!= USB_BOT_CSW_SIGNATURE
) {
358 // CSW is invalid, so perform reset recovery
360 Status
= UsbBotResetDevice (UsbBot
, FALSE
);
361 } else if (Csw
.CmdStatus
== USB_BOT_COMMAND_ERROR
) {
363 // Respond phase error also needs reset recovery
365 Status
= UsbBotResetDevice (UsbBot
, FALSE
);
367 *CmdStatus
= Csw
.CmdStatus
;
372 //The tag is increased even if there is an error.
381 Call the USB Mass Storage Class BOT protocol to issue
382 the command/data/status circle to execute the commands.
384 @param Context The context of the BOT protocol, that is,
386 @param Cmd The high level command
387 @param CmdLen The command length
388 @param DataDir The direction of the data transfer
389 @param Data The buffer to hold data
390 @param DataLen The length of the data
391 @param Lun The number of logic unit
392 @param Timeout The time to wait command
393 @param CmdStatus The result of high level command execution
395 @retval EFI_SUCCESS The command is executed successfully.
396 @retval Other Failed to excute command
404 IN EFI_USB_DATA_DIRECTION DataDir
,
409 OUT UINT32
*CmdStatus
412 USB_BOT_PROTOCOL
*UsbBot
;
417 *CmdStatus
= USB_MASS_CMD_FAIL
;
418 UsbBot
= (USB_BOT_PROTOCOL
*) Context
;
421 // Send the command to the device. Return immediately if device
422 // rejects the command.
424 Status
= UsbBotSendCommand (UsbBot
, Cmd
, CmdLen
, DataDir
, DataLen
, Lun
);
425 if (EFI_ERROR (Status
)) {
426 DEBUG ((EFI_D_ERROR
, "UsbBotExecCommand: UsbBotSendCommand (%r)\n", Status
));
431 // Transfer the data. Don't return immediately even data transfer
432 // failed. The host should attempt to receive the CSW no matter
433 // whether it succeeds or fails.
435 TransLen
= (UINTN
) DataLen
;
436 UsbBotDataTransfer (UsbBot
, DataDir
, Data
, &TransLen
, Timeout
);
439 // Get the status, if that succeeds, interpret the result
441 Status
= UsbBotGetStatus (UsbBot
, DataLen
, &Result
);
442 if (EFI_ERROR (Status
)) {
443 DEBUG ((EFI_D_ERROR
, "UsbBotExecCommand: UsbBotGetStatus (%r)\n", Status
));
448 *CmdStatus
= USB_MASS_CMD_SUCCESS
;
456 Reset the USB mass storage device by BOT protocol.
458 @param Context The context of the BOT protocol, that is,
460 @param ExtendedVerification If FALSE, just issue Bulk-Only Mass Storage Reset request.
461 If TRUE, additionally reset parent hub port.
463 @retval EFI_SUCCESS The device is reset.
464 @retval Others Failed to reset the device..
470 IN BOOLEAN ExtendedVerification
473 USB_BOT_PROTOCOL
*UsbBot
;
474 EFI_USB_DEVICE_REQUEST Request
;
479 UsbBot
= (USB_BOT_PROTOCOL
*) Context
;
481 if (ExtendedVerification
) {
483 // If we need to do strictly reset, reset its parent hub port
485 Status
= UsbBot
->UsbIo
->UsbPortReset (UsbBot
->UsbIo
);
486 if (EFI_ERROR (Status
)) {
492 // Issue a class specific Bulk-Only Mass Storage Reset request,
493 // according to section 3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
495 Request
.RequestType
= 0x21;
496 Request
.Request
= USB_BOT_RESET_REQUEST
;
498 Request
.Index
= UsbBot
->Interface
.InterfaceNumber
;
500 Timeout
= USB_BOT_RESET_DEVICE_TIMEOUT
/ USB_MASS_1_MILLISECOND
;
502 Status
= UsbBot
->UsbIo
->UsbControlTransfer (
512 if (EFI_ERROR (Status
)) {
517 // The device shall NAK the host's request until the reset is
518 // complete. We can use this to sync the device and host. For
519 // now just stall 100ms to wait for the device.
521 gBS
->Stall (USB_BOT_RESET_DEVICE_STALL
);
524 // Clear the Bulk-In and Bulk-Out stall condition.
526 UsbClearEndpointStall (UsbBot
->UsbIo
, UsbBot
->BulkInEndpoint
->EndpointAddress
);
527 UsbClearEndpointStall (UsbBot
->UsbIo
, UsbBot
->BulkOutEndpoint
->EndpointAddress
);
534 Get the max LUN (Logical Unit Number) of USB mass storage device.
536 @param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL
537 @param MaxLun Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and
540 @retval EFI_SUCCESS Max LUN is got successfully.
541 @retval Others Fail to execute this request.
550 USB_BOT_PROTOCOL
*UsbBot
;
551 EFI_USB_DEVICE_REQUEST Request
;
558 UsbBot
= (USB_BOT_PROTOCOL
*) Context
;
561 // Issue a class specific Bulk-Only Mass Storage get max lun reqest.
562 // according to section 3.2 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
564 Request
.RequestType
= 0xA1;
565 Request
.Request
= USB_BOT_GETLUN_REQUEST
;
567 Request
.Index
= UsbBot
->Interface
.InterfaceNumber
;
569 Timeout
= USB_BOT_RESET_DEVICE_TIMEOUT
/ USB_MASS_1_MILLISECOND
;
571 Status
= UsbBot
->UsbIo
->UsbControlTransfer (
585 Clean up the resource used by this BOT protocol.
587 @param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL.
589 @retval EFI_SUCCESS The resource is cleaned up.