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