MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBus.h

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