[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 <Protocol/PciRootBridgeIo.h>\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
\r
#include <WorkingBlockHeader.h>\r
\r
#define EFI_D_FTW_LITE  EFI_D_ERROR\r
#define EFI_D_FTW_INFO  EFI_D_INFO\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 EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')\r
\r
//\r
// MACRO for Block size.\r
// Flash Erasing will do in block granularity.\r
//\r
#ifdef FV_BLOCK_SIZE\r
#define FTW_BLOCK_SIZE  FV_BLOCK_SIZE\r
#else\r
#define FV_BLOCK_SIZE   0x10000\r
#define FTW_BLOCK_SIZE  FV_BLOCK_SIZE\r
#endif\r
//\r
// MACRO for FTW WORK SPACE Base & Size\r
//\r
#ifdef EFI_FTW_WORKING_OFFSET\r
#define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET\r
#else\r
#define FTW_WORK_SPACE_BASE 0x00E000\r
#endif\r
\r
#ifdef EFI_FTW_WORKING_LENGTH\r
#define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH\r
#else\r
#define FTW_WORK_SPACE_SIZE 0x002000\r
#endif\r
//\r
// MACRO for FTW header and record\r
//\r
#define FTW_WORKING_QUEUE_SIZE  (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))\r
#define FTW_LITE_RECORD_SIZE    (sizeof (EFI_FTW_LITE_RECORD))\r
#define WRITE_TOTAL_SIZE        FTW_LITE_RECORD_SIZE\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;\r
  UINTN                                   WorkSpaceLength;\r
  EFI_PHYSICAL_ADDRESS                    SpareAreaAddress;\r
  UINTN                                   SpareAreaLength;\r
  UINTN                                   NumberOfSpareBlock; // Number of the blocks in spare block\r
  UINTN                                   SizeOfSpareBlock;   // Block size in bytes of the blocks in spare block\r
  EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;\r
  EFI_FTW_LITE_RECORD                     *FtwLastRecord;\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;\r
  EFI_LBA                                 FtwWorkBlockLba;    // Start LBA of working block\r
  EFI_LBA                                 FtwWorkSpaceLba;    // Start LBA of working space\r
  UINTN                                   FtwWorkSpaceBase;   // Offset from LBA start addr\r
  UINTN                                   FtwWorkSpaceSize;\r
  UINT8                                   *FtwWorkSpace;\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
EFI_STATUS\r
EFIAPI\r
InitializeFtwLite (\r
  IN EFI_HANDLE                 ImageHandle,\r
  IN EFI_SYSTEM_TABLE           *SystemTable\r
  )\r
/*++\r
\r
Routine Description:\r
    This function is the entry point of the Fault Tolerant Write driver.\r
\r
Arguments:\r
    ImageHandle   - EFI_HANDLE: A handle for the image that is initializing \r
                    this driver\r
    SystemTable   - EFI_SYSTEM_TABLE: A pointer to the EFI system table\r
\r
Returns:\r
    EFI_SUCCESS           - FTW has finished the initialization\r
    EFI_ABORTED           - FTW initialization error\r
\r
--*/\r
;\r
\r
//\r
// Fault Tolerant Write Protocol API\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 UINTN                                 *NumBytes,\r
  IN VOID                                  *Buffer\r
  )\r
/*++\r
\r
Routine Description:\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
Arguments:\r
    This             - Calling context\r
    FvbHandle        - The handle of FVB protocol that provides services for \r
                       reading, writing, and erasing the target block.\r
    Lba              - The logical block address of the target block.  \r
    Offset           - The offset within the target block to place the data.\r
    NumBytes         - The number of bytes to write to the target block.\r
    Buffer           - The data to write.\r
\r
Returns:\r
    EFI_SUCCESS          - The function completed successfully\r
    EFI_BAD_BUFFER_SIZE  - The write would span a target block, which is not \r
                           a valid action.\r
    EFI_ACCESS_DENIED    - No writes have been allocated.\r
    EFI_NOT_FOUND        - Cannot find FVB by handle.\r
    EFI_OUT_OF_RESOURCES - Cannot allocate memory.\r
    EFI_ABORTED          - The function could not complete successfully.\r
\r
--*/\r
;\r
\r
//\r
// Internal functions\r
//\r
EFI_STATUS\r
FtwRestart (\r
  IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
    Restarts a previously interrupted write. The caller must provide the \r
    block protocol needed to complete the interrupted write.\r
\r
Arguments:\r
    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
Returns:\r
    EFI_SUCCESS         - The function completed successfully\r
    EFI_ACCESS_DENIED   - No pending writes exist\r
    EFI_NOT_FOUND       - FVB protocol not found by the handle\r
    EFI_ABORTED         - The function could not complete successfully\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
FtwAbort (\r
  IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
    Aborts all previous allocated writes.\r
\r
Arguments:\r
    FtwLiteDevice    - The private data of FTW_LITE driver\r
\r
Returns:\r
    EFI_SUCCESS      - The function completed successfully\r
    EFI_ABORTED      - The function could not complete successfully.\r
    EFI_NOT_FOUND    - No allocated writes exist.\r
\r
--*/\r
;\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
Routine Description:\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
Arguments:\r
    FtwLiteDevice       - The private data of FTW_LITE driver\r
    Fvb                 - The FVB protocol that provides services for \r
                          reading, writing, and erasing the target block.\r
\r
Returns:\r
    EFI_SUCCESS         - The function completed successfully\r
    EFI_ABORTED         - The function could not complete successfully\r
\r
--*/\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
Routine Description:\r
    To Erase one block. The size is FTW_BLOCK_SIZE\r
\r
Arguments:\r
    FtwLiteDevice - Calling context\r
    FvBlock       - FVB Protocol interface\r
    Lba           - Lba of the firmware block\r
\r
Returns:\r
    EFI_SUCCESS   - Block LBA is Erased successfully\r
    Others        - Error occurs\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
FtwEraseSpareBlock (\r
  IN EFI_FTW_LITE_DEVICE   *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Erase spare block.\r
\r
Arguments:\r
\r
  FtwLiteDevice - Calling context\r
\r
Returns:\r
\r
  Status code\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
FtwGetFvbByHandle (\r
  IN EFI_HANDLE                           FvBlockHandle,\r
  OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock\r
  )\r
/*++\r
\r
Routine Description:\r
    Retrive the proper FVB protocol interface by HANDLE.\r
\r
Arguments:\r
    FvBlockHandle       - The handle of FVB protocol that provides services for \r
                          reading, writing, and erasing the target block.\r
    FvBlock             - The interface of FVB protocol\r
\r
Returns:\r
    EFI_SUCCESS         - The function completed successfully\r
    EFI_ABORTED         - The function could not complete successfully\r
--*/\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
Routine Description:\r
\r
  Get firmware block by address.\r
\r
Arguments:\r
\r
  Address - Address specified the block\r
  FvBlock - The block caller wanted\r
\r
Returns:\r
\r
  Status code\r
\r
  EFI_NOT_FOUND - Block not found\r
\r
--*/\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
Routine Description:\r
\r
  Is it in working block?\r
\r
Arguments:\r
\r
  FtwLiteDevice - Calling context\r
  FvBlock       - Fvb protocol instance\r
  Lba           - The block specified\r
\r
Returns:\r
\r
  In working block or not\r
\r
--*/\r
;\r
\r
BOOLEAN\r
IsBootBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,\r
  EFI_LBA                             Lba\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Check whether the block is a boot block.\r
\r
Arguments:\r
\r
  FtwLiteDevice - Calling context\r
  FvBlock       - Fvb protocol instance\r
  Lba           - Lba value\r
\r
Returns:\r
\r
  Is a boot block or not\r
\r
--*/\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
Routine Description:\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
Arguments:\r
    FtwLiteDevice  - The private data of FTW_LITE driver\r
    FvBlock        - FVB Protocol interface to access target block\r
    Lba            - Lba of the target block\r
\r
Returns:\r
    EFI_SUCCESS              - Spare block content is copied to target block\r
    EFI_INVALID_PARAMETER    - Input parameter error\r
    EFI_OUT_OF_RESOURCES     - Allocate memory error\r
    EFI_ABORTED              - The function could not complete successfully\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
FlushSpareBlockToWorkingBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\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
Arguments:\r
    FtwLiteDevice  - The private data of FTW_LITE driver\r
\r
Returns:\r
    EFI_SUCCESS              - Spare block content is copied to target block\r
    EFI_OUT_OF_RESOURCES     - Allocate memory error\r
    EFI_ABORTED              - The function could not complete successfully\r
\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
;\r
\r
EFI_STATUS\r
FlushSpareBlockToBootBlock (\r
  EFI_FTW_LITE_DEVICE                 *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
    Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.\r
    Spare block is accessed by FTW backup FVB protocol interface. LBA is \r
    FtwLiteDevice->FtwSpareLba.\r
    Boot block is accessed by BootFvb protocol interface. LBA is 0.\r
\r
Arguments:\r
    FtwLiteDevice  - The private data of FTW_LITE driver\r
\r
Returns:\r
    EFI_SUCCESS              - Spare block content is copied to boot block\r
    EFI_INVALID_PARAMETER    - Input parameter error\r
    EFI_OUT_OF_RESOURCES     - Allocate memory error\r
    EFI_ABORTED              - The function could not complete successfully\r
\r
Notes:\r
\r
--*/\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
Routine Description:\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
Arguments:\r
    FvBlock    - FVB Protocol interface to access SrcBlock and DestBlock\r
    Lba        - Lba of a block\r
    Offset     - Offset on the Lba\r
    NewBit     - New value that will override the old value if it can be change\r
\r
Returns:\r
    EFI_SUCCESS   - A state bit has been updated successfully\r
    Others        - Access block device error.\r
\r
Notes:\r
    Assume all bits of State are inside the same BYTE. \r
\r
    EFI_ABORTED   - Read block fail\r
--*/\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
Routine Description:\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
Arguments:\r
    FtwLiteDevice   - Private data of this driver\r
    FtwLastRecord   - Pointer to retrieve the last write record\r
\r
Returns:\r
    EFI_SUCCESS     - Get the last write record successfully\r
    EFI_ABORTED     - The FTW work space is damaged\r
\r
--*/\r
;\r
\r
BOOLEAN\r
IsErasedFlashBuffer (\r
  IN BOOLEAN         Polarity,\r
  IN UINT8           *Buffer,\r
  IN UINTN           BufferSize\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Check whether a flash buffer is erased.\r
\r
Arguments:\r
\r
  Polarity    - All 1 or all 0\r
  Buffer      - Buffer to check\r
  BufferSize  - Size of the buffer\r
\r
Returns:\r
\r
  Erased or not.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
InitWorkSpaceHeader (\r
  IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
  )\r
/*++\r
\r
Routine Description:\r
    Initialize a work space when there is no work space.\r
\r
Arguments:\r
    WorkingHeader - Pointer of working block header \r
\r
Returns:\r
    EFI_SUCCESS   - The function completed successfully\r
    EFI_ABORTED   - The function could not complete successfully.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
WorkSpaceRefresh (\r
  IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
    Read from working block to refresh the work space in memory.\r
\r
Arguments:\r
    FtwLiteDevice     - Point to private data of FTW driver\r
\r
Returns:\r
    EFI_SUCCESS   - The function completed successfully\r
    EFI_ABORTED   - The function could not complete successfully.\r
\r
--*/\r
;\r
\r
BOOLEAN\r
IsValidWorkSpace (\r
  IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
  )\r
/*++\r
\r
Routine Description:\r
    Check to see if it is a valid work space.\r
\r
Arguments:\r
    WorkingHeader - Pointer of working block header \r
\r
Returns:\r
    EFI_SUCCESS   - The function completed successfully\r
    EFI_ABORTED   - The function could not complete successfully.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
CleanupWorkSpace (\r
  IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice,\r
  IN OUT UINT8            *BlockBuffer,\r
  IN UINTN                BufferSize\r
  )\r
/*++\r
\r
Routine Description:\r
    Reclaim the work space. Get rid of all the completed write records\r
    and write records in the Fault Tolerant work space.\r
\r
Arguments:\r
    FtwLiteDevice   - Point to private data of FTW driver\r
    FtwSpaceBuffer  - Buffer to contain the reclaimed clean data\r
    BufferSize      - Size of the FtwSpaceBuffer\r
\r
Returns:\r
    EFI_SUCCESS           - The function completed successfully\r
    EFI_BUFFER_TOO_SMALL  - The FtwSpaceBuffer is too small\r
    EFI_ABORTED           - The function could not complete successfully.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
FtwReclaimWorkSpace (\r
  IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice\r
  )\r
/*++\r
\r
Routine Description:\r
    Reclaim the work space on the working block.\r
\r
Arguments:\r
    FtwLiteDevice     - Point to private data of FTW driver\r
\r
Returns:\r
    EFI_SUCCESS           - The function completed successfully\r
    EFI_OUT_OF_RESOURCES  - Allocate memory error\r
    EFI_ABORTED           - The function could not complete successfully\r
\r
--*/\r
;\r
\r
#endif\r
Commit	Line	Data
6cc9ca32	1	/** @file\r
d7dec593	2	\r
6cc9ca32 LG	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
d7dec593	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
6cc9ca32	15	**/\r
d7dec593	16	\r
	17	#ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
	18	#define _EFI_FAULT_TOLERANT_WRITE_LITE_H_\r
	19	\r
ed7748fe	20	\r
d7dec593	21	#include <PiDxe.h>\r
ed7748fe	22	\r
d7dec593	23	#include <Protocol/PciRootBridgeIo.h>\r
	24	#include <Guid/SystemNvDataGuid.h>\r
	25	#include <Protocol/FaultTolerantWriteLite.h>\r
	26	#include <Protocol/FirmwareVolumeBlock.h>\r
ed7748fe	27	\r
d7dec593	28	#include <Library/PcdLib.h>\r
	29	#include <Library/DebugLib.h>\r
	30	#include <Library/UefiDriverEntryPoint.h>\r
	31	#include <Library/BaseMemoryLib.h>\r
	32	#include <Library/MemoryAllocationLib.h>\r
	33	#include <Library/UefiBootServicesTableLib.h>\r
	34	\r
3cfb790c	35	#include <WorkingBlockHeader.h>\r
d7dec593	36	\r
	37	#define EFI_D_FTW_LITE EFI_D_ERROR\r
	38	#define EFI_D_FTW_INFO EFI_D_INFO\r
	39	\r
	40	//\r
	41	// Flash erase polarity is 1\r
	42	//\r
	43	#define FTW_ERASE_POLARITY 1\r
	44	\r
	45	#define FTW_VALID_STATE 0\r
	46	#define FTW_INVALID_STATE 1\r
	47	\r
	48	#define FTW_ERASED_BYTE ((UINT8) (255))\r
	49	#define FTW_POLARITY_REVERT ((UINT8) (255))\r
	50	\r
	51	typedef struct {\r
	52	UINT8 WriteAllocated : 1;\r
	53	UINT8 SpareCompleted : 1;\r
	54	UINT8 WriteCompleted : 1;\r
	55	UINT8 Reserved : 5;\r
	56	#define WRITE_ALLOCATED 0x1\r
	57	#define SPARE_COMPLETED 0x2\r
	58	#define WRITE_COMPLETED 0x4\r
	59	\r
	60	EFI_DEV_PATH DevPath;\r
	61	EFI_LBA Lba;\r
	62	UINTN Offset;\r
	63	UINTN NumBytes;\r
	64	//\r
	65	// UINTN SpareAreaOffset;\r
	66	//\r
	67	} EFI_FTW_LITE_RECORD;\r
	68	\r
	69	#define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')\r
	70	\r
	71	//\r
	72	// MACRO for Block size.\r
	73	// Flash Erasing will do in block granularity.\r
	74	//\r
	75	#ifdef FV_BLOCK_SIZE\r
	76	#define FTW_BLOCK_SIZE FV_BLOCK_SIZE\r
	77	#else\r
	78	#define FV_BLOCK_SIZE 0x10000\r
	79	#define FTW_BLOCK_SIZE FV_BLOCK_SIZE\r
	80	#endif\r
	81	//\r
	82	// MACRO for FTW WORK SPACE Base & Size\r
	83	//\r
	84	#ifdef EFI_FTW_WORKING_OFFSET\r
	85	#define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET\r
	86	#else\r
	87	#define FTW_WORK_SPACE_BASE 0x00E000\r
	88	#endif\r
	89	\r
	90	#ifdef EFI_FTW_WORKING_LENGTH\r
	91	#define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH\r
	92	#else\r
	93	#define FTW_WORK_SPACE_SIZE 0x002000\r
	94	#endif\r
	95	//\r
	96	// MACRO for FTW header and record\r
	97	//\r
	98	#define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))\r
	99	#define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))\r
100	#define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE\r
101	\r
102	//\r
103	// EFI Fault tolerant protocol private data structure\r
104	//\r
105	typedef struct {\r
106	UINTN Signature;\r
107	EFI_HANDLE Handle;\r
108	EFI_FTW_LITE_PROTOCOL FtwLiteInstance;\r
109	EFI_PHYSICAL_ADDRESS WorkSpaceAddress;\r
110	UINTN WorkSpaceLength;\r
111	EFI_PHYSICAL_ADDRESS SpareAreaAddress;\r
112	UINTN SpareAreaLength;\r
113	UINTN NumberOfSpareBlock; // Number of the blocks in spare block\r
114	UINTN SizeOfSpareBlock; // Block size in bytes of the blocks in spare block\r
115	EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;\r
116	EFI_FTW_LITE_RECORD *FtwLastRecord;\r
117	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwFvBlock; // FVB of working block\r
118	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwBackupFvb; // FVB of spare block\r
119	EFI_LBA FtwSpareLba;\r
120	EFI_LBA FtwWorkBlockLba; // Start LBA of working block\r
121	EFI_LBA FtwWorkSpaceLba; // Start LBA of working space\r
122	UINTN FtwWorkSpaceBase; // Offset from LBA start addr\r
123	UINTN FtwWorkSpaceSize;\r
124	UINT8 *FtwWorkSpace;\r
125	//\r
126	// Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],\r
127	// Allocated with EFI_FTW_LITE_DEVICE.\r
128	//\r
129	} EFI_FTW_LITE_DEVICE;\r
130	\r
131	#define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)\r
132	\r
133	//\r
134	// Driver entry point\r
135	//\r
136	EFI_STATUS\r
137	EFIAPI\r
138	InitializeFtwLite (\r
139	IN EFI_HANDLE ImageHandle,\r
140	IN EFI_SYSTEM_TABLE *SystemTable\r
141	)\r
142	/*++\r
143	\r
144	Routine Description:\r
145	This function is the entry point of the Fault Tolerant Write driver.\r
146	\r
147	Arguments:\r
148	ImageHandle - EFI_HANDLE: A handle for the image that is initializing \r
149	this driver\r
150	SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table\r
151	\r
152	Returns:\r
153	EFI_SUCCESS - FTW has finished the initialization\r
154	EFI_ABORTED - FTW initialization error\r
155	\r
156	--*/\r
157	;\r
158	\r
159	//\r
160	// Fault Tolerant Write Protocol API\r
161	//\r
162	EFI_STATUS\r
163	EFIAPI\r
164	FtwLiteWrite (\r
165	IN EFI_FTW_LITE_PROTOCOL *This,\r
166	IN EFI_HANDLE FvbHandle,\r
167	IN EFI_LBA Lba,\r
168	IN UINTN Offset,\r
169	IN UINTN *NumBytes,\r
170	IN VOID *Buffer\r
171	)\r
172	/*++\r
173	\r
174	Routine Description:\r
175	Starts a target block update. This function will record data about write \r
176	in fault tolerant storage and will complete the write in a recoverable \r
177	manner, ensuring at all times that either the original contents or \r
178	the modified contents are available.\r
179	\r
180	Arguments:\r
181	This - Calling context\r
182	FvbHandle - The handle of FVB protocol that provides services for \r
183	reading, writing, and erasing the target block.\r
184	Lba - The logical block address of the target block. \r
185	Offset - The offset within the target block to place the data.\r
186	NumBytes - The number of bytes to write to the target block.\r
187	Buffer - The data to write.\r
188	\r
189	Returns:\r
190	EFI_SUCCESS - The function completed successfully\r
191	EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not \r
192	a valid action.\r
193	EFI_ACCESS_DENIED - No writes have been allocated.\r
194	EFI_NOT_FOUND - Cannot find FVB by handle.\r
195	EFI_OUT_OF_RESOURCES - Cannot allocate memory.\r
196	EFI_ABORTED - The function could not complete successfully.\r
197	\r
198	--*/\r
199	;\r
200	\r
201	//\r
202	// Internal functions\r
203	//\r
204	EFI_STATUS\r
205	FtwRestart (\r
206	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
207	)\r
208	/*++\r
209	\r
210	Routine Description:\r
211	Restarts a previously interrupted write. The caller must provide the \r
212	block protocol needed to complete the interrupted write.\r
213	\r
214	Arguments:\r
215	FtwLiteDevice - The private data of FTW_LITE driver\r
216	FvbHandle - The handle of FVB protocol that provides services for \r
217	reading, writing, and erasing the target block.\r
218	\r
219	Returns:\r
220	EFI_SUCCESS - The function completed successfully\r
221	EFI_ACCESS_DENIED - No pending writes exist\r
222	EFI_NOT_FOUND - FVB protocol not found by the handle\r
223	EFI_ABORTED - The function could not complete successfully\r
224	\r
225	--*/\r
226	;\r
227	\r
228	EFI_STATUS\r
229	FtwAbort (\r
230	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
231	)\r
232	/*++\r
233	\r
234	Routine Description:\r
235	Aborts all previous allocated writes.\r
236	\r
237	Arguments:\r
238	FtwLiteDevice - The private data of FTW_LITE driver\r
239	\r
240	Returns:\r
241	EFI_SUCCESS - The function completed successfully\r
242	EFI_ABORTED - The function could not complete successfully.\r
243	EFI_NOT_FOUND - No allocated writes exist.\r
244	\r
245	--*/\r
246	;\r
247	\r
248	\r
249	EFI_STATUS\r
250	FtwWriteRecord (\r
251	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
252	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb\r
253	)\r
254	/*++\r
255	\r
256	Routine Description:\r
257	Write a record with fault tolerant mannaer.\r
258	Since the content has already backuped in spare block, the write is \r
259	guaranteed to be completed with fault tolerant manner.\r
260	\r
261	Arguments:\r
262	FtwLiteDevice - The private data of FTW_LITE driver\r
263	Fvb - The FVB protocol that provides services for \r
264	reading, writing, and erasing the target block.\r
265	\r
266	Returns:\r
267	EFI_SUCCESS - The function completed successfully\r
268	EFI_ABORTED - The function could not complete successfully\r
269	\r
270	--*/\r
271	;\r
272	\r
273	EFI_STATUS\r
274	FtwEraseBlock (\r
275	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
276	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
277	EFI_LBA Lba\r
278	)\r
279	/*++\r
280	\r
281	Routine Description:\r
282	To Erase one block. The size is FTW_BLOCK_SIZE\r
283	\r
284	Arguments:\r
285	FtwLiteDevice - Calling context\r
286	FvBlock - FVB Protocol interface\r
287	Lba - Lba of the firmware block\r
288	\r
289	Returns:\r
290	EFI_SUCCESS - Block LBA is Erased successfully\r
291	Others - Error occurs\r
292	\r
293	--*/\r
294	;\r
295	\r
296	EFI_STATUS\r
297	FtwEraseSpareBlock (\r
298	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
299	)\r
300	/*++\r
301	\r
302	Routine Description:\r
303	\r
304	Erase spare block.\r
305	\r
306	Arguments:\r
307	\r
308	FtwLiteDevice - Calling context\r
309	\r
310	Returns:\r
311	\r
312	Status code\r
313	\r
314	--*/\r
315	;\r
316	\r
317	EFI_STATUS\r
318	FtwGetFvbByHandle (\r
319	IN EFI_HANDLE FvBlockHandle,\r
320	OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock\r
321	)\r
322	/*++\r
323	\r
324	Routine Description:\r
325	Retrive the proper FVB protocol interface by HANDLE.\r
326	\r
327	Arguments:\r
328	FvBlockHandle - The handle of FVB protocol that provides services for \r
329	reading, writing, and erasing the target block.\r
330	FvBlock - The interface of FVB protocol\r
331	\r
332	Returns:\r
333	EFI_SUCCESS - The function completed successfully\r
334	EFI_ABORTED - The function could not complete successfully\r
335	--*/\r
336	;\r
337	\r
338	EFI_STATUS\r
339	GetFvbByAddress (\r
340	IN EFI_PHYSICAL_ADDRESS Address,\r
341	OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock\r
342	)\r
343	/*++\r
344	\r
345	Routine Description:\r
346	\r
347	Get firmware block by address.\r
348	\r
349	Arguments:\r
350	\r
351	Address - Address specified the block\r
352	FvBlock - The block caller wanted\r
353	\r
354	Returns:\r
355	\r
356	Status code\r
357	\r
358	EFI_NOT_FOUND - Block not found\r
359	\r
360	--*/\r
361	;\r
362	\r
363	BOOLEAN\r
364	IsInWorkingBlock (\r
365	EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
366	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
367	EFI_LBA Lba\r
368	)\r
369	/*++\r
370	\r
371	Routine Description:\r
372	\r
373	Is it in working block?\r
374	\r
375	Arguments:\r
376	\r
377	FtwLiteDevice - Calling context\r
378	FvBlock - Fvb protocol instance\r
379	Lba - The block specified\r
380	\r
381	Returns:\r
382	\r
383	In working block or not\r
384	\r
385	--*/\r
386	;\r
387	\r
388	BOOLEAN\r
389	IsBootBlock (\r
390	EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
391	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
392	EFI_LBA Lba\r
393	)\r
394	/*++\r
395	\r
396	Routine Description:\r
397	\r
398	Check whether the block is a boot block.\r
399	\r
400	Arguments:\r
401	\r
402	FtwLiteDevice - Calling context\r
403	FvBlock - Fvb protocol instance\r
404	Lba - Lba value\r
405	\r
406	Returns:\r
407	\r
408	Is a boot block or not\r
409	\r
410	--*/\r
411	;\r
412	\r
413	EFI_STATUS\r
414	FlushSpareBlockToTargetBlock (\r
415	EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
416	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
417	EFI_LBA Lba\r
418	)\r
419	/*++\r
420	\r
421	Routine Description:\r
422	Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.\r
423	Spare block is accessed by FTW backup FVB protocol interface. LBA is \r
424	FtwLiteDevice->FtwSpareLba.\r
425	Target block is accessed by FvBlock protocol interface. LBA is Lba.\r
426	\r
427	Arguments:\r
428	FtwLiteDevice - The private data of FTW_LITE driver\r
429	FvBlock - FVB Protocol interface to access target block\r
430	Lba - Lba of the target block\r
431	\r
432	Returns:\r
433	EFI_SUCCESS - Spare block content is copied to target block\r
434	EFI_INVALID_PARAMETER - Input parameter error\r
435	EFI_OUT_OF_RESOURCES - Allocate memory error\r
436	EFI_ABORTED - The function could not complete successfully\r
437	\r
438	--*/\r
439	;\r
440	\r
441	EFI_STATUS\r
442	FlushSpareBlockToWorkingBlock (\r
443	EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
444	)\r
445	/*++\r
446	\r
447	Routine Description:\r
448	Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.\r
449	Spare block is accessed by FTW backup FVB protocol interface. LBA is \r
450	FtwLiteDevice->FtwSpareLba.\r
451	Working block is accessed by FTW working FVB protocol interface. LBA is \r
452	FtwLiteDevice->FtwWorkBlockLba.\r
453	\r
454	Arguments:\r
455	FtwLiteDevice - The private data of FTW_LITE driver\r
456	\r
457	Returns:\r
458	EFI_SUCCESS - Spare block content is copied to target block\r
459	EFI_OUT_OF_RESOURCES - Allocate memory error\r
460	EFI_ABORTED - The function could not complete successfully\r
461	\r
462	Notes:\r
463	Since the working block header is important when FTW initializes, the \r
464	state of the operation should be handled carefully. The Crc value is \r
465	calculated without STATE element. \r
466	\r
467	--*/\r
468	;\r
469	\r
470	EFI_STATUS\r
471	FlushSpareBlockToBootBlock (\r
472	EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
473	)\r
474	/*++\r
475	\r
476	Routine Description:\r
477	Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.\r
478	Spare block is accessed by FTW backup FVB protocol interface. LBA is \r
479	FtwLiteDevice->FtwSpareLba.\r
480	Boot block is accessed by BootFvb protocol interface. LBA is 0.\r
481	\r
482	Arguments:\r
483	FtwLiteDevice - The private data of FTW_LITE driver\r
484	\r
485	Returns:\r
486	EFI_SUCCESS - Spare block content is copied to boot block\r
487	EFI_INVALID_PARAMETER - Input parameter error\r
488	EFI_OUT_OF_RESOURCES - Allocate memory error\r
489	EFI_ABORTED - The function could not complete successfully\r
490	\r
491	Notes:\r
492	\r
493	--*/\r
494	;\r
495	\r
496	EFI_STATUS\r
497	FtwUpdateFvState (\r
498	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,\r
499	IN EFI_LBA Lba,\r
500	IN UINTN Offset,\r
501	IN UINT8 NewBit\r
502	)\r
503	/*++\r
504	\r
505	Routine Description:\r
506	Update a bit of state on a block device. The location of the bit is \r
507	calculated by the (Lba, Offset, bit). Here bit is determined by the \r
508	the name of a certain bit.\r
509	\r
510	Arguments:\r
511	FvBlock - FVB Protocol interface to access SrcBlock and DestBlock\r
512	Lba - Lba of a block\r
513	Offset - Offset on the Lba\r
514	NewBit - New value that will override the old value if it can be change\r
515	\r
516	Returns:\r
517	EFI_SUCCESS - A state bit has been updated successfully\r
518	Others - Access block device error.\r
519	\r
520	Notes:\r
521	Assume all bits of State are inside the same BYTE. \r
522	\r
523	EFI_ABORTED - Read block fail\r
524	--*/\r
525	;\r
526	\r
527	EFI_STATUS\r
528	FtwGetLastRecord (\r
529	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
530	OUT EFI_FTW_LITE_RECORD **FtwLastRecord\r
531	)\r
532	/*++\r
533	\r
534	Routine Description:\r
535	Get the last Write record pointer. \r
536	The last record is the record whose 'complete' state hasn't been set.\r
537	After all, this header may be a EMPTY header entry for next Allocate. \r
538	\r
539	Arguments:\r
540	FtwLiteDevice - Private data of this driver\r
541	FtwLastRecord - Pointer to retrieve the last write record\r
542	\r
543	Returns:\r
544	EFI_SUCCESS - Get the last write record successfully\r
545	EFI_ABORTED - The FTW work space is damaged\r
546	\r
547	--*/\r
548	;\r
549	\r
550	BOOLEAN\r
551	IsErasedFlashBuffer (\r
552	IN BOOLEAN Polarity,\r
553	IN UINT8 *Buffer,\r
554	IN UINTN BufferSize\r
555	)\r
556	/*++\r
557	\r
558	Routine Description:\r
559	\r
560	Check whether a flash buffer is erased.\r
561	\r
562	Arguments:\r
563	\r
564	Polarity - All 1 or all 0\r
565	Buffer - Buffer to check\r
566	BufferSize - Size of the buffer\r
567	\r
568	Returns:\r
569	\r
570	Erased or not.\r
571	\r
572	--*/\r
573	;\r
574	\r
575	EFI_STATUS\r
576	InitWorkSpaceHeader (\r
577	IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
578	)\r
579	/*++\r
580	\r
581	Routine Description:\r
582	Initialize a work space when there is no work space.\r
583	\r
584	Arguments:\r
585	WorkingHeader - Pointer of working block header \r
586	\r
587	Returns:\r
588	EFI_SUCCESS - The function completed successfully\r
589	EFI_ABORTED - The function could not complete successfully.\r
590	\r
591	--*/\r
592	;\r
593	\r
594	EFI_STATUS\r
595	WorkSpaceRefresh (\r
596	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
597	)\r
598	/*++\r
599	\r
600	Routine Description:\r
601	Read from working block to refresh the work space in memory.\r
602	\r
603	Arguments:\r
604	FtwLiteDevice - Point to private data of FTW driver\r
605	\r
606	Returns:\r
607	EFI_SUCCESS - The function completed successfully\r
608	EFI_ABORTED - The function could not complete successfully.\r
609	\r
610	--*/\r
611	;\r
612	\r
613	BOOLEAN\r
614	IsValidWorkSpace (\r
615	IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader\r
616	)\r
617	/*++\r
618	\r
619	Routine Description:\r
620	Check to see if it is a valid work space.\r
621	\r
622	Arguments:\r
623	WorkingHeader - Pointer of working block header \r
624	\r
625	Returns:\r
626	EFI_SUCCESS - The function completed successfully\r
627	EFI_ABORTED - The function could not complete successfully.\r
628	\r
629	--*/\r
630	;\r
631	\r
632	EFI_STATUS\r
633	CleanupWorkSpace (\r
634	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,\r
635	IN OUT UINT8 *BlockBuffer,\r
636	IN UINTN BufferSize\r
637	)\r
638	/*++\r
639	\r
640	Routine Description:\r
641	Reclaim the work space. Get rid of all the completed write records\r
642	and write records in the Fault Tolerant work space.\r
643	\r
644	Arguments:\r
645	FtwLiteDevice - Point to private data of FTW driver\r
646	FtwSpaceBuffer - Buffer to contain the reclaimed clean data\r
647	BufferSize - Size of the FtwSpaceBuffer\r
648	\r
649	Returns:\r
650	EFI_SUCCESS - The function completed successfully\r
651	EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small\r
652	EFI_ABORTED - The function could not complete successfully.\r
653	\r
654	--*/\r
655	;\r
656	\r
657	EFI_STATUS\r
658	FtwReclaimWorkSpace (\r
659	IN EFI_FTW_LITE_DEVICE *FtwLiteDevice\r
660	)\r
661	/*++\r
662	\r
663	Routine Description:\r
664	Reclaim the work space on the working block.\r
665	\r
666	Arguments:\r
667	FtwLiteDevice - Point to private data of FTW driver\r
668	\r
669	Returns:\r
670	EFI_SUCCESS - The function completed successfully\r
671	EFI_OUT_OF_RESOURCES - Allocate memory error\r
672	EFI_ABORTED - The function could not complete successfully\r
673	\r
674	--*/\r
675	;\r
676	\r
677	#endif\r