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   Used to retrieve the list of legal Target IDs for SCSI devices
 153   on a SCSI channel.
 154
 155   @param  This   Protocol instance pointer.
 156   @param  Target On input, a pointer to the Target ID of a
 157                  SCSI device present on the SCSI channel.
 158                  On output, a pointer to the Target ID of
 159                  the next SCSI device present on a SCSI channel.
 160                  An input value of 0xFFFFFFFF retrieves the
 161                  Target ID of the first SCSI device present on
 162                  a SCSI channel.
 163   @param  Lun    On input, a pointer to the LUN of a SCSI device
 164                  present on the SCSI channel.On output, a pointer
 165                  to the LUN of the next SCSI device present on a
 166                  SCSI channel.
 167
 168   @retval EFI_SUCCESS           The Target ID of the next SCSI device on the SCSI
 169                                 channel was returned in Target and Lun.
 170   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 171   @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF, and Target and Lun were
 172                                  not returned on a previous call to GetNextDevice().
 173
 174 **/
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE)(
 178   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 179   IN OUT UINT32                             *Target,
 180   IN OUT UINT64                             *Lun
 181   );
 182
 183 /**
 184   Used to allocate and build a device path node for a SCSI device
 185   on a SCSI channel.
 186
 187   @param  This       Protocol instance pointer.
 188   @param  Target     The Target ID of the SCSI device for which
 189                      a device path node is to be allocated and built.
 190   @param  Lun        The LUN of the SCSI device for which a device
 191                      path node is to be allocated and built.
 192   @param  DevicePath A pointer to a single device path node that
 193                      describes the SCSI device specified by
 194                      Target and Lun. This function is responsible
 195                      for allocating the buffer DevicePath with the boot
 196                      service AllocatePool().  It is the caller's
 197                      responsibility to free DevicePath when the caller
 198                      is finished with DevicePath.
 199
 200   @retval EFI_SUCCESS           The device path node that describes the SCSI device
 201                                 specified by Target and Lun was allocated and
 202                                 returned in DevicePath.
 203   @retval EFI_NOT_FOUND         The SCSI devices specified by Target and Lun does
 204                                 not exist on the SCSI channel.
 205   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 206   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate
 207                                 DevicePath.
 208
 209 **/
 210 typedef
 211 EFI_STATUS
 212 (EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH)(
 213   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 214   IN     UINT32                             Target,
 215   IN     UINT64                             Lun,
 216   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath
 217   );
 218
 219 /**
 220   Used to translate a device path node to a Target ID and LUN.
 221
 222   @param  This       Protocol instance pointer.
 223   @param  DevicePath A pointer to the device path node that
 224                      describes a SCSI device on the SCSI channel.
 225   @param  Target     A pointer to the Target ID of a SCSI device
 226                      on the SCSI channel.
 227   @param  Lun        A pointer to the LUN of a SCSI device on
 228                      the SCSI channel.
 229
 230   @retval EFI_SUCCESS           DevicePath was successfully translated to a
 231                                 Target ID and LUN, and they were returned
 232                                 in Target and Lun.
 233   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 234   @retval EFI_INVALID_PARAMETER Target is NULL.
 235   @retval EFI_INVALID_PARAMETER Lun is NULL.
 236   @retval EFI_UNSUPPORTED       This driver does not support the device path
 237                                 node type in DevicePath.
 238   @retval EFI_NOT_FOUND         A valid translation from DevicePath to a
 239                                 Target ID and LUN does not exist.
 240
 241 **/
 242 typedef
 243 EFI_STATUS
 244 (EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN)(
 245   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
 246   IN  EFI_DEVICE_PATH_PROTOCOL              *DevicePath,
 247   OUT UINT32                                *Target,
 248   OUT UINT64                                *Lun
 249   );
 250
 251 /**
 252   Resets a SCSI channel.This operation resets all the
 253   SCSI devices connected to the SCSI channel.
 254
 255   @param  This Protocol instance pointer.
 256
 257   @retval EFI_SUCCESS      The SCSI channel was reset.
 258   @retval EFI_UNSUPPORTED  The SCSI channel does not support
 259                            a channel reset operation.
 260   @retval EFI_DEVICE_ERROR A device error occurred while
 261                            attempting to reset the SCSI channel.
 262   @retval EFI_TIMEOUT      A timeout occurred while attempting
 263                            to reset the SCSI channel.
 264
 265 **/
 266 typedef
 267 EFI_STATUS
 268 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL)(
 269   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This
 270   );
 271
 272 /**
 273   Resets a SCSI device that is connected to a SCSI channel.
 274
 275   @param  This   Protocol instance pointer.
 276   @param  Target The Target ID of the SCSI device to reset.
 277   @param  Lun    The LUN of the SCSI device to reset.
 278
 279   @retval EFI_SUCCESS           The SCSI device specified by Target and
 280                                 Lun was reset.
 281   @retval EFI_UNSUPPORTED       The SCSI channel does not support a target
 282                                 reset operation.
 283   @retval EFI_INVALID_PARAMETER Target or Lun are invalid.
 284   @retval EFI_DEVICE_ERROR      A device error occurred while attempting
 285                                 to reset the SCSI device specified by Target
 286                                 and Lun.
 287   @retval EFI_TIMEOUT           A timeout occurred while attempting to reset
 288                                 the SCSI device specified by Target and Lun.
 289
 290 **/
 291 typedef
 292 EFI_STATUS
 293 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET)(
 294   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This,
 295   IN UINT32                                  Target,
 296   IN UINT64                                  Lun
 297   );
 298
 299 /**
 300   @par Protocol Description:
 301   The EFI_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel and
 302   the ability to send SCI Request Packets to any SCSI device attached to that SCSI channel. The
 303   information includes the Target ID of the host controller on the SCSI channel, the attributes of
 304   the SCSI channel, the printable name for the SCSI controller, and the printable name of the
 305   SCSI channel.
 306 **/
 307 struct _EFI_SCSI_PASS_THRU_PROTOCOL {
 308   EFI_SCSI_PASS_THRU_MODE               *Mode;
 309   EFI_SCSI_PASS_THRU_PASSTHRU           PassThru;
 310   EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE    GetNextDevice;
 311   EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH  BuildDevicePath;
 312   EFI_SCSI_PASS_THRU_GET_TARGET_LUN     GetTargetLun;
 313   EFI_SCSI_PASS_THRU_RESET_CHANNEL      ResetChannel;
 314   EFI_SCSI_PASS_THRU_RESET_TARGET       ResetTarget;
 315 };
 316
 317 extern EFI_GUID gEfiScsiPassThruProtocolGuid;
 318
 319 #endif