1 /** @file 2 Header file for SCSI Bus Driver. 3 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 9 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. 12 13 **/ 14 15 #ifndef _SCSI_BUS_H_ 16 #define _SCSI_BUS_H_ 17 18 19 #include <Uefi.h> 20 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> 27 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> 37 38 #include <IndustryStandard/Scsi.h> 39 40 #define SCSI_IO_DEV_SIGNATURE SIGNATURE_32 ('s', 'c', 'i', 'o') 41 42 typedef union { 43 UINT32 Scsi; 44 UINT8 ExtScsi[4]; 45 } SCSI_ID; 46 47 typedef struct _SCSI_TARGET_ID { 48 SCSI_ID ScsiId; 49 UINT8 ExtScsiId[12]; 50 }SCSI_TARGET_ID; 51 52 53 typedef struct { 54 VOID *Data1; 55 VOID *Data2; 56 } SCSI_EVENT_DATA; 57 58 // 59 // SCSI Bus Controller device strcuture 60 // 61 #define SCSI_BUS_DEVICE_SIGNATURE SIGNATURE_32 ('s', 'c', 's', 'i') 62 63 // 64 // SCSI Bus Timeout Experience Value 65 // 66 #define SCSI_BUS_TIMEOUT EFI_TIMER_PERIOD_SECONDS (3) 67 68 // 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. 74 // 75 typedef struct _EFI_SCSI_BUS_PROTOCOL { 76 UINT64 Reserved; 77 } EFI_SCSI_BUS_PROTOCOL; 78 79 typedef struct _SCSI_BUS_DEVICE { 80 UINTN Signature; 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; 86 } SCSI_BUS_DEVICE; 87 88 #define SCSI_BUS_CONTROLLER_DEVICE_FROM_THIS(a) CR (a, SCSI_BUS_DEVICE, BusIdentify, SCSI_BUS_DEVICE_SIGNATURE) 89 90 typedef struct { 91 UINT32 Signature; 92 EFI_HANDLE Handle; 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; 99 SCSI_TARGET_ID Pun; 100 UINT64 Lun; 101 UINT8 ScsiDeviceType; 102 UINT8 ScsiVersion; 103 BOOLEAN RemovableDevice; 104 } SCSI_IO_DEV; 105 106 #define SCSI_IO_DEV_FROM_THIS(a) CR (a, SCSI_IO_DEV, ScsiIo, SCSI_IO_DEV_SIGNATURE) 107 108 // 109 // Global Variables 110 // 111 extern EFI_DRIVER_BINDING_PROTOCOL gScsiBusDriverBinding; 112 extern EFI_COMPONENT_NAME_PROTOCOL gScsiBusComponentName; 113 extern EFI_COMPONENT_NAME2_PROTOCOL gScsiBusComponentName2; 114 115 /** 116 Test to see if this driver supports ControllerHandle. 117 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 122 restrictions. 123 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 127 device to start. 128 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 132 133 **/ 134 EFI_STATUS 135 EFIAPI 136 SCSIBusDriverBindingSupported ( 137 IN EFI_DRIVER_BINDING_PROTOCOL *This, 138 IN EFI_HANDLE Controller, 139 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 140 ); 141 142 /** 143 Start this driver on ControllerHandle. 144 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 149 restrictions. 150 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 154 device to start. 155 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 159 160 **/ 161 EFI_STATUS 162 EFIAPI 163 SCSIBusDriverBindingStart ( 164 IN EFI_DRIVER_BINDING_PROTOCOL *This, 165 IN EFI_HANDLE Controller, 166 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 167 ); 168 169 /** 170 Stop this driver on ControllerHandle. 171 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. 177 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. 183 184 @retval EFI_SUCCESS This driver is removed ControllerHandle 185 @retval other This driver was not removed from this device 186 187 **/ 188 EFI_STATUS 189 EFIAPI 190 SCSIBusDriverBindingStop ( 191 IN EFI_DRIVER_BINDING_PROTOCOL *This, 192 IN EFI_HANDLE Controller, 193 IN UINTN NumberOfChildren, 194 IN EFI_HANDLE *ChildHandleBuffer 195 ); 196 197 // 198 // EFI Component Name Functions 199 // 200 /** 201 Retrieves a Unicode string that is the user readable name of the driver. 202 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. 209 210 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 211 EFI_COMPONENT_NAME_PROTOCOL instance. 212 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. 221 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. 226 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. 230 231 @retval EFI_INVALID_PARAMETER Language is NULL. 232 233 @retval EFI_INVALID_PARAMETER DriverName is NULL. 234 235 @retval EFI_UNSUPPORTED The driver specified by This does not support 236 the language specified by Language. 237 238 **/ 239 EFI_STATUS 240 EFIAPI 241 ScsiBusComponentNameGetDriverName ( 242 IN EFI_COMPONENT_NAME_PROTOCOL *This, 243 IN CHAR8 *Language, 244 OUT CHAR16 **DriverName 245 ); 246 247 /** 248 Retrieves a Unicode string that is the user readable name of the controller 249 that is being managed by a driver. 250 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. 259 260 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 261 EFI_COMPONENT_NAME_PROTOCOL instance. 262 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 266 returned. 267 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 275 child controller. 276 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. 285 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 291 specified by This. 292 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 296 DriverName. 297 298 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 299 300 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 301 EFI_HANDLE. 302 303 @retval EFI_INVALID_PARAMETER Language is NULL. 304 305 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 306 307 @retval EFI_UNSUPPORTED The driver specified by This is not currently 308 managing the controller specified by 309 ControllerHandle and ChildHandle. 310 311 @retval EFI_UNSUPPORTED The driver specified by This does not support 312 the language specified by Language. 313 314 **/ 315 EFI_STATUS 316 EFIAPI 317 ScsiBusComponentNameGetControllerName ( 318 IN EFI_COMPONENT_NAME_PROTOCOL *This, 319 IN EFI_HANDLE ControllerHandle, 320 IN EFI_HANDLE ChildHandle OPTIONAL, 321 IN CHAR8 *Language, 322 OUT CHAR16 **ControllerName 323 ); 324 325 /** 326 Retrieves the device type information of the SCSI Controller. 327 328 @param This Protocol instance pointer. 329 @param DeviceType A pointer to the device type information retrieved from 330 the SCSI Controller. 331 332 @retval EFI_SUCCESS Retrieves the device type information successfully. 333 @retval EFI_INVALID_PARAMETER The DeviceType is NULL. 334 335 **/ 336 EFI_STATUS 337 EFIAPI 338 ScsiGetDeviceType ( 339 IN EFI_SCSI_IO_PROTOCOL *This, 340 OUT UINT8 *DeviceType 341 ); 342 343 /** 344 Retrieves the device location in the SCSI channel. 345 346 @param This Protocol instance pointer. 347 @param Target A pointer to the Target ID of a SCSI device 348 on the SCSI channel. 349 @param Lun A pointer to the LUN of the SCSI device on 350 the SCSI channel. 351 352 @retval EFI_SUCCESS Retrieves the device location successfully. 353 @retval EFI_INVALID_PARAMETER The Target or Lun is NULL. 354 355 **/ 356 EFI_STATUS 357 EFIAPI 358 ScsiGetDeviceLocation ( 359 IN EFI_SCSI_IO_PROTOCOL *This, 360 IN OUT UINT8 **Target, 361 OUT UINT64 *Lun 362 ); 363 364 /** 365 Resets the SCSI Bus that the SCSI Controller is attached to. 366 367 @param This Protocol instance pointer. 368 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 374 the SCSI bus. 375 **/ 376 EFI_STATUS 377 EFIAPI 378 ScsiResetBus ( 379 IN EFI_SCSI_IO_PROTOCOL *This 380 ); 381 382 /** 383 Resets the SCSI Controller that the device handle specifies. 384 385 @param This Protocol instance pointer. 386 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 391 SCSI Controller. 392 **/ 393 EFI_STATUS 394 EFIAPI 395 ScsiResetDevice ( 396 IN EFI_SCSI_IO_PROTOCOL *This 397 ); 398 399 /** 400 Sends a SCSI Request Packet to the SCSI Controller for execution. 401 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 412 Packet completes. 413 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 440 available. 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. 445 **/ 446 EFI_STATUS 447 EFIAPI 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 452 ); 453 454 /** 455 Scan SCSI Bus to discover the device, and attach ScsiIoProtocol to it. 456 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 462 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. 466 467 **/ 468 EFI_STATUS 469 EFIAPI 470 ScsiScanCreateDevice ( 471 IN EFI_DRIVER_BINDING_PROTOCOL *This, 472 IN EFI_HANDLE Controller, 473 IN SCSI_TARGET_ID *TargetId, 474 IN UINT64 Lun, 475 IN OUT SCSI_BUS_DEVICE *ScsiBusDev 476 ); 477 478 /** 479 Discovery SCSI Device 480 481 @param ScsiIoDevice The pointer of SCSI_IO_DEV 482 483 @retval TRUE Find SCSI Device and verify it. 484 @retval FALSE Unable to find SCSI Device. 485 486 **/ 487 BOOLEAN 488 DiscoverScsiDevice ( 489 IN OUT SCSI_IO_DEV *ScsiIoDevice 490 ); 491 492 #endif 493