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. All rights reserved.<BR> 12 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 /// 70 /// The timeout, in 100 ns units, to use for the execution of this SCSI 71 /// Request Packet. A Timeout value of 0 means that this function 72 /// will wait indefinitely for the SCSI Request Packet to execute. If 73 /// Timeout is greater than zero, then this function will return 74 /// EFI_TIMEOUT if the time required to execute the SCSI Request 75 /// Packet is greater than Timeout. 76 /// 77 UINT64 Timeout; 78 /// 79 /// A pointer to the data buffer to transfer between the SCSI 80 /// controller and the SCSI device. Must be aligned to the boundary 81 /// specified in the IoAlign field of the 82 /// EFI_SCSI_PASS_THRU_MODE structure. 83 /// 84 VOID *DataBuffer; 85 /// 86 /// A pointer to the sense data that was generated by the execution of 87 /// the SCSI Request Packet. 88 /// 89 VOID *SenseData; 90 /// 91 /// A pointer to buffer that contains the Command Data Block to 92 /// send to the SCSI device. 93 /// 94 VOID *Cdb; 95 /// 96 /// On Input, the size, in bytes, of InDataBuffer. On output, the 97 /// number of bytes transferred between the SCSI controller and the SCSI device. 98 /// 99 UINT32 TransferLength; 100 /// 101 /// The length, in bytes, of the buffer Cdb. The standard values are 102 /// 6, 10, 12, and 16, but other values are possible if a variable length CDB is used. 103 /// 104 UINT8 CdbLength; 105 /// 106 /// The direction of the data transfer. 0 for reads, 1 for writes. A 107 /// value of 2 is Reserved for Bi-Directional SCSI commands. 108 /// 109 UINT8 DataDirection; 110 /// 111 /// The status of the SCSI Host Controller that produces the SCSI 112 /// bus where the SCSI device attached when the SCSI Request 113 /// Packet was executed on the SCSI Controller. 114 /// 115 UINT8 HostAdapterStatus; 116 /// 117 /// The status returned by the SCSI device when the SCSI Request 118 /// Packet was executed. 119 /// 120 UINT8 TargetStatus; 121 /// 122 /// On input, the length in bytes of the SenseData buffer. On 123 /// output, the number of bytes written to the SenseData buffer. 124 /// 125 UINT8 SenseDataLength; 126 } EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET; 127 128 typedef struct { 129 /// 130 /// A Null-terminated Unicode string that represents the printable name of the SCSI controller. 131 /// 132 CHAR16 *ControllerName; 133 /// 134 /// A Null-terminated Unicode string that represents the printable name of the SCSI channel. 135 /// 136 CHAR16 *ChannelName; 137 /// 138 /// The Target ID of the host adapter on the SCSI channel. 139 /// 140 UINT32 AdapterId; 141 /// 142 /// Additional information on the attributes of the SCSI channel. 143 /// 144 UINT32 Attributes; 145 /// 146 /// Supplies the alignment requirement for any buffer used in a data transfer. 147 /// 148 UINT32 IoAlign; 149 } EFI_SCSI_PASS_THRU_MODE; 150 151 /** 152 Sends a SCSI Request Packet to a SCSI device that is attached to 153 the SCSI channel. This function supports both blocking I/O and 154 non-blocking I/O. The blocking I/O functionality is required, 155 and the non-blocking I/O functionality is optional. 156 157 @param This Protocol instance pointer. 158 @param Target The Target ID of the SCSI device to 159 send the SCSI Request Packet. 160 @param Lun The LUN of the SCSI device to send the 161 SCSI Request Packet. 162 @param Packet A pointer to the SCSI Request Packet to send 163 to the SCSI device specified by Target and Lun. 164 @param Event If non-blocking I/O is not supported then Event 165 is ignored, and blocking I/O is performed. 166 If Event is NULL, then blocking I/O is performed. 167 If Event is not NULL and non blocking I/O is 168 supported, then non-blocking I/O is performed, 169 and Event will be signaled when the SCSI Request 170 Packet completes 171 172 @retval EFI_SUCCESS The SCSI Request Packet was sent by the host, and 173 TransferLength bytes were transferred to/from 174 DataBuffer. See HostAdapterStatus, TargetStatus, 175 SenseDataLength, and SenseData in that order 176 for additional status information. 177 @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, but the 178 entire DataBuffer could not be transferred. 179 The actual number of bytes transferred is returned 180 in TransferLength. See HostAdapterStatus, 181 TargetStatus, SenseDataLength, and SenseData in 182 that order for additional status information. 183 @retval EFI_NOT_READY The SCSI Request Packet could not be sent because 184 there are too many SCSI Request Packets already 185 queued. The caller may retry again later. 186 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send 187 the SCSI Request Packet. See HostAdapterStatus, 188 TargetStatus, SenseDataLength, and SenseData in 189 that order for additional status information. 190 @retval EFI_INVALID_PARAMETER Target, Lun, or the contents of ScsiRequestPacket 191 are invalid. The SCSI Request Packet was not sent, 192 so no additional status information is available. 193 @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet 194 is not supported by the host adapter. The SCSI 195 Request Packet was not sent, so no additional 196 status information is available. 197 @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI 198 Request Packet to execute. See HostAdapterStatus, 199 TargetStatus, SenseDataLength, and SenseData in 200 that order for additional status information. 201 202 **/ 203 typedef 204 EFI_STATUS 205 (EFIAPI *EFI_SCSI_PASS_THRU_PASSTHRU)( 206 IN EFI_SCSI_PASS_THRU_PROTOCOL *This, 207 IN UINT32 Target, 208 IN UINT64 Lun, 209 IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet, 210 IN EFI_EVENT Event OPTIONAL 211 ); 212 213 /** 214 Used to retrieve the list of legal Target IDs for SCSI devices 215 on a SCSI channel. 216 217 @param This Protocol instance pointer. 218 @param Target On input, a pointer to the Target ID of a 219 SCSI device present on the SCSI channel. 220 On output, a pointer to the Target ID of 221 the next SCSI device present on a SCSI channel. 222 An input value of 0xFFFFFFFF retrieves the 223 Target ID of the first SCSI device present on 224 a SCSI channel. 225 @param Lun On input, a pointer to the LUN of a SCSI device 226 present on the SCSI channel. On output, a pointer 227 to the LUN of the next SCSI device present on a 228 SCSI channel. 229 230 @retval EFI_SUCCESS The Target ID of the next SCSI device on the SCSI 231 channel was returned in Target and Lun. 232 @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel. 233 @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF, and Target and Lun were 234 not returned on a previous call to GetNextDevice(). 235 236 **/ 237 typedef 238 EFI_STATUS 239 (EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE)( 240 IN EFI_SCSI_PASS_THRU_PROTOCOL *This, 241 IN OUT UINT32 *Target, 242 IN OUT UINT64 *Lun 243 ); 244 245 /** 246 Used to allocate and build a device path node for a SCSI device 247 on a SCSI channel. 248 249 @param This Protocol instance pointer. 250 @param Target The Target ID of the SCSI device for which 251 a device path node is to be allocated and built. 252 @param Lun The LUN of the SCSI device for which a device 253 path node is to be allocated and built. 254 @param DevicePath A pointer to a single device path node that 255 describes the SCSI device specified by 256 Target and Lun. This function is responsible 257 for allocating the buffer DevicePath with the boot 258 service AllocatePool(). It is the caller's 259 responsibility to free DevicePath when the caller 260 is finished with DevicePath. 261 262 @retval EFI_SUCCESS The device path node that describes the SCSI device 263 specified by Target and Lun was allocated and 264 returned in DevicePath. 265 @retval EFI_NOT_FOUND The SCSI devices specified by Target and Lun does 266 not exist on the SCSI channel. 267 @retval EFI_INVALID_PARAMETER DevicePath is NULL. 268 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate 269 DevicePath. 270 271 **/ 272 typedef 273 EFI_STATUS 274 (EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH)( 275 IN EFI_SCSI_PASS_THRU_PROTOCOL *This, 276 IN UINT32 Target, 277 IN UINT64 Lun, 278 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath 279 ); 280 281 /** 282 Used to translate a device path node to a Target ID and LUN. 283 284 @param This Protocol instance pointer. 285 @param DevicePath A pointer to the device path node that 286 describes a SCSI device on the SCSI channel. 287 @param Target A pointer to the Target ID of a SCSI device 288 on the SCSI channel. 289 @param Lun A pointer to the LUN of a SCSI device on 290 the SCSI channel. 291 292 @retval EFI_SUCCESS DevicePath was successfully translated to a 293 Target ID and LUN, and they were returned 294 in Target and Lun. 295 @retval EFI_INVALID_PARAMETER DevicePath is NULL. 296 @retval EFI_INVALID_PARAMETER Target is NULL. 297 @retval EFI_INVALID_PARAMETER Lun is NULL. 298 @retval EFI_UNSUPPORTED This driver does not support the device path 299 node type in DevicePath. 300 @retval EFI_NOT_FOUND A valid translation from DevicePath to a 301 Target ID and LUN does not exist. 302 303 **/ 304 typedef 305 EFI_STATUS 306 (EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN)( 307 IN EFI_SCSI_PASS_THRU_PROTOCOL *This, 308 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 309 OUT UINT32 *Target, 310 OUT UINT64 *Lun 311 ); 312 313 /** 314 Resets a SCSI channel.This operation resets all the 315 SCSI devices connected to the SCSI channel. 316 317 @param This Protocol instance pointer. 318 319 @retval EFI_SUCCESS The SCSI channel was reset. 320 @retval EFI_UNSUPPORTED The SCSI channel does not support 321 a channel reset operation. 322 @retval EFI_DEVICE_ERROR A device error occurred while 323 attempting to reset the SCSI channel. 324 @retval EFI_TIMEOUT A timeout occurred while attempting 325 to reset the SCSI channel. 326 327 **/ 328 typedef 329 EFI_STATUS 330 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL)( 331 IN EFI_SCSI_PASS_THRU_PROTOCOL *This 332 ); 333 334 /** 335 Resets a SCSI device that is connected to a SCSI channel. 336 337 @param This Protocol instance pointer. 338 @param Target The Target ID of the SCSI device to reset. 339 @param Lun The LUN of the SCSI device to reset. 340 341 @retval EFI_SUCCESS The SCSI device specified by Target and 342 Lun was reset. 343 @retval EFI_UNSUPPORTED The SCSI channel does not support a target 344 reset operation. 345 @retval EFI_INVALID_PARAMETER Target or Lun are invalid. 346 @retval EFI_DEVICE_ERROR A device error occurred while attempting 347 to reset the SCSI device specified by Target 348 and Lun. 349 @retval EFI_TIMEOUT A timeout occurred while attempting to reset 350 the SCSI device specified by Target and Lun. 351 352 **/ 353 typedef 354 EFI_STATUS 355 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET)( 356 IN EFI_SCSI_PASS_THRU_PROTOCOL *This, 357 IN UINT32 Target, 358 IN UINT64 Lun 359 ); 360 361 /// 362 /// The EFI_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel and 363 /// the ability to send SCSI Request Packets to any SCSI device attached to that SCSI channel. The 364 /// information includes the Target ID of the host controller on the SCSI channel, the attributes of 365 /// the SCSI channel, the printable name for the SCSI controller, and the printable name of the 366 /// SCSI channel. 367 /// 368 struct _EFI_SCSI_PASS_THRU_PROTOCOL { 369 /// 370 /// A pointer to the EFI_SCSI_PASS_THRU_MODE data for this SCSI channel. 371 /// 372 EFI_SCSI_PASS_THRU_MODE *Mode; 373 EFI_SCSI_PASS_THRU_PASSTHRU PassThru; 374 EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE GetNextDevice; 375 EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; 376 EFI_SCSI_PASS_THRU_GET_TARGET_LUN GetTargetLun; 377 EFI_SCSI_PASS_THRU_RESET_CHANNEL ResetChannel; 378 EFI_SCSI_PASS_THRU_RESET_TARGET ResetTarget; 379 }; 380 381 extern EFI_GUID gEfiScsiPassThruProtocolGuid; 382 383 #endif 384