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
= (UINT16
) (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
= (UINT8
) (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
= (UINT8
) (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
= (UINT8
) (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
= (UINT8
) (USB_BOOT_PDT (InquiryData
.Pdt
));
427 Media
->RemovableMedia
= (BOOLEAN
) (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
= (UINT8
) (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
;
632 &(UsbMass
->BlockIoMedia
),
633 sizeof (EFI_BLOCK_IO_MEDIA
)
637 // First test whether the device is ready and get status
638 // If media changed or ready, need read the device's capacity
640 Status
= UsbBootIsUnitReady (UsbMass
);
641 if ((Status
== EFI_SUCCESS
&& Media
->MediaPresent
) ||
642 (Status
== EFI_MEDIA_CHANGED
)) {
643 if ((UsbMass
->Pdt
!= USB_PDT_CDROM
) &&
644 (UsbMass
->Pdt
!= USB_PDT_OPTICAL
)) {
646 // Non CD-Rom device need ModeSenseCmd between InquiryCmd and ReadCapacityCmd
648 UsbBootModeSense (UsbMass
);
650 DEBUG ((mUsbMscInfo
, "UsbBootDetectMedia: Need Read Capacity\n"));
651 Status
= UsbBootReadCapacity (UsbMass
);
653 if (EFI_ERROR (Status
)) {
658 // Detect whether it is necessary to reinstall the BlockIO
660 if ((Media
->MediaId
!= OldMedia
.MediaId
) ||
661 (Media
->MediaPresent
!= OldMedia
.MediaPresent
) ||
662 (Media
->ReadOnly
!= OldMedia
.ReadOnly
) ||
663 (Media
->BlockSize
!= OldMedia
.BlockSize
) ||
664 (Media
->LastBlock
!= OldMedia
.LastBlock
)) {
665 DEBUG ((mUsbMscInfo
, "UsbBootDetectMedia: Need reinstall BlockIoProtocol\n"));
667 gBS
->ReinstallProtocolInterface (
669 &gEfiBlockIoProtocolGuid
,
674 // Check whether media present or media changed or write protected
676 if (Media
->MediaPresent
== FALSE
) {
677 Status
= EFI_NO_MEDIA
;
679 if (Media
->MediaId
!= OldMedia
.MediaId
) {
680 Status
= EFI_MEDIA_CHANGED
;
682 if (Media
->ReadOnly
!= OldMedia
.ReadOnly
) {
683 Status
= EFI_WRITE_PROTECTED
;
692 Read some blocks from the device.
694 @param UsbMass The USB mass storage device to read from
695 @param Lba The start block number
696 @param TotalBlock Total block number to read
697 @param Buffer The buffer to read to
699 @retval EFI_SUCCESS Data are read into the buffer
700 @retval Others Failed to read all the data
705 IN USB_MASS_DEVICE
*UsbMass
,
711 USB_BOOT_READ10_CMD ReadCmd
;
718 BlockSize
= UsbMass
->BlockIoMedia
.BlockSize
;
719 Status
= EFI_SUCCESS
;
721 while (TotalBlock
> 0) {
723 // Split the total blocks into smaller pieces to ease the pressure
724 // on the device. We must split the total block because the READ10
725 // command only has 16 bit transfer length (in the unit of block).
727 Count
= (UINT16
)((TotalBlock
< USB_BOOT_IO_BLOCKS
) ? TotalBlock
: USB_BOOT_IO_BLOCKS
);
728 ByteSize
= (UINT32
)Count
* BlockSize
;
731 // Optical device need longer timeout than other device
733 if (UsbMass
->OpticalStorage
== TRUE
) {
734 Timeout
= (UINT32
)Count
* USB_BOOT_OPTICAL_BLOCK_TIMEOUT
;
736 Timeout
= (UINT32
)Count
* USB_BOOT_GENERAL_BLOCK_TIMEOUT
;
740 // Fill in the command then execute
742 ZeroMem (&ReadCmd
, sizeof (USB_BOOT_READ10_CMD
));
744 ReadCmd
.OpCode
= USB_BOOT_READ10_OPCODE
;
745 ReadCmd
.Lun
= (UINT8
) (USB_BOOT_LUN (UsbMass
->Lun
));
746 UsbBootPutUint32 (ReadCmd
.Lba
, Lba
);
747 UsbBootPutUint16 (ReadCmd
.TransferLen
, Count
);
749 Status
= UsbBootExecCmdWithRetry (
752 sizeof (USB_BOOT_READ10_CMD
),
758 if (EFI_ERROR (Status
)) {
763 Buffer
+= Count
* BlockSize
;
772 Write some blocks to the device.
774 @param UsbMass The USB mass storage device to write to
775 @param Lba The start block number
776 @param TotalBlock Total block number to write
777 @param Buffer The buffer to write to
779 @retval EFI_SUCCESS Data are written into the buffer
780 @retval Others Failed to write all the data
785 IN USB_MASS_DEVICE
*UsbMass
,
791 USB_BOOT_WRITE10_CMD WriteCmd
;
798 BlockSize
= UsbMass
->BlockIoMedia
.BlockSize
;
799 Status
= EFI_SUCCESS
;
801 while (TotalBlock
> 0) {
803 // Split the total blocks into smaller pieces to ease the pressure
804 // on the device. We must split the total block because the WRITE10
805 // command only has 16 bit transfer length (in the unit of block).
807 Count
= (UINT16
)((TotalBlock
< USB_BOOT_IO_BLOCKS
) ? TotalBlock
: USB_BOOT_IO_BLOCKS
);
808 ByteSize
= (UINT32
)Count
* BlockSize
;
811 // Optical device need longer timeout than other device
813 if (UsbMass
->OpticalStorage
== TRUE
) {
814 Timeout
= (UINT32
)Count
* USB_BOOT_OPTICAL_BLOCK_TIMEOUT
;
816 Timeout
= (UINT32
)Count
* USB_BOOT_GENERAL_BLOCK_TIMEOUT
;
820 // Fill in the write10 command block
822 ZeroMem (&WriteCmd
, sizeof (USB_BOOT_WRITE10_CMD
));
824 WriteCmd
.OpCode
= USB_BOOT_WRITE10_OPCODE
;
825 WriteCmd
.Lun
= (UINT8
) (USB_BOOT_LUN (UsbMass
->Lun
));
826 UsbBootPutUint32 (WriteCmd
.Lba
, Lba
);
827 UsbBootPutUint16 (WriteCmd
.TransferLen
, Count
);
829 Status
= UsbBootExecCmdWithRetry (
832 sizeof (USB_BOOT_WRITE10_CMD
),
838 if (EFI_ERROR (Status
)) {
843 Buffer
+= Count
* BlockSize
;
852 Use the USB clear feature control transfer to clear the endpoint
855 @param UsbIo The USB IO protocol to use
856 @param EndpointAddr The endpoint to clear stall for
858 @retval EFI_SUCCESS The endpoint stall condtion is clear
859 @retval Others Failed to clear the endpoint stall condtion
863 UsbClearEndpointStall (
864 IN EFI_USB_IO_PROTOCOL
*UsbIo
,
865 IN UINT8 EndpointAddr
868 EFI_USB_DEVICE_REQUEST Request
;
873 Request
.RequestType
= 0x02;
874 Request
.Request
= USB_REQ_CLEAR_FEATURE
;
875 Request
.Value
= USB_FEATURE_ENDPOINT_HALT
;
876 Request
.Index
= EndpointAddr
;
878 Timeout
= USB_BOOT_GENERAL_CMD_TIMEOUT
/ USB_MASS_STALL_1_MS
;
880 Status
= UsbIo
->UsbControlTransfer (