MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBus.h

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