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 The implementation of USB mass storage class device driver.
19 The command set supported is "USB Mass Storage Specification
27 #include "UsbMassImpl.h"
30 // The underlying transport protocol. CBI support isn't included
31 // in the current build. It is being obseleted by the standard
32 // body. If you want to enable it, remove the if directive here,
33 // then add the UsbMassCbi.c/.h to the driver's inf file.
36 USB_MASS_TRANSPORT
*mUsbMassTransport
[] = {
43 UINTN mUsbMscInfo
= DEBUG_INFO
;
44 UINTN mUsbMscError
= DEBUG_ERROR
;
48 Retrieve the media parameters such as disk gemotric for the
49 device's BLOCK IO protocol.
51 @param UsbMass The USB mass storage device
53 @retval EFI_SUCCESS The media parameters is updated successfully.
54 @retval Others Failed to get the media parameters.
59 IN USB_MASS_DEVICE
*UsbMass
62 EFI_BLOCK_IO_MEDIA
*Media
;
66 Media
= &UsbMass
->BlockIoMedia
;
69 // Initialize the MediaPrsent/ReadOnly and others to the default.
70 // We are not forced to get it right at this time, check UEFI2.0
71 // spec for more information:
73 // MediaPresent: This field shows the media present status as
74 // of the most recent ReadBlocks or WriteBlocks call.
76 // ReadOnly : This field shows the read-only status as of the
77 // recent WriteBlocks call.
79 // but remember to update MediaId/MediaPresent/ReadOnly status
80 // after ReadBlocks and WriteBlocks
82 Media
->MediaPresent
= FALSE
;
83 Media
->LogicalPartition
= FALSE
;
84 Media
->ReadOnly
= FALSE
;
85 Media
->WriteCaching
= FALSE
;
89 // Some device may spend several seconds before it is ready.
90 // Try several times before giving up. Wait 5s at most.
94 for (Index
= 0; Index
< USB_BOOT_WAIT_RETRY
; Index
++) {
96 Status
= UsbBootGetParams (UsbMass
);
97 if ((Status
!= EFI_MEDIA_CHANGED
)
98 && (Status
!= EFI_NOT_READY
)
99 && (Status
!= EFI_TIMEOUT
)) {
103 Status
= UsbBootIsUnitReady (UsbMass
);
104 if (EFI_ERROR (Status
)) {
105 gBS
->Stall (USB_BOOT_UNIT_READY_STALL
* (Index
+ 1));
115 Reset the block device. ExtendedVerification is ignored for this.
117 @param This The BLOCK IO protocol
118 @param ExtendedVerification Whether to execute extended verfication.
120 @retval EFI_SUCCESS The device is successfully resetted.
121 @retval Others Failed to reset the device.
126 IN EFI_BLOCK_IO_PROTOCOL
*This
,
127 IN BOOLEAN ExtendedVerification
130 USB_MASS_DEVICE
*UsbMass
;
132 UsbMass
= USB_MASS_DEVICE_FROM_BLOCKIO (This
);
133 return UsbMass
->Transport
->Reset (UsbMass
->Context
, ExtendedVerification
);
138 Read some blocks of data from the block device.
140 @param This The Block IO protocol
141 @param MediaId The media's ID of the device for current request
142 @param Lba The start block number
143 @param BufferSize The size of buffer to read data in
144 @param Buffer The buffer to read data to
146 @retval EFI_SUCCESS The data is successfully read
147 @retval EFI_NO_MEDIA Media isn't present
148 @retval EFI_MEDIA_CHANGED The device media has been changed, that is,
150 @retval EFI_INVALID_PARAMETER Some parameters are invalid, such as Buffer is
152 @retval EFI_BAD_BUFFER_SIZE The buffer size isn't a multiple of media's block
153 size, or overflow the last block number.
158 IN EFI_BLOCK_IO_PROTOCOL
*This
,
165 USB_MASS_DEVICE
*UsbMass
;
166 EFI_BLOCK_IO_MEDIA
*Media
;
170 UsbMass
= USB_MASS_DEVICE_FROM_BLOCKIO (This
);
171 Media
= &UsbMass
->BlockIoMedia
;
174 // First, validate the parameters
176 if ((Buffer
== NULL
) || (BufferSize
== 0)) {
177 return EFI_INVALID_PARAMETER
;
181 // If it is a remoable media, such as CD-Rom or Usb-Floppy,
182 // if, need to detect the media before each rw, while Usb-Flash
183 // needn't. However, it's hard to identify Usb-Floppy between
184 // Usb-Flash by now, so detect media every time.
186 Status
= UsbBootDetectMedia (UsbMass
);
187 if (EFI_ERROR (Status
)) {
188 DEBUG ((mUsbMscError
, "UsbMassReadBlocks: UsbBootDetectMedia (%r)\n", Status
));
193 // Make sure BlockSize and LBA is consistent with BufferSize
195 if ((BufferSize
% Media
->BlockSize
) != 0) {
196 return EFI_BAD_BUFFER_SIZE
;
199 TotalBlock
= BufferSize
/ Media
->BlockSize
;
201 if (Lba
+ TotalBlock
- 1 > Media
->LastBlock
) {
202 return EFI_BAD_BUFFER_SIZE
;
205 Status
= UsbBootReadBlocks (UsbMass
, (UINT32
) Lba
, TotalBlock
, Buffer
);
206 if (EFI_ERROR (Status
)) {
207 DEBUG ((mUsbMscError
, "UsbMassReadBlocks: UsbBootReadBlocks (%r) -> Reset\n", Status
));
208 UsbMassReset (This
, TRUE
);
216 Write some blocks of data to the block device.
218 @param This The Block IO protocol
219 @param MediaId The media's ID of the device for current request
220 @param Lba The start block number
221 @param BufferSize The size of buffer to write data to
222 @param Buffer The buffer to write data to
224 @retval EFI_SUCCESS The data is successfully written
225 @retval EFI_NO_MEDIA Media isn't present
226 @retval EFI_MEDIA_CHANGED The device media has been changed, that is,
228 @retval EFI_INVALID_PARAMETER Some parameters are invalid, such as Buffer is
230 @retval EFI_BAD_BUFFER_SIZE The buffer size isn't a multiple of media's block
236 IN EFI_BLOCK_IO_PROTOCOL
*This
,
243 USB_MASS_DEVICE
*UsbMass
;
244 EFI_BLOCK_IO_MEDIA
*Media
;
248 UsbMass
= USB_MASS_DEVICE_FROM_BLOCKIO (This
);
249 Media
= &UsbMass
->BlockIoMedia
;
252 // First, validate the parameters
254 if ((Buffer
== NULL
) || (BufferSize
== 0)) {
255 return EFI_INVALID_PARAMETER
;
259 // If it is a remoable media, such as CD-Rom or Usb-Floppy,
260 // if, need to detect the media before each rw, while Usb-Flash
261 // needn't. However, it's hard to identify Usb-Floppy between
262 // Usb-Flash by now, so detect media every time.
264 Status
= UsbBootDetectMedia (UsbMass
);
265 if (EFI_ERROR (Status
)) {
266 DEBUG ((mUsbMscError
, "UsbMassWriteBlocks: UsbBootDetectMedia (%r)\n", Status
));
271 // Make sure BlockSize and LBA is consistent with BufferSize
273 if ((BufferSize
% Media
->BlockSize
) != 0) {
274 return EFI_BAD_BUFFER_SIZE
;
277 TotalBlock
= BufferSize
/ Media
->BlockSize
;
279 if (Lba
+ TotalBlock
- 1 > Media
->LastBlock
) {
280 return EFI_BAD_BUFFER_SIZE
;
284 // Try to write the data even the device is marked as ReadOnly,
285 // and clear the status should the write succeed.
287 Status
= UsbBootWriteBlocks (UsbMass
, (UINT32
) Lba
, TotalBlock
, Buffer
);
288 if (EFI_ERROR (Status
)) {
289 DEBUG ((mUsbMscError
, "UsbMassWriteBlocks: UsbBootWriteBlocks (%r) -> Reset\n", Status
));
290 UsbMassReset (This
, TRUE
);
298 Flush the cached writes to disks. USB mass storage device doesn't
299 support write cache, so return EFI_SUCCESS directly.
301 @param This The BLOCK IO protocol
303 @retval EFI_SUCCESS Always returns success
308 IN EFI_BLOCK_IO_PROTOCOL
*This
316 Check whether the controller is a supported USB mass storage.
318 @param This The USB mass driver's driver binding.
319 @param Controller The device to test against.
320 @param RemainingDevicePath The remaining device path
322 @retval EFI_SUCCESS This device is a supported USB mass storage.
323 @retval EFI_UNSUPPORTED The device isn't supported
324 @retval Others Some error happened.
329 USBMassDriverBindingSupported (
330 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
331 IN EFI_HANDLE Controller
,
332 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
335 EFI_USB_IO_PROTOCOL
*UsbIo
;
336 EFI_USB_INTERFACE_DESCRIPTOR Interface
;
337 USB_MASS_TRANSPORT
*Transport
;
342 // Check whether the controlelr support USB_IO
344 Status
= gBS
->OpenProtocol (
346 &gEfiUsbIoProtocolGuid
,
348 This
->DriverBindingHandle
,
350 EFI_OPEN_PROTOCOL_BY_DRIVER
352 if (EFI_ERROR (Status
)) {
357 // Get the interface to check the USB class and find a transport
360 Status
= UsbIo
->UsbGetInterfaceDescriptor (UsbIo
, &Interface
);
361 if (EFI_ERROR (Status
)) {
365 Status
= EFI_UNSUPPORTED
;
367 if (Interface
.InterfaceClass
!= USB_MASS_STORE_CLASS
) {
371 for (Index
= 0; mUsbMassTransport
[Index
] != NULL
; Index
++) {
372 Transport
= mUsbMassTransport
[Index
];
373 if (Interface
.InterfaceProtocol
== Transport
->Protocol
) {
374 Status
= Transport
->Init (UsbIo
, Controller
, NULL
);
379 DEBUG ((mUsbMscInfo
, "Found a USB mass store device %r\n", Status
));
384 &gEfiUsbIoProtocolGuid
,
385 This
->DriverBindingHandle
,
394 Start the USB mass storage device on the controller. It will
395 install a BLOCK_IO protocol on the device if everything is OK.
397 @param This The USB mass storage driver binding.
398 @param Controller The USB mass storage device to start on
399 @param RemainingDevicePath The remaining device path.
401 @retval EFI_SUCCESS The driver has started on the device.
402 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory
403 @retval Others Failed to start the driver on the device.
408 USBMassDriverBindingStart (
409 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
410 IN EFI_HANDLE Controller
,
411 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
414 EFI_USB_IO_PROTOCOL
*UsbIo
;
415 EFI_USB_INTERFACE_DESCRIPTOR Interface
;
416 USB_MASS_DEVICE
*UsbMass
;
417 USB_MASS_TRANSPORT
*Transport
;
421 Status
= gBS
->OpenProtocol (
423 &gEfiUsbIoProtocolGuid
,
425 This
->DriverBindingHandle
,
427 EFI_OPEN_PROTOCOL_BY_DRIVER
430 if (EFI_ERROR (Status
)) {
434 UsbMass
= AllocateZeroPool (sizeof (USB_MASS_DEVICE
));
435 if (UsbMass
== NULL
) {
436 return EFI_OUT_OF_RESOURCES
;
440 // Initialize the transport protocols
442 Status
= UsbIo
->UsbGetInterfaceDescriptor (UsbIo
, &Interface
);
443 if (EFI_ERROR (Status
)) {
444 DEBUG ((mUsbMscError
, "USBMassDriverBindingStart: UsbIo->UsbGetInterfaceDescriptor (%r)\n", Status
));
448 Status
= EFI_UNSUPPORTED
;
450 for (Index
= 0; mUsbMassTransport
[Index
] != NULL
; Index
++) {
451 Transport
= mUsbMassTransport
[Index
];
453 if (Interface
.InterfaceProtocol
== Transport
->Protocol
) {
454 UsbMass
->Transport
= Transport
;
455 Status
= Transport
->Init (UsbIo
, Controller
, &UsbMass
->Context
);
460 if (EFI_ERROR (Status
)) {
461 DEBUG ((mUsbMscError
, "USBMassDriverBindingStart: Transport->Init (%r)\n", Status
));
465 UsbMass
->Signature
= USB_MASS_SIGNATURE
;
466 UsbMass
->Controller
= Controller
;
467 UsbMass
->UsbIo
= UsbIo
;
468 UsbMass
->BlockIo
.Media
= &UsbMass
->BlockIoMedia
;
469 UsbMass
->BlockIo
.Reset
= UsbMassReset
;
470 UsbMass
->BlockIo
.ReadBlocks
= UsbMassReadBlocks
;
471 UsbMass
->BlockIo
.WriteBlocks
= UsbMassWriteBlocks
;
472 UsbMass
->BlockIo
.FlushBlocks
= UsbMassFlushBlocks
;
473 UsbMass
->OpticalStorage
= FALSE
;
476 // Get the storage's parameters, such as last block number.
477 // then install the BLOCK_IO
479 Status
= UsbMassInitMedia (UsbMass
);
480 if (!EFI_ERROR (Status
)) {
481 if ((UsbMass
->Pdt
!= USB_PDT_DIRECT_ACCESS
) &&
482 (UsbMass
->Pdt
!= USB_PDT_CDROM
) &&
483 (UsbMass
->Pdt
!= USB_PDT_OPTICAL
) &&
484 (UsbMass
->Pdt
!= USB_PDT_SIMPLE_DIRECT
)) {
485 DEBUG ((mUsbMscError
, "USBMassDriverBindingStart: Found an unsupported peripheral type[%d]\n", UsbMass
->Pdt
));
488 } else if (Status
!= EFI_NO_MEDIA
){
489 DEBUG ((mUsbMscError
, "USBMassDriverBindingStart: UsbMassInitMedia (%r)\n", Status
));
493 Status
= gBS
->InstallProtocolInterface (
495 &gEfiBlockIoProtocolGuid
,
496 EFI_NATIVE_INTERFACE
,
499 if (EFI_ERROR (Status
)) {
506 gBS
->FreePool (UsbMass
);
510 &gEfiUsbIoProtocolGuid
,
511 This
->DriverBindingHandle
,
520 Stop controlling the device.
522 @param This The USB mass storage driver binding
523 @param Controller The device controller controlled by the driver.
524 @param NumberOfChildren The number of children of this device
525 @param ChildHandleBuffer The buffer of children handle.
527 @retval EFI_SUCCESS The driver stopped from controlling the device.
528 @retval Others Failed to stop the driver
533 USBMassDriverBindingStop (
534 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
535 IN EFI_HANDLE Controller
,
536 IN UINTN NumberOfChildren
,
537 IN EFI_HANDLE
*ChildHandleBuffer
541 USB_MASS_DEVICE
*UsbMass
;
542 EFI_BLOCK_IO_PROTOCOL
*BlockIo
;
545 // First, get our context back from the BLOCK_IO
547 Status
= gBS
->OpenProtocol (
549 &gEfiBlockIoProtocolGuid
,
551 This
->DriverBindingHandle
,
553 EFI_OPEN_PROTOCOL_GET_PROTOCOL
556 if (EFI_ERROR (Status
)) {
560 UsbMass
= USB_MASS_DEVICE_FROM_BLOCKIO (BlockIo
);
563 // Uninstall Block I/O protocol from the device handle,
564 // then call the transport protocol to stop itself.
566 Status
= gBS
->UninstallProtocolInterface (
568 &gEfiBlockIoProtocolGuid
,
571 if (EFI_ERROR (Status
)) {
577 &gEfiUsbIoProtocolGuid
,
578 This
->DriverBindingHandle
,
582 UsbMass
->Transport
->Fini (UsbMass
->Context
);
583 gBS
->FreePool (UsbMass
);
588 EFI_DRIVER_BINDING_PROTOCOL gUSBMassDriverBinding
= {
589 USBMassDriverBindingSupported
,
590 USBMassDriverBindingStart
,
591 USBMassDriverBindingStop
,
597 //@MT: EFI_DRIVER_ENTRY_POINT (USBMassStorageEntryPoint)
601 USBMassStorageEntryPoint (
602 IN EFI_HANDLE ImageHandle
,
603 IN EFI_SYSTEM_TABLE
*SystemTable
609 The entry point for the driver, which will install the driver binding and
610 component name protocol
614 ImageHandle - The image handle of this driver
615 SystemTable - The system table
619 EFI_SUCCESS - the protocols are installed OK
620 Others - Failed to install protocols.
627 // Install driver binding protocol
629 Status
= EfiLibInstallAllDriverProtocols (
632 &gUSBMassDriverBinding
,
634 &gUsbMassStorageComponentName
,