1 /** @file 2 Header file for EFI_BLOCK_IO_PROTOCOL interface. 3 4 Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _EFI_NVME_BLOCKIO_H_ 16 #define _EFI_NVME_BLOCKIO_H_ 17 18 /** 19 Reset the Block Device. 20 21 @param This Indicates a pointer to the calling context. 22 @param ExtendedVerification Driver may perform diagnostics on reset. 23 24 @retval EFI_SUCCESS The device was reset. 25 @retval EFI_DEVICE_ERROR The device is not functioning properly and could 26 not be reset. 27 28 **/ 29 EFI_STATUS 30 EFIAPI 31 NvmeBlockIoReset ( 32 IN EFI_BLOCK_IO_PROTOCOL *This, 33 IN BOOLEAN ExtendedVerification 34 ); 35 36 /** 37 Read BufferSize bytes from Lba into Buffer. 38 39 @param This Indicates a pointer to the calling context. 40 @param MediaId Id of the media, changes every time the media is replaced. 41 @param Lba The starting Logical Block Address to read from 42 @param BufferSize Size of Buffer, must be a multiple of device block size. 43 @param Buffer A pointer to the destination buffer for the data. The caller is 44 responsible for either having implicit or explicit ownership of the buffer. 45 46 @retval EFI_SUCCESS The data was read correctly from the device. 47 @retval EFI_DEVICE_ERROR The device reported an error while performing the read. 48 @retval EFI_NO_MEDIA There is no media in the device. 49 @retval EFI_MEDIA_CHANGED The MediaId does not matched the current device. 50 @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device. 51 @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, 52 or the buffer is not on proper alignment. 53 54 **/ 55 EFI_STATUS 56 EFIAPI 57 NvmeBlockIoReadBlocks ( 58 IN EFI_BLOCK_IO_PROTOCOL *This, 59 IN UINT32 MediaId, 60 IN EFI_LBA Lba, 61 IN UINTN BufferSize, 62 OUT VOID *Buffer 63 ); 64 65 /** 66 Write BufferSize bytes from Lba into Buffer. 67 68 @param This Indicates a pointer to the calling context. 69 @param MediaId The media ID that the write request is for. 70 @param Lba The starting logical block address to be written. The caller is 71 responsible for writing to only legitimate locations. 72 @param BufferSize Size of Buffer, must be a multiple of device block size. 73 @param Buffer A pointer to the source buffer for the data. 74 75 @retval EFI_SUCCESS The data was written correctly to the device. 76 @retval EFI_WRITE_PROTECTED The device can not be written to. 77 @retval EFI_DEVICE_ERROR The device reported an error while performing the write. 78 @retval EFI_NO_MEDIA There is no media in the device. 79 @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device. 80 @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device. 81 @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, 82 or the buffer is not on proper alignment. 83 84 **/ 85 EFI_STATUS 86 EFIAPI 87 NvmeBlockIoWriteBlocks ( 88 IN EFI_BLOCK_IO_PROTOCOL *This, 89 IN UINT32 MediaId, 90 IN EFI_LBA Lba, 91 IN UINTN BufferSize, 92 IN VOID *Buffer 93 ); 94 95 /** 96 Flush the Block Device. 97 98 @param This Indicates a pointer to the calling context. 99 100 @retval EFI_SUCCESS All outstanding data was written to the device 101 @retval EFI_DEVICE_ERROR The device reported an error while writing back the data 102 @retval EFI_NO_MEDIA There is no media in the device. 103 104 **/ 105 EFI_STATUS 106 EFIAPI 107 NvmeBlockIoFlushBlocks ( 108 IN EFI_BLOCK_IO_PROTOCOL *This 109 ); 110 111 /** 112 Reset the block device hardware. 113 114 @param[in] This Indicates a pointer to the calling context. 115 @param[in] ExtendedVerification Indicates that the driver may perform a more 116 exhausive verfication operation of the 117 device during reset. 118 119 @retval EFI_SUCCESS The device was reset. 120 @retval EFI_DEVICE_ERROR The device is not functioning properly and could 121 not be reset. 122 123 **/ 124 EFI_STATUS 125 EFIAPI 126 NvmeBlockIoResetEx ( 127 IN EFI_BLOCK_IO2_PROTOCOL *This, 128 IN BOOLEAN ExtendedVerification 129 ); 130 131 /** 132 Read BufferSize bytes from Lba into Buffer. 133 134 This function reads the requested number of blocks from the device. All the 135 blocks are read, or an error is returned. 136 If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and 137 non-blocking I/O is being used, the Event associated with this request will 138 not be signaled. 139 140 @param[in] This Indicates a pointer to the calling context. 141 @param[in] MediaId Id of the media, changes every time the media is 142 replaced. 143 @param[in] Lba The starting Logical Block Address to read from. 144 @param[in, out] Token A pointer to the token associated with the 145 transaction. 146 @param[in] BufferSize Size of Buffer, must be a multiple of device 147 block size. 148 @param[out] Buffer A pointer to the destination buffer for the data. 149 The caller is responsible for either having 150 implicit or explicit ownership of the buffer. 151 152 @retval EFI_SUCCESS The read request was queued if Token->Event is 153 not NULL.The data was read correctly from the 154 device if the Token->Event is NULL. 155 @retval EFI_DEVICE_ERROR The device reported an error while performing 156 the read. 157 @retval EFI_NO_MEDIA There is no media in the device. 158 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 159 @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of 160 the intrinsic block size of the device. 161 @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not 162 valid, or the buffer is not on proper 163 alignment. 164 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a 165 lack of resources. 166 167 **/ 168 EFI_STATUS 169 EFIAPI 170 NvmeBlockIoReadBlocksEx ( 171 IN EFI_BLOCK_IO2_PROTOCOL *This, 172 IN UINT32 MediaId, 173 IN EFI_LBA Lba, 174 IN OUT EFI_BLOCK_IO2_TOKEN *Token, 175 IN UINTN BufferSize, 176 OUT VOID *Buffer 177 ); 178 179 /** 180 Write BufferSize bytes from Lba into Buffer. 181 182 This function writes the requested number of blocks to the device. All blocks 183 are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA, 184 EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is 185 being used, the Event associated with this request will not be signaled. 186 187 @param[in] This Indicates a pointer to the calling context. 188 @param[in] MediaId The media ID that the write request is for. 189 @param[in] Lba The starting logical block address to be written. 190 The caller is responsible for writing to only 191 legitimate locations. 192 @param[in, out] Token A pointer to the token associated with the 193 transaction. 194 @param[in] BufferSize Size of Buffer, must be a multiple of device 195 block size. 196 @param[in] Buffer A pointer to the source buffer for the data. 197 198 @retval EFI_SUCCESS The write request was queued if Event is not 199 NULL. 200 The data was written correctly to the device if 201 the Event is NULL. 202 @retval EFI_WRITE_PROTECTED The device can not be written to. 203 @retval EFI_NO_MEDIA There is no media in the device. 204 @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current 205 device. 206 @retval EFI_DEVICE_ERROR The device reported an error while performing 207 the write. 208 @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size 209 of the device. 210 @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not 211 valid, or the buffer is not on proper 212 alignment. 213 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a 214 lack of resources. 215 216 **/ 217 EFI_STATUS 218 EFIAPI 219 NvmeBlockIoWriteBlocksEx ( 220 IN EFI_BLOCK_IO2_PROTOCOL *This, 221 IN UINT32 MediaId, 222 IN EFI_LBA Lba, 223 IN OUT EFI_BLOCK_IO2_TOKEN *Token, 224 IN UINTN BufferSize, 225 IN VOID *Buffer 226 ); 227 228 /** 229 Flush the Block Device. 230 231 If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED 232 is returned and non-blocking I/O is being used, the Event associated with 233 this request will not be signaled. 234 235 @param[in] This Indicates a pointer to the calling context. 236 @param[in,out] Token A pointer to the token associated with the 237 transaction. 238 239 @retval EFI_SUCCESS The flush request was queued if Event is not 240 NULL. 241 All outstanding data was written correctly to 242 the device if the Event is NULL. 243 @retval EFI_DEVICE_ERROR The device reported an error while writting back 244 the data. 245 @retval EFI_WRITE_PROTECTED The device cannot be written to. 246 @retval EFI_NO_MEDIA There is no media in the device. 247 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 248 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack 249 of resources. 250 251 **/ 252 EFI_STATUS 253 EFIAPI 254 NvmeBlockIoFlushBlocksEx ( 255 IN EFI_BLOCK_IO2_PROTOCOL *This, 256 IN OUT EFI_BLOCK_IO2_TOKEN *Token 257 ); 258 259 /** 260 Send a security protocol command to a device that receives data and/or the result 261 of one or more commands sent by SendData. 262 263 The ReceiveData function sends a security protocol command to the given MediaId. 264 The security protocol command sent is defined by SecurityProtocolId and contains 265 the security protocol specific data SecurityProtocolSpecificData. The function 266 returns the data from the security protocol command in PayloadBuffer. 267 268 For devices supporting the SCSI command set, the security protocol command is sent 269 using the SECURITY PROTOCOL IN command defined in SPC-4. 270 271 For devices supporting the ATA command set, the security protocol command is sent 272 using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize 273 is non-zero. 274 275 If the PayloadBufferSize is zero, the security protocol command is sent using the 276 Trusted Non-Data command defined in ATA8-ACS. 277 278 If PayloadBufferSize is too small to store the available data from the security 279 protocol command, the function shall copy PayloadBufferSize bytes into the 280 PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL. 281 282 If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero, 283 the function shall return EFI_INVALID_PARAMETER. 284 285 If the given MediaId does not support security protocol commands, the function shall 286 return EFI_UNSUPPORTED. If there is no media in the device, the function returns 287 EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, 288 the function returns EFI_MEDIA_CHANGED. 289 290 If the security protocol fails to complete within the Timeout period, the function 291 shall return EFI_TIMEOUT. 292 293 If the security protocol command completes without an error, the function shall 294 return EFI_SUCCESS. If the security protocol command completes with an error, the 295 function shall return EFI_DEVICE_ERROR. 296 297 @param This Indicates a pointer to the calling context. 298 @param MediaId ID of the medium to receive data from. 299 @param Timeout The timeout, in 100ns units, to use for the execution 300 of the security protocol command. A Timeout value of 0 301 means that this function will wait indefinitely for the 302 security protocol command to execute. If Timeout is greater 303 than zero, then this function will return EFI_TIMEOUT 304 if the time required to execute the receive data command 305 is greater than Timeout. 306 @param SecurityProtocolId The value of the "Security Protocol" parameter of 307 the security protocol command to be sent. 308 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 309 of the security protocol command to be sent. 310 @param PayloadBufferSize Size in bytes of the payload data buffer. 311 @param PayloadBuffer A pointer to a destination buffer to store the security 312 protocol command specific payload data for the security 313 protocol command. The caller is responsible for having 314 either implicit or explicit ownership of the buffer. 315 @param PayloadTransferSize A pointer to a buffer to store the size in bytes of the 316 data written to the payload data buffer. 317 318 @retval EFI_SUCCESS The security protocol command completed successfully. 319 @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to store the available 320 data from the device. The PayloadBuffer contains the truncated data. 321 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 322 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 323 @retval EFI_NO_MEDIA There is no media in the device. 324 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 325 @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize is NULL and 326 PayloadBufferSize is non-zero. 327 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 328 protocol command to execute. 329 330 **/ 331 EFI_STATUS 332 EFIAPI 333 NvmeStorageSecurityReceiveData ( 334 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 335 IN UINT32 MediaId, 336 IN UINT64 Timeout, 337 IN UINT8 SecurityProtocolId, 338 IN UINT16 SecurityProtocolSpecificData, 339 IN UINTN PayloadBufferSize, 340 OUT VOID *PayloadBuffer, 341 OUT UINTN *PayloadTransferSize 342 ); 343 344 /** 345 Send a security protocol command to a device. 346 347 The SendData function sends a security protocol command containing the payload 348 PayloadBuffer to the given MediaId. The security protocol command sent is 349 defined by SecurityProtocolId and contains the security protocol specific data 350 SecurityProtocolSpecificData. If the underlying protocol command requires a 351 specific padding for the command payload, the SendData function shall add padding 352 bytes to the command payload to satisfy the padding requirements. 353 354 For devices supporting the SCSI command set, the security protocol command is sent 355 using the SECURITY PROTOCOL OUT command defined in SPC-4. 356 357 For devices supporting the ATA command set, the security protocol command is sent 358 using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize 359 is non-zero. If the PayloadBufferSize is zero, the security protocol command is 360 sent using the Trusted Non-Data command defined in ATA8-ACS. 361 362 If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall 363 return EFI_INVALID_PARAMETER. 364 365 If the given MediaId does not support security protocol commands, the function 366 shall return EFI_UNSUPPORTED. If there is no media in the device, the function 367 returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the 368 device, the function returns EFI_MEDIA_CHANGED. 369 370 If the security protocol fails to complete within the Timeout period, the function 371 shall return EFI_TIMEOUT. 372 373 If the security protocol command completes without an error, the function shall return 374 EFI_SUCCESS. If the security protocol command completes with an error, the function 375 shall return EFI_DEVICE_ERROR. 376 377 @param This Indicates a pointer to the calling context. 378 @param MediaId ID of the medium to receive data from. 379 @param Timeout The timeout, in 100ns units, to use for the execution 380 of the security protocol command. A Timeout value of 0 381 means that this function will wait indefinitely for the 382 security protocol command to execute. If Timeout is greater 383 than zero, then this function will return EFI_TIMEOUT 384 if the time required to execute the receive data command 385 is greater than Timeout. 386 @param SecurityProtocolId The value of the "Security Protocol" parameter of 387 the security protocol command to be sent. 388 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 389 of the security protocol command to be sent. 390 @param PayloadBufferSize Size in bytes of the payload data buffer. 391 @param PayloadBuffer A pointer to a destination buffer to store the security 392 protocol command specific payload data for the security 393 protocol command. 394 395 @retval EFI_SUCCESS The security protocol command completed successfully. 396 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 397 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 398 @retval EFI_NO_MEDIA There is no media in the device. 399 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 400 @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize is non-zero. 401 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 402 protocol command to execute. 403 404 **/ 405 EFI_STATUS 406 EFIAPI 407 NvmeStorageSecuritySendData ( 408 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 409 IN UINT32 MediaId, 410 IN UINT64 Timeout, 411 IN UINT8 SecurityProtocolId, 412 IN UINT16 SecurityProtocolSpecificData, 413 IN UINTN PayloadBufferSize, 414 IN VOID *PayloadBuffer 415 ); 416 417 #endif 418