1 /** @file 2 Header file for EFI_BLOCK_IO_PROTOCOL interface. 3 4 Copyright (c) 2013 - 2015, 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 Send a security protocol command to a device that receives data and/or the result 113 of one or more commands sent by SendData. 114 115 The ReceiveData function sends a security protocol command to the given MediaId. 116 The security protocol command sent is defined by SecurityProtocolId and contains 117 the security protocol specific data SecurityProtocolSpecificData. The function 118 returns the data from the security protocol command in PayloadBuffer. 119 120 For devices supporting the SCSI command set, the security protocol command is sent 121 using the SECURITY PROTOCOL IN command defined in SPC-4. 122 123 For devices supporting the ATA command set, the security protocol command is sent 124 using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize 125 is non-zero. 126 127 If the PayloadBufferSize is zero, the security protocol command is sent using the 128 Trusted Non-Data command defined in ATA8-ACS. 129 130 If PayloadBufferSize is too small to store the available data from the security 131 protocol command, the function shall copy PayloadBufferSize bytes into the 132 PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL. 133 134 If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero, 135 the function shall return EFI_INVALID_PARAMETER. 136 137 If the given MediaId does not support security protocol commands, the function shall 138 return EFI_UNSUPPORTED. If there is no media in the device, the function returns 139 EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, 140 the function returns EFI_MEDIA_CHANGED. 141 142 If the security protocol fails to complete within the Timeout period, the function 143 shall return EFI_TIMEOUT. 144 145 If the security protocol command completes without an error, the function shall 146 return EFI_SUCCESS. If the security protocol command completes with an error, the 147 function shall return EFI_DEVICE_ERROR. 148 149 @param This Indicates a pointer to the calling context. 150 @param MediaId ID of the medium to receive data from. 151 @param Timeout The timeout, in 100ns units, to use for the execution 152 of the security protocol command. A Timeout value of 0 153 means that this function will wait indefinitely for the 154 security protocol command to execute. If Timeout is greater 155 than zero, then this function will return EFI_TIMEOUT 156 if the time required to execute the receive data command 157 is greater than Timeout. 158 @param SecurityProtocolId The value of the "Security Protocol" parameter of 159 the security protocol command to be sent. 160 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 161 of the security protocol command to be sent. 162 @param PayloadBufferSize Size in bytes of the payload data buffer. 163 @param PayloadBuffer A pointer to a destination buffer to store the security 164 protocol command specific payload data for the security 165 protocol command. The caller is responsible for having 166 either implicit or explicit ownership of the buffer. 167 @param PayloadTransferSize A pointer to a buffer to store the size in bytes of the 168 data written to the payload data buffer. 169 170 @retval EFI_SUCCESS The security protocol command completed successfully. 171 @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to store the available 172 data from the device. The PayloadBuffer contains the truncated data. 173 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 174 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 175 @retval EFI_NO_MEDIA There is no media in the device. 176 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 177 @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize is NULL and 178 PayloadBufferSize is non-zero. 179 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 180 protocol command to execute. 181 182 **/ 183 EFI_STATUS 184 EFIAPI 185 NvmeStorageSecurityReceiveData ( 186 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 187 IN UINT32 MediaId, 188 IN UINT64 Timeout, 189 IN UINT8 SecurityProtocolId, 190 IN UINT16 SecurityProtocolSpecificData, 191 IN UINTN PayloadBufferSize, 192 OUT VOID *PayloadBuffer, 193 OUT UINTN *PayloadTransferSize 194 ); 195 196 /** 197 Send a security protocol command to a device. 198 199 The SendData function sends a security protocol command containing the payload 200 PayloadBuffer to the given MediaId. The security protocol command sent is 201 defined by SecurityProtocolId and contains the security protocol specific data 202 SecurityProtocolSpecificData. If the underlying protocol command requires a 203 specific padding for the command payload, the SendData function shall add padding 204 bytes to the command payload to satisfy the padding requirements. 205 206 For devices supporting the SCSI command set, the security protocol command is sent 207 using the SECURITY PROTOCOL OUT command defined in SPC-4. 208 209 For devices supporting the ATA command set, the security protocol command is sent 210 using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize 211 is non-zero. If the PayloadBufferSize is zero, the security protocol command is 212 sent using the Trusted Non-Data command defined in ATA8-ACS. 213 214 If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall 215 return EFI_INVALID_PARAMETER. 216 217 If the given MediaId does not support security protocol commands, the function 218 shall return EFI_UNSUPPORTED. If there is no media in the device, the function 219 returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the 220 device, the function returns EFI_MEDIA_CHANGED. 221 222 If the security protocol fails to complete within the Timeout period, the function 223 shall return EFI_TIMEOUT. 224 225 If the security protocol command completes without an error, the function shall return 226 EFI_SUCCESS. If the security protocol command completes with an error, the function 227 shall return EFI_DEVICE_ERROR. 228 229 @param This Indicates a pointer to the calling context. 230 @param MediaId ID of the medium to receive data from. 231 @param Timeout The timeout, in 100ns units, to use for the execution 232 of the security protocol command. A Timeout value of 0 233 means that this function will wait indefinitely for the 234 security protocol command to execute. If Timeout is greater 235 than zero, then this function will return EFI_TIMEOUT 236 if the time required to execute the receive data command 237 is greater than Timeout. 238 @param SecurityProtocolId The value of the "Security Protocol" parameter of 239 the security protocol command to be sent. 240 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 241 of the security protocol command to be sent. 242 @param PayloadBufferSize Size in bytes of the payload data buffer. 243 @param PayloadBuffer A pointer to a destination buffer to store the security 244 protocol command specific payload data for the security 245 protocol command. 246 247 @retval EFI_SUCCESS The security protocol command completed successfully. 248 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 249 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 250 @retval EFI_NO_MEDIA There is no media in the device. 251 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 252 @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize is non-zero. 253 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 254 protocol command to execute. 255 256 **/ 257 EFI_STATUS 258 EFIAPI 259 NvmeStorageSecuritySendData ( 260 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 261 IN UINT32 MediaId, 262 IN UINT64 Timeout, 263 IN UINT8 SecurityProtocolId, 264 IN UINT16 SecurityProtocolSpecificData, 265 IN UINTN PayloadBufferSize, 266 IN VOID *PayloadBuffer 267 ); 268 269 #endif 270