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