MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBus.h

   1 /** @file
   2   Header file for SCSI Bus Driver.
   3
   4 Copyright (c) 2006 - 2018, 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