Add full version FaultTolerantWrite Dxe driver.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7787 6f19259b-4bc3-4df7-8a09-765794883524

2 files changed, 389 insertions, 0 deletions

diff --git a/MdeModulePkg/Include/Protocol/FaultTolerantWrite.h b/MdeModulePkg/Include/Protocol/FaultTolerantWrite.h
new file mode 100644
index 0000000000..d673627249
--- /dev/null
+++ b/MdeModulePkg/Include/Protocol/FaultTolerantWrite.h
@@ -0,0 +1,207 @@
+/** @file

+Fault Tolerant Write protocol provides boot-time service to do fault tolerant 

+write capability for block devices.  The protocol provides for non-volatile 

+intermediate storage of the data and private information a caller would need to 

+recover from a critical fault, such as power failure.   

+

+Copyright (c) 2009, Intel Corporation                                                         

+All rights reserved. This program and the accompanying materials                          

+are licensed and made available under the terms and conditions of the BSD License         

+which accompanies this distribution.  The full text of the license may be found at        

+http://opensource.org/licenses/bsd-license.php                                            

+                                                                                          

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 

+

+**/

+

+#ifndef _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_

+#define _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_

+

+#define EFI_FAULT_TOLERANT_WRITE_PROTOCOL_GUID \

+  { \

+    0x3ebd9e82, 0x2c78, 0x4de6, {0x97, 0x86, 0x8d, 0x4b, 0xfc, 0xb7, 0xc8, 0x81 } \

+  }

+

+//

+// Forward reference for pure ANSI compatability

+//

+typedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL  EFI_FAULT_TOLERANT_WRITE_PROTOCOL;

+

+/**

+  Query the largest block that may be updated in a fault tolerant manner.

+

+  @param  This                 Indicates a pointer to the calling context.

+  @param  BlockSize            A pointer to a caller allocated UINTN that is

+                               updated to  indicate the size of the largest block

+                               that can be updated.

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    * This,

+  OUT UINTN                               *BlockSize

+  );

+

+/**

+  Allocates space for the protocol to maintain information about writes.

+  Since writes must be completed in a fault tolerant manner and multiple

+  updates will require more resources to be successful, this function

+  enables the protocol to ensure that enough space exists to track

+  information about the upcoming writes.

+

+  @param  This                 Indicates a pointer to the calling context.

+  @param  CallerId             The GUID identifying the write.

+  @param  PrivateDataSize      The size of the caller's private data  that must be

+                               recorded for each write.

+  @param  NumberOfWrites       The number of fault tolerant block writes  that will

+                               need to occur.

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+  @retval EFI_ACCESS_DENIED    All allocated writes have not been completed.   All

+                               writes must be completed or aborted before  another

+                               fault tolerant write can occur.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    * This,

+  IN EFI_GUID                             * CallerId,

+  IN UINTN                                PrivateDataSize,

+  IN UINTN                                NumberOfWrites

+  );

+

+/**

+  Starts a target block update. This records information about the write

+  in fault tolerant storage and will complete the write in a recoverable

+  manner, ensuring at all times that either the original contents or

+  the modified contents are available.

+

+  @param  This                 Calling context

+  @param  Lba                  The logical block address of the target block.

+  @param  Offset               The offset within the target block to place the

+                               data.

+  @param  Length               The number of bytes to write to the target block.

+  @param  PrivateData          A pointer to private data that the caller requires

+                               to  complete any pending writes in the event of a

+                               fault.

+  @param  FvBlockHandle        The handle of FVB protocol that provides services

+                               for  reading, writing, and erasing the target block.

+  @param  Buffer               The data to write.

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+  @retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary,  which is not

+                               a valid action.

+  @retval EFI_ACCESS_DENIED    No writes have been allocated.

+  @retval EFI_NOT_READY        The last write has not been completed.   Restart ()

+                               must be called to complete it.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,

+  IN EFI_LBA                               Lba,

+  IN UINTN                                 Offset,

+  IN UINTN                                 Length,

+  IN VOID                                  *PrivateData,

+  IN EFI_HANDLE                            FvbHandle,

+  IN VOID                                  *Buffer

+  );

+

+/**

+  Restarts a previously interrupted write. The caller must provide the

+  block protocol needed to complete the interrupted write.

+

+  @param  This                 Calling context.

+  @param  FvBlockProtocol      The handle of FVB protocol that provides services

+                               for  reading, writing, and erasing the target block.

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+  @retval EFI_ACCESS_DENIED    No pending writes exist.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,

+  IN EFI_HANDLE                            FvbHandle

+  );

+

+/**

+  Aborts all previous allocated writes.

+

+  @param  This                 Calling context

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+  @retval EFI_NOT_FOUND        No allocated writes exist.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This

+  );

+

+/**

+  Starts a target block update. This records information about the write

+  in fault tolerant storage and will complete the write in a recoverable

+  manner, ensuring at all times that either the original contents or

+  the modified contents are available.

+

+  @param  This                 Indicates a pointer to the calling context.

+  @param  CallerId             The GUID identifying the last write.

+  @param  Lba                  The logical block address of the last write.

+  @param  Offset               The offset within the block of the last write.

+  @param  Length               The length of the last write.

+  @param  PrivateDataSize      On input, the size of the PrivateData buffer.   On

+                               output, the size of the private data stored  for

+                               this write.

+  @param  PrivateData          A pointer to a buffer. The function will copy

+                               PrivateDataSize bytes from the private data  stored

+                               for this write.

+  @param  Complete             A Boolean value with TRUE indicating  that the write

+                               was completed.

+

+  @retval EFI_SUCCESS          The function completed successfully

+  @retval EFI_ABORTED          The function could not complete successfully.

+  @retval EFI_NOT_FOUND        No allocated writes exist.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE) (

+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,

+  OUT EFI_GUID                             * CallerId,

+  OUT EFI_LBA                              *Lba,

+  OUT UINTN                                *Offset,

+  OUT UINTN                                *Length,

+  IN OUT UINTN                             *PrivateDataSize,

+  OUT VOID                                 *PrivateData,

+  OUT BOOLEAN                              *Complete

+  );

+

+//

+// Protocol declaration

+//

+struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL {

+  EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE GetMaxBlockSize;

+  EFI_FAULT_TOLERANT_WRITE_ALLOCATE           Allocate;

+  EFI_FAULT_TOLERANT_WRITE_WRITE              Write;

+  EFI_FAULT_TOLERANT_WRITE_RESTART            Restart;

+  EFI_FAULT_TOLERANT_WRITE_ABORT              Abort;

+  EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE     GetLastWrite;

+};

+

+extern EFI_GUID gEfiFaultTolerantWriteProtocolGuid;

+

+#endif

diff --git a/MdeModulePkg/Include/Protocol/SwapAddressRange.h b/MdeModulePkg/Include/Protocol/SwapAddressRange.h
new file mode 100644
index 0000000000..0aff5835a4
--- /dev/null
+++ b/MdeModulePkg/Include/Protocol/SwapAddressRange.h
@@ -0,0 +1,182 @@
+/** @file

+The EFI_SWAP_ADDRESS_RANGE_PROTOCOL is used to abstract the swap operation of boot block 

+and backup block of FV. This swap is especially needed when updating the boot block of FV. If any 

+power failure happens during updating boot block, the swapped backup block (now is the boot block) 

+can boot the machine with old boot block backuped in it. The swap operation is platform dependent, so 

+other protocols such as FTW (Fault Tolerant Write) should use this protocol instead of handling hardward directly.

+

+Copyright (c) 2009, Intel Corporation                                                         

+All rights reserved. This program and the accompanying materials                          

+are licensed and made available under the terms and conditions of the BSD License         

+which accompanies this distribution.  The full text of the license may be found at        

+http://opensource.org/licenses/bsd-license.php                                            

+                                                                                          

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 

+

+**/

+

+#ifndef _EFI_SWAP_ADDRESS_RANGE_PROTOCOL_H_

+#define _EFI_SWAP_ADDRESS_RANGE_PROTOCOL_H_

+

+#define EFI_SWAP_ADDRESS_RANGE_PROTOCOL_GUID \

+  { \

+    0x1259f60d, 0xb754, 0x468e, {0xa7, 0x89, 0x4d, 0xb8, 0x5d, 0x55, 0xe8, 0x7e } \

+  }

+

+//

+// Forward reference for pure ANSI compatability

+//

+typedef struct _EFI_SWAP_ADDRESS_RANGE_PROTOCOL  EFI_SWAP_ADDRESS_RANGE_PROTOCOL;

+

+#define EFI_UNSUPPORT_LOCK  0

+#define EFI_SOFTWARE_LOCK   1

+#define EFI_HARDWARE_LOCK   2

+

+typedef UINT8 EFI_SWAP_LOCK_CAPABILITY;

+

+//

+// Protocl APIs

+//

+

+/**

+  This service gets the address range location of boot block and backup block.

+  The EFI_GET_RANGE_LOCATION service allows caller to get the range location of 

+  boot block and backup block. 

+

+  @param This		Indicates the calling context.  

+  @param BootBlockBase		Base address of current boot block.

+  @param BootBlockSize	 	Size (in bytes) of current boot block.

+  @param BackupBlockBase		Base address of current backup block.

+  @param BackupBlockSize	 	Size (in bytes) of current backup block.

+

+  @retval EFI_SUCCESS	The call was successful.

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_GET_RANGE_LOCATION) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  OUT EFI_PHYSICAL_ADDRESS                      * BootBlockBase,

+  OUT UINTN                                     *BootBlockSize,

+  OUT EFI_PHYSICAL_ADDRESS                      * BackupBlockBase,

+  OUT UINTN                                     *BackupBlockSize

+  );

+

+/**

+  This service checks if the boot block and backup block has been swapped.

+

+  The EFI_GET_SWAP_STATE service allows caller to get current swap state of boot block and backup block.

+

+  @param This		Indicates the calling context.  

+  @param SwapState	 	True if the boot block and backup block has been swapped. 

+                                   False if the boot block and backup block has not been swapped.

+

+  @retval EFI_SUCCESS	The call was successful.

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_GET_SWAP_STATE) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  OUT BOOLEAN                                   *SwapState

+  );

+

+/**

+  This service swaps the boot block and backup block, or swaps them back.

+

+  The EFI_SET_SWAP_STATE service allows caller to set the swap state of boot block and backup block. 

+  It also acquires and releases software swap lock during operation. Note the setting of new swap state 

+  is not affected by the old swap state.

+

+  @param This		Indicates the calling context.  

+  @param NewSwapState	 	True to swap real boot block and backup block , False to swap them back..

+

+  @retval EFI_SUCCESS	The call was successful.

+  @retval EFI_ABORTED	Set swap state error

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_SET_SWAP_STATE) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  IN BOOLEAN                                    NewSwapState

+  );

+

+

+

+/**

+  This service checks if a RTC (Real Time Clock) power failure happened.

+

+  The EFI_GET_RTC_POWER_STATUS service allows caller to get Real Time Clock power failure status.  

+  If parameter RtcPowerFailed is true after function returns, the trickle current (from the main battery or trickle supply) 

+  has been removed or failed, this means the swap status was lost in some platform (such as IA32). 

+  So it is recommended to check RTC power status before calling GetSwapState().

+

+  @param This   Indicates the calling context.  

+  @param RtcPowerFailed   True if a RTC (Real Time Clock) power failure has happened.

+

+  @retval EFI_SUCCESS The call was successful.

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_GET_RTC_POWER_STATUS) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  OUT BOOLEAN                                   *RtcPowerFailed

+  );

+

+/**

+  This service returns supported lock methods for swap operation in current platform. Could be software lock, hardware lock, or unsupport lock.

+

+  The EFI_GET_SWAP_LOCK_CAPABILITY service allows caller to get supported lock method for swap operation in current platform. 

+  Note that software and hardware lock mothod can be used simultaneously.

+

+  @param This   Indicates the calling context.

+  @param LockCapability	 	Current lock method for swap operation. 

+

+  @retval EFI_SUCCESS The call was successful.

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_GET_SWAP_LOCK_CAPABILITY) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  OUT EFI_SWAP_LOCK_CAPABILITY                  * LockCapability

+  );

+

+

+

+/**

+  This service is used to acquire or release appointed kind of lock for Swap Address Range operation.

+

+  The EFI_GET_SWAP_LOCK_CAPABILITY service allows caller to get supported lock method for swap operation in current platform. 

+  Note that software and hardware lock mothod can be used simultaneously.

+

+  @param This    Indicates the calling context.

+  @param LockCapability    Indicates which lock to acquire or release.

+  @param NewLockState            True to acquire lock, False to release lock.

+

+  @retval EFI_SUCCESS The call was successful.

+    

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_SET_SWAP_LOCK) (

+  IN EFI_SWAP_ADDRESS_RANGE_PROTOCOL            * This,

+  IN EFI_SWAP_LOCK_CAPABILITY                   LockCapability,

+  IN BOOLEAN                                    NewLockState

+  );

+

+struct _EFI_SWAP_ADDRESS_RANGE_PROTOCOL {

+  EFI_GET_RANGE_LOCATION        GetRangeLocation;       // has output parameters for base and length

+  EFI_GET_SWAP_STATE            GetSwapState;           // are ranges swapped or not

+  EFI_SET_SWAP_STATE            SetSwapState;           // swap or unswap ranges

+  EFI_GET_RTC_POWER_STATUS      GetRtcPowerStatus;      // checks RTC battery, or whatever...

+  EFI_GET_SWAP_LOCK_CAPABILITY  GetSwapLockCapability;  // Get TOP_SWAP lock capability,

+  EFI_SET_SWAP_LOCK             SetSwapLock;            // Set TOP_SWAP lock state

+};

+

+extern EFI_GUID gEfiSwapAddressRangeProtocolGuid;

+

+#endif