ScsiBus.h revision f3f2e05db8c89628498ec4efdb16184747824c63
1/** @file 2 Header file for SCSI Bus Driver. 3 4Copyright (c) 2006 - 2008, Intel Corporation. <BR> 5All rights reserved. This program and the accompanying materials 6are licensed and made available under the terms and conditions of the BSD License 7which accompanies this distribution. The full text of the license may be found at 8http://opensource.org/licenses/bsd-license.php 9 10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11WITHOUT 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 37#include <IndustryStandard/Scsi.h> 38 39#define SCSI_IO_DEV_SIGNATURE SIGNATURE_32 ('s', 'c', 'i', 'o') 40 41typedef struct _SCSI_TARGET_ID { 42 union { 43 UINT32 Scsi; 44 UINT8 ExtScsi[4]; 45 } ScsiId; 46 UINT8 ExtScsiId[12]; 47}SCSI_TARGET_ID; 48 49 50typedef struct { 51 VOID *Data1; 52 VOID *Data2; 53} SCSI_EVENT_DATA; 54 55 56typedef struct { 57 UINT32 Signature; 58 EFI_HANDLE Handle; 59 EFI_SCSI_IO_PROTOCOL ScsiIo; 60 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 61 BOOLEAN ExtScsiSupport; 62 EFI_SCSI_PASS_THRU_PROTOCOL *ScsiPassThru; 63 EFI_EXT_SCSI_PASS_THRU_PROTOCOL *ExtScsiPassThru; 64 SCSI_TARGET_ID Pun; 65 UINT64 Lun; 66 UINT8 ScsiDeviceType; 67 UINT8 ScsiVersion; 68 BOOLEAN RemovableDevice; 69} SCSI_IO_DEV; 70 71#define SCSI_IO_DEV_FROM_THIS(a) CR (a, SCSI_IO_DEV, ScsiIo, SCSI_IO_DEV_SIGNATURE) 72 73// 74// SCSI Bus Controller device strcuture 75// 76#define EFI_SCSI_BUS_PROTOCOL_GUID \ 77 { \ 78 0x5261213D, 0x3A3D, 0x441E, {0xB3, 0xAF, 0x21, 0xD3, 0xF7, 0xA4, 0xCA, 0x17} \ 79 } 80 81typedef struct _EFI_SCSI_BUS_PROTOCOL { 82 UINT64 Reserved; 83} EFI_SCSI_BUS_PROTOCOL; 84 85#define SCSI_BUS_DEVICE_SIGNATURE SIGNATURE_32 ('s', 'c', 's', 'i') 86 87 88typedef struct _SCSI_BUS_DEVICE { 89 UINTN Signature; 90 EFI_SCSI_BUS_PROTOCOL BusIdentify; 91 BOOLEAN ExtScsiSupport; 92 EFI_SCSI_PASS_THRU_PROTOCOL *ScsiInterface; 93 EFI_EXT_SCSI_PASS_THRU_PROTOCOL *ExtScsiInterface; 94 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 95} SCSI_BUS_DEVICE; 96 97#define SCSI_BUS_CONTROLLER_DEVICE_FROM_THIS(a) CR (a, SCSI_BUS_DEVICE, BusIdentify, SCSI_BUS_DEVICE_SIGNATURE) 98 99// 100// Global Variables 101// 102extern EFI_DRIVER_BINDING_PROTOCOL gScsiBusDriverBinding; 103extern EFI_COMPONENT_NAME_PROTOCOL gScsiBusComponentName; 104extern EFI_COMPONENT_NAME2_PROTOCOL gScsiBusComponentName2; 105 106/** 107 Test to see if this driver supports ControllerHandle. 108 109 This service is called by the EFI boot service ConnectController(). In order 110 to make drivers as small as possible, there are a few calling restrictions for 111 this service. ConnectController() must follow these calling restrictions. If 112 any other agent wishes to call Supported() it must also follow these calling 113 restrictions. 114 115 @param This Protocol instance pointer. 116 @param ControllerHandle Handle of device to test 117 @param RemainingDevicePath Optional parameter use to pick a specific child 118 device to start. 119 120 @retval EFI_SUCCESS This driver supports this device 121 @retval EFI_ALREADY_STARTED This driver is already running on this device 122 @retval other This driver does not support this device 123 124**/ 125EFI_STATUS 126EFIAPI 127SCSIBusDriverBindingSupported ( 128 IN EFI_DRIVER_BINDING_PROTOCOL *This, 129 IN EFI_HANDLE Controller, 130 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 131 ); 132 133/** 134 Start this driver on ControllerHandle. 135 136 This service is called by the EFI boot service ConnectController(). In order 137 to make drivers as small as possible, there are a few calling restrictions for 138 this service. ConnectController() must follow these calling restrictions. If 139 any other agent wishes to call Start() it must also follow these calling 140 restrictions. 141 142 @param This Protocol instance pointer. 143 @param ControllerHandle Handle of device to bind driver to 144 @param RemainingDevicePath Optional parameter use to pick a specific child 145 device to start. 146 147 @retval EFI_SUCCESS This driver is added to ControllerHandle 148 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle 149 @retval other This driver does not support this device 150 151**/ 152EFI_STATUS 153EFIAPI 154SCSIBusDriverBindingStart ( 155 IN EFI_DRIVER_BINDING_PROTOCOL *This, 156 IN EFI_HANDLE Controller, 157 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 158 ); 159 160/** 161 Stop this driver on ControllerHandle. 162 163 This service is called by the EFI boot service DisconnectController(). 164 In order to make drivers as small as possible, there are a few calling 165 restrictions for this service. DisconnectController() must follow these 166 calling restrictions. If any other agent wishes to call Stop() it must also 167 follow these calling restrictions. 168 169 @param This Protocol instance pointer. 170 @param ControllerHandle Handle of device to stop driver on 171 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of 172 children is zero stop the entire bus driver. 173 @param ChildHandleBuffer List of Child Handles to Stop. 174 175 @retval EFI_SUCCESS This driver is removed ControllerHandle 176 @retval other This driver was not removed from this device 177 178**/ 179EFI_STATUS 180EFIAPI 181SCSIBusDriverBindingStop ( 182 IN EFI_DRIVER_BINDING_PROTOCOL *This, 183 IN EFI_HANDLE Controller, 184 IN UINTN NumberOfChildren, 185 IN EFI_HANDLE *ChildHandleBuffer 186 ); 187 188// 189// EFI Component Name Functions 190// 191/** 192 Retrieves a Unicode string that is the user readable name of the driver. 193 194 This function retrieves the user readable name of a driver in the form of a 195 Unicode string. If the driver specified by This has a user readable name in 196 the language specified by Language, then a pointer to the driver name is 197 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 198 by This does not support the language specified by Language, 199 then EFI_UNSUPPORTED is returned. 200 201 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 202 EFI_COMPONENT_NAME_PROTOCOL instance. 203 204 @param Language A pointer to a Null-terminated ASCII string 205 array indicating the language. This is the 206 language of the driver name that the caller is 207 requesting, and it must match one of the 208 languages specified in SupportedLanguages. The 209 number of languages supported by a driver is up 210 to the driver writer. Language is specified 211 in RFC 3066 or ISO 639-2 language code format. 212 213 @param DriverName A pointer to the Unicode string to return. 214 This Unicode string is the name of the 215 driver specified by This in the language 216 specified by Language. 217 218 @retval EFI_SUCCESS The Unicode string for the Driver specified by 219 This and the language specified by Language was 220 returned in DriverName. 221 222 @retval EFI_INVALID_PARAMETER Language is NULL. 223 224 @retval EFI_INVALID_PARAMETER DriverName is NULL. 225 226 @retval EFI_UNSUPPORTED The driver specified by This does not support 227 the language specified by Language. 228 229**/ 230EFI_STATUS 231EFIAPI 232ScsiBusComponentNameGetDriverName ( 233 IN EFI_COMPONENT_NAME_PROTOCOL *This, 234 IN CHAR8 *Language, 235 OUT CHAR16 **DriverName 236 ); 237 238/** 239 Retrieves a Unicode string that is the user readable name of the controller 240 that is being managed by a driver. 241 242 This function retrieves the user readable name of the controller specified by 243 ControllerHandle and ChildHandle in the form of a Unicode string. If the 244 driver specified by This has a user readable name in the language specified by 245 Language, then a pointer to the controller name is returned in ControllerName, 246 and EFI_SUCCESS is returned. If the driver specified by This is not currently 247 managing the controller specified by ControllerHandle and ChildHandle, 248 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 249 support the language specified by Language, then EFI_UNSUPPORTED is returned. 250 251 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 252 EFI_COMPONENT_NAME_PROTOCOL instance. 253 254 @param ControllerHandle The handle of a controller that the driver 255 specified by This is managing. This handle 256 specifies the controller whose name is to be 257 returned. 258 259 @param ChildHandle The handle of the child controller to retrieve 260 the name of. This is an optional parameter that 261 may be NULL. It will be NULL for device 262 drivers. It will also be NULL for a bus drivers 263 that wish to retrieve the name of the bus 264 controller. It will not be NULL for a bus 265 driver that wishes to retrieve the name of a 266 child controller. 267 268 @param Language A pointer to a Null-terminated ASCII string 269 array indicating the language. This is the 270 language of the driver name that the caller is 271 requesting, and it must match one of the 272 languages specified in SupportedLanguages. The 273 number of languages supported by a driver is up 274 to the driver writer. Language is specified in 275 RFC 3066 or ISO 639-2 language code format. 276 277 @param ControllerName A pointer to the Unicode string to return. 278 This Unicode string is the name of the 279 controller specified by ControllerHandle and 280 ChildHandle in the language specified by 281 Language from the point of view of the driver 282 specified by This. 283 284 @retval EFI_SUCCESS The Unicode string for the user readable name in 285 the language specified by Language for the 286 driver specified by This was returned in 287 DriverName. 288 289 @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. 290 291 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 292 EFI_HANDLE. 293 294 @retval EFI_INVALID_PARAMETER Language is NULL. 295 296 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 297 298 @retval EFI_UNSUPPORTED The driver specified by This is not currently 299 managing the controller specified by 300 ControllerHandle and ChildHandle. 301 302 @retval EFI_UNSUPPORTED The driver specified by This does not support 303 the language specified by Language. 304 305**/ 306EFI_STATUS 307EFIAPI 308ScsiBusComponentNameGetControllerName ( 309 IN EFI_COMPONENT_NAME_PROTOCOL *This, 310 IN EFI_HANDLE ControllerHandle, 311 IN EFI_HANDLE ChildHandle OPTIONAL, 312 IN CHAR8 *Language, 313 OUT CHAR16 **ControllerName 314 ); 315 316/** 317 Retrieves the device type information of the SCSI Controller. 318 319 @param This Protocol instance pointer. 320 @param DeviceType A pointer to the device type information retrieved from 321 the SCSI Controller. 322 323 @retval EFI_SUCCESS Retrieves the device type information successfully. 324 @retval EFI_INVALID_PARAMETER The DeviceType is NULL. 325 326**/ 327EFI_STATUS 328EFIAPI 329ScsiGetDeviceType ( 330 IN EFI_SCSI_IO_PROTOCOL *This, 331 OUT UINT8 *DeviceType 332 ); 333 334/** 335 Retrieves the device location in the SCSI channel. 336 337 @param This Protocol instance pointer. 338 @param Target A pointer to the Target ID of a SCSI device 339 on the SCSI channel. 340 @param Lun A pointer to the LUN of the SCSI device on 341 the SCSI channel. 342 343 @retval EFI_SUCCESS Retrieves the device location successfully. 344 @retval EFI_INVALID_PARAMETER The Target or Lun is NULL. 345 346**/ 347EFI_STATUS 348EFIAPI 349ScsiGetDeviceLocation ( 350 IN EFI_SCSI_IO_PROTOCOL *This, 351 IN OUT UINT8 **Target, 352 OUT UINT64 *Lun 353 ); 354 355/** 356 Resets the SCSI Bus that the SCSI Controller is attached to. 357 358 @param This Protocol instance pointer. 359 360 @retval EFI_SUCCESS The SCSI bus is reset successfully. 361 @retval EFI_DEVICE_ERROR Errors encountered when resetting the SCSI bus. 362 @retval EFI_UNSUPPORTED The bus reset operation is not supported by the 363 SCSI Host Controller. 364 @retval EFI_TIMEOUT A timeout occurred while attempting to reset 365 the SCSI bus. 366**/ 367EFI_STATUS 368EFIAPI 369ScsiResetBus ( 370 IN EFI_SCSI_IO_PROTOCOL *This 371 ); 372 373/** 374 Resets the SCSI Controller that the device handle specifies. 375 376 @param This Protocol instance pointer. 377 378 @retval EFI_SUCCESS Reset the SCSI controller successfully. 379 @retval EFI_DEVICE_ERROR Errors are encountered when resetting the SCSI Controller. 380 @retval EFI_UNSUPPORTED The SCSI bus does not support a device reset operation. 381 @retval EFI_TIMEOUT A timeout occurred while attempting to reset the 382 SCSI Controller. 383**/ 384EFI_STATUS 385EFIAPI 386ScsiResetDevice ( 387 IN EFI_SCSI_IO_PROTOCOL *This 388 ); 389 390/** 391 Sends a SCSI Request Packet to the SCSI Controller for execution. 392 393 @param This Protocol instance pointer. 394 @param CommandPacket The SCSI request packet to send to the SCSI 395 Controller specified by the device handle. 396 @param Event If the SCSI bus where the SCSI device is attached 397 does not support non-blocking I/O, then Event is 398 ignored, and blocking I/O is performed. 399 If Event is NULL, then blocking I/O is performed. 400 If Event is not NULL and non-blocking I/O is 401 supported, then non-blocking I/O is performed, 402 and Event will be signaled when the SCSI Request 403 Packet completes. 404 405 @retval EFI_SUCCESS The SCSI Request Packet was sent by the host 406 successfully, and TransferLength bytes were 407 transferred to/from DataBuffer.See 408 HostAdapterStatus, TargetStatus, 409 SenseDataLength, and SenseData in that order 410 for additional status information. 411 @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, 412 but the entire DataBuffer could not be transferred. 413 The actual number of bytes transferred is returned 414 in TransferLength. See HostAdapterStatus, 415 TargetStatus, SenseDataLength, and SenseData in 416 that order for additional status information. 417 @retval EFI_NOT_READY The SCSI Request Packet could not be sent because 418 there are too many SCSI Command Packets already 419 queued.The caller may retry again later. 420 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send 421 the SCSI Request Packet. See HostAdapterStatus, 422 TargetStatus, SenseDataLength, and SenseData in 423 that order for additional status information. 424 @retval EFI_INVALID_PARAMETER The contents of CommandPacket are invalid. 425 The SCSI Request Packet was not sent, so no 426 additional status information is available. 427 @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet 428 is not supported by the SCSI initiator(i.e., SCSI 429 Host Controller). The SCSI Request Packet was not 430 sent, so no additional status information is 431 available. 432 @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI 433 Request Packet to execute. See HostAdapterStatus, 434 TargetStatus, SenseDataLength, and SenseData in 435 that order for additional status information. 436**/ 437EFI_STATUS 438EFIAPI 439ScsiExecuteSCSICommand ( 440 IN EFI_SCSI_IO_PROTOCOL *This, 441 IN OUT EFI_SCSI_IO_SCSI_REQUEST_PACKET *CommandPacket, 442 IN EFI_EVENT Event OPTIONAL 443 ); 444 445/** 446 Scan SCSI Bus to discover the device, and attach ScsiIoProtocol to it. 447 448 @param This Protocol instance pointer 449 @param Controller Controller handle 450 @param TargetId Tartget to be scanned 451 @param Lun The Lun of the SCSI device on the SCSI channel. 452 @param ScsiBusDev The pointer of SCSI_BUS_DEVICE 453 454 @retval EFI_SUCCESS Successfully to discover the device and attach 455 ScsiIoProtocol to it. 456 @retval EFI_OUT_OF_RESOURCES Fail to discover the device. 457 458**/ 459EFI_STATUS 460EFIAPI 461ScsiScanCreateDevice ( 462 IN EFI_DRIVER_BINDING_PROTOCOL *This, 463 IN EFI_HANDLE Controller, 464 IN SCSI_TARGET_ID *TargetId, 465 IN UINT64 Lun, 466 IN OUT SCSI_BUS_DEVICE *ScsiBusDev 467 ); 468 469/** 470 Discovery SCSI Device 471 472 @param ScsiIoDevice The pointer of SCSI_IO_DEV 473 474 @retval TRUE Find SCSI Device and verify it. 475 @retval FALSE Unable to find SCSI Device. 476 477**/ 478BOOLEAN 479DiscoverScsiDevice ( 480 IN OUT SCSI_IO_DEV *ScsiIoDevice 481 ); 482 483#endif 484