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