2 Header file for SCSI Disk Driver.
4 Copyright (c) 2004 - 2008, Intel Corporation. <BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
22 #include <Protocol/ScsiIo.h>
23 #include <Protocol/ComponentName.h>
24 #include <Protocol/BlockIo.h>
25 #include <Protocol/DriverBinding.h>
26 #include <Protocol/ScsiPassThruExt.h>
28 #include <Library/DebugLib.h>
29 #include <Library/UefiDriverEntryPoint.h>
30 #include <Library/UefiLib.h>
31 #include <Library/BaseMemoryLib.h>
32 #include <Library/ScsiLib.h>
33 #include <Library/UefiBootServicesTableLib.h>
35 #include <IndustryStandard/Scsi.h>
37 #define IS_DEVICE_FIXED(a) (a)->FixedDevice ? 1 : 0
39 #define SCSI_DISK_DEV_SIGNATURE EFI_SIGNATURE_32 ('s', 'c', 'd', 'k')
46 EFI_BLOCK_IO_PROTOCOL BlkIo
;
47 EFI_BLOCK_IO_MEDIA BlkIoMedia
;
48 EFI_SCSI_IO_PROTOCOL
*ScsiIo
;
53 EFI_SCSI_SENSE_DATA
*SenseData
;
54 UINTN SenseDataNumber
;
55 EFI_SCSI_INQUIRY_DATA InquiryData
;
57 EFI_UNICODE_STRING_TABLE
*ControllerNameTable
;
61 #define SCSI_DISK_DEV_FROM_THIS(a) CR (a, SCSI_DISK_DEV, BlkIo, SCSI_DISK_DEV_SIGNATURE)
66 extern EFI_DRIVER_BINDING_PROTOCOL gScsiDiskDriverBinding
;
67 extern EFI_COMPONENT_NAME_PROTOCOL gScsiDiskComponentName
;
68 extern EFI_COMPONENT_NAME2_PROTOCOL gScsiDiskComponentName2
;
70 // action code used in detect media process
72 #define ACTION_NO_ACTION 0x00
73 #define ACTION_READ_CAPACITY 0x01
74 #define ACTION_RETRY_COMMAND_LATER 0x02
77 Test to see if this driver supports ControllerHandle.
79 This service is called by the EFI boot service ConnectController(). In order
80 to make drivers as small as possible, there are a few calling restrictions for
81 this service. ConnectController() must follow these calling restrictions.
82 If any other agent wishes to call Supported() it must also follow these
85 @param This Protocol instance pointer.
86 @param ControllerHandle Handle of device to test
87 @param RemainingDevicePath Optional parameter use to pick a specific child
90 @retval EFI_SUCCESS This driver supports this device
91 @retval EFI_ALREADY_STARTED This driver is already running on this device
92 @retval other This driver does not support this device
97 ScsiDiskDriverBindingSupported (
98 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
99 IN EFI_HANDLE Controller
,
100 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
104 Start this driver on ControllerHandle.
106 This service is called by the EFI boot service ConnectController(). In order
107 to make drivers as small as possible, there are a few calling restrictions for
108 this service. ConnectController() must follow these calling restrictions. If
109 any other agent wishes to call Start() it must also follow these calling
112 @param This Protocol instance pointer.
113 @param ControllerHandle Handle of device to bind driver to
114 @param RemainingDevicePath Optional parameter use to pick a specific child
117 @retval EFI_SUCCESS This driver is added to ControllerHandle
118 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
119 @retval other This driver does not support this device
124 ScsiDiskDriverBindingStart (
125 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
126 IN EFI_HANDLE Controller
,
127 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
131 Stop this driver on ControllerHandle.
133 This service is called by the EFI boot service DisconnectController().
134 In order to make drivers as small as possible, there are a few calling
135 restrictions for this service. DisconnectController() must follow these
136 calling restrictions. If any other agent wishes to call Stop() it must
137 also follow these calling restrictions.
139 @param This Protocol instance pointer.
140 @param ControllerHandle Handle of device to stop driver on
141 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
142 children is zero stop the entire bus driver.
143 @param ChildHandleBuffer List of Child Handles to Stop.
145 @retval EFI_SUCCESS This driver is removed ControllerHandle
146 @retval other This driver was not removed from this device
151 ScsiDiskDriverBindingStop (
152 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
153 IN EFI_HANDLE Controller
,
154 IN UINTN NumberOfChildren
,
155 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL
159 // EFI Component Name Functions
162 Retrieves a Unicode string that is the user readable name of the driver.
164 This function retrieves the user readable name of a driver in the form of a
165 Unicode string. If the driver specified by This has a user readable name in
166 the language specified by Language, then a pointer to the driver name is
167 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
168 by This does not support the language specified by Language,
169 then EFI_UNSUPPORTED is returned.
171 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
172 EFI_COMPONENT_NAME_PROTOCOL instance.
174 @param Language A pointer to a Null-terminated ASCII string
175 array indicating the language. This is the
176 language of the driver name that the caller is
177 requesting, and it must match one of the
178 languages specified in SupportedLanguages. The
179 number of languages supported by a driver is up
180 to the driver writer. Language is specified
181 in RFC 3066 or ISO 639-2 language code format.
183 @param DriverName A pointer to the Unicode string to return.
184 This Unicode string is the name of the
185 driver specified by This in the language
186 specified by Language.
188 @retval EFI_SUCCESS The Unicode string for the Driver specified by
189 This and the language specified by Language was
190 returned in DriverName.
192 @retval EFI_INVALID_PARAMETER Language is NULL.
194 @retval EFI_INVALID_PARAMETER DriverName is NULL.
196 @retval EFI_UNSUPPORTED The driver specified by This does not support
197 the language specified by Language.
202 ScsiDiskComponentNameGetDriverName (
203 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
205 OUT CHAR16
**DriverName
210 Retrieves a Unicode string that is the user readable name of the controller
211 that is being managed by a driver.
213 This function retrieves the user readable name of the controller specified by
214 ControllerHandle and ChildHandle in the form of a Unicode string. If the
215 driver specified by This has a user readable name in the language specified by
216 Language, then a pointer to the controller name is returned in ControllerName,
217 and EFI_SUCCESS is returned. If the driver specified by This is not currently
218 managing the controller specified by ControllerHandle and ChildHandle,
219 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
220 support the language specified by Language, then EFI_UNSUPPORTED is returned.
222 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
223 EFI_COMPONENT_NAME_PROTOCOL instance.
225 @param ControllerHandle The handle of a controller that the driver
226 specified by This is managing. This handle
227 specifies the controller whose name is to be
230 @param ChildHandle The handle of the child controller to retrieve
231 the name of. This is an optional parameter that
232 may be NULL. It will be NULL for device
233 drivers. It will also be NULL for a bus drivers
234 that wish to retrieve the name of the bus
235 controller. It will not be NULL for a bus
236 driver that wishes to retrieve the name of a
239 @param Language A pointer to a Null-terminated ASCII string
240 array indicating the language. This is the
241 language of the driver name that the caller is
242 requesting, and it must match one of the
243 languages specified in SupportedLanguages. The
244 number of languages supported by a driver is up
245 to the driver writer. Language is specified in
246 RFC 3066 or ISO 639-2 language code format.
248 @param ControllerName A pointer to the Unicode string to return.
249 This Unicode string is the name of the
250 controller specified by ControllerHandle and
251 ChildHandle in the language specified by
252 Language from the point of view of the driver
255 @retval EFI_SUCCESS The Unicode string for the user readable name in
256 the language specified by Language for the
257 driver specified by This was returned in
260 @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
262 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
265 @retval EFI_INVALID_PARAMETER Language is NULL.
267 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
269 @retval EFI_UNSUPPORTED The driver specified by This is not currently
270 managing the controller specified by
271 ControllerHandle and ChildHandle.
273 @retval EFI_UNSUPPORTED The driver specified by This does not support
274 the language specified by Language.
279 ScsiDiskComponentNameGetControllerName (
280 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
281 IN EFI_HANDLE ControllerHandle
,
282 IN EFI_HANDLE ChildHandle OPTIONAL
,
284 OUT CHAR16
**ControllerName
291 @param This The pointer of EFI_BLOCK_IO_PROTOCOL
292 @param ExtendedVerification The flag about if extend verificate
294 @retval EFI_SUCCESS The device was reset.
295 @retval EFI_DEVICE_ERROR The device is not functioning properly and could
297 @return EFI_STATUS is retured from EFI_SCSI_IO_PROTOCOL.ResetDevice().
303 IN EFI_BLOCK_IO_PROTOCOL
*This
,
304 IN BOOLEAN ExtendedVerification
309 The function is to Read Block from SCSI Disk.
311 @param This The pointer of EFI_BLOCK_IO_PROTOCOL.
312 @param MediaId The Id of Media detected
313 @param Lba The logic block address
314 @param BufferSize The size of Buffer
315 @param Buffer The buffer to fill the read out data
317 @retval EFI_SUCCESS Successfully to read out block.
318 @retval EFI_DEVICE_ERROR Fail to detect media.
319 @retval EFI_NO_MEDIA Media is not present.
320 @retval EFI_MEDIA_CHANGED Media has changed.
321 @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.
322 @retval EFI_INVALID_PARAMETER Invalid parameter passed in.
328 IN EFI_BLOCK_IO_PROTOCOL
*This
,
337 The function is to Write Block to SCSI Disk.
339 @param This The pointer of EFI_BLOCK_IO_PROTOCOL
340 @param MediaId The Id of Media detected
341 @param Lba The logic block address
342 @param BufferSize The size of Buffer
343 @param Buffer The buffer to fill the read out data
345 @retval EFI_SUCCESS Successfully to read out block.
346 @retval EFI_WRITE_PROTECTED The device can not be written to.
347 @retval EFI_DEVICE_ERROR Fail to detect media.
348 @retval EFI_NO_MEDIA Media is not present.
349 @retval EFI_MEDIA_CHNAGED Media has changed.
350 @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.
351 @retval EFI_INVALID_PARAMETER Invalid parameter passed in.
356 ScsiDiskWriteBlocks (
357 IN EFI_BLOCK_IO_PROTOCOL
*This
,
368 EFI_SUCCESS is returned directly.
370 @param This The pointer of EFI_BLOCK_IO_PROTOCOL
372 @retval EFI_SUCCESS All outstanding data was written to the device
377 ScsiDiskFlushBlocks (
378 IN EFI_BLOCK_IO_PROTOCOL
*This
382 Dectect Device and read out capacity ,if error occurs, parse the sense key.
384 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
385 @param MustReadCapacity The flag about reading device capacity
386 @param MediaChange The pointer of flag indicates if media has changed
388 @retval EFI_DEVICE_ERROR Indicates that error occurs
389 @retval EFI_SUCCESS Successfully to detect media
393 ScsiDiskDetectMedia (
394 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
395 IN BOOLEAN MustReadCapacity
,
396 OUT BOOLEAN
*MediaChange
402 When Test Unit Ready command succeeds, retrieve Sense Keys via Request Sense;
403 When Test Unit Ready command encounters any error caused by host adapter or
404 target, return error without retrieving Sense Keys.
406 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
407 @param NeedRetry The pointer of flag indicates try again
408 @param SenseDataArray The pointer of an array of sense data
409 @param NumberOfSenseKeys The pointer of the number of sense data array
411 @retval EFI_DEVICE_ERROR Indicates that error occurs
412 @retval EFI_SUCCESS Successfully to test unit
416 ScsiDiskTestUnitReady (
417 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
418 OUT BOOLEAN
*NeedRetry
,
419 OUT EFI_SCSI_SENSE_DATA
**SenseDataArray
,
420 OUT UINTN
*NumberOfSenseKeys
425 Parsing Sense Keys which got from request sense command.
427 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
428 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
429 @param NumberOfSenseKeys The number of sense key
430 @param Action The pointer of action which indicates what is need to do next
432 @retval EFI_DEVICE_ERROR Indicates that error occurs
433 @retval EFI_SUCCESS Successfully to complete the parsing
437 DetectMediaParsingSenseKeys (
438 OUT SCSI_DISK_DEV
*ScsiDiskDevice
,
439 IN EFI_SCSI_SENSE_DATA
*SenseData
,
440 IN UINTN NumberOfSenseKeys
,
446 Send read capacity command to device and get the device parameter.
448 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
449 @param NeedRetry The pointer of flag indicates if need a retry
450 @param SenseDataArray The pointer of an array of sense data
451 @param NumberOfSenseKeys The number of sense key
453 @retval EFI_DEVICE_ERROR Indicates that error occurs
454 @retval EFI_SUCCESS Successfully to read capacity
458 ScsiDiskReadCapacity (
459 IN OUT SCSI_DISK_DEV
*ScsiDiskDevice
,
460 OUT BOOLEAN
*NeedRetry
,
461 OUT EFI_SCSI_SENSE_DATA
**SenseDataArray
,
462 OUT UINTN
*NumberOfSenseKeys
466 Check the HostAdapter status and re-interpret it in EFI_STATUS.
468 @param HostAdapterStatus Host Adapter status
470 @retval EFI_SUCCESS Host adapter is OK.
471 @retval EFI_TIMEOUT Timeout.
472 @retval EFI_NOT_READY Adapter NOT ready.
473 @retval EFI_DEVICE_ERROR Adapter device error.
477 CheckHostAdapterStatus (
478 IN UINT8 HostAdapterStatus
483 Check the target status and re-interpret it in EFI_STATUS.
485 @param TargetStatus Target status
487 @retval EFI_NOT_READY Device is NOT ready.
488 @retval EFI_DEVICE_ERROR
494 IN UINT8 TargetStatus
498 Retrieve all sense keys from the device.
500 When encountering error during the process, if retrieve sense keys before
501 error encounterred, it returns the sense keys with return status set to EFI_SUCCESS,
502 and NeedRetry set to FALSE; otherwize, return the proper return status.
504 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
505 @param NeedRetry The pointer of flag indicates if need a retry
506 @param SenseDataArray The pointer of an array of sense data
507 @param NumberOfSenseKeys The number of sense key
508 @param AskResetIfError The flag indicates if need reset when error occurs
510 @retval EFI_DEVICE_ERROR Indicates that error occurs
511 @retval EFI_SUCCESS Successfully to request sense key
515 ScsiDiskRequestSenseKeys (
516 IN OUT SCSI_DISK_DEV
*ScsiDiskDevice
,
517 OUT BOOLEAN
*NeedRetry
,
518 OUT EFI_SCSI_SENSE_DATA
**SenseDataArray
,
519 OUT UINTN
*NumberOfSenseKeys
,
520 IN BOOLEAN AskResetIfError
524 Send out Inquiry command to Device.
526 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
527 @param NeedRetry Indicates if needs try again when error happens
529 @retval EFI_DEVICE_ERROR Indicates that error occurs
530 @retval EFI_SUCCESS Successfully to detect media
534 ScsiDiskInquiryDevice (
535 IN OUT SCSI_DISK_DEV
*ScsiDiskDevice
,
536 OUT BOOLEAN
*NeedRetry
542 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
547 IN OUT SCSI_DISK_DEV
*ScsiDiskDevice
551 Read sector from SCSI Disk.
553 @param ScsiDiskDevice The poiniter of SCSI_DISK_DEV
554 @param Buffer The buffer to fill in the read out data
555 @param Lba Logic block address
556 @param NumberOfBlocks The number of blocks to read
558 @retval EFI_DEVICE_ERROR Indicates a device error.
559 @retval EFI_SUCCESS Operation is successful.
563 ScsiDiskReadSectors (
564 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
567 IN UINTN NumberOfBlocks
571 Write sector to SCSI Disk.
573 @param ScsiDiskDevice The poiniter of SCSI_DISK_DEV
574 @param Buffer The buffer of data to be written into SCSI Disk
575 @param Lba Logic block address
576 @param NumberOfBlocks The number of blocks to read
578 @retval EFI_DEVICE_ERROR Indicates a device error.
579 @retval EFI_SUCCESS Operation is successful.
583 ScsiDiskWriteSectors (
584 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
587 IN UINTN NumberOfBlocks
591 Sumbmit Read command.
593 @param ScsiDiskDevice The pointer of ScsiDiskDevice
594 @param NeedRetry The pointer of flag indicates if needs retry if error happens
595 @param SenseDataArray NOT used yet in this function
596 @param NumberOfSenseKeys The number of sense key
597 @param Timeout The time to complete the command
598 @param DataBuffer The buffer to fill with the read out data
599 @param DataLength The length of buffer
600 @param StartLba The start logic block address
601 @param SectorSize The size of sector
603 @return EFI_STATUS is returned by calling ScsiRead10Command().
607 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
608 OUT BOOLEAN
*NeedRetry
,
609 OUT EFI_SCSI_SENSE_DATA
**SenseDataArray
, OPTIONAL
610 OUT UINTN
*NumberOfSenseKeys
,
612 OUT UINT8
*DataBuffer
,
613 IN OUT UINT32
*DataLength
,
619 Submit Write Command.
621 @param ScsiDiskDevice The pointer of ScsiDiskDevice
622 @param NeedRetry The pointer of flag indicates if needs retry if error happens
623 @param SenseDataArray NOT used yet in this function
624 @param NumberOfSenseKeys The number of sense key
625 @param Timeout The time to complete the command
626 @param DataBuffer The buffer to fill with the read out data
627 @param DataLength The length of buffer
628 @param StartLba The start logic block address
629 @param SectorSize The size of sector
631 @return EFI_STATUS is returned by calling ScsiWrite10Command().
636 IN SCSI_DISK_DEV
*ScsiDiskDevice
,
637 OUT BOOLEAN
*NeedRetry
,
638 OUT EFI_SCSI_SENSE_DATA
**SenseDataArray
, OPTIONAL
639 OUT UINTN
*NumberOfSenseKeys
,
641 IN UINT8
*DataBuffer
,
642 IN OUT UINT32
*DataLength
,
648 Get information from media read capacity command.
650 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
651 @param Capacity The pointer of EFI_SCSI_DISK_CAPACITY_DATA
656 IN OUT SCSI_DISK_DEV
*ScsiDiskDevice
,
657 IN EFI_SCSI_DISK_CAPACITY_DATA
*Capacity
661 Check sense key to find if media presents.
663 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
664 @param SenseCounts The number of sense key
666 @retval TRUE NOT any media
667 @retval FALSE Media presents
671 IN EFI_SCSI_SENSE_DATA
*SenseData
,
678 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
679 @param SenseCounts The number of sense key
682 @retval FALSE NOT error
686 ScsiDiskIsMediaError (
687 IN EFI_SCSI_SENSE_DATA
*SenseData
,
692 Check sense key to find if hardware error happens.
694 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
695 @param SenseCounts The number of sense key
697 @retval TRUE Hardware error exits.
698 @retval FALSE NO error.
702 ScsiDiskIsHardwareError (
703 IN EFI_SCSI_SENSE_DATA
*SenseData
,
708 Check sense key to find if media has changed.
710 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
711 @param SenseCounts The number of sense key
713 @retval TRUE Media is changed.
714 @retval FALSE Medit is NOT changed.
717 ScsiDiskIsMediaChange (
718 IN EFI_SCSI_SENSE_DATA
*SenseData
,
723 Check sense key to find if reset happens.
725 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
726 @param SenseCounts The number of sense key
728 @retval TRUE It is reset before.
729 @retval FALSE It is NOT reset before.
733 ScsiDiskIsResetBefore (
734 IN EFI_SCSI_SENSE_DATA
*SenseData
,
739 Check sense key to find if the drive is ready.
741 @param SenseData The pointer of EFI_SCSI_SENSE_DATA
742 @param SenseCounts The number of sense key
743 @param RetryLater The flag means if need a retry
745 @retval TRUE Drive is ready.
746 @retval FALSE Drive is NOT ready.
750 ScsiDiskIsDriveReady (
751 IN EFI_SCSI_SENSE_DATA
*SenseData
,
752 IN UINTN SenseCounts
,
753 OUT BOOLEAN
*RetryLater
757 Check sense key to find if it has sense key.
759 @param SenseData - The pointer of EFI_SCSI_SENSE_DATA
760 @param SenseCounts - The number of sense key
762 @retval TRUE It has sense key.
763 @retval FALSE It has NOT any sense key.
767 ScsiDiskHaveSenseKey (
768 IN EFI_SCSI_SENSE_DATA
*SenseData
,
773 Release resource about disk device.
775 @param ScsiDiskDevice The pointer of SCSI_DISK_DEV
779 ReleaseScsiDiskDeviceResources (
780 IN SCSI_DISK_DEV
*ScsiDiskDevice