2 Header file for SCSI Bus Driver.
4 Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
5 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.
21 #include <Protocol/ScsiPassThru.h>
22 #include <Protocol/ScsiPassThruExt.h>
23 #include <Protocol/ScsiIo.h>
24 #include <Protocol/ComponentName.h>
25 #include <Protocol/DriverBinding.h>
26 #include <Protocol/DevicePath.h>
28 #include <Library/DebugLib.h>
29 #include <Library/UefiDriverEntryPoint.h>
30 #include <Library/UefiLib.h>
31 #include <Library/BaseMemoryLib.h>
32 #include <Library/MemoryAllocationLib.h>
33 #include <Library/UefiScsiLib.h>
34 #include <Library/UefiBootServicesTableLib.h>
35 #include <Library/DevicePathLib.h>
36 #include <Library/ReportStatusCodeLib.h>
38 #include <IndustryStandard/Scsi.h>
40 #define SCSI_IO_DEV_SIGNATURE SIGNATURE_32 ('s', 'c', 'i', 'o')
47 typedef struct _SCSI_TARGET_ID
{
59 // SCSI Bus Controller device strcuture
61 #define SCSI_BUS_DEVICE_SIGNATURE SIGNATURE_32 ('s', 'c', 's', 'i')
64 // SCSI Bus Timeout Experience Value
66 #define SCSI_BUS_TIMEOUT EFI_TIMER_PERIOD_SECONDS (3)
69 // The ScsiBusProtocol is just used to locate ScsiBusDev
70 // structure in the SCSIBusDriverBindingStop(). Then we can
71 // Close all opened protocols and release this structure.
72 // ScsiBusProtocol is the private protocol.
73 // gEfiCallerIdGuid will be used as its protocol guid.
75 typedef struct _EFI_SCSI_BUS_PROTOCOL
{
77 } EFI_SCSI_BUS_PROTOCOL
;
79 typedef struct _SCSI_BUS_DEVICE
{
81 EFI_SCSI_BUS_PROTOCOL BusIdentify
;
82 BOOLEAN ExtScsiSupport
;
83 EFI_SCSI_PASS_THRU_PROTOCOL
*ScsiInterface
;
84 EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*ExtScsiInterface
;
85 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
88 #define SCSI_BUS_CONTROLLER_DEVICE_FROM_THIS(a) CR (a, SCSI_BUS_DEVICE, BusIdentify, SCSI_BUS_DEVICE_SIGNATURE)
93 EFI_SCSI_IO_PROTOCOL ScsiIo
;
94 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
95 BOOLEAN ExtScsiSupport
;
96 EFI_SCSI_PASS_THRU_PROTOCOL
*ScsiPassThru
;
97 EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*ExtScsiPassThru
;
98 SCSI_BUS_DEVICE
*ScsiBusDeviceData
;
101 UINT8 ScsiDeviceType
;
103 BOOLEAN RemovableDevice
;
106 #define SCSI_IO_DEV_FROM_THIS(a) CR (a, SCSI_IO_DEV, ScsiIo, SCSI_IO_DEV_SIGNATURE)
111 extern EFI_DRIVER_BINDING_PROTOCOL gScsiBusDriverBinding
;
112 extern EFI_COMPONENT_NAME_PROTOCOL gScsiBusComponentName
;
113 extern EFI_COMPONENT_NAME2_PROTOCOL gScsiBusComponentName2
;
116 Test to see if this driver supports ControllerHandle.
118 This service is called by the EFI boot service ConnectController(). In order
119 to make drivers as small as possible, there are a few calling restrictions for
120 this service. ConnectController() must follow these calling restrictions. If
121 any other agent wishes to call Supported() it must also follow these calling
124 @param This Protocol instance pointer.
125 @param ControllerHandle Handle of device to test
126 @param RemainingDevicePath Optional parameter use to pick a specific child
129 @retval EFI_SUCCESS This driver supports this device
130 @retval EFI_ALREADY_STARTED This driver is already running on this device
131 @retval other This driver does not support this device
136 SCSIBusDriverBindingSupported (
137 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
138 IN EFI_HANDLE Controller
,
139 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
143 Start this driver on ControllerHandle.
145 This service is called by the EFI boot service ConnectController(). In order
146 to make drivers as small as possible, there are a few calling restrictions for
147 this service. ConnectController() must follow these calling restrictions. If
148 any other agent wishes to call Start() it must also follow these calling
151 @param This Protocol instance pointer.
152 @param ControllerHandle Handle of device to bind driver to
153 @param RemainingDevicePath Optional parameter use to pick a specific child
156 @retval EFI_SUCCESS This driver is added to ControllerHandle
157 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
158 @retval other This driver does not support this device
163 SCSIBusDriverBindingStart (
164 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
165 IN EFI_HANDLE Controller
,
166 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
170 Stop this driver on ControllerHandle.
172 This service is called by the EFI boot service DisconnectController().
173 In order to make drivers as small as possible, there are a few calling
174 restrictions for this service. DisconnectController() must follow these
175 calling restrictions. If any other agent wishes to call Stop() it must also
176 follow these calling restrictions.
178 @param This Protocol instance pointer.
179 @param ControllerHandle Handle of device to stop driver on
180 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
181 children is zero stop the entire bus driver.
182 @param ChildHandleBuffer List of Child Handles to Stop.
184 @retval EFI_SUCCESS This driver is removed ControllerHandle
185 @retval other This driver was not removed from this device
190 SCSIBusDriverBindingStop (
191 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
192 IN EFI_HANDLE Controller
,
193 IN UINTN NumberOfChildren
,
194 IN EFI_HANDLE
*ChildHandleBuffer
198 // EFI Component Name Functions
201 Retrieves a Unicode string that is the user readable name of the driver.
203 This function retrieves the user readable name of a driver in the form of a
204 Unicode string. If the driver specified by This has a user readable name in
205 the language specified by Language, then a pointer to the driver name is
206 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
207 by This does not support the language specified by Language,
208 then EFI_UNSUPPORTED is returned.
210 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
211 EFI_COMPONENT_NAME_PROTOCOL instance.
213 @param Language A pointer to a Null-terminated ASCII string
214 array indicating the language. This is the
215 language of the driver name that the caller is
216 requesting, and it must match one of the
217 languages specified in SupportedLanguages. The
218 number of languages supported by a driver is up
219 to the driver writer. Language is specified
220 in RFC 4646 or ISO 639-2 language code format.
222 @param DriverName A pointer to the Unicode string to return.
223 This Unicode string is the name of the
224 driver specified by This in the language
225 specified by Language.
227 @retval EFI_SUCCESS The Unicode string for the Driver specified by
228 This and the language specified by Language was
229 returned in DriverName.
231 @retval EFI_INVALID_PARAMETER Language is NULL.
233 @retval EFI_INVALID_PARAMETER DriverName is NULL.
235 @retval EFI_UNSUPPORTED The driver specified by This does not support
236 the language specified by Language.
241 ScsiBusComponentNameGetDriverName (
242 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
244 OUT CHAR16
**DriverName
248 Retrieves a Unicode string that is the user readable name of the controller
249 that is being managed by a driver.
251 This function retrieves the user readable name of the controller specified by
252 ControllerHandle and ChildHandle in the form of a Unicode string. If the
253 driver specified by This has a user readable name in the language specified by
254 Language, then a pointer to the controller name is returned in ControllerName,
255 and EFI_SUCCESS is returned. If the driver specified by This is not currently
256 managing the controller specified by ControllerHandle and ChildHandle,
257 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
258 support the language specified by Language, then EFI_UNSUPPORTED is returned.
260 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
261 EFI_COMPONENT_NAME_PROTOCOL instance.
263 @param ControllerHandle The handle of a controller that the driver
264 specified by This is managing. This handle
265 specifies the controller whose name is to be
268 @param ChildHandle The handle of the child controller to retrieve
269 the name of. This is an optional parameter that
270 may be NULL. It will be NULL for device
271 drivers. It will also be NULL for a bus drivers
272 that wish to retrieve the name of the bus
273 controller. It will not be NULL for a bus
274 driver that wishes to retrieve the name of a
277 @param Language A pointer to a Null-terminated ASCII string
278 array indicating the language. This is the
279 language of the driver name that the caller is
280 requesting, and it must match one of the
281 languages specified in SupportedLanguages. The
282 number of languages supported by a driver is up
283 to the driver writer. Language is specified in
284 RFC 4646 or ISO 639-2 language code format.
286 @param ControllerName A pointer to the Unicode string to return.
287 This Unicode string is the name of the
288 controller specified by ControllerHandle and
289 ChildHandle in the language specified by
290 Language from the point of view of the driver
293 @retval EFI_SUCCESS The Unicode string for the user readable name in
294 the language specified by Language for the
295 driver specified by This was returned in
298 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
300 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
303 @retval EFI_INVALID_PARAMETER Language is NULL.
305 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
307 @retval EFI_UNSUPPORTED The driver specified by This is not currently
308 managing the controller specified by
309 ControllerHandle and ChildHandle.
311 @retval EFI_UNSUPPORTED The driver specified by This does not support
312 the language specified by Language.
317 ScsiBusComponentNameGetControllerName (
318 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
319 IN EFI_HANDLE ControllerHandle
,
320 IN EFI_HANDLE ChildHandle OPTIONAL
,
322 OUT CHAR16
**ControllerName
326 Retrieves the device type information of the SCSI Controller.
328 @param This Protocol instance pointer.
329 @param DeviceType A pointer to the device type information retrieved from
332 @retval EFI_SUCCESS Retrieves the device type information successfully.
333 @retval EFI_INVALID_PARAMETER The DeviceType is NULL.
339 IN EFI_SCSI_IO_PROTOCOL
*This
,
340 OUT UINT8
*DeviceType
344 Retrieves the device location in the SCSI channel.
346 @param This Protocol instance pointer.
347 @param Target A pointer to the Target ID of a SCSI device
349 @param Lun A pointer to the LUN of the SCSI device on
352 @retval EFI_SUCCESS Retrieves the device location successfully.
353 @retval EFI_INVALID_PARAMETER The Target or Lun is NULL.
358 ScsiGetDeviceLocation (
359 IN EFI_SCSI_IO_PROTOCOL
*This
,
360 IN OUT UINT8
**Target
,
365 Resets the SCSI Bus that the SCSI Controller is attached to.
367 @param This Protocol instance pointer.
369 @retval EFI_SUCCESS The SCSI bus is reset successfully.
370 @retval EFI_DEVICE_ERROR Errors encountered when resetting the SCSI bus.
371 @retval EFI_UNSUPPORTED The bus reset operation is not supported by the
372 SCSI Host Controller.
373 @retval EFI_TIMEOUT A timeout occurred while attempting to reset
379 IN EFI_SCSI_IO_PROTOCOL
*This
383 Resets the SCSI Controller that the device handle specifies.
385 @param This Protocol instance pointer.
387 @retval EFI_SUCCESS Reset the SCSI controller successfully.
388 @retval EFI_DEVICE_ERROR Errors are encountered when resetting the SCSI Controller.
389 @retval EFI_UNSUPPORTED The SCSI bus does not support a device reset operation.
390 @retval EFI_TIMEOUT A timeout occurred while attempting to reset the
396 IN EFI_SCSI_IO_PROTOCOL
*This
400 Sends a SCSI Request Packet to the SCSI Controller for execution.
402 @param This Protocol instance pointer.
403 @param CommandPacket The SCSI request packet to send to the SCSI
404 Controller specified by the device handle.
405 @param Event If the SCSI bus where the SCSI device is attached
406 does not support non-blocking I/O, then Event is
407 ignored, and blocking I/O is performed.
408 If Event is NULL, then blocking I/O is performed.
409 If Event is not NULL and non-blocking I/O is
410 supported, then non-blocking I/O is performed,
411 and Event will be signaled when the SCSI Request
414 @retval EFI_SUCCESS The SCSI Request Packet was sent by the host
415 successfully, and TransferLength bytes were
416 transferred to/from DataBuffer.See
417 HostAdapterStatus, TargetStatus,
418 SenseDataLength, and SenseData in that order
419 for additional status information.
420 @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed,
421 but the entire DataBuffer could not be transferred.
422 The actual number of bytes transferred is returned
423 in TransferLength. See HostAdapterStatus,
424 TargetStatus, SenseDataLength, and SenseData in
425 that order for additional status information.
426 @retval EFI_NOT_READY The SCSI Request Packet could not be sent because
427 there are too many SCSI Command Packets already
428 queued.The caller may retry again later.
429 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send
430 the SCSI Request Packet. See HostAdapterStatus,
431 TargetStatus, SenseDataLength, and SenseData in
432 that order for additional status information.
433 @retval EFI_INVALID_PARAMETER The contents of CommandPacket are invalid.
434 The SCSI Request Packet was not sent, so no
435 additional status information is available.
436 @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet
437 is not supported by the SCSI initiator(i.e., SCSI
438 Host Controller). The SCSI Request Packet was not
439 sent, so no additional status information is
441 @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI
442 Request Packet to execute. See HostAdapterStatus,
443 TargetStatus, SenseDataLength, and SenseData in
444 that order for additional status information.
448 ScsiExecuteSCSICommand (
449 IN EFI_SCSI_IO_PROTOCOL
*This
,
450 IN OUT EFI_SCSI_IO_SCSI_REQUEST_PACKET
*CommandPacket
,
451 IN EFI_EVENT Event OPTIONAL
455 Scan SCSI Bus to discover the device, and attach ScsiIoProtocol to it.
457 @param This Protocol instance pointer
458 @param Controller Controller handle
459 @param TargetId Tartget to be scanned
460 @param Lun The Lun of the SCSI device on the SCSI channel.
461 @param ScsiBusDev The pointer of SCSI_BUS_DEVICE
463 @retval EFI_SUCCESS Successfully to discover the device and attach
464 ScsiIoProtocol to it.
465 @retval EFI_OUT_OF_RESOURCES Fail to discover the device.
470 ScsiScanCreateDevice (
471 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
472 IN EFI_HANDLE Controller
,
473 IN SCSI_TARGET_ID
*TargetId
,
475 IN OUT SCSI_BUS_DEVICE
*ScsiBusDev
479 Discovery SCSI Device
481 @param ScsiIoDevice The pointer of SCSI_IO_DEV
483 @retval TRUE Find SCSI Device and verify it.
484 @retval FALSE Unable to find SCSI Device.
489 IN OUT SCSI_IO_DEV
*ScsiIoDevice