MdePkg/Include/Protocol/ScsiPassThru.h

   1 /** @file
   2   SCSI Pass Through protocol as defined in EFI 1.1.
   3   This protocol allows information about a SCSI channel to be collected,
   4   and allows SCSI Request Packets to be sent to any SCSI devices on a SCSI
   5   channel even if those devices are not boot devices. This protocol is attached
   6   to the device handle of each SCSI channel in a system that the protocol
   7   supports, and can be used for diagnostics. It may also be used to build
   8   a Block I/O driver for SCSI hard drives and SCSI CD-ROM or DVD drives to
   9   allow those devices to become boot devices.
  10
  11   Copyright (c) 2006 - 2008, Intel Corporation
  12   All rights reserved. This program and the accompanying materials
  13   are licensed and made available under the terms and conditions of the BSD License
  14   which accompanies this distribution.  The full text of the license may be found at
  15   http://opensource.org/licenses/bsd-license.php
  16
  17   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  18   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  19
  20 **/
  21
  22 #ifndef __SCSI_PASS_THROUGH_H__
  23 #define __SCSI_PASS_THROUGH_H__
  24
  25 #define EFI_SCSI_PASS_THRU_PROTOCOL_GUID \
  26   { \
  27     0xa59e8fcf, 0xbda0, 0x43bb, {0x90, 0xb1, 0xd3, 0x73, 0x2e, 0xca, 0xa8, 0x77 } \
  28   }
  29
  30 //
  31 // Forward reference for pure ANSI compatability
  32 //
  33 typedef struct _EFI_SCSI_PASS_THRU_PROTOCOL  EFI_SCSI_PASS_THRU_PROTOCOL;
  34
  35 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL    0x0001
  36 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL     0x0002
  37 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_NONBLOCKIO  0x0004
  38
  39 //
  40 // SCSI Host Adapter Status definition
  41 //
  42 #define EFI_SCSI_STATUS_HOST_ADAPTER_OK                     0x00
  43 #define EFI_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND        0x09  // timeout when processing the command
  44 #define EFI_SCSI_STATUS_HOST_ADAPTER_TIMEOUT                0x0b  // timeout when waiting for the command processing
  45 #define EFI_SCSI_STATUS_HOST_ADAPTER_MESSAGE_REJECT         0x0d  // a message reject was received when processing command
  46 #define EFI_SCSI_STATUS_HOST_ADAPTER_BUS_RESET              0x0e  // a bus reset was detected
  47 #define EFI_SCSI_STATUS_HOST_ADAPTER_PARITY_ERROR           0x0f
  48 #define EFI_SCSI_STATUS_HOST_ADAPTER_REQUEST_SENSE_FAILED   0x10  // the adapter failed in issuing request sense command
  49 #define EFI_SCSI_STATUS_HOST_ADAPTER_SELECTION_TIMEOUT      0x11  // selection timeout
  50 #define EFI_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN  0x12  // data overrun or data underrun
  51 #define EFI_SCSI_STATUS_HOST_ADAPTER_BUS_FREE               0x13  // Unexepected bus free
  52 #define EFI_SCSI_STATUS_HOST_ADAPTER_PHASE_ERROR            0x14  // Target bus phase sequence failure
  53 #define EFI_SCSI_STATUS_HOST_ADAPTER_OTHER                  0x7f
  54
  55 //
  56 // SCSI Target Status definition
  57 //
  58 #define EFI_SCSI_STATUS_TARGET_GOOD                       0x00
  59 #define EFI_SCSI_STATUS_TARGET_CHECK_CONDITION            0x02  // check condition
  60 #define EFI_SCSI_STATUS_TARGET_CONDITION_MET              0x04  // condition met
  61 #define EFI_SCSI_STATUS_TARGET_BUSY                       0x08  // busy
  62 #define EFI_SCSI_STATUS_TARGET_INTERMEDIATE               0x10  // intermediate
  63 #define EFI_SCSI_STATUS_TARGET_INTERMEDIATE_CONDITION_MET 0x14  // intermediate-condition met
  64 #define EFI_SCSI_STATUS_TARGET_RESERVATION_CONFLICT       0x18  // reservation conflict
  65 #define EFI_SCSI_STATUS_TARGET_COMMOND_TERMINATED         0x22  // command terminated
  66 #define EFI_SCSI_STATUS_TARGET_QUEUE_FULL                 0x28  // queue full
  67
  68 typedef struct {
  69   UINT64  Timeout;
  70   VOID    *DataBuffer;
  71   VOID    *SenseData;
  72   VOID    *Cdb;
  73   UINT32  TransferLength;
  74   UINT8   CdbLength;
  75   UINT8   DataDirection;
  76   UINT8   HostAdapterStatus;
  77   UINT8   TargetStatus;
  78   UINT8   SenseDataLength;
  79 } EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET;
  80
  81 typedef struct {
  82   CHAR16  *ControllerName;
  83   CHAR16  *ChannelName;
  84   UINT32  AdapterId;
  85   UINT32  Attributes;
  86   UINT32  IoAlign;
  87 } EFI_SCSI_PASS_THRU_MODE;
  88
  89 /**
  90   Sends a SCSI Request Packet to a SCSI device that is attached to
  91   the SCSI channel. This function supports both blocking I/O and
  92   non-blocking I/O.  The blocking I/O functionality is required,
  93   and the non-blocking I/O functionality is optional.
  94
  95   @param  This   Protocol instance pointer.
  96   @param  Target The Target ID of the SCSI device to
  97                  send the SCSI Request Packet.
  98   @param  Lun    The LUN of the SCSI device to send the
  99                  SCSI Request Packet.
 100   @param  Packet A pointer to the SCSI Request Packet to send
 101                  to the SCSI device specified by Target and Lun.
 102   @param  Event  If non-blocking I/O is not supported then Event
 103                  is ignored, and blocking I/O is performed.
 104                  If Event is NULL, then blocking I/O is performed.
 105                  If Event is not NULL and non blocking I/O is
 106                  supported, then non-blocking I/O is performed,
 107                  and Event will be signaled when the SCSI Request
 108                  Packet completes
 109
 110   @retval EFI_SUCCESS               The SCSI Request Packet was sent by the host, and
 111                                     TransferLength bytes were transferred to/from
 112                                     DataBuffer.See HostAdapterStatus, TargetStatus,
 113                                     SenseDataLength,and SenseData in that order
 114                                     for additional status information.
 115   @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, but the
 116                                     entire DataBuffer could not be transferred.
 117                                     The actual number of bytes transferred is returned
 118                                     in TransferLength. See HostAdapterStatus,
 119                                     TargetStatus, SenseDataLength, and SenseData in
 120                                     that order for additional status information.
 121   @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because
 122                                     there are too many SCSI Request Packets already
 123                                     queued.  The caller may retry again later.
 124   @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send
 125                                     the SCSI Request Packet. See HostAdapterStatus,
 126                                     TargetStatus, SenseDataLength, and SenseData in
 127                                     that order for additional status information.
 128   @retval EFI_INVALID_PARAMETER     Target, Lun, or the contents of ScsiRequestPacket
 129                                     are invalid. The SCSI Request Packet was not sent,
 130                                     so no additional status information is available.
 131   @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet
 132                                     is not supported by the host adapter. The SCSI
 133                                     Request Packet was not sent, so no additional
 134                                     status information is available.
 135   @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI
 136                                     Request Packet to execute. See HostAdapterStatus,
 137                                     TargetStatus, SenseDataLength, and SenseData in
 138                                     that order for additional status information.
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_SCSI_PASS_THRU_PASSTHRU)(
 144   IN EFI_SCSI_PASS_THRU_PROTOCOL                          *This,
 145   IN UINT32                                               Target,
 146   IN UINT64                                               Lun,
 147   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET           *Packet,
 148   IN EFI_EVENT                                            Event   OPTIONAL
 149   )
 150 ;
 151
 152 /**
 153   Used to retrieve the list of legal Target IDs for SCSI devices
 154   on a SCSI channel.
 155
 156   @param  This   Protocol instance pointer.
 157   @param  Target On input, a pointer to the Target ID of a
 158                  SCSI device present on the SCSI channel.
 159                  On output, a pointer to the Target ID of
 160                  the next SCSI device present on a SCSI channel.
 161                  An input value of 0xFFFFFFFF retrieves the
 162                  Target ID of the first SCSI device present on
 163                  a SCSI channel.
 164   @param  Lun    On input, a pointer to the LUN of a SCSI device
 165                  present on the SCSI channel.On output, a pointer
 166                  to the LUN of the next SCSI device present on a
 167                  SCSI channel.
 168
 169   @retval EFI_SUCCESS           The Target ID of the next SCSI device on the SCSI
 170                                 channel was returned in Target and Lun.
 171   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 172   @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF, and Target and Lun were
 173                                  not returned on a previous call to GetNextDevice().
 174
 175 **/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE)(
 179   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 180   IN OUT UINT32                             *Target,
 181   IN OUT UINT64                             *Lun
 182   )
 183 ;
 184
 185 /**
 186   Used to allocate and build a device path node for a SCSI device
 187   on a SCSI channel.
 188
 189   @param  This       Protocol instance pointer.
 190   @param  Target     The Target ID of the SCSI device for which
 191                      a device path node is to be allocated and built.
 192   @param  Lun        The LUN of the SCSI device for which a device
 193                      path node is to be allocated and built.
 194   @param  DevicePath A pointer to a single device path node that
 195                      describes the SCSI device specified by
 196                      Target and Lun. This function is responsible
 197                      for allocating the buffer DevicePath with the boot
 198                      service AllocatePool().  It is the caller's
 199                      responsibility to free DevicePath when the caller
 200                      is finished with DevicePath.
 201
 202   @retval EFI_SUCCESS           The device path node that describes the SCSI device
 203                                 specified by Target and Lun was allocated and
 204                                 returned in DevicePath.
 205   @retval EFI_NOT_FOUND         The SCSI devices specified by Target and Lun does
 206                                 not exist on the SCSI channel.
 207   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 208   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate
 209                                 DevicePath.
 210
 211 **/
 212 typedef
 213 EFI_STATUS
 214 (EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH)(
 215   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 216   IN     UINT32                             Target,
 217   IN     UINT64                             Lun,
 218   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath
 219   )
 220 ;
 221
 222 /**
 223   Used to translate a device path node to a Target ID and LUN.
 224
 225   @param  This       Protocol instance pointer.
 226   @param  DevicePath A pointer to the device path node that
 227                      describes a SCSI device on the SCSI channel.
 228   @param  Target     A pointer to the Target ID of a SCSI device
 229                      on the SCSI channel.
 230   @param  Lun        A pointer to the LUN of a SCSI device on
 231                      the SCSI channel.
 232
 233   @retval EFI_SUCCESS           DevicePath was successfully translated to a
 234                                 Target ID and LUN, and they were returned
 235                                 in Target and Lun.
 236   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 237   @retval EFI_INVALID_PARAMETER Target is NULL.
 238   @retval EFI_INVALID_PARAMETER Lun is NULL.
 239   @retval EFI_UNSUPPORTED       This driver does not support the device path
 240                                 node type in DevicePath.
 241   @retval EFI_NOT_FOUND         A valid translation from DevicePath to a
 242                                 Target ID and LUN does not exist.
 243
 244 **/
 245 typedef
 246 EFI_STATUS
 247 (EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN)(
 248   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 249   IN  EFI_DEVICE_PATH_PROTOCOL              *DevicePath,
 250   OUT UINT32                                *Target,
 251   OUT UINT64                                *Lun
 252   )
 253 ;
 254
 255 /**
 256   Resets a SCSI channel.This operation resets all the
 257   SCSI devices connected to the SCSI channel.
 258
 259   @param  This Protocol instance pointer.
 260
 261   @retval EFI_SUCCESS      The SCSI channel was reset.
 262   @retval EFI_UNSUPPORTED  The SCSI channel does not support
 263                            a channel reset operation.
 264   @retval EFI_DEVICE_ERROR A device error occurred while
 265                            attempting to reset the SCSI channel.
 266   @retval EFI_TIMEOUT      A timeout occurred while attempting
 267                            to reset the SCSI channel.
 268
 269 **/
 270 typedef
 271 EFI_STATUS
 272 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL)(
 273   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This
 274   )
 275 ;
 276
 277 /**
 278   Resets a SCSI device that is connected to a SCSI channel.
 279
 280   @param  This   Protocol instance pointer.
 281   @param  Target The Target ID of the SCSI device to reset.
 282   @param  Lun    The LUN of the SCSI device to reset.
 283
 284   @retval EFI_SUCCESS           The SCSI device specified by Target and
 285                                 Lun was reset.
 286   @retval EFI_UNSUPPORTED       The SCSI channel does not support a target
 287                                 reset operation.
 288   @retval EFI_INVALID_PARAMETER Target or Lun are invalid.
 289   @retval EFI_DEVICE_ERROR      A device error occurred while attempting
 290                                 to reset the SCSI device specified by Target
 291                                 and Lun.
 292   @retval EFI_TIMEOUT           A timeout occurred while attempting to reset
 293                                 the SCSI device specified by Target and Lun.
 294
 295 **/
 296 typedef
 297 EFI_STATUS
 298 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET)(
 299   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This,
 300   IN UINT32                                  Target,
 301   IN UINT64                                  Lun
 302   )
 303 ;
 304
 305 /**
 306   @par Protocol Description:
 307   The EFI_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel and
 308   the ability to send SCI Request Packets to any SCSI device attached to that SCSI channel. The
 309   information includes the Target ID of the host controller on the SCSI channel, the attributes of
 310   the SCSI channel, the printable name for the SCSI controller, and the printable name of the
 311   SCSI channel.
 312
 313   @param Mode
 314   A pointer to the EFI_SCSI_PASS_THRU_MODE data for this SCSI channel.
 315
 316   @param PassThru
 317   Sends a SCSI Request Packet to a SCSI device that is connected to the SCSI channel.
 318
 319   @param GetNextDevice
 320   Used to retrieve the list of legal Target IDs and LUNs for the
 321   SCSI devices on a SCSI channel.
 322
 323   @param BuildDevicePath
 324   Used to allocate and build a device path node for a SCSI device on a SCSI channel.
 325
 326   @param GetTargetLun
 327   Used to translate a device path node to a Target ID and LUN.
 328
 329   @param ResetChannel
 330   Resets the SCSI channel. This operation resets all the SCSI
 331   devices connected to the SCSI channel.
 332
 333   @param ResetTarget
 334   Resets a SCSI device that is connected to the SCSI channel.
 335 **/
 336 struct _EFI_SCSI_PASS_THRU_PROTOCOL {
 337   EFI_SCSI_PASS_THRU_MODE               *Mode;
 338   EFI_SCSI_PASS_THRU_PASSTHRU           PassThru;
 339   EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE    GetNextDevice;
 340   EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH  BuildDevicePath;
 341   EFI_SCSI_PASS_THRU_GET_TARGET_LUN     GetTargetLun;
 342   EFI_SCSI_PASS_THRU_RESET_CHANNEL      ResetChannel;
 343   EFI_SCSI_PASS_THRU_RESET_TARGET       ResetTarget;
 344 };
 345
 346 extern EFI_GUID gEfiScsiPassThruProtocolGuid;
 347
 348 #endif