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 This file implement the command set of "USB Mass Storage Specification
26 #include "UsbMassImpl.h"
30 Read an UINT32 from the buffer to avoid byte alignment problems, then
31 convert that to the little endia. The USB mass storage bootability spec
34 @param Buf The buffer contains the first byte of the UINT32
37 @return The UINT32 value read from the buffer in little endia.
48 CopyMem (&Value
, Buf
, sizeof (UINT32
));
49 return USB_BOOT_SWAP32 (Value
);
54 Put an UINT32 in little endia to the buffer. The data is converted to
55 big endia before writing.
57 @param Buf The buffer to write data to
58 @param Data32 The data to write.
70 Data32
= USB_BOOT_SWAP32 (Data32
);
71 CopyMem (Buf
, &Data32
, sizeof (UINT32
));
76 Put an UINT16 in little endia to the buffer. The data is converted to
77 big endia before writing.
79 @param Buf The buffer to write data to
80 @param Data16 The data to write
92 Data16
= USB_BOOT_SWAP16 (Data16
);
93 CopyMem (Buf
, &Data16
, sizeof (UINT16
));
98 Request sense information via sending Request Sense
101 @param UsbMass The device to be requested sense data
103 @retval EFI_DEVICE_ERROR Hardware error
104 @retval EFI_SUCCESS Success
108 UsbBootRequestSense (
109 IN USB_MASS_DEVICE
*UsbMass
112 USB_BOOT_REQUEST_SENSE_CMD SenseCmd
;
113 USB_BOOT_REQUEST_SENSE_DATA SenseData
;
114 EFI_BLOCK_IO_MEDIA
*Media
;
115 USB_MASS_TRANSPORT
*Transport
;
119 Transport
= UsbMass
->Transport
;
122 // Request the sense data from the device if command failed
124 ZeroMem (&SenseCmd
, sizeof (USB_BOOT_REQUEST_SENSE_CMD
));
125 ZeroMem (&SenseData
, sizeof (USB_BOOT_REQUEST_SENSE_DATA
));
127 SenseCmd
.OpCode
= USB_BOOT_REQUEST_SENSE_OPCODE
;
128 SenseCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
129 SenseCmd
.AllocLen
= sizeof (USB_BOOT_REQUEST_SENSE_DATA
);
131 Status
= Transport
->ExecCommand (
134 sizeof (USB_BOOT_REQUEST_SENSE_CMD
),
137 sizeof (USB_BOOT_REQUEST_SENSE_DATA
),
138 USB_BOOT_GENERAL_CMD_TIMEOUT
,
141 if (EFI_ERROR (Status
) || CmdResult
!= USB_MASS_CMD_SUCCESS
) {
142 DEBUG ((mUsbMscError
, "UsbBootRequestSense: (%r) CmdResult=0x%x\n", Status
, CmdResult
));
143 return EFI_DEVICE_ERROR
;
147 // Interpret the sense data and update the media status if necessary.
149 Media
= &UsbMass
->BlockIoMedia
;
151 switch (USB_BOOT_SENSE_KEY (SenseData
.SenseKey
)) {
153 case USB_BOOT_SENSE_NO_SENSE
:
154 case USB_BOOT_SENSE_RECOVERED
:
156 // Suppose hardware can handle this case, and recover later by itself
158 Status
= EFI_NOT_READY
;
161 case USB_BOOT_SENSE_NOT_READY
:
162 switch (SenseData
.ASC
) {
163 case USB_BOOT_ASC_NO_MEDIA
:
164 Status
= EFI_NO_MEDIA
;
165 Media
->MediaPresent
= FALSE
;
168 case USB_BOOT_ASC_MEDIA_UPSIDE_DOWN
:
169 Status
= EFI_DEVICE_ERROR
;
170 Media
->MediaPresent
= FALSE
;
173 case USB_BOOT_ASC_NOT_READY
:
174 if (SenseData
.ASCQ
== USB_BOOT_ASCQ_IN_PROGRESS
||
175 SenseData
.ASCQ
== USB_BOOT_ASCQ_DEVICE_BUSY
) {
177 // Regular timeout, and need retry once more
179 DEBUG ((mUsbMscInfo
, "UsbBootRequestSense: Not ready and need retry once more\n"));
180 Status
= EFI_NOT_READY
;
185 case USB_BOOT_SENSE_ILLEGAL_REQUEST
:
186 Status
= EFI_INVALID_PARAMETER
;
189 case USB_BOOT_SENSE_UNIT_ATTENTION
:
190 Status
= EFI_DEVICE_ERROR
;
191 if (SenseData
.ASC
== USB_BOOT_ASC_MEDIA_CHANGE
) {
192 Status
= EFI_MEDIA_CHANGED
;
193 UsbMass
->BlockIoMedia
.MediaId
++;
197 case USB_BOOT_SNESE_DATA_PROTECT
:
198 Status
= EFI_WRITE_PROTECTED
;
199 UsbMass
->BlockIoMedia
.ReadOnly
= TRUE
;
203 Status
= EFI_DEVICE_ERROR
;
207 DEBUG ((mUsbMscInfo
, "UsbBootRequestSense: (%r) with sense key %x/%x/%x\n",
209 USB_BOOT_SENSE_KEY (SenseData
.SenseKey
),
219 Execute the USB mass storage bootability commands. If execution
220 failed, retrieve the error by REQUEST_SENSE then update the device's
221 status, such as ReadyOnly.
223 @param UsbMass The device to issue commands to
224 @param Cmd The command to execute
225 @param CmdLen The length of the command
226 @param DataDir The direction of data transfer
227 @param Data The buffer to hold the data
228 @param DataLen The length of expected data
229 @param Timeout The timeout used to transfer
231 @retval EFI_SUCCESS The command is excuted OK
232 @retval EFI_DEVICE_ERROR Failed to request sense
233 @retval EFI_INVALID_PARAMETER The command has some invalid parameters
234 @retval EFI_WRITE_PROTECTED The device is write protected
235 @retval EFI_MEDIA_CHANGED The device media has been changed
241 IN USB_MASS_DEVICE
*UsbMass
,
244 IN EFI_USB_DATA_DIRECTION DataDir
,
250 USB_MASS_TRANSPORT
*Transport
;
254 Transport
= UsbMass
->Transport
;
255 Status
= Transport
->ExecCommand (
266 // ExecCommand return success and get the right CmdResult means
267 // the commnad transfer is OK.
269 if ((CmdResult
== USB_MASS_CMD_SUCCESS
) && !EFI_ERROR(Status
)) {
273 return UsbBootRequestSense (UsbMass
);
278 Execute the USB mass storage bootability commands. If execution
279 failed, retrieve the error by REQUEST_SENSE then update the device's
280 status, such as ReadyOnly.
282 @param UsbMass The device to issue commands to
283 @param Cmd The command to execute
284 @param CmdLen The length of the command
285 @param DataDir The direction of data transfer
286 @param Data The buffer to hold the data
287 @param DataLen The length of expected data
289 @retval EFI_SUCCESS The command is excuted OK
290 @retval EFI_DEVICE_ERROR Failed to request sense
291 @retval EFI_INVALID_PARAMETER The command has some invalid parameters
292 @retval EFI_WRITE_PROTECTED The device is write protected
293 @retval EFI_MEDIA_CHANGED The device media has been changed
298 UsbBootExecCmdWithRetry (
299 IN USB_MASS_DEVICE
*UsbMass
,
302 IN EFI_USB_DATA_DIRECTION DataDir
,
312 // If the device isn't ready, wait some time. If the device is ready,
313 // retry the command again.
315 Status
= EFI_SUCCESS
;
317 for (Index
= 0; Index
< USB_BOOT_COMMAND_RETRY
; Index
++) {
319 // Execute the command with an increasingly larger timeout value.
321 Status
= UsbBootExecCmd (
328 Timeout
* (Index
+ 1)
330 if (Status
== EFI_SUCCESS
||
331 Status
== EFI_MEDIA_CHANGED
) {
335 // Need retry once more, so reset index
337 if (Status
== EFI_NOT_READY
) {
348 Use the TEST UNIT READY command to check whether it is ready.
349 If it is ready, update the parameters.
351 @param UsbMass The device to test
353 @retval EFI_SUCCESS The device is ready and parameters are updated.
354 @retval Others Device not ready.
359 IN USB_MASS_DEVICE
*UsbMass
362 USB_BOOT_TEST_UNIT_READY_CMD TestCmd
;
364 ZeroMem (&TestCmd
, sizeof (USB_BOOT_TEST_UNIT_READY_CMD
));
366 TestCmd
.OpCode
= USB_BOOT_TEST_UNIT_READY_OPCODE
;
367 TestCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
369 return UsbBootExecCmdWithRetry (
372 sizeof (USB_BOOT_TEST_UNIT_READY_CMD
),
376 USB_BOOT_GENERAL_CMD_TIMEOUT
382 Inquiry Command requests that information regrarding parameters of
383 the Device be sent to the Host.
385 @param UsbMass The device to inquiry.
387 @retval EFI_SUCCESS The device is ready and parameters are updated.
388 @retval Others Device not ready.
393 IN USB_MASS_DEVICE
*UsbMass
396 USB_BOOT_INQUIRY_CMD InquiryCmd
;
397 USB_BOOT_INQUIRY_DATA InquiryData
;
398 EFI_BLOCK_IO_MEDIA
*Media
;
401 Media
= &(UsbMass
->BlockIoMedia
);
404 // Use the Inquiry command to get the RemovableMedia setting.
406 ZeroMem (&InquiryCmd
, sizeof (USB_BOOT_INQUIRY_CMD
));
407 ZeroMem (&InquiryData
, sizeof (USB_BOOT_INQUIRY_DATA
));
409 InquiryCmd
.OpCode
= USB_BOOT_INQUIRY_OPCODE
;
410 InquiryCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
411 InquiryCmd
.AllocLen
= sizeof (InquiryData
);
413 Status
= UsbBootExecCmdWithRetry (
416 sizeof (USB_BOOT_INQUIRY_CMD
),
419 sizeof (USB_BOOT_INQUIRY_DATA
),
420 USB_BOOT_INQUIRY_CMD_TIMEOUT
422 if (EFI_ERROR (Status
)) {
426 UsbMass
->Pdt
= USB_BOOT_PDT (InquiryData
.Pdt
);
427 Media
->RemovableMedia
= USB_BOOT_REMOVABLE (InquiryData
.Removable
);
429 // Default value 512 Bytes, in case no media present at first time
431 Media
->BlockSize
= 0x0200;
438 Get the capacity of the USB mass storage media, including
439 the presentation, block size, and last block number. This
440 function is used to get the disk parameters at the start if
441 it is a non-removable media or to detect the media if it is
444 @param UsbMass The device to retireve disk gemotric.
446 @retval EFI_SUCCESS The disk gemotric is successfully retrieved.
447 @retval EFI_DEVICE_ERROR Something is inconsistent with the disk gemotric.
451 UsbBootReadCapacity (
452 IN USB_MASS_DEVICE
*UsbMass
455 USB_BOOT_READ_CAPACITY_CMD CapacityCmd
;
456 USB_BOOT_READ_CAPACITY_DATA CapacityData
;
457 EFI_BLOCK_IO_MEDIA
*Media
;
460 Media
= &UsbMass
->BlockIoMedia
;
463 // Use the READ CAPACITY command to get the block length and last blockno
465 ZeroMem (&CapacityCmd
, sizeof (USB_BOOT_READ_CAPACITY_CMD
));
466 ZeroMem (&CapacityData
, sizeof (USB_BOOT_READ_CAPACITY_DATA
));
468 CapacityCmd
.OpCode
= USB_BOOT_READ_CAPACITY_OPCODE
;
469 CapacityCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
471 Status
= UsbBootExecCmdWithRetry (
474 sizeof (USB_BOOT_READ_CAPACITY_CMD
),
477 sizeof (USB_BOOT_READ_CAPACITY_DATA
),
478 USB_BOOT_GENERAL_CMD_TIMEOUT
480 if (EFI_ERROR (Status
)) {
484 Media
->MediaPresent
= TRUE
;
485 Media
->LastBlock
= UsbBootGetUint32 (CapacityData
.LastLba
);
486 Media
->BlockSize
= UsbBootGetUint32 (CapacityData
.BlockLen
);
488 DEBUG ((mUsbMscInfo
, "UsbBootReadCapacity Success LBA=%d BlockSize=%d\n",
489 Media
->LastBlock
, Media
->BlockSize
));
496 Retrieves mode sense information via sending Mode Sense
499 @param UsbMass The USB_FLOPPY_DEV instance.
501 @retval EFI_DEVICE_ERROR Hardware error
502 @retval EFI_SUCCESS Success
507 IN USB_MASS_DEVICE
*UsbMass
511 USB_BOOT_MODE_SENSE_CMD ModeSenseCmd
;
512 USB_BOOT_MODE_PARA_HEADER ModeParaHeader
;
515 ZeroMem (&ModeSenseCmd
, sizeof (USB_BOOT_MODE_SENSE_CMD
));
516 ZeroMem (&ModeParaHeader
, sizeof (USB_BOOT_MODE_PARA_HEADER
));
519 // overuse Context Pointer, the first field of Bot or Cbi is EFI_USB_INTERFACE_DESCRIPTOR
521 CommandSet
= ((EFI_USB_INTERFACE_DESCRIPTOR
*) (UsbMass
->Context
))->InterfaceSubClass
;
523 if (CommandSet
== USB_MASS_STORE_SCSI
) {
525 // Not UFI Command Set, no ModeSense Command
530 ModeSenseCmd
.OpCode
= USB_BOOT_MODE_SENSE10_OPCODE
;
531 ModeSenseCmd
.PageCode
= 0x3f;
532 ModeSenseCmd
.ParaListLenLsb
= (UINT8
) sizeof (USB_BOOT_MODE_PARA_HEADER
);
534 Status
= UsbBootExecCmdWithRetry (
537 sizeof (USB_BOOT_MODE_SENSE_CMD
),
540 sizeof (USB_BOOT_MODE_PARA_HEADER
),
541 USB_BOOT_GENERAL_CMD_TIMEOUT
544 // Did nothing with the Header here
545 // But probably should
553 Get the parameters for the USB mass storage media, including
554 the RemovableMedia, block size, and last block number. This
555 function is used both to initialize the media during the
556 DriverBindingStart and to re-initialize it when the media is
557 changed. Althought the RemoveableMedia is unlikely to change,
560 @param UsbMass The device to retireve disk gemotric.
562 @retval EFI_SUCCESS The disk gemotric is successfully retrieved.
563 @retval EFI_DEVICE_ERROR Something is inconsistent with the disk gemotric.
568 IN USB_MASS_DEVICE
*UsbMass
571 EFI_BLOCK_IO_MEDIA
*Media
;
574 Status
= UsbBootInquiry (UsbMass
);
575 if (EFI_ERROR (Status
)) {
576 DEBUG ((mUsbMscError
, "UsbBootGetParams: UsbBootInquiry (%r)\n", Status
));
580 Media
= &(UsbMass
->BlockIoMedia
);
582 // Don't use the Removable bit in inquirydata to test whether the media
583 // is removable because many flash disks wrongly set this bit.
585 if ((UsbMass
->Pdt
== USB_PDT_CDROM
) || (UsbMass
->Pdt
== USB_PDT_OPTICAL
)) {
587 // CD-Rom or Optical device
589 UsbMass
->OpticalStorage
= TRUE
;
591 // Default value 2048 Bytes, in case no media present at first time
593 Media
->BlockSize
= 0x0800;
596 // Non CD-Rom device need ModeSenseCmd between InquiryCmd and ReadCapacityCmd
598 Status
= UsbBootModeSense (UsbMass
);
599 if (EFI_ERROR (Status
)) {
600 DEBUG ((mUsbMscError
, "UsbBootGetParams: UsbBootModeSense (%r)\n", Status
));
605 return UsbBootReadCapacity (UsbMass
);
610 Detect whether the removable media is present and whether it has changed.
611 The Non-removable media doesn't need it.
613 @param UsbMass The device to retireve disk gemotric.
615 @retval EFI_SUCCESS The disk gemotric is successfully retrieved.
616 @retval EFI_DEVICE_ERROR Something is inconsistent with the disk gemotric.
621 IN USB_MASS_DEVICE
*UsbMass
624 EFI_BLOCK_IO_MEDIA OldMedia
;
625 EFI_BLOCK_IO_MEDIA
*Media
;
628 Media
= &UsbMass
->BlockIoMedia
;
629 OldMedia
= UsbMass
->BlockIoMedia
;
632 // First test whether the device is ready and get status
633 // If media changed or ready, need read the device's capacity
635 Status
= UsbBootIsUnitReady (UsbMass
);
636 if ((Status
== EFI_SUCCESS
&& Media
->MediaPresent
) ||
637 (Status
== EFI_MEDIA_CHANGED
)) {
638 if ((UsbMass
->Pdt
!= USB_PDT_CDROM
) &&
639 (UsbMass
->Pdt
!= USB_PDT_OPTICAL
)) {
641 // Non CD-Rom device need ModeSenseCmd between InquiryCmd and ReadCapacityCmd
643 UsbBootModeSense (UsbMass
);
645 DEBUG ((mUsbMscInfo
, "UsbBootDetectMedia: Need Read Capacity\n"));
646 Status
= UsbBootReadCapacity (UsbMass
);
648 if (EFI_ERROR (Status
)) {
653 // Detect whether it is necessary to reinstall the BlockIO
655 if ((Media
->MediaId
!= OldMedia
.MediaId
) ||
656 (Media
->MediaPresent
!= OldMedia
.MediaPresent
) ||
657 (Media
->ReadOnly
!= OldMedia
.ReadOnly
) ||
658 (Media
->BlockSize
!= OldMedia
.BlockSize
) ||
659 (Media
->LastBlock
!= OldMedia
.LastBlock
)) {
660 DEBUG ((mUsbMscInfo
, "UsbBootDetectMedia: Need reinstall BlockIoProtocol\n"));
662 gBS
->ReinstallProtocolInterface (
664 &gEfiBlockIoProtocolGuid
,
669 // Check whether media present or media changed or write protected
671 if (Media
->MediaPresent
== FALSE
) {
672 Status
= EFI_NO_MEDIA
;
674 if (Media
->MediaId
!= OldMedia
.MediaId
) {
675 Status
= EFI_MEDIA_CHANGED
;
677 if (Media
->ReadOnly
!= OldMedia
.ReadOnly
) {
678 Status
= EFI_WRITE_PROTECTED
;
687 Read some blocks from the device.
689 @param UsbMass The USB mass storage device to read from
690 @param Lba The start block number
691 @param TotalBlock Total block number to read
692 @param Buffer The buffer to read to
694 @retval EFI_SUCCESS Data are read into the buffer
695 @retval Others Failed to read all the data
700 IN USB_MASS_DEVICE
*UsbMass
,
706 USB_BOOT_READ10_CMD ReadCmd
;
713 BlockSize
= UsbMass
->BlockIoMedia
.BlockSize
;
714 Status
= EFI_SUCCESS
;
716 while (TotalBlock
> 0) {
718 // Split the total blocks into smaller pieces to ease the pressure
719 // on the device. We must split the total block because the READ10
720 // command only has 16 bit transfer length (in the unit of block).
722 Count
= (UINT16
)((TotalBlock
< USB_BOOT_IO_BLOCKS
) ? TotalBlock
: USB_BOOT_IO_BLOCKS
);
723 ByteSize
= (UINT32
)Count
* BlockSize
;
726 // Optical device need longer timeout than other device
728 if (UsbMass
->OpticalStorage
== TRUE
) {
729 Timeout
= (UINT32
)Count
* USB_BOOT_OPTICAL_BLOCK_TIMEOUT
;
731 Timeout
= (UINT32
)Count
* USB_BOOT_GENERAL_BLOCK_TIMEOUT
;
735 // Fill in the command then execute
737 ZeroMem (&ReadCmd
, sizeof (USB_BOOT_READ10_CMD
));
739 ReadCmd
.OpCode
= USB_BOOT_READ10_OPCODE
;
740 ReadCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
741 UsbBootPutUint32 (ReadCmd
.Lba
, Lba
);
742 UsbBootPutUint16 (ReadCmd
.TransferLen
, Count
);
744 Status
= UsbBootExecCmdWithRetry (
747 sizeof (USB_BOOT_READ10_CMD
),
753 if (EFI_ERROR (Status
)) {
758 Buffer
+= Count
* BlockSize
;
767 Write some blocks to the device.
769 @param UsbMass The USB mass storage device to write to
770 @param Lba The start block number
771 @param TotalBlock Total block number to write
772 @param Buffer The buffer to write to
774 @retval EFI_SUCCESS Data are written into the buffer
775 @retval Others Failed to write all the data
780 IN USB_MASS_DEVICE
*UsbMass
,
786 USB_BOOT_WRITE10_CMD WriteCmd
;
793 BlockSize
= UsbMass
->BlockIoMedia
.BlockSize
;
794 Status
= EFI_SUCCESS
;
796 while (TotalBlock
> 0) {
798 // Split the total blocks into smaller pieces to ease the pressure
799 // on the device. We must split the total block because the WRITE10
800 // command only has 16 bit transfer length (in the unit of block).
802 Count
= (UINT16
)((TotalBlock
< USB_BOOT_IO_BLOCKS
) ? TotalBlock
: USB_BOOT_IO_BLOCKS
);
803 ByteSize
= (UINT32
)Count
* BlockSize
;
806 // Optical device need longer timeout than other device
808 if (UsbMass
->OpticalStorage
== TRUE
) {
809 Timeout
= (UINT32
)Count
* USB_BOOT_OPTICAL_BLOCK_TIMEOUT
;
811 Timeout
= (UINT32
)Count
* USB_BOOT_GENERAL_BLOCK_TIMEOUT
;
815 // Fill in the write10 command block
817 ZeroMem (&WriteCmd
, sizeof (USB_BOOT_WRITE10_CMD
));
819 WriteCmd
.OpCode
= USB_BOOT_WRITE10_OPCODE
;
820 WriteCmd
.Lun
= USB_BOOT_LUN (UsbMass
->Lun
);
821 UsbBootPutUint32 (WriteCmd
.Lba
, Lba
);
822 UsbBootPutUint16 (WriteCmd
.TransferLen
, Count
);
824 Status
= UsbBootExecCmdWithRetry (
827 sizeof (USB_BOOT_WRITE10_CMD
),
833 if (EFI_ERROR (Status
)) {
838 Buffer
+= Count
* BlockSize
;
847 Use the USB clear feature control transfer to clear the endpoint
850 @param UsbIo The USB IO protocol to use
851 @param EndpointAddr The endpoint to clear stall for
853 @retval EFI_SUCCESS The endpoint stall condtion is clear
854 @retval Others Failed to clear the endpoint stall condtion
858 UsbClearEndpointStall (
859 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
860 IN UINT8 EndpointAddr
863 EFI_USB_DEVICE_REQUEST Request
;
868 Request
.RequestType
= 0x02;
869 Request
.Request
= USB_REQ_CLEAR_FEATURE
;
870 Request
.Value
= USB_FEATURE_ENDPOINT_HALT
;
871 Request
.Index
= EndpointAddr
;
873 Timeout
= USB_BOOT_GENERAL_CMD_TIMEOUT
/ USB_MASS_STALL_1_MS
;
875 Status
= UsbIo
->UsbControlTransfer (