summaryrefslogtreecommitdiff
path: root/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c
diff options
context:
space:
mode:
authorxli24 <xli24@6f19259b-4bc3-4df7-8a09-765794883524>2009-01-12 03:11:00 +0000
committerxli24 <xli24@6f19259b-4bc3-4df7-8a09-765794883524>2009-01-12 03:11:00 +0000
commitd80ed2a76eec1786412fb76cc080cfb38ae77011 (patch)
tree231c6639f54dce8c49809101730ba2e55d14e8d5 /MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c
parentcdfdbb970a8b7311391a28e046f39d4cc3b7d610 (diff)
downloadedk2-platforms-d80ed2a76eec1786412fb76cc080cfb38ae77011.tar.xz
Code scrub for USB Mass Storage Driver.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7243 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c')
-rw-r--r--MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c205
1 files changed, 94 insertions, 111 deletions
diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c
index ba5f9d025b..178aa80d3e 100644
--- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c
+++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c
@@ -1,6 +1,6 @@
/** @file
-
- Implementation of the USB mass storage Bulk-Only Transport protocol.
+ Implementation of the USB mass storage Bulk-Only Transport protocol,
+ according to USB Mass Storage Class Bulk-Only Transport, Revision 1.0.
Copyright (c) 2007 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -16,41 +16,36 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include "UsbMass.h"
#include "UsbMassBot.h"
-/**
- Reset the mass storage device by BOT protocol.
-
- @param Context The context of the BOT protocol, that is,
- USB_BOT_PROTOCOL.
- @param ExtendedVerification The flag controlling the rule of reset dev.
-
- @retval EFI_SUCCESS The device is reset.
- @retval Others Failed to reset the device..
-
-**/
-EFI_STATUS
-UsbBotResetDevice (
- IN VOID *Context,
- IN BOOLEAN ExtendedVerification
- );
-
+//
+// Definition of USB BOT Transport Protocol
+//
+USB_MASS_TRANSPORT mUsbBotTransport = {
+ USB_MASS_STORE_BOT,
+ UsbBotInit,
+ UsbBotExecCommand,
+ UsbBotResetDevice,
+ UsbBotGetMaxLun,
+ UsbBotCleanUp
+};
/**
- Initialize the USB mass storage class BOT transport protocol.
+ Initializes USB BOT protocol.
+
+ This function initializes the USB mass storage class BOT protocol.
It will save its context which is a USB_BOT_PROTOCOL structure
in the Context if Context isn't NULL.
- @param UsbIo The USB IO protocol to use
- @param Context The variable to save the context to
+ @param UsbIo The USB I/O Protocol instance
+ @param Context The buffer to save the context to
- @retval EFI_OUT_OF_RESOURCES Failed to allocate memory
+ @retval EFI_SUCCESS The device is successfully initialized.
@retval EFI_UNSUPPORTED The transport protocol doesn't support the device.
- @retval EFI_SUCCESS The device is supported and protocol initialized.
- @retval Other The UBS BOT initialization fails.
+ @retval Other The USB BOT initialization fails.
**/
EFI_STATUS
UsbBotInit (
- IN EFI_USB_IO_PROTOCOL * UsbIo,
+ IN EFI_USB_IO_PROTOCOL *UsbIo,
OUT VOID **Context OPTIONAL
)
{
@@ -61,25 +56,22 @@ UsbBotInit (
UINT8 Index;
//
- // Allocate the BOT context, append two endpoint descriptors to it
+ // Allocate the BOT context for USB_BOT_PROTOCOL and two endpoint descriptors.
//
UsbBot = AllocateZeroPool (
sizeof (USB_BOT_PROTOCOL) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)
);
- if (UsbBot == NULL) {
- return EFI_OUT_OF_RESOURCES;
- }
+ ASSERT (UsbBot != NULL);
UsbBot->UsbIo = UsbIo;
//
// Get the interface descriptor and validate that it
- // is a USB MSC BOT interface.
+ // is a USB Mass Storage BOT interface.
//
Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &UsbBot->Interface);
if (EFI_ERROR (Status)) {
- DEBUG ((EFI_D_ERROR, "UsbBotInit: Get invalid BOT interface (%r)\n", Status));
goto ON_ERROR;
}
@@ -115,14 +107,16 @@ UsbBotInit (
}
}
+ //
+ // If bulk-in or bulk-out endpoint is not found, report error.
+ //
if ((UsbBot->BulkInEndpoint == NULL) || (UsbBot->BulkOutEndpoint == NULL)) {
- DEBUG ((EFI_D_ERROR, "UsbBotInit: In/Out Endpoint invalid\n"));
Status = EFI_UNSUPPORTED;
goto ON_ERROR;
}
//
- // The USB BOT protocol uses dCBWTag to match the CBW and CSW.
+ // The USB BOT protocol uses CBWTag to match the CBW and CSW.
//
UsbBot->CbwTag = 0x01;
@@ -139,19 +133,22 @@ ON_ERROR:
return Status;
}
-
/**
Send the command to the device using Bulk-Out endpoint.
+ This function sends the command to the device using Bulk-Out endpoint.
+ BOT transfer is composed of three phases: Command, Data, and Status.
+ This is the Command phase.
+
@param UsbBot The USB BOT device
@param Cmd The command to transfer to device
- @param CmdLen the length of the command
+ @param CmdLen The length of the command
@param DataDir The direction of the data
@param TransLen The expected length of the data
@param Lun The number of logic unit
- @retval EFI_NOT_READY The device return NAK to the transfer
@retval EFI_SUCCESS The command is sent to the device.
+ @retval EFI_NOT_READY The device return NAK to the transfer
@retval Others Failed to send the command to device
**/
@@ -174,25 +171,24 @@ UsbBotSendCommand (
ASSERT ((CmdLen > 0) && (CmdLen <= USB_BOT_MAX_CMDLEN));
//
- // Fill in the CSW. Only the first LUN is supported now.
+ // Fill in the Command Block Wrapper.
//
Cbw.Signature = USB_BOT_CBW_SIGNATURE;
Cbw.Tag = UsbBot->CbwTag;
Cbw.DataLen = TransLen;
- Cbw.Flag = (UINT8) ((DataDir == EfiUsbDataIn) ? 0x80 : 0);
+ Cbw.Flag = (UINT8) ((DataDir == EfiUsbDataIn) ? BIT7 : 0);
Cbw.Lun = Lun;
Cbw.CmdLen = CmdLen;
ZeroMem (Cbw.CmdBlock, USB_BOT_MAX_CMDLEN);
CopyMem (Cbw.CmdBlock, Cmd, CmdLen);
- Result = 0;
- DataLen = sizeof (USB_BOT_CBW);
- Timeout = USB_BOT_SEND_CBW_TIMEOUT / USB_MASS_1_MILLISECOND;
+ Result = 0;
+ DataLen = sizeof (USB_BOT_CBW);
+ Timeout = USB_BOT_SEND_CBW_TIMEOUT / USB_MASS_1_MILLISECOND;
//
- // Use the UsbIo to send the command to the device. The default
- // time out is enough.
+ // Use USB I/O Protocol to send the Command Block Wrapper to the device.
//
Status = UsbBot->UsbIo->UsbBulkTransfer (
UsbBot->UsbIo,
@@ -202,12 +198,12 @@ UsbBotSendCommand (
Timeout,
&Result
);
- //
- // Respond to Bulk-Out endpoint stall with a Reset Recovery,
- // see the spec section 5.3.1
- //
if (EFI_ERROR (Status)) {
if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL) && DataDir == EfiUsbDataOut) {
+ //
+ // Respond to Bulk-Out endpoint stall with a Reset Recovery,
+ // according to section 5.3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
+ //
UsbBotResetDevice (UsbBot, FALSE);
} else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
Status = EFI_NOT_READY;
@@ -219,8 +215,11 @@ UsbBotSendCommand (
/**
- Transfer the data between the device and host. BOT transfer
- is composed of three phase, command, data, and status.
+ Transfer the data between the device and host.
+
+ This function transfers the data between the device and host.
+ BOT transfer is composed of three phases: Command, Data, and Status.
+ This is the Data phase.
@param UsbBot The USB BOT device
@param DataDir The direction of the data
@@ -229,6 +228,8 @@ UsbBotSendCommand (
@param Timeout The time to wait the command to complete
@retval EFI_SUCCESS The data is transferred
+ @retval EFI_SUCCESS No data to transfer
+ @retval EFI_NOT_READY The device return NAK to the transfer
@retval Others Failed to transfer data
**/
@@ -246,7 +247,7 @@ UsbBotDataTransfer (
UINT32 Result;
//
- // It's OK if no data to transfer
+ // If no data to transfer, just return EFI_SUCCESS.
//
if ((DataDir == EfiUsbNoData) || (*TransLen == 0)) {
return EFI_SUCCESS;
@@ -273,9 +274,7 @@ UsbBotDataTransfer (
&Result
);
if (EFI_ERROR (Status)) {
- DEBUG ((EFI_D_ERROR, "UsbBotDataTransfer: (%r)\n", Status));
if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
- DEBUG ((EFI_D_ERROR, "UsbBotDataTransfer: DataIn Stall\n"));
UsbClearEndpointStall (UsbBot->UsbIo, Endpoint->EndpointAddress);
} else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
Status = EFI_NOT_READY;
@@ -287,19 +286,22 @@ UsbBotDataTransfer (
/**
- Get the command execution status from device. BOT transfer is
- composed of three phase, command, data, and status.
- This function return the transfer status of the BOT's CSW status,
- and return the high level command execution result in Result. So
- even it returns EFI_SUCCESS, the command may still have failed.
+ Get the command execution status from device.
+
+ This function gets the command execution status from device.
+ BOT transfer is composed of three phases: Command, Data, and Status.
+ This is the Status phase.
- @param UsbBot The USB BOT device.
- @param TransLen The expected length of the data.
- @param CmdStatus The result of the command execution.
+ This function returns the transfer status of the BOT's CSW status,
+ and returns the high level command execution result in Result. So
+ even if EFI_SUCCESS is returned, the command may still have failed.
- @retval EFI_SUCCESS Command execute result is retrieved and in the
- Result.
- @retval Other Failed to get status.
+ @param UsbBot The USB BOT device.
+ @param TransLen The expected length of the data.
+ @param CmdStatus The result of the command execution.
+
+ @retval EFI_SUCCESS Command execute result is retrieved and in the Result.
+ @retval Other Error occurred when trying to get status.
**/
EFI_STATUS
@@ -326,7 +328,7 @@ UsbBotGetStatus (
for (Index = 0; Index < USB_BOT_RECV_CSW_RETRY; Index++) {
//
- // Attemp to the read CSW from bulk in endpoint
+ // Attemp to the read Command Status Wrapper from bulk in endpoint
//
ZeroMem (&Csw, sizeof (USB_BOT_CSW));
Result = 0;
@@ -340,9 +342,7 @@ UsbBotGetStatus (
&Result
);
if (EFI_ERROR(Status)) {
- DEBUG ((EFI_D_ERROR, "UsbBotGetStatus (%r)\n", Status));
if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
- DEBUG ((EFI_D_ERROR, "UsbBotGetStatus: DataIn Stall\n"));
UsbClearEndpointStall (UsbIo, Endpoint);
}
continue;
@@ -350,24 +350,21 @@ UsbBotGetStatus (
if (Csw.Signature != USB_BOT_CSW_SIGNATURE) {
//
- // Invalid Csw need perform reset recovery
+ // CSW is invalid, so perform reset recovery
//
- DEBUG ((EFI_D_ERROR, "UsbBotGetStatus: Device return a invalid signature\n"));
Status = UsbBotResetDevice (UsbBot, FALSE);
} else if (Csw.CmdStatus == USB_BOT_COMMAND_ERROR) {
//
- // Respond phase error need perform reset recovery
+ // Respond phase error also needs reset recovery
//
- DEBUG ((EFI_D_ERROR, "UsbBotGetStatus: Device return a phase error\n"));
Status = UsbBotResetDevice (UsbBot, FALSE);
} else {
-
*CmdStatus = Csw.CmdStatus;
break;
}
}
//
- //The tag is increased even there is an error.
+ //The tag is increased even if there is an error.
//
UsbBot->CbwTag++;
@@ -376,7 +373,7 @@ UsbBotGetStatus (
/**
- Call the Usb mass storage class transport protocol to issue
+ Call the USB Mass Storage Class BOT protocol to issue
the command/data/status circle to execute the commands.
@param Context The context of the BOT protocol, that is,
@@ -390,7 +387,7 @@ UsbBotGetStatus (
@param Timeout The time to wait command
@param CmdStatus The result of high level command execution
- @retval EFI_SUCCESS The command is executed OK, and result in CmdStatus
+ @retval EFI_SUCCESS The command is executed successfully.
@retval Other Failed to excute command
**/
@@ -428,7 +425,7 @@ UsbBotExecCommand (
//
// Transfer the data. Don't return immediately even data transfer
// failed. The host should attempt to receive the CSW no matter
- // whether it succeeds or failed.
+ // whether it succeeds or fails.
//
TransLen = (UINTN) DataLen;
UsbBotDataTransfer (UsbBot, DataDir, Data, &TransLen, Timeout);
@@ -451,11 +448,12 @@ UsbBotExecCommand (
/**
- Reset the mass storage device by BOT protocol.
+ Reset the USB mass storage device by BOT protocol.
@param Context The context of the BOT protocol, that is,
USB_BOT_PROTOCOL.
- @param ExtendedVerification The flag controlling the rule of reset dev.
+ @param ExtendedVerification If FALSE, just issue Bulk-Only Mass Storage Reset request.
+ If TRUE, additionally reset parent hub port.
@retval EFI_SUCCESS The device is reset.
@retval Others Failed to reset the device..
@@ -464,7 +462,7 @@ UsbBotExecCommand (
EFI_STATUS
UsbBotResetDevice (
IN VOID *Context,
- IN BOOLEAN ExtendedVerification
+ IN BOOLEAN ExtendedVerification
)
{
USB_BOT_PROTOCOL *UsbBot;
@@ -486,10 +484,10 @@ UsbBotResetDevice (
}
//
- // Issue a class specific Bulk-Only Mass Storage Reset reqest.
- // See the spec section 3.1
+ // Issue a class specific Bulk-Only Mass Storage Reset request,
+ // according to section 3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
//
- Request.RequestType = 0x21; // Class, Interface, Host to Device
+ Request.RequestType = 0x21;
Request.Request = USB_BOT_RESET_REQUEST;
Request.Value = 0;
Request.Index = UsbBot->Interface.InterfaceNumber;
@@ -507,14 +505,13 @@ UsbBotResetDevice (
);
if (EFI_ERROR (Status)) {
- DEBUG ((EFI_D_ERROR, "UsbBotResetDevice: (%r)\n", Status));
return Status;
}
//
// The device shall NAK the host's request until the reset is
// complete. We can use this to sync the device and host. For
- // now just stall 100ms to wait the device.
+ // now just stall 100ms to wait for the device.
//
gBS->Stall (USB_BOT_RESET_DEVICE_STALL);
@@ -523,25 +520,26 @@ UsbBotResetDevice (
//
UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkInEndpoint->EndpointAddress);
UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkOutEndpoint->EndpointAddress);
+
return Status;
}
/**
- Get the max lun of mass storage device.
+ Get the max LUN (Logical Unit Number) of USB mass storage device.
@param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL
- @param MaxLun Return pointer to the max number of lun. Maxlun=1 means lun0 and
- lun1 in all.
+ @param MaxLun Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and
+ LUN1 in all.)
- @retval EFI_SUCCESS Get max lun success.
- @retval Others Failed to execute this request.
+ @retval EFI_SUCCESS Max LUN is got successfully.
+ @retval Others Fail to execute this request.
**/
EFI_STATUS
UsbBotGetMaxLun (
IN VOID *Context,
- IN UINT8 *MaxLun
+ OUT UINT8 *MaxLun
)
{
USB_BOT_PROTOCOL *UsbBot;
@@ -556,9 +554,9 @@ UsbBotGetMaxLun (
//
// Issue a class specific Bulk-Only Mass Storage get max lun reqest.
- // See the spec section 3.2
+ // according to section 3.2 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
//
- Request.RequestType = 0xA1; // Class, Interface, Device to Host
+ Request.RequestType = 0xA1;
Request.Request = USB_BOT_GETLUN_REQUEST;
Request.Value = 0;
Request.Index = UsbBot->Interface.InterfaceNumber;
@@ -570,29 +568,24 @@ UsbBotGetMaxLun (
&Request,
EfiUsbDataIn,
Timeout,
- (VOID *)MaxLun,
+ (VOID *) MaxLun,
1,
&Result
);
- if (EFI_ERROR (Status)) {
- DEBUG ((EFI_D_ERROR, "UsbBotGetMaxLun: (%r)\n", Status));
- }
-
return Status;
}
/**
Clean up the resource used by this BOT protocol.
- @param Context The context of the BOT protocol, that is,
- USB_BOT_PROTOCOL.
+ @param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL.
- @retval EFI_SUCCESS The resource is cleaned up.
+ @retval EFI_SUCCESS The resource is cleaned up.
**/
EFI_STATUS
-UsbBotFini (
+UsbBotCleanUp (
IN VOID *Context
)
{
@@ -600,13 +593,3 @@ UsbBotFini (
return EFI_SUCCESS;
}
-USB_MASS_TRANSPORT
-mUsbBotTransport = {
- USB_MASS_STORE_BOT,
- UsbBotInit,
- UsbBotExecCommand,
- UsbBotResetDevice,
- UsbBotGetMaxLun,
- UsbBotFini
-};
-