MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBus.h

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