185e923a52851b242f8fc9f937c1fad7ce51246eelgao/** @file 264a80549c8ab874c5b23b376adbb99008e6143b0myronporter Fault Tolerant Write protocol provides boot-time service for fault tolerant 364a80549c8ab874c5b23b376adbb99008e6143b0myronporter write capability for block devices. The protocol provides for non-volatile 464a80549c8ab874c5b23b376adbb99008e6143b0myronporter storage of the intermediate data and private information a caller would need to 564a80549c8ab874c5b23b376adbb99008e6143b0myronporter recover from a critical fault, such as a power failure. 664a80549c8ab874c5b23b376adbb99008e6143b0myronporter 7cd5ebaa06dca3e6ef3c464081e6defe00d358c69hhtianCopyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> 864a80549c8ab874c5b23b376adbb99008e6143b0myronporterThis program and the accompanying materials are licensed and made available under 964a80549c8ab874c5b23b376adbb99008e6143b0myronporterthe terms and conditions of the BSD License that accompanies this distribution. 1064a80549c8ab874c5b23b376adbb99008e6143b0myronporterThe full text of the license may be found at 1164a80549c8ab874c5b23b376adbb99008e6143b0myronporterhttp://opensource.org/licenses/bsd-license.php. 1264a80549c8ab874c5b23b376adbb99008e6143b0myronporter 1385e923a52851b242f8fc9f937c1fad7ce51246eelgaoTHE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 1485e923a52851b242f8fc9f937c1fad7ce51246eelgaoWITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 1585e923a52851b242f8fc9f937c1fad7ce51246eelgao 1685e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 1785e923a52851b242f8fc9f937c1fad7ce51246eelgao 1885e923a52851b242f8fc9f937c1fad7ce51246eelgao#ifndef _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_ 1985e923a52851b242f8fc9f937c1fad7ce51246eelgao#define _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_ 2085e923a52851b242f8fc9f937c1fad7ce51246eelgao 2185e923a52851b242f8fc9f937c1fad7ce51246eelgao#define EFI_FAULT_TOLERANT_WRITE_PROTOCOL_GUID \ 2285e923a52851b242f8fc9f937c1fad7ce51246eelgao { \ 2385e923a52851b242f8fc9f937c1fad7ce51246eelgao 0x3ebd9e82, 0x2c78, 0x4de6, {0x97, 0x86, 0x8d, 0x4b, 0xfc, 0xb7, 0xc8, 0x81 } \ 2485e923a52851b242f8fc9f937c1fad7ce51246eelgao } 2585e923a52851b242f8fc9f937c1fad7ce51246eelgao 2685e923a52851b242f8fc9f937c1fad7ce51246eelgao// 2785e923a52851b242f8fc9f937c1fad7ce51246eelgao// Forward reference for pure ANSI compatability 2885e923a52851b242f8fc9f937c1fad7ce51246eelgao// 2985e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL EFI_FAULT_TOLERANT_WRITE_PROTOCOL; 3085e923a52851b242f8fc9f937c1fad7ce51246eelgao 3185e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 32e9b67286ad4428d63e2495f38b71273b81e0846fpkandel Get the size of the largest block that can be updated in a fault-tolerant manner. 3385e923a52851b242f8fc9f937c1fad7ce51246eelgao 3485e923a52851b242f8fc9f937c1fad7ce51246eelgao @param This Indicates a pointer to the calling context. 35e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @param BlockSize A pointer to a caller-allocated UINTN that is 36e9b67286ad4428d63e2495f38b71273b81e0846fpkandel updated to indicate the size of the largest block 3785e923a52851b242f8fc9f937c1fad7ce51246eelgao that can be updated. 3885e923a52851b242f8fc9f937c1fad7ce51246eelgao 3964a80549c8ab874c5b23b376adbb99008e6143b0myronporter @retval EFI_SUCCESS The function completed successfully. 4085e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 4185e923a52851b242f8fc9f937c1fad7ce51246eelgao 4285e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 4385e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 4485e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 450c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE)( 4685e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This, 4785e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT UINTN *BlockSize 4885e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 4985e923a52851b242f8fc9f937c1fad7ce51246eelgao 5085e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 5185e923a52851b242f8fc9f937c1fad7ce51246eelgao Allocates space for the protocol to maintain information about writes. 52e9b67286ad4428d63e2495f38b71273b81e0846fpkandel Since writes must be completed in a fault-tolerant manner and multiple 53e9b67286ad4428d63e2495f38b71273b81e0846fpkandel writes require more resources to be successful, this function 5485e923a52851b242f8fc9f937c1fad7ce51246eelgao enables the protocol to ensure that enough space exists to track 55e9b67286ad4428d63e2495f38b71273b81e0846fpkandel information about upcoming writes. 5685e923a52851b242f8fc9f937c1fad7ce51246eelgao 57e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @param This A pointer to the calling context. 5885e923a52851b242f8fc9f937c1fad7ce51246eelgao @param CallerId The GUID identifying the write. 5985e923a52851b242f8fc9f937c1fad7ce51246eelgao @param PrivateDataSize The size of the caller's private data that must be 6085e923a52851b242f8fc9f937c1fad7ce51246eelgao recorded for each write. 61e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @param NumberOfWrites The number of fault tolerant block writes that will 6285e923a52851b242f8fc9f937c1fad7ce51246eelgao need to occur. 6385e923a52851b242f8fc9f937c1fad7ce51246eelgao 6485e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_SUCCESS The function completed successfully 6585e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 66e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @retval EFI_ACCESS_DENIED Not all allocated writes have been completed. All 67e9b67286ad4428d63e2495f38b71273b81e0846fpkandel writes must be completed or aborted before another 6885e923a52851b242f8fc9f937c1fad7ce51246eelgao fault tolerant write can occur. 6985e923a52851b242f8fc9f937c1fad7ce51246eelgao 7085e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 7185e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 7285e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 730c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE)( 7485e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This, 7585e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_GUID * CallerId, 7685e923a52851b242f8fc9f937c1fad7ce51246eelgao IN UINTN PrivateDataSize, 7785e923a52851b242f8fc9f937c1fad7ce51246eelgao IN UINTN NumberOfWrites 7885e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 7985e923a52851b242f8fc9f937c1fad7ce51246eelgao 8085e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 8185e923a52851b242f8fc9f937c1fad7ce51246eelgao Starts a target block update. This records information about the write 82e9b67286ad4428d63e2495f38b71273b81e0846fpkandel in fault tolerant storage, and will complete the write in a recoverable 8385e923a52851b242f8fc9f937c1fad7ce51246eelgao manner, ensuring at all times that either the original contents or 8485e923a52851b242f8fc9f937c1fad7ce51246eelgao the modified contents are available. 8585e923a52851b242f8fc9f937c1fad7ce51246eelgao 8664a80549c8ab874c5b23b376adbb99008e6143b0myronporter @param This The calling context. 8785e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Lba The logical block address of the target block. 8885e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Offset The offset within the target block to place the 8985e923a52851b242f8fc9f937c1fad7ce51246eelgao data. 9085e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Length The number of bytes to write to the target block. 9185e923a52851b242f8fc9f937c1fad7ce51246eelgao @param PrivateData A pointer to private data that the caller requires 92e9b67286ad4428d63e2495f38b71273b81e0846fpkandel to complete any pending writes in the event of a 9385e923a52851b242f8fc9f937c1fad7ce51246eelgao fault. 9485e923a52851b242f8fc9f937c1fad7ce51246eelgao @param FvBlockHandle The handle of FVB protocol that provides services 95e9b67286ad4428d63e2495f38b71273b81e0846fpkandel for reading, writing, and erasing the target block. 9685e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Buffer The data to write. 9785e923a52851b242f8fc9f937c1fad7ce51246eelgao 9864a80549c8ab874c5b23b376adbb99008e6143b0myronporter @retval EFI_SUCCESS The function completed successfully. 9985e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 100e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @retval EFI_BAD_BUFFER_SIZE The write would span a block boundary, which is not 10185e923a52851b242f8fc9f937c1fad7ce51246eelgao a valid action. 10285e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ACCESS_DENIED No writes have been allocated. 103e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @retval EFI_NOT_READY The last write has not been completed. Restart() 10485e923a52851b242f8fc9f937c1fad7ce51246eelgao must be called to complete it. 10585e923a52851b242f8fc9f937c1fad7ce51246eelgao 10685e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 10785e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 10885e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 1090c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE)( 11085e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This, 11185e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_LBA Lba, 11285e923a52851b242f8fc9f937c1fad7ce51246eelgao IN UINTN Offset, 11385e923a52851b242f8fc9f937c1fad7ce51246eelgao IN UINTN Length, 11485e923a52851b242f8fc9f937c1fad7ce51246eelgao IN VOID *PrivateData, 11585e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_HANDLE FvbHandle, 11685e923a52851b242f8fc9f937c1fad7ce51246eelgao IN VOID *Buffer 11785e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 11885e923a52851b242f8fc9f937c1fad7ce51246eelgao 11985e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 12085e923a52851b242f8fc9f937c1fad7ce51246eelgao Restarts a previously interrupted write. The caller must provide the 12185e923a52851b242f8fc9f937c1fad7ce51246eelgao block protocol needed to complete the interrupted write. 12285e923a52851b242f8fc9f937c1fad7ce51246eelgao 12364a80549c8ab874c5b23b376adbb99008e6143b0myronporter @param This The calling context. 12464a80549c8ab874c5b23b376adbb99008e6143b0myronporter @param FvBlockProtocol The handle of FVB protocol that provides services. 125e9b67286ad4428d63e2495f38b71273b81e0846fpkandel for reading, writing, and erasing the target block. 12685e923a52851b242f8fc9f937c1fad7ce51246eelgao 12764a80549c8ab874c5b23b376adbb99008e6143b0myronporter @retval EFI_SUCCESS The function completed successfully. 12885e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 12985e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ACCESS_DENIED No pending writes exist. 13085e923a52851b242f8fc9f937c1fad7ce51246eelgao 13185e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 13285e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 13385e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 1340c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART)( 13585e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This, 13685e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_HANDLE FvbHandle 13785e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 13885e923a52851b242f8fc9f937c1fad7ce51246eelgao 13985e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 140e9b67286ad4428d63e2495f38b71273b81e0846fpkandel Aborts all previously allocated writes. 14185e923a52851b242f8fc9f937c1fad7ce51246eelgao 14264a80549c8ab874c5b23b376adbb99008e6143b0myronporter @param This The calling context. 14385e923a52851b242f8fc9f937c1fad7ce51246eelgao 14464a80549c8ab874c5b23b376adbb99008e6143b0myronporter @retval EFI_SUCCESS The function completed successfully. 14585e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 14685e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_NOT_FOUND No allocated writes exist. 14785e923a52851b242f8fc9f937c1fad7ce51246eelgao 14885e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 14985e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 15085e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 1510c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT)( 15285e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This 15385e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 15485e923a52851b242f8fc9f937c1fad7ce51246eelgao 15585e923a52851b242f8fc9f937c1fad7ce51246eelgao/** 156e9b67286ad4428d63e2495f38b71273b81e0846fpkandel Starts a target block update. This function records information about the write 15764a80549c8ab874c5b23b376adbb99008e6143b0myronporter in fault-tolerant storage and completes the write in a recoverable 15885e923a52851b242f8fc9f937c1fad7ce51246eelgao manner, ensuring at all times that either the original contents or 15985e923a52851b242f8fc9f937c1fad7ce51246eelgao the modified contents are available. 16085e923a52851b242f8fc9f937c1fad7ce51246eelgao 16185e923a52851b242f8fc9f937c1fad7ce51246eelgao @param This Indicates a pointer to the calling context. 16285e923a52851b242f8fc9f937c1fad7ce51246eelgao @param CallerId The GUID identifying the last write. 16385e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Lba The logical block address of the last write. 16485e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Offset The offset within the block of the last write. 16585e923a52851b242f8fc9f937c1fad7ce51246eelgao @param Length The length of the last write. 166e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @param PrivateDataSize On input, the size of the PrivateData buffer. On 167e9b67286ad4428d63e2495f38b71273b81e0846fpkandel output, the size of the private data stored for 16885e923a52851b242f8fc9f937c1fad7ce51246eelgao this write. 16985e923a52851b242f8fc9f937c1fad7ce51246eelgao @param PrivateData A pointer to a buffer. The function will copy 170e9b67286ad4428d63e2495f38b71273b81e0846fpkandel PrivateDataSize bytes from the private data stored 17185e923a52851b242f8fc9f937c1fad7ce51246eelgao for this write. 172e9b67286ad4428d63e2495f38b71273b81e0846fpkandel @param Complete A Boolean value with TRUE indicating that the write 17385e923a52851b242f8fc9f937c1fad7ce51246eelgao was completed. 17485e923a52851b242f8fc9f937c1fad7ce51246eelgao 17564a80549c8ab874c5b23b376adbb99008e6143b0myronporter @retval EFI_SUCCESS The function completed successfully. 17685e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_ABORTED The function could not complete successfully. 17785e923a52851b242f8fc9f937c1fad7ce51246eelgao @retval EFI_NOT_FOUND No allocated writes exist. 17885e923a52851b242f8fc9f937c1fad7ce51246eelgao 17985e923a52851b242f8fc9f937c1fad7ce51246eelgao**/ 18085e923a52851b242f8fc9f937c1fad7ce51246eelgaotypedef 18185e923a52851b242f8fc9f937c1fad7ce51246eelgaoEFI_STATUS 1820c1a4aa69a1810ae053afa62c913e371d89a496ersun(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE)( 18385e923a52851b242f8fc9f937c1fad7ce51246eelgao IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This, 18485e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT EFI_GUID * CallerId, 18585e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT EFI_LBA *Lba, 18685e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT UINTN *Offset, 18785e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT UINTN *Length, 18885e923a52851b242f8fc9f937c1fad7ce51246eelgao IN OUT UINTN *PrivateDataSize, 18985e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT VOID *PrivateData, 19085e923a52851b242f8fc9f937c1fad7ce51246eelgao OUT BOOLEAN *Complete 19185e923a52851b242f8fc9f937c1fad7ce51246eelgao ); 19285e923a52851b242f8fc9f937c1fad7ce51246eelgao 19385e923a52851b242f8fc9f937c1fad7ce51246eelgao// 19485e923a52851b242f8fc9f937c1fad7ce51246eelgao// Protocol declaration 19585e923a52851b242f8fc9f937c1fad7ce51246eelgao// 19685e923a52851b242f8fc9f937c1fad7ce51246eelgaostruct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL { 19785e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE GetMaxBlockSize; 19885e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_ALLOCATE Allocate; 19985e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_WRITE Write; 20085e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_RESTART Restart; 20185e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_ABORT Abort; 20285e923a52851b242f8fc9f937c1fad7ce51246eelgao EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE GetLastWrite; 20385e923a52851b242f8fc9f937c1fad7ce51246eelgao}; 20485e923a52851b242f8fc9f937c1fad7ce51246eelgao 20585e923a52851b242f8fc9f937c1fad7ce51246eelgaoextern EFI_GUID gEfiFaultTolerantWriteProtocolGuid; 20685e923a52851b242f8fc9f937c1fad7ce51246eelgao 20785e923a52851b242f8fc9f937c1fad7ce51246eelgao#endif 208