3 Copyright (c) 2006, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 This is a simple fault tolerant write driver, based on PlatformFd library.
20 And it only supports write BufferSize <= SpareAreaLength.
22 This boot service only protocol provides fault tolerant write capability for
23 block devices. The protocol has internal non-volatile intermediate storage
24 of the data and private information. It should be able to recover
25 automatically from a critical fault, such as power failure.
29 #ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_
30 #define _EFI_FAULT_TOLERANT_WRITE_LITE_H_
33 // The package level header files this module uses
37 // The protocols, PPI and GUID defintions for this module
39 #include <Protocol/PciRootBridgeIo.h>
40 #include <Guid/SystemNvDataGuid.h>
41 #include <Guid/FlashMapHob.h>
42 #include <Protocol/FaultTolerantWriteLite.h>
43 #include <Protocol/FirmwareVolumeBlock.h>
45 // The Library classes this module consumes
47 #include <Library/PcdLib.h>
48 #include <Library/DebugLib.h>
49 #include <Library/UefiDriverEntryPoint.h>
50 #include <Library/BaseMemoryLib.h>
51 #include <Library/MemoryAllocationLib.h>
52 #include <Library/UefiBootServicesTableLib.h>
53 #include <Library/HobLib.h>
55 #include <Common/WorkingBlockHeader.h>
56 #include <Common/FlashMap.h>
58 #define EFI_D_FTW_LITE EFI_D_ERROR
59 #define EFI_D_FTW_INFO EFI_D_INFO
62 // Flash erase polarity is 1
64 #define FTW_ERASE_POLARITY 1
66 #define FTW_VALID_STATE 0
67 #define FTW_INVALID_STATE 1
69 #define FTW_ERASED_BYTE ((UINT8) (255))
70 #define FTW_POLARITY_REVERT ((UINT8) (255))
73 UINT8 WriteAllocated
: 1;
74 UINT8 SpareCompleted
: 1;
75 UINT8 WriteCompleted
: 1;
77 #define WRITE_ALLOCATED 0x1
78 #define SPARE_COMPLETED 0x2
79 #define WRITE_COMPLETED 0x4
86 // UINTN SpareAreaOffset;
88 } EFI_FTW_LITE_RECORD
;
90 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
93 // MACRO for Block size.
94 // Flash Erasing will do in block granularity.
97 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
99 #define FV_BLOCK_SIZE 0x10000
100 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
103 // MACRO for FTW WORK SPACE Base & Size
105 #ifdef EFI_FTW_WORKING_OFFSET
106 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
108 #define FTW_WORK_SPACE_BASE 0x00E000
111 #ifdef EFI_FTW_WORKING_LENGTH
112 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
114 #define FTW_WORK_SPACE_SIZE 0x002000
117 // MACRO for FTW header and record
119 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
120 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
121 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
124 // EFI Fault tolerant protocol private data structure
129 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
130 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
131 UINTN WorkSpaceLength
;
132 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
133 UINTN SpareAreaLength
;
134 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
135 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
136 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
137 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
138 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
139 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
141 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
142 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
143 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
144 UINTN FtwWorkSpaceSize
;
147 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
148 // Allocated with EFI_FTW_LITE_DEVICE.
150 } EFI_FTW_LITE_DEVICE
;
152 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
155 // Driver entry point
160 IN EFI_HANDLE ImageHandle
,
161 IN EFI_SYSTEM_TABLE
*SystemTable
166 This function is the entry point of the Fault Tolerant Write driver.
169 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
171 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
174 EFI_SUCCESS - FTW has finished the initialization
175 EFI_ABORTED - FTW initialization error
181 // Fault Tolerant Write Protocol API
186 IN EFI_FTW_LITE_PROTOCOL
*This
,
187 IN EFI_HANDLE FvbHandle
,
196 Starts a target block update. This function will record data about write
197 in fault tolerant storage and will complete the write in a recoverable
198 manner, ensuring at all times that either the original contents or
199 the modified contents are available.
202 This - Calling context
203 FvbHandle - The handle of FVB protocol that provides services for
204 reading, writing, and erasing the target block.
205 Lba - The logical block address of the target block.
206 Offset - The offset within the target block to place the data.
207 NumBytes - The number of bytes to write to the target block.
208 Buffer - The data to write.
211 EFI_SUCCESS - The function completed successfully
212 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
214 EFI_ACCESS_DENIED - No writes have been allocated.
215 EFI_NOT_FOUND - Cannot find FVB by handle.
216 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
217 EFI_ABORTED - The function could not complete successfully.
223 // Internal functions
227 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
232 Restarts a previously interrupted write. The caller must provide the
233 block protocol needed to complete the interrupted write.
236 FtwLiteDevice - The private data of FTW_LITE driver
237 FvbHandle - The handle of FVB protocol that provides services for
238 reading, writing, and erasing the target block.
241 EFI_SUCCESS - The function completed successfully
242 EFI_ACCESS_DENIED - No pending writes exist
243 EFI_NOT_FOUND - FVB protocol not found by the handle
244 EFI_ABORTED - The function could not complete successfully
251 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
256 Aborts all previous allocated writes.
259 FtwLiteDevice - The private data of FTW_LITE driver
262 EFI_SUCCESS - The function completed successfully
263 EFI_ABORTED - The function could not complete successfully.
264 EFI_NOT_FOUND - No allocated writes exist.
272 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
273 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
278 Write a record with fault tolerant mannaer.
279 Since the content has already backuped in spare block, the write is
280 guaranteed to be completed with fault tolerant manner.
283 FtwLiteDevice - The private data of FTW_LITE driver
284 Fvb - The FVB protocol that provides services for
285 reading, writing, and erasing the target block.
288 EFI_SUCCESS - The function completed successfully
289 EFI_ABORTED - The function could not complete successfully
296 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
297 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
303 To Erase one block. The size is FTW_BLOCK_SIZE
306 FtwLiteDevice - Calling context
307 FvBlock - FVB Protocol interface
308 Lba - Lba of the firmware block
311 EFI_SUCCESS - Block LBA is Erased successfully
312 Others - Error occurs
319 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
329 FtwLiteDevice - Calling context
340 IN EFI_HANDLE FvBlockHandle
,
341 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
346 Retrive the proper FVB protocol interface by HANDLE.
349 FvBlockHandle - The handle of FVB protocol that provides services for
350 reading, writing, and erasing the target block.
351 FvBlock - The interface of FVB protocol
354 EFI_SUCCESS - The function completed successfully
355 EFI_ABORTED - The function could not complete successfully
361 IN EFI_PHYSICAL_ADDRESS Address
,
362 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
368 Get firmware block by address.
372 Address - Address specified the block
373 FvBlock - The block caller wanted
379 EFI_NOT_FOUND - Block not found
386 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
387 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
394 Is it in working block?
398 FtwLiteDevice - Calling context
399 FvBlock - Fvb protocol instance
400 Lba - The block specified
404 In working block or not
411 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
412 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
419 Check whether the block is a boot block.
423 FtwLiteDevice - Calling context
424 FvBlock - Fvb protocol instance
429 Is a boot block or not
435 FlushSpareBlockToTargetBlock (
436 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
437 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
443 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
444 Spare block is accessed by FTW backup FVB protocol interface. LBA is
445 FtwLiteDevice->FtwSpareLba.
446 Target block is accessed by FvBlock protocol interface. LBA is Lba.
449 FtwLiteDevice - The private data of FTW_LITE driver
450 FvBlock - FVB Protocol interface to access target block
451 Lba - Lba of the target block
454 EFI_SUCCESS - Spare block content is copied to target block
455 EFI_INVALID_PARAMETER - Input parameter error
456 EFI_OUT_OF_RESOURCES - Allocate memory error
457 EFI_ABORTED - The function could not complete successfully
463 FlushSpareBlockToWorkingBlock (
464 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
469 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
470 Spare block is accessed by FTW backup FVB protocol interface. LBA is
471 FtwLiteDevice->FtwSpareLba.
472 Working block is accessed by FTW working FVB protocol interface. LBA is
473 FtwLiteDevice->FtwWorkBlockLba.
476 FtwLiteDevice - The private data of FTW_LITE driver
479 EFI_SUCCESS - Spare block content is copied to target block
480 EFI_OUT_OF_RESOURCES - Allocate memory error
481 EFI_ABORTED - The function could not complete successfully
484 Since the working block header is important when FTW initializes, the
485 state of the operation should be handled carefully. The Crc value is
486 calculated without STATE element.
492 FlushSpareBlockToBootBlock (
493 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
498 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
499 Spare block is accessed by FTW backup FVB protocol interface. LBA is
500 FtwLiteDevice->FtwSpareLba.
501 Boot block is accessed by BootFvb protocol interface. LBA is 0.
504 FtwLiteDevice - The private data of FTW_LITE driver
507 EFI_SUCCESS - Spare block content is copied to boot block
508 EFI_INVALID_PARAMETER - Input parameter error
509 EFI_OUT_OF_RESOURCES - Allocate memory error
510 EFI_ABORTED - The function could not complete successfully
519 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
527 Update a bit of state on a block device. The location of the bit is
528 calculated by the (Lba, Offset, bit). Here bit is determined by the
529 the name of a certain bit.
532 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
534 Offset - Offset on the Lba
535 NewBit - New value that will override the old value if it can be change
538 EFI_SUCCESS - A state bit has been updated successfully
539 Others - Access block device error.
542 Assume all bits of State are inside the same BYTE.
544 EFI_ABORTED - Read block fail
550 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
551 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
556 Get the last Write record pointer.
557 The last record is the record whose 'complete' state hasn't been set.
558 After all, this header may be a EMPTY header entry for next Allocate.
561 FtwLiteDevice - Private data of this driver
562 FtwLastRecord - Pointer to retrieve the last write record
565 EFI_SUCCESS - Get the last write record successfully
566 EFI_ABORTED - The FTW work space is damaged
572 IsErasedFlashBuffer (
581 Check whether a flash buffer is erased.
585 Polarity - All 1 or all 0
586 Buffer - Buffer to check
587 BufferSize - Size of the buffer
597 InitWorkSpaceHeader (
598 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
603 Initialize a work space when there is no work space.
606 WorkingHeader - Pointer of working block header
609 EFI_SUCCESS - The function completed successfully
610 EFI_ABORTED - The function could not complete successfully.
617 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
622 Read from working block to refresh the work space in memory.
625 FtwLiteDevice - Point to private data of FTW driver
628 EFI_SUCCESS - The function completed successfully
629 EFI_ABORTED - The function could not complete successfully.
636 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
641 Check to see if it is a valid work space.
644 WorkingHeader - Pointer of working block header
647 EFI_SUCCESS - The function completed successfully
648 EFI_ABORTED - The function could not complete successfully.
655 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
656 IN OUT UINT8
*BlockBuffer
,
662 Reclaim the work space. Get rid of all the completed write records
663 and write records in the Fault Tolerant work space.
666 FtwLiteDevice - Point to private data of FTW driver
667 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
668 BufferSize - Size of the FtwSpaceBuffer
671 EFI_SUCCESS - The function completed successfully
672 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
673 EFI_ABORTED - The function could not complete successfully.
679 FtwReclaimWorkSpace (
680 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
685 Reclaim the work space on the working block.
688 FtwLiteDevice - Point to private data of FTW driver
691 EFI_SUCCESS - The function completed successfully
692 EFI_OUT_OF_RESOURCES - Allocate memory error
693 EFI_ABORTED - The function could not complete successfully