[mirror_edk2.git] / MdeModulePkg / Universal / FirmwareVolume / FaultTolerantWriteDxe / FtwLite.h

/** @file\r
\r
  The internal header file includes the common header files, defines\r
  internal structure and functions used by FtwLite module.\r
\r
Copyright (c) 2006 - 2008, 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
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
**/\r
\r
#ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
#define _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
\r
\r
#include <PiDxe.h>\r
\r
#include <Guid/SystemNvDataGuid.h>\r
#include <Protocol/FaultTolerantWriteLite.h>\r
#include <Protocol/FirmwareVolumeBlock.h>\r
\r
#include <Library/PcdLib.h>\r
#include <Library/DebugLib.h>\r
#include <Library/UefiDriverEntryPoint.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
#include <Library/UefiBootServicesTableLib.h>\r
#include <Library/DevicePathLib.h>\r
\r
#include <WorkingBlockHeader.h>\r
\r
//\r
// Flash erase polarity is 1\r
//\r
#define FTW_ERASE_POLARITY  1\r
\r
#define FTW_VALID_STATE     0\r
#define FTW_INVALID_STATE   1\r
\r
#define FTW_ERASED_BYTE     ((UINT8) (255))\r
#define FTW_POLARITY_REVERT ((UINT8) (255))\r
\r
typedef struct {\r
  UINT8         WriteAllocated : 1;\r
  UINT8         SpareCompleted : 1;\r
  UINT8         WriteCompleted : 1;\r
  UINT8         Reserved : 5;\r
#define WRITE_ALLOCATED 0x1\r
#define SPARE_COMPLETED 0x2\r
#define WRITE_COMPLETED 0x4\r
\r
  EFI_DEV_PATH  DevPath;\r
  EFI_LBA       Lba;\r
  UINTN         Offset;\r
  UINTN         NumBytes;\r
  //\r
  // UINTN           SpareAreaOffset;\r
  //\r
} EFI_FTW_LITE_RECORD;\r
\r
#define FTW_LITE_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'L')\r
\r
//\r
// MACRO for FTW header and record\r
//\r
#define FTW_LITE_RECORD_SIZE    (sizeof (EFI_FTW_LITE_RECORD))\r
\r
//\r
// EFI Fault tolerant protocol private data structure\r
//\r
typedef struct {\r
  UINTN                                   Signature;\r
  EFI_HANDLE                              Handle;\r
  EFI_FTW_LITE_PROTOCOL                   FtwLiteInstance;\r
  EFI_PHYSICAL_ADDRESS                    WorkSpaceAddress;   // Base address of working space range in flash.\r
  UINTN                                   WorkSpaceLength;    // Size of working space range in flash.\r
  EFI_PHYSICAL_ADDRESS                    SpareAreaAddress;   // Base address of spare range in flash.\r
  UINTN                                   SpareAreaLength;    // Size of spare range in flash.\r
  UINTN                                   NumberOfSpareBlock; // Number of the blocks in spare block.\r
  UINTN                                   BlockSize;          // Block size in bytes of the blocks in flash\r
  EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;// Pointer to Working Space Header in memory buffer\r
  EFI_FTW_LITE_RECORD                     *FtwLastRecord;     // Pointer to last record in memory buffer\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *FtwFvBlock;        // FVB of working block\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *FtwBackupFvb;      // FVB of spare block\r
  EFI_LBA                                 FtwSpareLba;        // Start LBA of spare block\r
  EFI_LBA                                 FtwWorkBlockLba;    // Start LBA of working block that contains working space in its last block.\r
  EFI_LBA                                 FtwWorkSpaceLba;    // Start LBA of working space\r
  UINTN                                   FtwWorkSpaceBase;   // Offset into the FtwWorkSpaceLba block.\r
  UINTN                                   FtwWorkSpaceSize;   // Size of working space range that stores write record.\r
  UINT8                                   *FtwWorkSpace;      // Point to Work Space in memory buffer \r
  //\r
  // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],\r
  // Allocated with EFI_FTW_LITE_DEVICE.\r
  //\r
} EFI_FTW_LITE_DEVICE;\r
\r
#define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)\r
\r
//\r
// Driver entry point\r
//\r
/**\r
  This function is the entry point of the Fault Tolerant Write driver.\r
\r
\r
  @param ImageHandle     A handle for the image that is initializing\r
                         this driver\r
  @param SystemTable     A pointer to the EFI system table\r
\r
  @retval  EFI_SUCCESS            FTW has finished the initialization\r
  @retval  EFI_ABORTED            FTW initialization error\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitializeFtwLite (\r
  IN EFI_HANDLE                 ImageHandle,\r
  IN EFI_SYSTEM_TABLE           *SystemTable\r
  );\r
\r
//\r
// Fault Tolerant Write Protocol API\r
//\r
/**\r
  Starts a target block update. This function will record data about write\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
\r
  @param This            Calling context\r
  @param FvbHandle       The handle of FVB protocol that provides services for\r
                         reading, writing, and erasing the target block.\r
  @param Lba             The logical block address of the target block.\r
  @param Offset          The offset within the target block to place the data.\r
  @param NumBytes        The number of bytes to write to the target block.\r
  @param Buffer          The data to write.\r
\r
  @retval  EFI_SUCCESS           The function completed successfully\r
  @retval  EFI_BAD_BUFFER_SIZE   The write would span a target block, which is not\r
                                 a valid action.\r
  @retval  EFI_ACCESS_DENIED     No writes have been allocated.\r
  @retval  EFI_NOT_FOUND         Cannot find FVB by handle.\r
  @retval  EFI_OUT_OF_RESOURCES  Cannot allocate memory.\r
  @retval  EFI_ABORTED           The function could not complete successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FtwLiteWrite (\r
  IN EFI_FTW_LITE_PROTOCOL                      *This,\r
  IN EFI_HANDLE                                 FvbHandle,\r
  IN EFI_LBA                                    Lba,\r
  IN UINTN                                      Offset,\r
  IN OUT UINTN                                 *NumBytes,\r
  IN VOID                                       *Buffer\r
  );\r
\r
//\r
// Internal functions\r
//\r
/**\r
  Restarts a previously interrupted write. The caller must provide the\r
  block protocol needed to complete the interrupted write.\r
\r
\r
  @param FtwLiteDevice   The private data of FTW_LITE driver\r
                         FvbHandle           - The handle of FVB protocol that provides services for\r
                         reading, writing, and erasing the target block.\r
\r
  @retval  EFI_SUCCESS          The function completed successfully\r
  @retval  EFI_ACCESS_DENIED    No pending writes exist\r
  @retval  EFI_NOT_FOUND        FVB protocol not found by the handle\r
  @retval  EFI_ABORTED          The function could not complete successfully\r
\r
**/\r
EFI_STATUS\r
FtwRestart (\r
  IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice\r
  );\r
\r
/**\r
  Aborts all previous allocated writes.\r
\r
\r
  @param FtwLiteDevice   The private data of FTW_LITE driver\r
\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
EFI_STATUS\r
FtwAbort (\r
  IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice\r
  );\r
\r
\r
/**\r
  Write a record with fault tolerant mannaer.\r
  Since the content has already backuped in spare block, the write is\r
  guaranteed to be completed with fault tolerant manner.\r
\r
\r
  @param FtwLiteDevice   The private data of FTW_LITE driver\r
  @param Fvb             The FVB protocol that provides services for\r
                         reading, writing, and erasing the target block.\r
\r
  @retval  EFI_SUCCESS          The function completed successfully\r
  @retval  EFI_ABORTED          The function could not complete successfully\r
\r
**/\r
EFI_STATUS\r
FtwWriteRecord (\r
  IN EFI_FTW_LITE_DEVICE                   *FtwLiteDevice,\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *Fvb\r
  );\r
\r
/**\r
  To erase the block with the spare block size.\r
\r
\r
  @param FtwLiteDevice   Calling context\r
  @param FvBlock         FVB Protocol interface\r
  @param Lba             Lba of the firmware block\r
\r
  @retval  EFI_SUCCESS    Block LBA is Erased successfully\r
  @retval  Others         Error occurs\r
\r
**/\r
EFI_STATUS\r
FtwEraseBlock (\r
  IN EFI_FTW_LITE_DEVICE              *FtwLiteDevice,\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,\r
  EFI_LBA                             Lba\r
  );\r
\r
/**\r
\r
  Erase spare block.\r
\r
\r
  @param FtwLiteDevice   Calling context\r
\r
  @retval EFI_SUCCESS The erase request was successfully\r
                      completed.\r
  \r
  @retval EFI_ACCESS_DENIED   The firmware volume is in the\r
                              WriteDisabled state.\r
  @retval EFI_DEVICE_ERROR  The block device is not functioning\r
                            correctly and could not be written.\r
                            The firmware device may have been\r
                            partially erased.\r
  @retval EFI_INVALID_PARAMETER One or more of the LBAs listed\r
                                in the variable argument list do\r
                                not exist in the firmware volume.  \r
\r
**/\r
EFI_STATUS\r
FtwEraseSpareBlock (\r
  IN EFI_FTW_LITE_DEVICE   *FtwLiteDevice\r
  );\r
\r
/**\r
  Retrive the proper FVB protocol interface by HANDLE.\r
\r
\r
  @param FvBlockHandle   The handle of FVB protocol that provides services for\r
                         reading, writing, and erasing the target block.\r
  @param FvBlock         The interface of FVB protocol\r
\r
  @retval  EFI_SUCCESS          The function completed successfully\r
  @retval  EFI_ABORTED          The function could not complete successfully\r
\r
**/\r
EFI_STATUS\r
FtwGetFvbByHandle (\r
  IN EFI_HANDLE                           FvBlockHandle,\r
  OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock\r
  );\r
\r
/**\r
\r
  Get firmware block by address.\r
\r
\r
  @param Address         Address specified the block\r
  @param FvBlock         The block caller wanted\r
\r
  @retval  EFI_SUCCESS    The protocol instance if found.\r
  @retval  EFI_NOT_FOUND  Block not found\r
\r
**/\r
EFI_STATUS\r
GetFvbByAddress (\r
  IN  EFI_PHYSICAL_ADDRESS               Address,\r
  OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock\r
  );\r
\r
/**\r
\r
  Is it in working block?\r
\r
\r
  @param FtwLiteDevice   Calling context\r
  @param FvBlock         Fvb protocol instance\r
  @param Lba             The block specified\r
\r
  @return A BOOLEAN value indicating in working block or not.\r
\r
**/\r
BOOLEAN\r
IsInWorkingBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,\r
  EFI_LBA                             Lba\r
  );\r
\r
/**\r
  Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.\r
  Spare block is accessed by FTW backup FVB protocol interface. LBA is\r
  FtwLiteDevice->FtwSpareLba.\r
  Target block is accessed by FvBlock protocol interface. LBA is Lba.\r
\r
\r
  @param FtwLiteDevice   The private data of FTW_LITE driver\r
  @param FvBlock         FVB Protocol interface to access target block\r
  @param Lba             Lba of the target block\r
\r
  @retval  EFI_SUCCESS               Spare block content is copied to target block\r
  @retval  EFI_INVALID_PARAMETER     Input parameter error\r
  @retval  EFI_OUT_OF_RESOURCES      Allocate memory error\r
  @retval  EFI_ABORTED               The function could not complete successfully\r
\r
**/\r
EFI_STATUS\r
FlushSpareBlockToTargetBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,\r
  EFI_LBA                             Lba\r
  );\r
\r
/**\r
  Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.\r
  Spare block is accessed by FTW backup FVB protocol interface. LBA is\r
  FtwLiteDevice->FtwSpareLba.\r
  Working block is accessed by FTW working FVB protocol interface. LBA is\r
  FtwLiteDevice->FtwWorkBlockLba.\r
\r
\r
  @param FtwLiteDevice   The private data of FTW_LITE driver\r
\r
  @retval  EFI_SUCCESS               Spare block content is copied to target block\r
  @retval  EFI_OUT_OF_RESOURCES      Allocate memory error\r
  @retval  EFI_ABORTED               The function could not complete successfully\r
                                     Notes:\r
                                     Since the working block header is important when FTW initializes, the\r
                                     state of the operation should be handled carefully. The Crc value is\r
                                     calculated without STATE element.\r
\r
**/\r
EFI_STATUS\r
FlushSpareBlockToWorkingBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice\r
  );\r
\r
/**\r
  Update a bit of state on a block device. The location of the bit is\r
  calculated by the (Lba, Offset, bit). Here bit is determined by the\r
  the name of a certain bit.\r
\r
\r
  @param FvBlock         FVB Protocol interface to access SrcBlock and DestBlock\r
  @param Lba             Lba of a block\r
  @param Offset          Offset on the Lba\r
  @param NewBit          New value that will override the old value if it can be change\r
\r
  @retval  EFI_SUCCESS    A state bit has been updated successfully\r
  @retval  Others         Access block device error.\r
                          Notes:\r
                          Assume all bits of State are inside the same BYTE.\r
  @retval  EFI_ABORTED    Read block fail\r
\r
**/\r
EFI_STATUS\r
FtwUpdateFvState (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,\r
  IN EFI_LBA                             Lba,\r
  IN UINTN                               Offset,\r
  IN UINT8                               NewBit\r
  );\r
\r
/**\r
  Get the last Write record pointer.\r
  The last record is the record whose 'complete' state hasn't been set.\r
  After all, this header may be a EMPTY header entry for next Allocate.\r
\r
\r
  @param FtwLiteDevice   Private data of this driver\r
  @param FtwLastRecord   Pointer to retrieve the last write record\r
\r
  @retval  EFI_SUCCESS      Get the last write record successfully\r
  @retval  EFI_ABORTED      The FTW work space is damaged\r
\r
**/\r
EFI_STATUS\r
FtwGetLastRecord (\r
  IN  EFI_FTW_LITE_DEVICE  *FtwLiteDevice,\r
  OUT EFI_FTW_LITE_RECORD  **FtwLastRecord\r
  );\r
\r
/**\r
\r
  Check whether a flash buffer is erased.\r
\r
\r
  @param Polarity        All 1 or all 0\r
  @param Buffer          Buffer to check\r
  @param BufferSize      Size of the buffer\r
\r
  @return A BOOLEAN value indicating erased or not.\r
\r
**/\r
BOOLEAN\r
IsErasedFlashBuffer (\r
  IN BOOLEAN         Polarity,\r
  IN UINT8           *Buffer,\r
  IN UINTN           BufferSize\r
  );\r
\r
/**\r
  Initialize a work space when there is no work space.\r
\r
\r
  @param WorkingHeader   Pointer of working block header\r
\r
  @retval  EFI_SUCCESS    The function completed successfully\r
  @retval  EFI_ABORTED    The function could not complete successfully.\r
\r
**/\r
EFI_STATUS\r
InitWorkSpaceHeader (\r
  IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
  );\r
\r
/**\r
  Read from working block to refresh the work space in memory.\r
\r
\r
  @param FtwLiteDevice   Point to private data of FTW driver\r
\r
  @retval  EFI_SUCCESS    The function completed successfully\r
  @retval  EFI_ABORTED    The function could not complete successfully.\r
\r
**/\r
EFI_STATUS\r
WorkSpaceRefresh (\r
  IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice\r
  );\r
\r
/**\r
  Check to see if it is a valid work space.\r
\r
\r
  @param WorkingHeader   Pointer of working block header\r
\r
  @retval  EFI_SUCCESS    The function completed successfully\r
  @retval  EFI_ABORTED    The function could not complete successfully.\r
\r
**/\r
BOOLEAN\r
IsValidWorkSpace (\r
  IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
  );\r
\r
/**\r
  Reclaim the work space on the working block.\r
\r
\r
  @param FtwLiteDevice   Point to private data of FTW driver\r
  @param PreserveRecord  Whether to preserve the working record is needed\r
\r
  @retval  EFI_SUCCESS            The function completed successfully\r
  @retval  EFI_OUT_OF_RESOURCES   Allocate memory error\r
  @retval  EFI_ABORTED            The function could not complete successfully\r
\r
**/\r
EFI_STATUS\r
FtwReclaimWorkSpace (\r
  IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice,\r
  IN BOOLEAN              PreserveRecord\r
  );\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	\r
	3	The internal header file includes the common header files, defines\r
	4	internal structure and functions used by FtwLite module.\r
	5	\r
	6	Copyright (c) 2006 - 2008, Intel Corporation \r
	7	All rights reserved. This program and the accompanying materials \r
	8	are licensed and made available under the terms and conditions of the BSD License \r
	9	which accompanies this distribution. The full text of the license may be found at \r
	10	http://opensource.org/licenses/bsd-license.php \r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	14	\r
	15	**/\r
	16	\r
	17	#ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
	18	#define _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
	19	\r
	20	\r
	21	#include <PiDxe.h>\r
	22	\r
	23	#include <Guid/SystemNvDataGuid.h>\r
	24	#include <Protocol/FaultTolerantWriteLite.h>\r
	25	#include <Protocol/FirmwareVolumeBlock.h>\r
	26	\r
	27	#include <Library/PcdLib.h>\r
	28	#include <Library/DebugLib.h>\r
	29	#include <Library/UefiDriverEntryPoint.h>\r
	30	#include <Library/BaseMemoryLib.h>\r
	31	#include <Library/MemoryAllocationLib.h>\r
	32	#include <Library/UefiBootServicesTableLib.h>\r
	33	#include <Library/DevicePathLib.h>\r
	34	\r
	35	#include <WorkingBlockHeader.h>\r
	36	\r
	37	//\r
	38	// Flash erase polarity is 1\r
	39	//\r
	40	#define FTW_ERASE_POLARITY 1\r
	41	\r
	42	#define FTW_VALID_STATE 0\r
	43	#define FTW_INVALID_STATE 1\r
	44	\r
	45	#define FTW_ERASED_BYTE ((UINT8) (255))\r
	46	#define FTW_POLARITY_REVERT ((UINT8) (255))\r
	47	\r
	48	typedef struct {\r
	49	UINT8 WriteAllocated : 1;\r
	50	UINT8 SpareCompleted : 1;\r
	51	UINT8 WriteCompleted : 1;\r
	52	UINT8 Reserved : 5;\r
	53	#define WRITE_ALLOCATED 0x1\r
	54	#define SPARE_COMPLETED 0x2\r
	55	#define WRITE_COMPLETED 0x4\r
	56	\r
	57	EFI_DEV_PATH DevPath;\r
	58	EFI_LBA Lba;\r
	59	UINTN Offset;\r
	60	UINTN NumBytes;\r
	61	//\r
	62	// UINTN SpareAreaOffset;\r
	63	//\r
	64	} EFI_FTW_LITE_RECORD;\r
	65	\r
	66	#define FTW_LITE_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'L')\r
	67	\r
	68	//\r
	69	// MACRO for FTW header and record\r
	70	//\r
	71	#define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))\r
	72	\r
	73	//\r
	74	// EFI Fault tolerant protocol private data structure\r
	75	//\r
	76	typedef struct {\r
	77	UINTN Signature;\r
	78	EFI_HANDLE Handle;\r
	79	EFI_FTW_LITE_PROTOCOL FtwLiteInstance;\r
	80	EFI_PHYSICAL_ADDRESS WorkSpaceAddress; // Base address of working space range in flash.\r
	81	UINTN WorkSpaceLength; // Size of working space range in flash.\r
	82	EFI_PHYSICAL_ADDRESS SpareAreaAddress; // Base address of spare range in flash.\r
	83	UINTN SpareAreaLength; // Size of spare range in flash.\r
	84	UINTN NumberOfSpareBlock; // Number of the blocks in spare block.\r
	85	UINTN BlockSize; // Block size in bytes of the blocks in flash\r
	86	EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;// Pointer to Working Space Header in memory buffer\r
	87	EFI_FTW_LITE_RECORD *FtwLastRecord; // Pointer to last record in memory buffer\r
	88	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwFvBlock; // FVB of working block\r
	89	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwBackupFvb; // FVB of spare block\r
	90	EFI_LBA FtwSpareLba; // Start LBA of spare block\r
	91	EFI_LBA FtwWorkBlockLba; // Start LBA of working block that contains working space in its last block.\r
	92	EFI_LBA FtwWorkSpaceLba; // Start LBA of working space\r
	93	UINTN FtwWorkSpaceBase; // Offset into the FtwWorkSpaceLba block.\r
	94	UINTN FtwWorkSpaceSize; // Size of working space range that stores write record.\r
	95	UINT8 *FtwWorkSpace; // Point to Work Space in memory buffer \r
	96	//\r
	97	// Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],\r
	98	// Allocated with EFI_FTW_LITE_DEVICE.\r
	99	//\r
	100	} EFI_FTW_LITE_DEVICE;\r
	101	\r
	102	#define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)\r
	103	\r
	104	//\r
	105	// Driver entry point\r
	106	//\r
	107	/**\r
	108	This function is the entry point of the Fault Tolerant Write driver.\r
	109	\r
	110	\r
	111	@param ImageHandle A handle for the image that is initializing\r
	112	this driver\r
	113	@param SystemTable A pointer to the EFI system table\r
	114	\r
	115	@retval EFI_SUCCESS FTW has finished the initialization\r
	116	@retval EFI_ABORTED FTW initialization error\r
	117	\r
	118	**/\r
	119	EFI_STATUS\r
	120	EFIAPI\r
	121	InitializeFtwLite (\r
	122	IN EFI_HANDLE ImageHandle,\r
	123	IN EFI_SYSTEM_TABLE *SystemTable\r
	124	);\r
	125	\r
	126	//\r
	127	// Fault Tolerant Write Protocol API\r
	128	//\r
	129	/**\r
	130	Starts a target block update. This function will record data about write\r
	131	in fault tolerant storage and will complete the write in a recoverable\r
	132	manner, ensuring at all times that either the original contents or\r
	133	the modified contents are available.\r
	134	\r
	135	\r
	136	@param This Calling context\r
	137	@param FvbHandle The handle of FVB protocol that provides services for\r
	138	reading, writing, and erasing the target block.\r
	139	@param Lba The logical block address of the target block.\r
	140	@param Offset The offset within the target block to place the data.\r
	141	@param NumBytes The number of bytes to write to the target block.\r
	142	@param Buffer The data to write.\r
	143	\r
	144	@retval EFI_SUCCESS The function completed successfully\r
	145	@retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not\r
	146	a valid action.\r
	147	@retval EFI_ACCESS_DENIED No writes have been allocated.\r
	148	@retval EFI_NOT_FOUND Cannot find FVB by handle.\r
	149	@retval EFI_OUT_OF_RESOURCES Cannot allocate memory.\r
	150	@retval EFI_ABORTED The function could not complete successfully.\r
	151	\r
	152	**/\r
	153	EFI_STATUS\r
	154	EFIAPI\r
	155	FtwLiteWrite (\r
	156	IN EFI_FTW_LITE_PROTOCOL *This,\r
	157	IN EFI_HANDLE FvbHandle,\r
	158	IN EFI_LBA Lba,\r
	159	IN UINTN Offset,\r
	160	IN OUT UINTN *NumBytes,\r
	161	IN VOID *Buffer\r
	162	);\r
	163	\r
	164	//\r
	165	// Internal functions\r
	166	//\r
	167	/**\r
	168	Restarts a previously interrupted write. The caller must provide the\r
	169	block protocol needed to complete the interrupted write.\r
	170	\r
	171	\r
	172	@param FtwLiteDevice The private data of FTW_LITE driver\r
	173	FvbHandle - The handle of FVB protocol that provides services for\r
	174	reading, writing, and erasing the target block.\r
	175	\r
	176	@retval EFI_SUCCESS The function completed successfully\r
	177	@retval EFI_ACCESS_DENIED No pending writes exist\r
	178	@retval EFI_NOT_FOUND FVB protocol not found by the handle\r
	179	@retval EFI_ABORTED The function could not complete successfully\r
	180	\r
	181	**/\r
	182	EFI_STATUS\r
	183	FtwRestart (\r
	184	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
	185	);\r
	186	\r
	187	/**\r
	188	Aborts all previous allocated writes.\r
	189	\r
	190	\r
	191	@param FtwLiteDevice The private data of FTW_LITE driver\r
	192	\r
	193	@retval EFI_SUCCESS The function completed successfully\r
	194	@retval EFI_ABORTED The function could not complete successfully.\r
	195	@retval EFI_NOT_FOUND No allocated writes exist.\r
	196	\r
	197	**/\r
	198	EFI_STATUS\r
	199	FtwAbort (\r
	200	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
	201	);\r
	202	\r
	203	\r
	204	/**\r
	205	Write a record with fault tolerant mannaer.\r
	206	Since the content has already backuped in spare block, the write is\r
	207	guaranteed to be completed with fault tolerant manner.\r
	208	\r
	209	\r
	210	@param FtwLiteDevice The private data of FTW_LITE driver\r
	211	@param Fvb The FVB protocol that provides services for\r
	212	reading, writing, and erasing the target block.\r
	213	\r
	214	@retval EFI_SUCCESS The function completed successfully\r
	215	@retval EFI_ABORTED The function could not complete successfully\r
	216	\r
	217	**/\r
	218	EFI_STATUS\r
	219	FtwWriteRecord (\r
	220	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	221	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb\r
	222	);\r
	223	\r
	224	/**\r
	225	To erase the block with the spare block size.\r
	226	\r
	227	\r
	228	@param FtwLiteDevice Calling context\r
	229	@param FvBlock FVB Protocol interface\r
	230	@param Lba Lba of the firmware block\r
	231	\r
	232	@retval EFI_SUCCESS Block LBA is Erased successfully\r
	233	@retval Others Error occurs\r
	234	\r
	235	**/\r
	236	EFI_STATUS\r
	237	FtwEraseBlock (\r
	238	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	239	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
	240	EFI_LBA Lba\r
	241	);\r
	242	\r
	243	/**\r
	244	\r
	245	Erase spare block.\r
	246	\r
	247	\r
	248	@param FtwLiteDevice Calling context\r
	249	\r
	250	@retval EFI_SUCCESS The erase request was successfully\r
	251	completed.\r
	252	\r
	253	@retval EFI_ACCESS_DENIED The firmware volume is in the\r
	254	WriteDisabled state.\r
	255	@retval EFI_DEVICE_ERROR The block device is not functioning\r
	256	correctly and could not be written.\r
	257	The firmware device may have been\r
	258	partially erased.\r
	259	@retval EFI_INVALID_PARAMETER One or more of the LBAs listed\r
	260	in the variable argument list do\r
	261	not exist in the firmware volume. \r
	262	\r
	263	**/\r
	264	EFI_STATUS\r
	265	FtwEraseSpareBlock (\r
	266	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
	267	);\r
	268	\r
	269	/**\r
	270	Retrive the proper FVB protocol interface by HANDLE.\r
	271	\r
	272	\r
	273	@param FvBlockHandle The handle of FVB protocol that provides services for\r
	274	reading, writing, and erasing the target block.\r
	275	@param FvBlock The interface of FVB protocol\r
	276	\r
	277	@retval EFI_SUCCESS The function completed successfully\r
	278	@retval EFI_ABORTED The function could not complete successfully\r
	279	\r
	280	**/\r
	281	EFI_STATUS\r
	282	FtwGetFvbByHandle (\r
	283	IN EFI_HANDLE FvBlockHandle,\r
	284	OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock\r
	285	);\r
	286	\r
	287	/**\r
	288	\r
	289	Get firmware block by address.\r
	290	\r
	291	\r
	292	@param Address Address specified the block\r
	293	@param FvBlock The block caller wanted\r
	294	\r
	295	@retval EFI_SUCCESS The protocol instance if found.\r
	296	@retval EFI_NOT_FOUND Block not found\r
	297	\r
	298	**/\r
	299	EFI_STATUS\r
	300	GetFvbByAddress (\r
	301	IN EFI_PHYSICAL_ADDRESS Address,\r
	302	OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock\r
	303	);\r
	304	\r
	305	/**\r
	306	\r
	307	Is it in working block?\r
	308	\r
	309	\r
	310	@param FtwLiteDevice Calling context\r
	311	@param FvBlock Fvb protocol instance\r
	312	@param Lba The block specified\r
	313	\r
	314	@return A BOOLEAN value indicating in working block or not.\r
	315	\r
	316	**/\r
	317	BOOLEAN\r
	318	IsInWorkingBlock (\r
	319	EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	320	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
	321	EFI_LBA Lba\r
	322	);\r
	323	\r
	324	/**\r
	325	Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.\r
	326	Spare block is accessed by FTW backup FVB protocol interface. LBA is\r
	327	FtwLiteDevice->FtwSpareLba.\r
	328	Target block is accessed by FvBlock protocol interface. LBA is Lba.\r
	329	\r
	330	\r
	331	@param FtwLiteDevice The private data of FTW_LITE driver\r
	332	@param FvBlock FVB Protocol interface to access target block\r
	333	@param Lba Lba of the target block\r
	334	\r
	335	@retval EFI_SUCCESS Spare block content is copied to target block\r
	336	@retval EFI_INVALID_PARAMETER Input parameter error\r
	337	@retval EFI_OUT_OF_RESOURCES Allocate memory error\r
	338	@retval EFI_ABORTED The function could not complete successfully\r
	339	\r
	340	**/\r
	341	EFI_STATUS\r
	342	FlushSpareBlockToTargetBlock (\r
	343	EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	344	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
	345	EFI_LBA Lba\r
	346	);\r
	347	\r
	348	/**\r
	349	Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.\r
	350	Spare block is accessed by FTW backup FVB protocol interface. LBA is\r
	351	FtwLiteDevice->FtwSpareLba.\r
	352	Working block is accessed by FTW working FVB protocol interface. LBA is\r
	353	FtwLiteDevice->FtwWorkBlockLba.\r
	354	\r
	355	\r
	356	@param FtwLiteDevice The private data of FTW_LITE driver\r
	357	\r
	358	@retval EFI_SUCCESS Spare block content is copied to target block\r
	359	@retval EFI_OUT_OF_RESOURCES Allocate memory error\r
	360	@retval EFI_ABORTED The function could not complete successfully\r
	361	Notes:\r
	362	Since the working block header is important when FTW initializes, the\r
	363	state of the operation should be handled carefully. The Crc value is\r
	364	calculated without STATE element.\r
	365	\r
	366	**/\r
	367	EFI_STATUS\r
	368	FlushSpareBlockToWorkingBlock (\r
	369	EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
	370	);\r
	371	\r
	372	/**\r
	373	Update a bit of state on a block device. The location of the bit is\r
	374	calculated by the (Lba, Offset, bit). Here bit is determined by the\r
	375	the name of a certain bit.\r
	376	\r
	377	\r
	378	@param FvBlock FVB Protocol interface to access SrcBlock and DestBlock\r
	379	@param Lba Lba of a block\r
	380	@param Offset Offset on the Lba\r
	381	@param NewBit New value that will override the old value if it can be change\r
	382	\r
	383	@retval EFI_SUCCESS A state bit has been updated successfully\r
	384	@retval Others Access block device error.\r
	385	Notes:\r
	386	Assume all bits of State are inside the same BYTE.\r
	387	@retval EFI_ABORTED Read block fail\r
	388	\r
	389	**/\r
	390	EFI_STATUS\r
	391	FtwUpdateFvState (\r
	392	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
	393	IN EFI_LBA Lba,\r
	394	IN UINTN Offset,\r
	395	IN UINT8 NewBit\r
	396	);\r
	397	\r
	398	/**\r
	399	Get the last Write record pointer.\r
	400	The last record is the record whose 'complete' state hasn't been set.\r
	401	After all, this header may be a EMPTY header entry for next Allocate.\r
	402	\r
	403	\r
	404	@param FtwLiteDevice Private data of this driver\r
	405	@param FtwLastRecord Pointer to retrieve the last write record\r
	406	\r
	407	@retval EFI_SUCCESS Get the last write record successfully\r
	408	@retval EFI_ABORTED The FTW work space is damaged\r
	409	\r
	410	**/\r
	411	EFI_STATUS\r
	412	FtwGetLastRecord (\r
	413	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	414	OUT EFI_FTW_LITE_RECORD **FtwLastRecord\r
	415	);\r
	416	\r
	417	/**\r
	418	\r
	419	Check whether a flash buffer is erased.\r
	420	\r
	421	\r
	422	@param Polarity All 1 or all 0\r
	423	@param Buffer Buffer to check\r
	424	@param BufferSize Size of the buffer\r
	425	\r
	426	@return A BOOLEAN value indicating erased or not.\r
	427	\r
	428	**/\r
	429	BOOLEAN\r
	430	IsErasedFlashBuffer (\r
	431	IN BOOLEAN Polarity,\r
	432	IN UINT8 *Buffer,\r
	433	IN UINTN BufferSize\r
	434	);\r
	435	\r
	436	/**\r
	437	Initialize a work space when there is no work space.\r
	438	\r
	439	\r
	440	@param WorkingHeader Pointer of working block header\r
	441	\r
	442	@retval EFI_SUCCESS The function completed successfully\r
	443	@retval EFI_ABORTED The function could not complete successfully.\r
	444	\r
	445	**/\r
	446	EFI_STATUS\r
	447	InitWorkSpaceHeader (\r
	448	IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
	449	);\r
	450	\r
	451	/**\r
	452	Read from working block to refresh the work space in memory.\r
	453	\r
	454	\r
	455	@param FtwLiteDevice Point to private data of FTW driver\r
	456	\r
	457	@retval EFI_SUCCESS The function completed successfully\r
	458	@retval EFI_ABORTED The function could not complete successfully.\r
	459	\r
	460	**/\r
	461	EFI_STATUS\r
	462	WorkSpaceRefresh (\r
	463	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
	464	);\r
	465	\r
	466	/**\r
	467	Check to see if it is a valid work space.\r
	468	\r
	469	\r
	470	@param WorkingHeader Pointer of working block header\r
	471	\r
	472	@retval EFI_SUCCESS The function completed successfully\r
	473	@retval EFI_ABORTED The function could not complete successfully.\r
	474	\r
	475	**/\r
	476	BOOLEAN\r
	477	IsValidWorkSpace (\r
	478	IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
	479	);\r
	480	\r
	481	/**\r
	482	Reclaim the work space on the working block.\r
	483	\r
	484	\r
	485	@param FtwLiteDevice Point to private data of FTW driver\r
	486	@param PreserveRecord Whether to preserve the working record is needed\r
	487	\r
	488	@retval EFI_SUCCESS The function completed successfully\r
	489	@retval EFI_OUT_OF_RESOURCES Allocate memory error\r
	490	@retval EFI_ABORTED The function could not complete successfully\r
	491	\r
	492	**/\r
	493	EFI_STATUS\r
	494	FtwReclaimWorkSpace (\r
	495	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
	496	IN BOOLEAN PreserveRecord\r
	497	);\r
	498	\r
	499	#endif\r