3 Copyright (c) 2007, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 Implementation of the USB mass storage Bulk-Only Transport protocol.
26 #include "UsbMassBot.h"
28 UINTN mUsbBotInfo
= DEBUG_INFO
;
29 UINTN mUsbBotError
= DEBUG_ERROR
;
35 IN BOOLEAN ExtendedVerification
40 Initialize the USB mass storage class BOT transport protocol.
41 It will save its context which is a USB_BOT_PROTOCOL structure
42 in the Context if Context isn't NULL.
44 @param UsbIo The USB IO protocol to use
45 @param Controller The controller to init
46 @param Context The variable to save the context to
48 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory
49 @retval EFI_UNSUPPORTED The transport protocol doesn't support the device.
50 @retval EFI_SUCCESS The device is supported and protocol initialized.
56 IN EFI_USB_IO_PROTOCOL
* UsbIo
,
57 IN EFI_HANDLE Controller
,
58 OUT VOID
**Context OPTIONAL
61 USB_BOT_PROTOCOL
*UsbBot
;
62 EFI_USB_INTERFACE_DESCRIPTOR
*Interface
;
63 EFI_USB_ENDPOINT_DESCRIPTOR EndPoint
;
68 // Allocate the BOT context, append two endpoint descriptors to it
70 UsbBot
= AllocateZeroPool (
71 sizeof (USB_BOT_PROTOCOL
) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR
)
74 return EFI_OUT_OF_RESOURCES
;
77 UsbBot
->UsbIo
= UsbIo
;
80 // Get the interface descriptor and validate that it
81 // is a USB MSC BOT interface.
83 Status
= UsbIo
->UsbGetInterfaceDescriptor (UsbIo
, &UsbBot
->Interface
);
85 if (EFI_ERROR (Status
)) {
86 DEBUG ((mUsbBotError
, "UsbBotInit: Get invalid BOT interface (%r)\n", Status
));
90 Interface
= &UsbBot
->Interface
;
92 if (Interface
->InterfaceProtocol
!= USB_MASS_STORE_BOT
) {
93 Status
= EFI_UNSUPPORTED
;
98 // Locate and save the first bulk-in and bulk-out endpoint
100 for (Index
= 0; Index
< Interface
->NumEndpoints
; Index
++) {
101 Status
= UsbIo
->UsbGetEndpointDescriptor (UsbIo
, Index
, &EndPoint
);
103 if (EFI_ERROR (Status
) || !USB_IS_BULK_ENDPOINT (EndPoint
.Attributes
)) {
107 if (USB_IS_IN_ENDPOINT (EndPoint
.EndpointAddress
) &&
108 (UsbBot
->BulkInEndpoint
== NULL
)) {
110 UsbBot
->BulkInEndpoint
= (EFI_USB_ENDPOINT_DESCRIPTOR
*) (UsbBot
+ 1);
111 *UsbBot
->BulkInEndpoint
= EndPoint
;
114 if (USB_IS_OUT_ENDPOINT (EndPoint
.EndpointAddress
) &&
115 (UsbBot
->BulkOutEndpoint
== NULL
)) {
117 UsbBot
->BulkOutEndpoint
= (EFI_USB_ENDPOINT_DESCRIPTOR
*) (UsbBot
+ 1) + 1;
118 *UsbBot
->BulkOutEndpoint
= EndPoint
;
122 if ((UsbBot
->BulkInEndpoint
== NULL
) || (UsbBot
->BulkOutEndpoint
== NULL
)) {
123 DEBUG ((mUsbBotError
, "UsbBotInit: In/Out Endpoint invalid\n"));
124 Status
= EFI_UNSUPPORTED
;
129 // The USB BOT protocol uses dCBWTag to match the CBW and CSW.
131 UsbBot
->CbwTag
= 0x01;
133 if (Context
!= NULL
) {
136 gBS
->FreePool (UsbBot
);
142 gBS
->FreePool (UsbBot
);
148 Send the command to the device using Bulk-Out endpoint
150 @param UsbBot The USB BOT device
151 @param Cmd The command to transfer to device
152 @param CmdLen the length of the command
153 @param DataDir The direction of the data
154 @param TransLen The expected length of the data
156 @retval EFI_NOT_READY The device return NAK to the transfer
157 @retval EFI_SUCCESS The command is sent to the device.
158 @retval Others Failed to send the command to device
164 IN USB_BOT_PROTOCOL
*UsbBot
,
167 IN EFI_USB_DATA_DIRECTION DataDir
,
177 ASSERT ((CmdLen
> 0) && (CmdLen
<= USB_BOT_MAX_CMDLEN
));
180 // Fill in the CSW. Only the first LUN is supported now.
182 Cbw
.Signature
= USB_BOT_CBW_SIGNATURE
;
183 Cbw
.Tag
= UsbBot
->CbwTag
;
184 Cbw
.DataLen
= TransLen
;
185 Cbw
.Flag
= (UINT8
) ((DataDir
== EfiUsbDataIn
) ? 0x80 : 0);
189 ZeroMem (Cbw
.CmdBlock
, USB_BOT_MAX_CMDLEN
);
190 CopyMem (Cbw
.CmdBlock
, Cmd
, CmdLen
);
193 DataLen
= sizeof (USB_BOT_CBW
);
194 Timeout
= USB_BOT_CBW_TIMEOUT
/ USB_MASS_STALL_1_MS
;
197 // Use the UsbIo to send the command to the device. The default
198 // time out is enough.
200 Status
= UsbBot
->UsbIo
->UsbBulkTransfer (
202 UsbBot
->BulkOutEndpoint
->EndpointAddress
,
209 // Respond to Bulk-Out endpoint stall with a Reset Recovery,
210 // see the spec section 5.3.1
212 if (EFI_ERROR (Status
)) {
213 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
) && DataDir
== EfiUsbDataOut
) {
214 UsbBotResetDevice (UsbBot
, FALSE
);
215 } else if (USB_IS_ERROR (Result
, EFI_USB_ERR_NAK
)) {
216 Status
= EFI_NOT_READY
;
225 Transfer the data between the device and host. BOT transfer
226 is composed of three phase, command, data, and status.
228 @param UsbBot The USB BOT device
229 @param DataDir The direction of the data
230 @param Data The buffer to hold data
231 @param TransLen The expected length of the data
232 @param Timeout The time to wait the command to complete
234 @retval EFI_SUCCESS The data is transferred
235 @retval Others Failed to transfer data
241 IN USB_BOT_PROTOCOL
*UsbBot
,
242 IN EFI_USB_DATA_DIRECTION DataDir
,
244 IN OUT UINTN
*TransLen
,
248 EFI_USB_ENDPOINT_DESCRIPTOR
*Endpoint
;
253 // It's OK if no data to transfer
255 if ((DataDir
== EfiUsbNoData
) || (*TransLen
== 0)) {
260 // Select the endpoint then issue the transfer
262 if (DataDir
== EfiUsbDataIn
) {
263 Endpoint
= UsbBot
->BulkInEndpoint
;
265 Endpoint
= UsbBot
->BulkOutEndpoint
;
269 Timeout
= Timeout
/ USB_MASS_STALL_1_MS
;
271 Status
= UsbBot
->UsbIo
->UsbBulkTransfer (
273 Endpoint
->EndpointAddress
,
279 if (EFI_ERROR (Status
)) {
280 DEBUG ((mUsbBotError
, "UsbBotDataTransfer: (%r)\n", Status
));
281 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
)) {
282 DEBUG ((mUsbBotError
, "UsbBotDataTransfer: DataIn Stall\n"));
283 UsbClearEndpointStall (UsbBot
->UsbIo
, Endpoint
->EndpointAddress
);
284 } else if (USB_IS_ERROR (Result
, EFI_USB_ERR_NAK
)) {
285 Status
= EFI_NOT_READY
;
294 Get the command execution status from device. BOT transfer is
295 composed of three phase, command, data, and status.
296 This function return the transfer status of the BOT's CSW status,
297 and return the high level command execution result in Result. So
298 even it returns EFI_SUCCESS, the command may still have failed.
300 @param UsbBot The USB BOT device
301 @param TransLen The expected length of the data
302 @param Timeout The time to wait the command to complete
303 @param CmdStatus The result of the command execution.
305 @retval EFI_DEVICE_ERROR Failed to retrieve the command execute result
306 @retval EFI_SUCCESS Command execute result is retrieved and in the
313 IN USB_BOT_PROTOCOL
*UsbBot
,
323 EFI_USB_IO_PROTOCOL
*UsbIo
;
327 *CmdStatus
= USB_BOT_COMMAND_ERROR
;
328 Status
= EFI_DEVICE_ERROR
;
329 Endpoint
= UsbBot
->BulkInEndpoint
->EndpointAddress
;
330 UsbIo
= UsbBot
->UsbIo
;
331 Timeout
= USB_BOT_CSW_TIMEOUT
/ USB_MASS_STALL_1_MS
;
333 for (Index
= 0; Index
< USB_BOT_GET_STATUS_RETRY
; Index
++) {
335 // Attemp to the read CSW from bulk in endpoint
337 ZeroMem (&Csw
, sizeof (USB_BOT_CSW
));
339 Len
= sizeof (USB_BOT_CSW
);
340 Status
= UsbIo
->UsbBulkTransfer (
348 if (EFI_ERROR(Status
)) {
349 DEBUG ((mUsbBotError
, "UsbBotGetStatus (%r)\n", Status
));
350 if (USB_IS_ERROR (Result
, EFI_USB_ERR_STALL
)) {
351 DEBUG ((mUsbBotError
, "UsbBotGetStatus: DataIn Stall\n"));
352 UsbClearEndpointStall (UsbIo
, Endpoint
);
357 if (Csw
.Signature
!= USB_BOT_CSW_SIGNATURE
) {
359 // Invalid Csw need perform reset recovery
361 DEBUG ((mUsbBotError
, "UsbBotGetStatus: Device return a invalid signature\n"));
362 Status
= UsbBotResetDevice (UsbBot
, FALSE
);
363 } else if (Csw
.CmdStatus
== USB_BOT_COMMAND_ERROR
) {
365 // Respond phase error need perform reset recovery
367 DEBUG ((mUsbBotError
, "UsbBotGetStatus: Device return a phase error\n"));
368 Status
= UsbBotResetDevice (UsbBot
, FALSE
);
371 *CmdStatus
= Csw
.CmdStatus
;
376 //The tag is increased even there is an error.
385 Call the Usb mass storage class transport protocol to issue
386 the command/data/status circle to execute the commands
388 @param Context The context of the BOT protocol, that is,
390 @param Cmd The high level command
391 @param CmdLen The command length
392 @param DataDir The direction of the data transfer
393 @param Data The buffer to hold data
394 @param DataLen The length of the data
395 @param Timeout The time to wait command
396 @param CmdStatus The result of high level command execution
398 @retval EFI_DEVICE_ERROR Failed to excute command
399 @retval EFI_SUCCESS The command is executed OK, and result in CmdStatus
408 IN EFI_USB_DATA_DIRECTION DataDir
,
412 OUT UINT32
*CmdStatus
415 USB_BOT_PROTOCOL
*UsbBot
;
420 *CmdStatus
= USB_MASS_CMD_FAIL
;
421 UsbBot
= (USB_BOT_PROTOCOL
*) Context
;
424 // Send the command to the device. Return immediately if device
425 // rejects the command.
427 Status
= UsbBotSendCommand (UsbBot
, Cmd
, CmdLen
, DataDir
, DataLen
);
428 if (EFI_ERROR (Status
)) {
429 DEBUG ((mUsbBotError
, "UsbBotExecCommand: UsbBotSendCommand (%r)\n", Status
));
434 // Transfer the data. Don't return immediately even data transfer
435 // failed. The host should attempt to receive the CSW no matter
436 // whether it succeeds or failed.
438 TransLen
= (UINTN
) DataLen
;
439 UsbBotDataTransfer (UsbBot
, DataDir
, Data
, &TransLen
, Timeout
);
442 // Get the status, if that succeeds, interpret the result
444 Status
= UsbBotGetStatus (UsbBot
, DataLen
, &Result
);
445 if (EFI_ERROR (Status
)) {
446 DEBUG ((mUsbBotError
, "UsbBotExecCommand: UsbBotGetStatus (%r)\n", Status
));
451 *CmdStatus
= USB_MASS_CMD_SUCCESS
;
459 Reset the mass storage device by BOT protocol
461 @param Context The context of the BOT protocol, that is,
464 @retval EFI_SUCCESS The device is reset
465 @retval Others Failed to reset the device.
472 IN BOOLEAN ExtendedVerification
475 USB_BOT_PROTOCOL
*UsbBot
;
476 EFI_USB_DEVICE_REQUEST Request
;
481 UsbBot
= (USB_BOT_PROTOCOL
*) Context
;
483 if (ExtendedVerification
) {
485 // If we need to do strictly reset, reset its parent hub port
487 Status
= UsbBot
->UsbIo
->UsbPortReset (UsbBot
->UsbIo
);
488 if (EFI_ERROR (Status
)) {
494 // Issue a class specific "Bulk-Only Mass Storage Reset reqest.
495 // See the spec section 3.1
497 Request
.RequestType
= 0x21;
498 Request
.Request
= USB_BOT_RESET_REQUEST
;
500 Request
.Index
= UsbBot
->Interface
.InterfaceNumber
;
502 Timeout
= USB_BOT_RESET_TIMEOUT
/ USB_MASS_STALL_1_MS
;
504 Status
= UsbBot
->UsbIo
->UsbControlTransfer (
514 if (EFI_ERROR (Status
)) {
515 DEBUG ((mUsbBotError
, "UsbBotResetDevice: (%r)\n", Status
));
520 // The device shall NAK the host's request until the reset is
521 // complete. We can use this to sync the device and host. For
522 // now just stall 100ms to wait the device.
524 gBS
->Stall (USB_BOT_RESET_STALL
);
527 // Clear the Bulk-In and Bulk-Out stall condition.
529 UsbClearEndpointStall (UsbBot
->UsbIo
, UsbBot
->BulkInEndpoint
->EndpointAddress
);
530 UsbClearEndpointStall (UsbBot
->UsbIo
, UsbBot
->BulkOutEndpoint
->EndpointAddress
);
536 Clean up the resource used by this BOT protocol
538 @param Context The context of the BOT protocol, that is,
541 @retval EFI_SUCCESS The resource is cleaned up.
550 gBS
->FreePool (Context
);