/** @file\r
-Fault Tolerant Write protocol provides boot-time service to do fault tolerant \r
-write capability for block devices. The protocol provides for non-volatile \r
-intermediate storage of the data and private information a caller would need to \r
-recover from a critical fault, such as power failure. \r
-\r
-Copyright (c) 2009, Intel Corporation \r
-All rights reserved. This program and the accompanying materials \r
-are licensed and made available under the terms and conditions of the BSD License \r
-which accompanies this distribution. The full text of the license may be found at \r
-http://opensource.org/licenses/bsd-license.php \r
- \r
+ Fault Tolerant Write protocol provides boot-time service for fault tolerant \r
+ write capability for block devices. The protocol provides for non-volatile \r
+ storage of the intermediate data and private information a caller would need to \r
+ recover from a critical fault, such as a power failure. \r
+\r
+Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials are licensed and made available under \r
+the terms and conditions of the BSD License that accompanies this distribution. \r
+The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php. \r
+\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
\r
typedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL EFI_FAULT_TOLERANT_WRITE_PROTOCOL;\r
\r
/**\r
- Query the largest block that may be updated in a fault tolerant manner.\r
+ Get the size of the largest block that can be updated in a fault-tolerant manner.\r
\r
@param This Indicates a pointer to the calling context.\r
- @param BlockSize A pointer to a caller allocated UINTN that is\r
- updated to indicate the size of the largest block\r
+ @param BlockSize A pointer to a caller-allocated UINTN that is\r
+ updated to indicate the size of the largest block\r
that can be updated.\r
\r
- @retval EFI_SUCCESS The function completed successfully\r
+ @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_ABORTED The function could not complete successfully.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r
OUT UINTN *BlockSize\r
);\r
\r
/**\r
Allocates space for the protocol to maintain information about writes.\r
- Since writes must be completed in a fault tolerant manner and multiple\r
- updates will require more resources to be successful, this function\r
+ Since writes must be completed in a fault-tolerant manner and multiple\r
+ writes require more resources to be successful, this function\r
enables the protocol to ensure that enough space exists to track\r
- information about the upcoming writes.\r
+ information about upcoming writes.\r
\r
- @param This Indicates a pointer to the calling context.\r
+ @param This A pointer to the calling context.\r
@param CallerId The GUID identifying the write.\r
@param PrivateDataSize The size of the caller's private data that must be\r
recorded for each write.\r
- @param NumberOfWrites The number of fault tolerant block writes that will\r
+ @param NumberOfWrites The number of fault tolerant block writes that will\r
need to occur.\r
\r
@retval EFI_SUCCESS The function completed successfully\r
@retval EFI_ABORTED The function could not complete successfully.\r
- @retval EFI_ACCESS_DENIED All allocated writes have not been completed. All\r
- writes must be completed or aborted before another\r
+ @retval EFI_ACCESS_DENIED Not all allocated writes have been completed. All\r
+ writes must be completed or aborted before another\r
fault tolerant write can occur.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r
IN EFI_GUID * CallerId,\r
IN UINTN PrivateDataSize,\r
\r
/**\r
Starts a target block update. This records information about the write\r
- in fault tolerant storage and will complete the write in a recoverable\r
+ in fault tolerant storage, and will complete the write in a recoverable\r
manner, ensuring at all times that either the original contents or\r
the modified contents are available.\r
\r
- @param This Calling context\r
+ @param This The calling context.\r
@param Lba The logical block address of the target block.\r
@param Offset The offset within the target block to place the\r
data.\r
@param Length The number of bytes to write to the target block.\r
@param PrivateData A pointer to private data that the caller requires\r
- to complete any pending writes in the event of a\r
+ to complete any pending writes in the event of a\r
fault.\r
@param FvBlockHandle The handle of FVB protocol that provides services\r
- for reading, writing, and erasing the target block.\r
+ for reading, writing, and erasing the target block.\r
@param Buffer The data to write.\r
\r
- @retval EFI_SUCCESS The function completed successfully\r
+ @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_ABORTED The function could not complete successfully.\r
- @retval EFI_BAD_BUFFER_SIZE The write would span a block boundary, which is not\r
+ @retval EFI_BAD_BUFFER_SIZE The write would span a block boundary, which is not\r
a valid action.\r
@retval EFI_ACCESS_DENIED No writes have been allocated.\r
- @retval EFI_NOT_READY The last write has not been completed. Restart ()\r
+ @retval EFI_NOT_READY The last write has not been completed. Restart()\r
must be called to complete it.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r
IN EFI_LBA Lba,\r
IN UINTN Offset,\r
Restarts a previously interrupted write. The caller must provide the\r
block protocol needed to complete the interrupted write.\r
\r
- @param This Calling context.\r
- @param FvBlockProtocol The handle of FVB protocol that provides services\r
- for reading, writing, and erasing the target block.\r
+ @param This The calling context.\r
+ @param FvBlockProtocol The handle of FVB protocol that provides services.\r
+ for reading, writing, and erasing the target block.\r
\r
- @retval EFI_SUCCESS The function completed successfully\r
+ @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_ABORTED The function could not complete successfully.\r
@retval EFI_ACCESS_DENIED No pending writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r
IN EFI_HANDLE FvbHandle\r
);\r
\r
/**\r
- Aborts all previous allocated writes.\r
+ Aborts all previously allocated writes.\r
\r
- @param This Calling context\r
+ @param This The calling context.\r
\r
- @retval EFI_SUCCESS The function completed successfully\r
+ @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_ABORTED The function could not complete successfully.\r
@retval EFI_NOT_FOUND No allocated writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This\r
);\r
\r
/**\r
- Starts a target block update. This records information about the write\r
- in fault tolerant storage and will complete the write in a recoverable\r
+ Starts a target block update. This function records information about the write\r
+ in fault-tolerant storage and completes the write in a recoverable\r
manner, ensuring at all times that either the original contents or\r
the modified contents are available.\r
\r
@param Lba The logical block address of the last write.\r
@param Offset The offset within the block of the last write.\r
@param Length The length of the last write.\r
- @param PrivateDataSize On input, the size of the PrivateData buffer. On\r
- output, the size of the private data stored for\r
+ @param PrivateDataSize On input, the size of the PrivateData buffer. On\r
+ output, the size of the private data stored for\r
this write.\r
@param PrivateData A pointer to a buffer. The function will copy\r
- PrivateDataSize bytes from the private data stored\r
+ PrivateDataSize bytes from the private data stored\r
for this write.\r
- @param Complete A Boolean value with TRUE indicating that the write\r
+ @param Complete A Boolean value with TRUE indicating that the write\r
was completed.\r
\r
- @retval EFI_SUCCESS The function completed successfully\r
+ @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_ABORTED The function could not complete successfully.\r
@retval EFI_NOT_FOUND No allocated writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE) (\r
+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE)(\r
IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r
OUT EFI_GUID * CallerId,\r
OUT EFI_LBA *Lba,\r