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