1 /** @file 2 EFI_EXT_SCSI_PASS_THRU_PROTOCOL as defined in UEFI 2.0. 3 This protocol provides services that allow SCSI Pass Thru commands 4 to be sent to SCSI devices attached to a SCSI channel. 5 6 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 7 SPDX-License-Identifier: BSD-2-Clause-Patent 8 9 **/ 10 11 #ifndef __EXT_SCSI_PASS_THROUGH_PROTOCOL_H__ 12 #define __EXT_SCSI_PASS_THROUGH_PROTOCOL_H__ 13 14 #define EFI_EXT_SCSI_PASS_THRU_PROTOCOL_GUID \ 15 { \ 16 0x143b7632, 0xb81b, 0x4cb7, {0xab, 0xd3, 0xb6, 0x25, 0xa5, 0xb9, 0xbf, 0xfe } \ 17 } 18 19 typedef struct _EFI_EXT_SCSI_PASS_THRU_PROTOCOL EFI_EXT_SCSI_PASS_THRU_PROTOCOL; 20 21 #define TARGET_MAX_BYTES 0x10 22 23 #define EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL 0x0001 24 #define EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL 0x0002 25 #define EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_NONBLOCKIO 0x0004 26 27 // 28 // DataDirection 29 // 30 #define EFI_EXT_SCSI_DATA_DIRECTION_READ 0 31 #define EFI_EXT_SCSI_DATA_DIRECTION_WRITE 1 32 #define EFI_EXT_SCSI_DATA_DIRECTION_BIDIRECTIONAL 2 33 // 34 // HostAdapterStatus 35 // 36 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK 0x00 37 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND 0x09 38 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_TIMEOUT 0x0b 39 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_MESSAGE_REJECT 0x0d 40 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_BUS_RESET 0x0e 41 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_PARITY_ERROR 0x0f 42 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_REQUEST_SENSE_FAILED 0x10 43 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_SELECTION_TIMEOUT 0x11 44 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN 0x12 45 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_BUS_FREE 0x13 46 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_PHASE_ERROR 0x14 47 #define EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER 0x7f 48 // 49 // TargetStatus 50 // 51 #define EFI_EXT_SCSI_STATUS_TARGET_GOOD 0x00 52 #define EFI_EXT_SCSI_STATUS_TARGET_CHECK_CONDITION 0x02 53 #define EFI_EXT_SCSI_STATUS_TARGET_CONDITION_MET 0x04 54 #define EFI_EXT_SCSI_STATUS_TARGET_BUSY 0x08 55 #define EFI_EXT_SCSI_STATUS_TARGET_INTERMEDIATE 0x10 56 #define EFI_EXT_SCSI_STATUS_TARGET_INTERMEDIATE_CONDITION_MET 0x14 57 #define EFI_EXT_SCSI_STATUS_TARGET_RESERVATION_CONFLICT 0x18 58 #define EFI_EXT_SCSI_STATUS_TARGET_TASK_SET_FULL 0x28 59 #define EFI_EXT_SCSI_STATUS_TARGET_ACA_ACTIVE 0x30 60 #define EFI_EXT_SCSI_STATUS_TARGET_TASK_ABORTED 0x40 61 62 typedef struct { 63 /// 64 /// The Target ID of the host adapter on the SCSI channel. 65 /// 66 UINT32 AdapterId; 67 /// 68 /// Additional information on the attributes of the SCSI channel. 69 /// 70 UINT32 Attributes; 71 /// 72 /// Supplies the alignment requirement for any buffer used in a data transfer. 73 /// 74 UINT32 IoAlign; 75 } EFI_EXT_SCSI_PASS_THRU_MODE; 76 77 typedef struct { 78 /// 79 /// The timeout, in 100 ns units, to use for the execution of this SCSI 80 /// Request Packet. A Timeout value of 0 means that this function 81 /// will wait indefinitely for the SCSI Request Packet to execute. If 82 /// Timeout is greater than zero, then this function will return 83 /// EFI_TIMEOUT if the time required to execute the SCSI 84 /// Request Packet is greater than Timeout. 85 /// 86 UINT64 Timeout; 87 /// 88 /// A pointer to the data buffer to transfer between the SCSI 89 /// controller and the SCSI device for read and bidirectional commands. 90 /// 91 VOID *InDataBuffer; 92 /// 93 /// A pointer to the data buffer to transfer between the SCSI 94 /// controller and the SCSI device for write or bidirectional commands. 95 /// 96 VOID *OutDataBuffer; 97 /// 98 /// A pointer to the sense data that was generated by the execution of 99 /// the SCSI Request Packet. 100 /// 101 VOID *SenseData; 102 /// 103 /// A pointer to buffer that contains the Command Data Block to 104 /// send to the SCSI device specified by Target and Lun. 105 /// 106 VOID *Cdb; 107 /// 108 /// On Input, the size, in bytes, of InDataBuffer. On output, the 109 /// number of bytes transferred between the SCSI controller and the SCSI device. 110 /// 111 UINT32 InTransferLength; 112 /// 113 /// On Input, the size, in bytes of OutDataBuffer. On Output, the 114 /// Number of bytes transferred between SCSI Controller and the SCSI device. 115 /// 116 UINT32 OutTransferLength; 117 /// 118 /// The length, in bytes, of the buffer Cdb. The standard values are 6, 119 /// 10, 12, and 16, but other values are possible if a variable length CDB is used. 120 /// 121 UINT8 CdbLength; 122 /// 123 /// The direction of the data transfer. 0 for reads, 1 for writes. A 124 /// value of 2 is Reserved for Bi-Directional SCSI commands. 125 /// 126 UINT8 DataDirection; 127 /// 128 /// The status of the host adapter specified by This when the SCSI 129 /// Request Packet was executed on the target device. 130 /// 131 UINT8 HostAdapterStatus; 132 /// 133 /// The status returned by the device specified by Target and Lun 134 /// when the SCSI Request Packet was executed. 135 /// 136 UINT8 TargetStatus; 137 /// 138 /// On input, the length in bytes of the SenseData buffer. On 139 /// output, the number of bytes written to the SenseData buffer. 140 /// 141 UINT8 SenseDataLength; 142 } EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET; 143 144 /** 145 Sends a SCSI Request Packet to a SCSI device that is attached to the SCSI channel. This function 146 supports both blocking I/O and nonblocking I/O. The blocking I/O functionality is required, and the 147 nonblocking I/O functionality is optional. 148 149 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 150 @param Target The Target is an array of size TARGET_MAX_BYTES and it represents 151 the id of the SCSI device to send the SCSI Request Packet. Each 152 transport driver may choose to utilize a subset of this size to suit the needs 153 of transport target representation. For example, a Fibre Channel driver 154 may use only 8 bytes (WWN) to represent an FC target. 155 @param Lun The LUN of the SCSI device to send the SCSI Request Packet. 156 @param Packet A pointer to the SCSI Request Packet to send to the SCSI device 157 specified by Target and Lun. 158 @param Event If nonblocking I/O is not supported then Event is ignored, and blocking 159 I/O is performed. If Event is NULL, then blocking I/O is performed. If 160 Event is not NULL and non blocking I/O is supported, then 161 nonblocking I/O is performed, and Event will be signaled when the 162 SCSI Request Packet completes. 163 164 @retval EFI_SUCCESS The SCSI Request Packet was sent by the host. For bi-directional 165 commands, InTransferLength bytes were transferred from 166 InDataBuffer. For write and bi-directional commands, 167 OutTransferLength bytes were transferred by 168 OutDataBuffer. 169 @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was not executed. The number of bytes that 170 could be transferred is returned in InTransferLength. For write 171 and bi-directional commands, OutTransferLength bytes were 172 transferred by OutDataBuffer. 173 @retval EFI_NOT_READY The SCSI Request Packet could not be sent because there are too many 174 SCSI Request Packets already queued. The caller may retry again later. 175 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send the SCSI Request 176 Packet. 177 @retval EFI_INVALID_PARAMETER Target, Lun, or the contents of ScsiRequestPacket are invalid. 178 @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet is not supported 179 by the host adapter. This includes the case of Bi-directional SCSI 180 commands not supported by the implementation. The SCSI Request 181 Packet was not sent, so no additional status information is available. 182 @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request Packet to execute. 183 184 **/ 185 typedef 186 EFI_STATUS 187 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_PASSTHRU)( 188 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 189 IN UINT8 *Target, 190 IN UINT64 Lun, 191 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet, 192 IN EFI_EVENT Event OPTIONAL 193 ); 194 195 /** 196 Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These 197 can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal 198 Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the 199 Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI 200 channel. 201 202 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 203 @param Target On input, a pointer to the Target ID (an array of size 204 TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel. 205 On output, a pointer to the Target ID (an array of 206 TARGET_MAX_BYTES) of the next SCSI device present on a SCSI 207 channel. An input value of 0xF(all bytes in the array are 0xF) in the 208 Target array retrieves the Target ID of the first SCSI device present on a 209 SCSI channel. 210 @param Lun On input, a pointer to the LUN of a SCSI device present on the SCSI 211 channel. On output, a pointer to the LUN of the next SCSI device present 212 on a SCSI channel. 213 214 @retval EFI_SUCCESS The Target ID and LUN of the next SCSI device on the SCSI 215 channel was returned in Target and Lun. 216 @retval EFI_INVALID_PARAMETER Target array is not all 0xF, and Target and Lun were 217 not returned on a previous call to GetNextTargetLun(). 218 @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel. 219 220 **/ 221 typedef 222 EFI_STATUS 223 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_GET_NEXT_TARGET_LUN)( 224 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 225 IN OUT UINT8 **Target, 226 IN OUT UINT64 *Lun 227 ); 228 229 /** 230 Used to allocate and build a device path node for a SCSI device on a SCSI channel. 231 232 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 233 @param Target The Target is an array of size TARGET_MAX_BYTES and it specifies the 234 Target ID of the SCSI device for which a device path node is to be 235 allocated and built. Transport drivers may chose to utilize a subset of 236 this size to suit the representation of targets. For example, a Fibre 237 Channel driver may use only 8 bytes (WWN) in the array to represent a 238 FC target. 239 @param Lun The LUN of the SCSI device for which a device path node is to be 240 allocated and built. 241 @param DevicePath A pointer to a single device path node that describes the SCSI device 242 specified by Target and Lun. This function is responsible for 243 allocating the buffer DevicePath with the boot service 244 AllocatePool(). It is the caller's responsibility to free 245 DevicePath when the caller is finished with DevicePath. 246 247 @retval EFI_SUCCESS The device path node that describes the SCSI device specified by 248 Target and Lun was allocated and returned in 249 DevicePath. 250 @retval EFI_INVALID_PARAMETER DevicePath is NULL. 251 @retval EFI_NOT_FOUND The SCSI devices specified by Target and Lun does not exist 252 on the SCSI channel. 253 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate DevicePath. 254 255 **/ 256 typedef 257 EFI_STATUS 258 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_BUILD_DEVICE_PATH)( 259 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 260 IN UINT8 *Target, 261 IN UINT64 Lun, 262 OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath 263 ); 264 265 /** 266 Used to translate a device path node to a Target ID and LUN. 267 268 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 269 @param DevicePath A pointer to a single device path node that describes the SCSI device 270 on the SCSI channel. 271 @param Target A pointer to the Target Array which represents the ID of a SCSI device 272 on the SCSI channel. 273 @param Lun A pointer to the LUN of a SCSI device on the SCSI channel. 274 275 @retval EFI_SUCCESS DevicePath was successfully translated to a Target ID and 276 LUN, and they were returned in Target and Lun. 277 @retval EFI_INVALID_PARAMETER DevicePath or Target or Lun is NULL. 278 @retval EFI_NOT_FOUND A valid translation from DevicePath to a Target ID and LUN 279 does not exist. 280 @retval EFI_UNSUPPORTED This driver does not support the device path node type in 281 DevicePath. 282 283 **/ 284 typedef 285 EFI_STATUS 286 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_GET_TARGET_LUN)( 287 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 288 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 289 OUT UINT8 **Target, 290 OUT UINT64 *Lun 291 ); 292 293 /** 294 Resets a SCSI channel. This operation resets all the SCSI devices connected to the SCSI channel. 295 296 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 297 298 @retval EFI_SUCCESS The SCSI channel was reset. 299 @retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the SCSI channel. 300 @retval EFI_TIMEOUT A timeout occurred while attempting to reset the SCSI channel. 301 @retval EFI_UNSUPPORTED The SCSI channel does not support a channel reset operation. 302 303 **/ 304 typedef 305 EFI_STATUS 306 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_RESET_CHANNEL)( 307 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This 308 ); 309 310 /** 311 Resets a SCSI logical unit that is connected to a SCSI channel. 312 313 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 314 @param Target The Target is an array of size TARGET_MAX_BYTE and it represents the 315 target port ID of the SCSI device containing the SCSI logical unit to 316 reset. Transport drivers may chose to utilize a subset of this array to suit 317 the representation of their targets. 318 @param Lun The LUN of the SCSI device to reset. 319 320 @retval EFI_SUCCESS The SCSI device specified by Target and Lun was reset. 321 @retval EFI_INVALID_PARAMETER Target or Lun is NULL. 322 @retval EFI_TIMEOUT A timeout occurred while attempting to reset the SCSI device 323 specified by Target and Lun. 324 @retval EFI_UNSUPPORTED The SCSI channel does not support a target reset operation. 325 @retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the SCSI device 326 specified by Target and Lun. 327 328 **/ 329 typedef 330 EFI_STATUS 331 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_RESET_TARGET_LUN)( 332 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 333 IN UINT8 *Target, 334 IN UINT64 Lun 335 ); 336 337 /** 338 Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. These can either 339 be the list SCSI devices that are actually present on the SCSI channel, or the list of legal Target IDs 340 for the SCSI channel. Regardless, the caller of this function must probe the Target ID returned to 341 see if a SCSI device is actually present at that location on the SCSI channel. 342 343 @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. 344 @param Target (TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel. 345 On output, a pointer to the Target ID (an array of 346 TARGET_MAX_BYTES) of the next SCSI device present on a SCSI 347 channel. An input value of 0xF(all bytes in the array are 0xF) in the 348 Target array retrieves the Target ID of the first SCSI device present on a 349 SCSI channel. 350 351 @retval EFI_SUCCESS The Target ID of the next SCSI device on the SCSI 352 channel was returned in Target. 353 @retval EFI_INVALID_PARAMETER Target or Lun is NULL. 354 @retval EFI_TIMEOUT Target array is not all 0xF, and Target was not 355 returned on a previous call to GetNextTarget(). 356 @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel. 357 358 **/ 359 typedef 360 EFI_STATUS 361 (EFIAPI *EFI_EXT_SCSI_PASS_THRU_GET_NEXT_TARGET)( 362 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, 363 IN OUT UINT8 **Target 364 ); 365 366 /// 367 /// The EFI_EXT_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel 368 /// and the ability to send SCI Request Packets to any SCSI device attached to 369 /// that SCSI channel. The information includes the Target ID of the host controller 370 /// on the SCSI channel and the attributes of the SCSI channel. 371 /// 372 struct _EFI_EXT_SCSI_PASS_THRU_PROTOCOL { 373 /// 374 /// A pointer to the EFI_EXT_SCSI_PASS_THRU_MODE data for this SCSI channel. 375 /// 376 EFI_EXT_SCSI_PASS_THRU_MODE *Mode; 377 EFI_EXT_SCSI_PASS_THRU_PASSTHRU PassThru; 378 EFI_EXT_SCSI_PASS_THRU_GET_NEXT_TARGET_LUN GetNextTargetLun; 379 EFI_EXT_SCSI_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; 380 EFI_EXT_SCSI_PASS_THRU_GET_TARGET_LUN GetTargetLun; 381 EFI_EXT_SCSI_PASS_THRU_RESET_CHANNEL ResetChannel; 382 EFI_EXT_SCSI_PASS_THRU_RESET_TARGET_LUN ResetTargetLun; 383 EFI_EXT_SCSI_PASS_THRU_GET_NEXT_TARGET GetNextTarget; 384 }; 385 386 extern EFI_GUID gEfiExtScsiPassThruProtocolGuid; 387 388 #endif 389