From 3e03cb4d84348029236764e179c9d3c788709664 Mon Sep 17 00:00:00 2001 From: xli24 Date: Mon, 12 Jan 2009 07:30:42 +0000 Subject: [PATCH] Refine USB Mass Storage Driver. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7247 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Bus/Usb/UsbMassStorageDxe/ComponentName.c | 170 ++---------------- .../Bus/Usb/UsbMassStorageDxe/UsbMass.h | 103 ++++++++--- .../Bus/Usb/UsbMassStorageDxe/UsbMassBoot.c | 1 - .../Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h | 54 +++--- .../Bus/Usb/UsbMassStorageDxe/UsbMassBot.c | 8 +- .../Bus/Usb/UsbMassStorageDxe/UsbMassBot.h | 2 + .../Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c | 2 +- .../Bus/Usb/UsbMassStorageDxe/UsbMassCbi.h | 2 + .../Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c | 155 ++++++++-------- .../Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h | 142 ++++++++++++--- .../UsbMassStorageDxe/UsbMassStorageDxe.inf | 16 +- 11 files changed, 341 insertions(+), 314 deletions(-) diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/ComponentName.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/ComponentName.c index a48f0bee7c..f159b3ed76 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/ComponentName.c +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/ComponentName.c @@ -1,6 +1,5 @@ /** @file - - UEFI Component Name(2) protocol implementation. + UEFI Component Name(2) protocol implementation for USB Mass Storage Driver. Copyright (c) 2004 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials @@ -13,141 +12,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ - -#include - - -#include - -// -// EFI Component Name Functions -// -/** - Retrieves a Unicode string that is the user readable name of the driver. - - This function retrieves the user readable name of a driver in the form of a - Unicode string. If the driver specified by This has a user readable name in - the language specified by Language, then a pointer to the driver name is - returned in DriverName, and EFI_SUCCESS is returned. If the driver specified - by This does not support the language specified by Language, - then EFI_UNSUPPORTED is returned. - - @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or - EFI_COMPONENT_NAME_PROTOCOL instance. - - @param Language[in] A pointer to a Null-terminated ASCII string - array indicating the language. This is the - language of the driver name that the caller is - requesting, and it must match one of the - languages specified in SupportedLanguages. The - number of languages supported by a driver is up - to the driver writer. Language is specified - in RFC 3066 or ISO 639-2 language code format. - - @param DriverName[out] A pointer to the Unicode string to return. - This Unicode string is the name of the - driver specified by This in the language - specified by Language. - - @retval EFI_SUCCESS The Unicode string for the Driver specified by - This and the language specified by Language was - returned in DriverName. - - @retval EFI_INVALID_PARAMETER Language is NULL. - - @retval EFI_INVALID_PARAMETER DriverName is NULL. - - @retval EFI_UNSUPPORTED The driver specified by This does not support - the language specified by Language. - -**/ -EFI_STATUS -EFIAPI -UsbMassStorageGetDriverName ( - IN EFI_COMPONENT_NAME_PROTOCOL *This, - IN CHAR8 *Language, - OUT CHAR16 **DriverName - ); - - -/** - Retrieves a Unicode string that is the user readable name of the controller - that is being managed by a driver. - - This function retrieves the user readable name of the controller specified by - ControllerHandle and ChildHandle in the form of a Unicode string. If the - driver specified by This has a user readable name in the language specified by - Language, then a pointer to the controller name is returned in ControllerName, - and EFI_SUCCESS is returned. If the driver specified by This is not currently - managing the controller specified by ControllerHandle and ChildHandle, - then EFI_UNSUPPORTED is returned. If the driver specified by This does not - support the language specified by Language, then EFI_UNSUPPORTED is returned. - - @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or - EFI_COMPONENT_NAME_PROTOCOL instance. - - @param ControllerHandle[in] The handle of a controller that the driver - specified by This is managing. This handle - specifies the controller whose name is to be - returned. - - @param ChildHandle[in] The handle of the child controller to retrieve - the name of. This is an optional parameter that - may be NULL. It will be NULL for device - drivers. It will also be NULL for a bus drivers - that wish to retrieve the name of the bus - controller. It will not be NULL for a bus - driver that wishes to retrieve the name of a - child controller. - - @param Language[in] A pointer to a Null-terminated ASCII string - array indicating the language. This is the - language of the driver name that the caller is - requesting, and it must match one of the - languages specified in SupportedLanguages. The - number of languages supported by a driver is up - to the driver writer. Language is specified in - RFC 3066 or ISO 639-2 language code format. - - @param ControllerName[out] A pointer to the Unicode string to return. - This Unicode string is the name of the - controller specified by ControllerHandle and - ChildHandle in the language specified by - Language from the point of view of the driver - specified by This. - - @retval EFI_SUCCESS The Unicode string for the user readable name in - the language specified by Language for the - driver specified by This was returned in - DriverName. - - @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. - - @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid - EFI_HANDLE. - - @retval EFI_INVALID_PARAMETER Language is NULL. - - @retval EFI_INVALID_PARAMETER ControllerName is NULL. - - @retval EFI_UNSUPPORTED The driver specified by This is not currently - managing the controller specified by - ControllerHandle and ChildHandle. - - @retval EFI_UNSUPPORTED The driver specified by This does not support - the language specified by Language. - -**/ -EFI_STATUS -EFIAPI -UsbMassStorageGetControllerName ( - IN EFI_COMPONENT_NAME_PROTOCOL *This, - IN EFI_HANDLE ControllerHandle, - IN EFI_HANDLE ChildHandle OPTIONAL, - IN CHAR8 *Language, - OUT CHAR16 **ControllerName - ); - +#include "UsbMassImpl.h" // // EFI Component Name Protocol @@ -184,10 +49,9 @@ mUsbMassStorageDriverNameTable[] = { by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned. - @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or + @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or EFI_COMPONENT_NAME_PROTOCOL instance. - - @param Language[in] A pointer to a Null-terminated ASCII string + @param Language A pointer to a Null-terminated ASCII string array indicating the language. This is the language of the driver name that the caller is requesting, and it must match one of the @@ -195,8 +59,7 @@ mUsbMassStorageDriverNameTable[] = { number of languages supported by a driver is up to the driver writer. Language is specified in RFC 3066 or ISO 639-2 language code format. - - @param DriverName[out] A pointer to the Unicode string to return. + @param DriverName A pointer to the Unicode string to return. This Unicode string is the name of the driver specified by This in the language specified by Language. @@ -204,11 +67,8 @@ mUsbMassStorageDriverNameTable[] = { @retval EFI_SUCCESS The Unicode string for the Driver specified by This and the language specified by Language was returned in DriverName. - @retval EFI_INVALID_PARAMETER Language is NULL. - @retval EFI_INVALID_PARAMETER DriverName is NULL. - @retval EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language. @@ -243,15 +103,13 @@ UsbMassStorageGetDriverName ( then EFI_UNSUPPORTED is returned. If the driver specified by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned. - @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or + @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or EFI_COMPONENT_NAME_PROTOCOL instance. - - @param ControllerHandle[in] The handle of a controller that the driver + @param ControllerHandle The handle of a controller that the driver specified by This is managing. This handle specifies the controller whose name is to be returned. - - @param ChildHandle[in] The handle of the child controller to retrieve + @param ChildHandle The handle of the child controller to retrieve the name of. This is an optional parameter that may be NULL. It will be NULL for device drivers. It will also be NULL for a bus drivers @@ -259,8 +117,7 @@ UsbMassStorageGetDriverName ( controller. It will not be NULL for a bus driver that wishes to retrieve the name of a child controller. - - @param Language[in] A pointer to a Null-terminated ASCII string + @param Language A pointer to a Null-terminated ASCII string array indicating the language. This is the language of the driver name that the caller is requesting, and it must match one of the @@ -268,8 +125,7 @@ UsbMassStorageGetDriverName ( number of languages supported by a driver is up to the driver writer. Language is specified in RFC 3066 or ISO 639-2 language code format. - - @param ControllerName[out] A pointer to the Unicode string to return. + @param ControllerName A pointer to the Unicode string to return. This Unicode string is the name of the controller specified by ControllerHandle and ChildHandle in the language specified by @@ -280,20 +136,14 @@ UsbMassStorageGetDriverName ( the language specified by Language for the driver specified by This was returned in DriverName. - @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. - @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE. - @retval EFI_INVALID_PARAMETER Language is NULL. - @retval EFI_INVALID_PARAMETER ControllerName is NULL. - @retval EFI_UNSUPPORTED The driver specified by This is not currently managing the controller specified by ControllerHandle and ChildHandle. - @retval EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language. diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMass.h b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMass.h index 546dbed882..d7708cb2d3 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMass.h +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMass.h @@ -1,12 +1,6 @@ /** @file - - Defination for the USB mass storage class driver. The USB mass storage - class is specified in two layers: the bottom layer is the transportation - protocol. The top layer is the command set. The transportation layer - provides the transportation of the command, data and result. The command - set defines what the command, data and result. The Bulk-Only-Transport and - Control/Bulk/Interrupt transport are two transportation protocol. USB mass - storage class adopts various industrial standard as its command set. + Definition of USB Mass Storage Class and its value, USB Mass Transport Protocol, + and other common definitions. Copyright (c) 2007 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials @@ -72,8 +66,22 @@ typedef enum { USB_MASS_CMD_SUCCESS = 0, USB_MASS_CMD_FAIL, USB_MASS_CMD_PERSISTENT -}USB_MASS_DEV_CLASS_AND_VALUE; +} USB_MASS_DEV_CLASS_AND_VALUE; + +/** + Initializes USB transport protocol. + + This function initializes the USB mass storage class transport protocol. + It will save its context in the Context if Context isn't NULL. + + @param UsbIo The USB I/O Protocol instance + @param Context The buffer to save the context to + @retval EFI_SUCCESS The device is successfully initialized. + @retval EFI_UNSUPPORTED The transport protocol doesn't support the device. + @retval Other The USB transport initialization fails. + +**/ typedef EFI_STATUS (*USB_MASS_INIT_TRANSPORT) ( @@ -81,6 +89,23 @@ EFI_STATUS OUT VOID **Context OPTIONAL ); +/** + Execute USB mass storage command through the transport protocol. + + @param Context The USB Transport Protocol. + @param Cmd The command to transfer to device + @param CmdLen The length of the command + @param DataDir The direction of data transfer + @param Data The buffer to hold the data + @param DataLen The length of the buffer + @param Lun Should be 0, this field for bot only + @param Timeout The time to wait + @param CmdStatus The result of the command execution + + @retval EFI_SUCCESS The command is executed successfully. + @retval Other Failed to execute the command + +**/ typedef EFI_STATUS (*USB_MASS_EXEC_COMMAND) ( @@ -95,6 +120,17 @@ EFI_STATUS OUT UINT32 *CmdStatus ); +/** + Reset the USB mass storage device by Transport protocol. + + @param Context The USB Transport Protocol + @param ExtendedVerification The flag controlling the rule of reset. + Not used here. + + @retval EFI_SUCCESS The device is reset. + @retval Others Failed to reset the device. + +**/ typedef EFI_STATUS (*USB_MASS_RESET) ( @@ -102,6 +138,17 @@ EFI_STATUS IN BOOLEAN ExtendedVerification ); +/** + Get the max LUN (Logical Unit Number) of USB mass storage device. + + @param Context The context of the transport protocol. + @param MaxLun Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and + LUN1 in all.) + + @retval EFI_SUCCESS Max LUN is got successfully. + @retval Others Fail to execute this request. + +**/ typedef EFI_STATUS (*USB_MASS_GET_MAX_LUN) ( @@ -109,6 +156,14 @@ EFI_STATUS IN UINT8 *MaxLun ); +/** + Clean up the transport protocol's resource. + + @param Context The instance of transport protocol. + + @retval EFI_SUCCESS The resource is cleaned up. + +**/ typedef EFI_STATUS (*USB_MASS_CLEAN_UP) ( @@ -132,22 +187,18 @@ typedef struct { USB_MASS_CLEAN_UP CleanUp; ///< Clean up the resources. } USB_MASS_TRANSPORT; - -/** - Use the USB clear feature control transfer to clear the endpoint - stall condition. - - @param UsbIo The USB IO protocol to use - @param EndpointAddr The endpoint to clear stall for - - @retval EFI_SUCCESS The endpoint stall condtion is clear - @retval Others Failed to clear the endpoint stall condtion - -**/ -EFI_STATUS -UsbClearEndpointStall ( - IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 EndpointAddr - ); +typedef struct { + UINT32 Signature; + EFI_HANDLE Controller; + EFI_USB_IO_PROTOCOL *UsbIo; + EFI_DEVICE_PATH_PROTOCOL *DevicePath; + EFI_BLOCK_IO_PROTOCOL BlockIo; + EFI_BLOCK_IO_MEDIA BlockIoMedia; + BOOLEAN OpticalStorage; + UINT8 Lun; ///< Logical Unit Number + UINT8 Pdt; ///< Peripheral Device Type + USB_MASS_TRANSPORT *Transport; ///< USB mass storage transport protocol + VOID *Context; +} USB_MASS_DEVICE; #endif diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.c index 44f0b03833..71deef051e 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.c +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.c @@ -788,7 +788,6 @@ UsbBootWriteBlocks ( return Status; } - /** Use the USB clear feature control transfer to clear the endpoint stall condition. diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h index ab3fb68e4a..cd66d825ef 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h @@ -16,6 +16,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_USB_MASS_BOOT_H_ #define _EFI_USB_MASS_BOOT_H_ +#include "UsbMass.h" + typedef enum { // // The opcodes of various USB boot commands: @@ -226,17 +228,18 @@ typedef struct { #define USB_BOOT_SENSE_KEY(Key) ((Key) & 0x0f) /** - Get the parameters for the USB mass storage media, including - the RemovableMedia, block size, and last block number. This - function is used both to initialize the media during the - DriverBindingStart and to re-initialize it when the media is + Get the parameters for the USB mass storage media. + + This function get the parameters for the USB mass storage media, + It is used both to initialize the media during the Start() phase + of Driver Binding Protocol and to re-initialize it when the media is changed. Althought the RemoveableMedia is unlikely to change, - I include it here. + it is also included here. - @param UsbMass The device to retireve disk gemotric. + @param UsbMass The device to retrieve disk gemotric. @retval EFI_SUCCESS The disk gemotric is successfully retrieved. - @retval Other Get the parameters failed. + @retval Other Failed to get the parameters. **/ EFI_STATUS @@ -244,14 +247,12 @@ UsbBootGetParams ( IN USB_MASS_DEVICE *UsbMass ); - /** - Use the TEST UNIT READY command to check whether it is ready. - If it is ready, update the parameters. + Execute TEST UNIT READY command to check if the device is ready. @param UsbMass The device to test - @retval EFI_SUCCESS The device is ready and parameters are updated. + @retval EFI_SUCCESS The device is ready. @retval Others Device not ready. **/ @@ -260,15 +261,13 @@ UsbBootIsUnitReady ( IN USB_MASS_DEVICE *UsbMass ); - /** Detect whether the removable media is present and whether it has changed. - The Non-removable media doesn't need it. - @param UsbMass The device to retireve disk gemotric. + @param UsbMass The device to check. - @retval EFI_SUCCESS The disk gemotric is successfully retrieved. - @retval Other Decect media fails. + @retval EFI_SUCCESS The media status is successfully checked. + @retval Other Failed to detect media. **/ EFI_STATUS @@ -276,7 +275,6 @@ UsbBootDetectMedia ( IN USB_MASS_DEVICE *UsbMass ); - /** Read some blocks from the device. @@ -297,14 +295,13 @@ UsbBootReadBlocks ( OUT UINT8 *Buffer ); - /** Write some blocks to the device. @param UsbMass The USB mass storage device to write to @param Lba The start block number @param TotalBlock Total block number to write - @param Buffer The buffer to write to + @param Buffer Pointer to the source buffer for the data. @retval EFI_SUCCESS Data are written into the buffer @retval Others Failed to write all the data @@ -315,7 +312,24 @@ UsbBootWriteBlocks ( IN USB_MASS_DEVICE *UsbMass, IN UINT32 Lba, IN UINTN TotalBlock, - OUT UINT8 *Buffer + IN UINT8 *Buffer ); + +/** + Use the USB clear feature control transfer to clear the endpoint stall condition. + + @param UsbIo The USB I/O Protocol instance + @param EndpointAddr The endpoint to clear stall for + + @retval EFI_SUCCESS The endpoint stall condition is cleared. + @retval Others Failed to clear the endpoint stall condition. + +**/ +EFI_STATUS +UsbClearEndpointStall ( + IN EFI_USB_IO_PROTOCOL *UsbIo, + IN UINT8 EndpointAddr + ); + #endif diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c index 178aa80d3e..c6c8f8d11b 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c @@ -13,7 +13,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ -#include "UsbMass.h" +#include "UsbMassBoot.h" #include "UsbMassBot.h" // @@ -58,9 +58,7 @@ UsbBotInit ( // // Allocate the BOT context for USB_BOT_PROTOCOL and two endpoint descriptors. // - UsbBot = AllocateZeroPool ( - sizeof (USB_BOT_PROTOCOL) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR) - ); + UsbBot = AllocateZeroPool (sizeof (USB_BOT_PROTOCOL) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)); ASSERT (UsbBot != NULL); UsbBot->UsbIo = UsbIo; @@ -103,7 +101,7 @@ UsbBotInit ( (UsbBot->BulkOutEndpoint == NULL)) { UsbBot->BulkOutEndpoint = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbBot + 1) + 1; - CopyMem(UsbBot->BulkOutEndpoint, &EndPoint, sizeof(EndPoint)); + CopyMem (UsbBot->BulkOutEndpoint, &EndPoint, sizeof(EndPoint)); } } diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.h b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.h index 7f6f5fff8e..63d9fecd81 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.h +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.h @@ -17,6 +17,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_USBMASS_BOT_H_ #define _EFI_USBMASS_BOT_H_ +#include "UsbMass.h" + extern USB_MASS_TRANSPORT mUsbBotTransport; typedef enum { diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c index d56254b77c..d1424e2f75 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c @@ -15,7 +15,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ -#include "UsbMass.h" +#include "UsbMassBoot.h" #include "UsbMassCbi.h" // diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.h b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.h index ec4c3e14da..05f3795d17 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.h +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.h @@ -16,6 +16,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_USBMASS_CBI_H_ #define _EFI_USBMASS_CBI_H_ +#include "UsbMass.h" + extern USB_MASS_TRANSPORT mUsbCbi0Transport; extern USB_MASS_TRANSPORT mUsbCbi1Transport; diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c index 6efdf10af1..0db4c14356 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c @@ -376,7 +376,7 @@ UsbMassInitMedia ( @param This The USB mass driver's driver binding. @param Controller The device to test. @param Transport The pointer to pointer to USB_MASS_TRANSPORT. - @param Context The passing parameter. + @param Context The parameter for USB_MASS_DEVICE.Context. @param MaxLun Get the MaxLun if is BOT dev. @retval EFI_SUCCESS The initialization is successful. @@ -457,22 +457,23 @@ ON_EXIT: } /** - Usb mass storage driver initializes multi lun. + Initialize data for device that supports multiple LUNSs. - @param This The USB mass driver's driver binding. - @param Controller The device to test. - @param Transport The pointer to USB_MASS_TRANSPORT. - @param Context The passing parameter. - @param DevicePath The remaining device path - @param MaxLun The MaxLun number passed. + @param This The Driver Binding Protocol instance. + @param Controller The device to initialize. + @param Transport Pointer to USB_MASS_TRANSPORT. + @param Context Parameter for USB_MASS_DEVICE.Context. + @param DevicePath The remaining device path. + @param MaxLun The max LUN number. - @retval EFI_SUCCESS Initialization is success. - @retval Other Initialization fails. + @retval EFI_SUCCESS At least one LUN is initialized successfully. + @retval EFI_OUT_OF_RESOURCES Out of resource while creating device path node. + @retval Other Initialization fails. **/ EFI_STATUS UsbMassInitMultiLun ( - IN EFI_DRIVER_BINDING_PROTOCOL *This, + IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN USB_MASS_TRANSPORT *Transport, IN VOID *Context, @@ -494,10 +495,7 @@ UsbMassInitMultiLun ( UsbIo = NULL; UsbMass = AllocateZeroPool (sizeof (USB_MASS_DEVICE)); - if (UsbMass == NULL) { - Status = EFI_OUT_OF_RESOURCES; - goto ON_ERROR; - } + ASSERT (UsbMass != NULL); UsbMass->Signature = USB_MASS_SIGNATURE; UsbMass->UsbIo = UsbIo; @@ -512,11 +510,14 @@ UsbMassInitMultiLun ( UsbMass->Lun = Index; // - // Get the storage's parameters, such as last block number. - // then install the BLOCK_IO + // Initialize the media parameter data for EFI_BLOCK_IO_MEDIA of Block I/O Protocol. // Status = UsbMassInitMedia (UsbMass); if (!EFI_ERROR (Status)) { + // + // According to USB Mass Storage Specification for Bootability, only following + // 4 Peripheral Device Types are in spec. + // if ((UsbMass->Pdt != USB_PDT_DIRECT_ACCESS) && (UsbMass->Pdt != USB_PDT_CDROM) && (UsbMass->Pdt != USB_PDT_OPTICAL) && @@ -530,7 +531,7 @@ UsbMassInitMultiLun ( } // - // Create a device path node of device logic unit, and append it + // Create a device path node for device logic unit, and append it. // LunNode.Header.Type = MESSAGING_DEVICE_PATH; LunNode.Header.SubType = MSG_DEVICE_LOGICAL_UNIT_DP; @@ -548,7 +549,7 @@ UsbMassInitMultiLun ( } // - // Create a UsbMass handle for each lun, and install blockio and devicepath protocols. + // Create a new handle for each LUN, and install Block I/O Protocol and Device Path Protocol. // Status = gBS->InstallMultipleProtocolInterfaces ( &UsbMass->Controller, @@ -565,7 +566,7 @@ UsbMassInitMultiLun ( } // - // Open UsbIo protocol by child to setup a parent-child relationship. + // Open USB I/O Protocol by child to setup a parent-child relationship. // Status = gBS->OpenProtocol ( Controller, @@ -596,10 +597,10 @@ UsbMassInitMultiLun ( ON_ERROR: if (UsbMass->DevicePath != NULL) { - gBS->FreePool (UsbMass->DevicePath); + FreePool (UsbMass->DevicePath); } if (UsbMass != NULL) { - gBS->FreePool (UsbMass); + FreePool (UsbMass); } if (UsbIo != NULL) { gBS->CloseProtocol ( @@ -611,7 +612,7 @@ ON_ERROR: } // - // If only success to initialize one lun, return success, or else return error + // Return EFI_SUCCESS if at least one LUN is initialized successfully. // if (Index > 0) { return EFI_SUCCESS; @@ -621,14 +622,14 @@ ON_ERROR: } /** - Initialize No/Unsupported LUN device. + Initialize data for device that does not support multiple LUNSs. - @param This The USB mass driver's driver binding. - @param Controller The device to test. - @param Transport The pointer to USB_MASS_TRANSPORT. - @param Context The passing parameter. + @param This The Driver Binding Protocol instance. + @param Controller The device to initialize. + @param Transport Pointer to USB_MASS_TRANSPORT. + @param Context Parameter for USB_MASS_DEVICE.Context. - @retval EFI_SUCCESS Initialization is success. + @retval EFI_SUCCESS Initialization succeeds. @retval Other Initialization fails. **/ @@ -646,9 +647,8 @@ UsbMassInitNonLun ( UsbIo = NULL; UsbMass = AllocateZeroPool (sizeof (USB_MASS_DEVICE)); - if (UsbMass == NULL) { - return EFI_OUT_OF_RESOURCES; - } + ASSERT (UsbMass != NULL); + Status = gBS->OpenProtocol ( Controller, &gEfiUsbIoProtocolGuid, @@ -676,11 +676,14 @@ UsbMassInitNonLun ( UsbMass->Context = Context; // - // Get the storage's parameters, such as last block number. - // then install the BLOCK_IO + // Initialize the media parameter data for EFI_BLOCK_IO_MEDIA of Block I/O Protocol. // Status = UsbMassInitMedia (UsbMass); if (!EFI_ERROR (Status)) { + // + // According to USB Mass Storage Specification for Bootability, only following + // 4 Peripheral Device Types are in spec. + // if ((UsbMass->Pdt != USB_PDT_DIRECT_ACCESS) && (UsbMass->Pdt != USB_PDT_CDROM) && (UsbMass->Pdt != USB_PDT_OPTICAL) && @@ -707,7 +710,7 @@ UsbMassInitNonLun ( ON_ERROR: if (UsbMass != NULL) { - gBS->FreePool (UsbMass); + FreePool (UsbMass); } gBS->CloseProtocol ( Controller, @@ -796,7 +799,6 @@ ON_EXIT: return Status; } - /** Starts the USB mass storage device with this driver. @@ -804,9 +806,9 @@ ON_EXIT: installs Block I/O Protocol, and submits Asynchronous Interrupt Transfer to manage the USB mass storage device. - @param This The USB mass storage driver binding protocol. - @param Controller The USB mass storage device to start on - @param RemainingDevicePath The remaining device path. + @param This The USB mass storage driver binding protocol. + @param Controller The USB mass storage device to start on + @param RemainingDevicePath The remaining device path. @retval EFI_SUCCESS This driver supports this device. @retval EFI_UNSUPPORTED This driver does not support this device. @@ -833,9 +835,6 @@ USBMassDriverBindingStart ( Context = NULL; MaxLun = 0; - // - // Get interface and protocols, initialize transport - // Status = UsbMassInitTransport (This, Controller, &Transport, &Context, &MaxLun); if (EFI_ERROR (Status)) { @@ -844,15 +843,15 @@ USBMassDriverBindingStart ( } if (MaxLun == 0) { // - // Initialize No/Unsupported LUN device + // Initialize data for device that does not support multiple LUNSs. // - Status = UsbMassInitNonLun(This, Controller, Transport, Context); + Status = UsbMassInitNonLun (This, Controller, Transport, Context); if (EFI_ERROR (Status)) { DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: UsbMassInitNonLun (%r)\n", Status)); } } else { // - // Open device path to prepare append Device Logic Unit node. + // Open device path to prepare for appending Device Logic Unit node. // Status = gBS->OpenProtocol ( Controller, @@ -869,7 +868,8 @@ USBMassDriverBindingStart ( } // - // Try best to initialize all LUNs, and return success only if one of LUNs successed to initialized. + // Initialize data for device that supports multiple LUNSs. + // EFI_SUCCESS is returned if at least 1 LUN is initialized successfully. // Status = UsbMassInitMultiLun (This, Controller, Transport, Context, DevicePath, MaxLun); if (EFI_ERROR (Status)) { @@ -895,6 +895,8 @@ USBMassDriverBindingStart ( @param ChildHandleBuffer The buffer of children handle. @retval EFI_SUCCESS The driver stopped from controlling the device. + @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. + @retval EFI_UNSUPPORTED Block I/O Protocol is not installed on Controller. @retval Others Failed to stop the driver **/ @@ -909,17 +911,17 @@ USBMassDriverBindingStop ( { EFI_STATUS Status; USB_MASS_DEVICE *UsbMass; - EFI_USB_IO_PROTOCOL *UsbIo; + EFI_USB_IO_PROTOCOL *UsbIo; EFI_BLOCK_IO_PROTOCOL *BlockIo; - UINTN Index; - BOOLEAN AllChildrenStopped; + UINTN Index; + BOOLEAN AllChildrenStopped; // - // This a bus driver stop function since multi-lun supported. There are three - // kinds of device handle might be passed, 1st is a handle with devicepath/ - // usbio/blockio installed(non-multi-lun), 2nd is a handle with devicepath/ - // usbio installed(multi-lun root), 3rd is a handle with devicepath/blockio - // installed(multi-lun). + // This is a bus driver stop function since multi-lun is supported. + // There are three kinds of device handles that might be passed: + // 1st is a handle with Device Path & USB I/O & Block I/O installed (non-multi-lun) + // 2nd is a handle with Device Path & USB I/O installed (multi-lun root) + // 3rd is a handle with Device Path & Block I/O installed (multi-lun). // if (NumberOfChildren == 0) { // @@ -936,8 +938,8 @@ USBMassDriverBindingStop ( if (EFI_ERROR(Status)) { // - // This is a 2nd type handle(multi-lun root), which only needs close - // devicepath protocol. + // This is a 2nd type handle(multi-lun root), which only needs to close + // Device Path Protocol. // gBS->CloseProtocol ( Controller, @@ -950,8 +952,8 @@ USBMassDriverBindingStop ( } // - // This is a 1st type handle(non-multi-lun), which only needs uninstall - // blockio protocol, close usbio protocol and free mass device. + // This is a 1st type handle(non-multi-lun), which only needs to uninstall + // Block I/O Protocol, close USB I/O Protocol and free mass device. // UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (BlockIo); @@ -976,7 +978,7 @@ USBMassDriverBindingStop ( ); UsbMass->Transport->CleanUp (UsbMass->Context); - gBS->FreePool (UsbMass); + FreePool (UsbMass); DEBUG ((EFI_D_INFO, "Success to stop non-multi-lun root handle\n")); return EFI_SUCCESS; @@ -984,8 +986,8 @@ USBMassDriverBindingStop ( // // This is a 3rd type handle(multi-lun), which needs uninstall - // blockio and devicepath protocol, close usbio protocol and - // free mass device. + // Block I/O Protocol and Device Path Protocol, close USB I/O Protocol and + // free mass device for all children. // AllChildrenStopped = TRUE; @@ -1008,11 +1010,11 @@ USBMassDriverBindingStop ( UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (BlockIo); gBS->CloseProtocol ( - Controller, - &gEfiUsbIoProtocolGuid, - This->DriverBindingHandle, - ChildHandleBuffer[Index] - ); + Controller, + &gEfiUsbIoProtocolGuid, + This->DriverBindingHandle, + ChildHandleBuffer[Index] + ); Status = gBS->UninstallMultipleProtocolInterfaces ( ChildHandleBuffer[Index], @@ -1025,7 +1027,7 @@ USBMassDriverBindingStop ( if (EFI_ERROR (Status)) { // - // Fail to uninstall blockio and devicepath protocol, so re-open usbio by child. + // Fail to uninstall Block I/O Protocol and Device Path Protocol, so re-open USB I/O Protocol by child. // AllChildrenStopped = FALSE; DEBUG ((EFI_D_ERROR, "Fail to stop No.%d multi-lun child handle when uninstalling blockio and devicepath\n", (UINT32)Index)); @@ -1040,12 +1042,12 @@ USBMassDriverBindingStop ( ); } else { // - // Success to stop this multi-lun handle, so go on next child. + // Succeed to stop this multi-lun handle, so go on with next child. // if (((Index + 1) == NumberOfChildren) && AllChildrenStopped) { UsbMass->Transport->CleanUp (UsbMass->Context); } - gBS->FreePool (UsbMass); + FreePool (UsbMass); } } @@ -1053,19 +1055,20 @@ USBMassDriverBindingStop ( return EFI_DEVICE_ERROR; } - DEBUG ((EFI_D_INFO, "Success to stop all %d multi-lun children handles\n", (UINT32)NumberOfChildren)); + DEBUG ((EFI_D_INFO, "Success to stop all %d multi-lun children handles\n", (UINT32) NumberOfChildren)); return EFI_SUCCESS; } /** - The entry point for the driver, which will install the driver binding and - component name protocol. + Entrypoint of USB Mass Storage Driver. + + This function is the entrypoint of USB Mass Storage Driver. It installs Driver Binding + Protocol together with Component Name Protocols. - @param ImageHandle The image handle of this driver. - @param SystemTable The system table. + @param ImageHandle The firmware allocated handle for the EFI image. + @param SystemTable A pointer to the EFI System Table. - @retval EFI_SUCCESS The protocols are installed OK. - @retval Others Failed to install protocols. + @retval EFI_SUCCESS The entry point is executed successfully. **/ EFI_STATUS diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h index c4c987f2f6..252cde2ff1 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h @@ -1,6 +1,6 @@ /** @file - - The implementation of USB mass storage class device driver. + Definitions of functions for Driver Binding Protocol and Block I/O Protocol, + and other internal definitions. Copyright (c) 2007 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials @@ -16,8 +16,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_USBMASS_IMPL_H_ #define _EFI_USBMASS_IMPL_H_ -typedef struct _USB_MASS_DEVICE USB_MASS_DEVICE; - #include "UsbMass.h" #include "UsbMassBot.h" #include "UsbMassCbi.h" @@ -25,20 +23,6 @@ typedef struct _USB_MASS_DEVICE USB_MASS_DEVICE; #define USB_MASS_SIGNATURE SIGNATURE_32 ('U', 's', 'b', 'M') -struct _USB_MASS_DEVICE { - UINT32 Signature; - EFI_HANDLE Controller; - EFI_USB_IO_PROTOCOL *UsbIo; - EFI_DEVICE_PATH_PROTOCOL *DevicePath; - EFI_BLOCK_IO_PROTOCOL BlockIo; - EFI_BLOCK_IO_MEDIA BlockIoMedia; - BOOLEAN OpticalStorage; - UINT8 Lun; // Logical Unit Number - UINT8 Pdt; // Peripheral Device Type - USB_MASS_TRANSPORT *Transport; // USB mass storage transport protocol - VOID *Context; // Opaque storage for mass transport -}; - #define USB_MASS_DEVICE_FROM_BLOCK_IO(a) \ CR (a, USB_MASS_DEVICE, BlockIo, USB_MASS_SIGNATURE) @@ -75,9 +59,9 @@ USBMassDriverBindingSupported ( installs Block I/O Protocol, and submits Asynchronous Interrupt Transfer to manage the USB mass storage device. - @param This The USB mass storage driver binding protocol. - @param Controller The USB mass storage device to start on - @param RemainingDevicePath The remaining device path. + @param This The USB mass storage driver binding protocol. + @param Controller The USB mass storage device to start on + @param RemainingDevicePath The remaining device path. @retval EFI_SUCCESS This driver supports this device. @retval EFI_UNSUPPORTED This driver does not support this device. @@ -103,6 +87,8 @@ USBMassDriverBindingStart ( @param ChildHandleBuffer The buffer of children handle. @retval EFI_SUCCESS The driver stopped from controlling the device. + @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. + @retval EFI_UNSUPPORTED Block I/O Protocol is not installed on Controller. @retval Others Failed to stop the driver **/ @@ -230,5 +216,119 @@ UsbMassFlushBlocks ( IN EFI_BLOCK_IO_PROTOCOL *This ); +// +// EFI Component Name Functions +// + +/** + Retrieves a Unicode string that is the user readable name of the driver. + + This function retrieves the user readable name of a driver in the form of a + Unicode string. If the driver specified by This has a user readable name in + the language specified by Language, then a pointer to the driver name is + returned in DriverName, and EFI_SUCCESS is returned. If the driver specified + by This does not support the language specified by Language, + then EFI_UNSUPPORTED is returned. + + @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or + EFI_COMPONENT_NAME_PROTOCOL instance. + @param Language A pointer to a Null-terminated ASCII string + array indicating the language. This is the + language of the driver name that the caller is + requesting, and it must match one of the + languages specified in SupportedLanguages. The + number of languages supported by a driver is up + to the driver writer. Language is specified + in RFC 3066 or ISO 639-2 language code format. + @param DriverName A pointer to the Unicode string to return. + This Unicode string is the name of the + driver specified by This in the language + specified by Language. + + @retval EFI_SUCCESS The Unicode string for the Driver specified by + This and the language specified by Language was + returned in DriverName. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER DriverName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support + the language specified by Language. + +**/ +EFI_STATUS +EFIAPI +UsbMassStorageGetDriverName ( + IN EFI_COMPONENT_NAME_PROTOCOL *This, + IN CHAR8 *Language, + OUT CHAR16 **DriverName + ); + + +/** + Retrieves a Unicode string that is the user readable name of the controller + that is being managed by a driver. + + This function retrieves the user readable name of the controller specified by + ControllerHandle and ChildHandle in the form of a Unicode string. If the + driver specified by This has a user readable name in the language specified by + Language, then a pointer to the controller name is returned in ControllerName, + and EFI_SUCCESS is returned. If the driver specified by This is not currently + managing the controller specified by ControllerHandle and ChildHandle, + then EFI_UNSUPPORTED is returned. If the driver specified by This does not + support the language specified by Language, then EFI_UNSUPPORTED is returned. + + @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or + EFI_COMPONENT_NAME_PROTOCOL instance. + @param ControllerHandle The handle of a controller that the driver + specified by This is managing. This handle + specifies the controller whose name is to be + returned. + @param ChildHandle The handle of the child controller to retrieve + the name of. This is an optional parameter that + may be NULL. It will be NULL for device + drivers. It will also be NULL for a bus drivers + that wish to retrieve the name of the bus + controller. It will not be NULL for a bus + driver that wishes to retrieve the name of a + child controller. + @param Language A pointer to a Null-terminated ASCII string + array indicating the language. This is the + language of the driver name that the caller is + requesting, and it must match one of the + languages specified in SupportedLanguages. The + number of languages supported by a driver is up + to the driver writer. Language is specified in + RFC 3066 or ISO 639-2 language code format. + @param ControllerName A pointer to the Unicode string to return. + This Unicode string is the name of the + controller specified by ControllerHandle and + ChildHandle in the language specified by + Language from the point of view of the driver + specified by This. + + @retval EFI_SUCCESS The Unicode string for the user readable name in + the language specified by Language for the + driver specified by This was returned in + DriverName. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid + EFI_HANDLE. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER ControllerName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This is not currently + managing the controller specified by + ControllerHandle and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support + the language specified by Language. + +**/ +EFI_STATUS +EFIAPI +UsbMassStorageGetControllerName ( + IN EFI_COMPONENT_NAME_PROTOCOL *This, + IN EFI_HANDLE ControllerHandle, + IN EFI_HANDLE ChildHandle OPTIONAL, + IN CHAR8 *Language, + OUT CHAR16 **ControllerName + ); #endif diff --git a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassStorageDxe.inf b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassStorageDxe.inf index e9bdf4ef27..0025e86f9d 100644 --- a/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassStorageDxe.inf +++ b/MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassStorageDxe.inf @@ -1,5 +1,13 @@ #/** @file -# Component name for module UsbMassStorage +# USB Mass Storage Driver that manages USB mass storage devices and +# produces Block I/O Protocol. +# +# The USB mass storage class is specified in two layers: the bottom layer +# is the transportation protocol. The top layer is the command set. +# The transportation layer provides the transportation of the command, data and result. +# The command set defines the command, data and result. +# The Bulk-Only-Transport and Control/Bulk/Interrupt transport are two transportation protocol. +# USB mass storage class adopts various industrial standard as its command set. # # Copyright (c) 2006 - 2008, Intel Corporation. # @@ -59,7 +67,7 @@ [Protocols] - gEfiUsbIoProtocolGuid # PROTOCOL ALWAYS_CONSUMED - gEfiBlockIoProtocolGuid # PROTOCOL ALWAYS_PRODUCED - gEfiDevicePathProtocolGuid # PROTOCOL ALWAYS_CONSUMED + gEfiUsbIoProtocolGuid # PROTOCOL TO_START + gEfiDevicePathProtocolGuid # PROTOCOL TO_START + gEfiBlockIoProtocolGuid # PROTOCOL BY_START -- 2.39.2