3 This is a simple fault tolerant write driver.
5 This boot service protocol only provides fault tolerant write capability for
6 block devices. The protocol has internal non-volatile intermediate storage
7 of the data and private information. It should be able to recover
8 automatically from a critical fault, such as power failure.
10 The implementation uses an FTW (Fault Tolerant Write) Work Space.
11 This work space is a memory copy of the work space on the Working Block,
12 the size of the work space is the FTW_WORK_SPACE_SIZE bytes.
14 The work space stores each write record as EFI_FTW_RECORD structure.
15 The spare block stores the write buffer before write to the target block.
17 The write record has three states to specify the different phase of write operation.
18 1) WRITE_ALLOCATED is that the record is allocated in write space.
19 The information of write operation is stored in write record structure.
20 2) SPARE_COMPLETED is that the data from write buffer is writed into the spare block as the backup.
21 3) WRITE_COMPLETED is that the data is copied from the spare block to the target block.
23 This driver operates the data as the whole size of spare block.
24 It first read the SpareAreaLength data from the target block into the spare memory buffer.
25 Then copy the write buffer data into the spare memory buffer.
26 Then write the spare memory buffer into the spare block.
27 Final copy the data from the spare block to the target block.
29 To make this drive work well, the following conditions must be satisfied:
30 1. The write NumBytes data must be fit within Spare area.
31 Offset + NumBytes <= SpareAreaLength
32 2. The whole flash range has the same block size.
33 3. Working block is an area which contains working space in its last block and has the same size as spare block.
34 4. Working Block area must be in the single one Firmware Volume Block range which FVB protocol is produced on.
35 5. Spare area must be in the single one Firmware Volume Block range which FVB protocol is produced on.
36 6. Any write data area (SpareAreaLength Area) which the data will be written into must be
37 in the single one Firmware Volume Block range which FVB protocol is produced on.
38 7. If write data area (such as Variable range) is enlarged, the spare area range must be enlarged.
39 The spare area must be enough large to store the write data before write them into the target range.
40 If one of them is not satisfied, FtwWrite may fail.
41 Usually, Spare area only takes one block. That's SpareAreaLength = BlockSize, NumberOfSpareBlock = 1.
43 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
44 This program and the accompanying materials
45 are licensed and made available under the terms and conditions of the BSD License
46 which accompanies this distribution. The full text of the license may be found at
47 http://opensource.org/licenses/bsd-license.php
49 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
50 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
54 #include "FaultTolerantWrite.h"
56 EFI_EVENT mFvbRegistration
= NULL
;
59 // Fault Tolerant Write Protocol API
62 Query the largest block that may be updated in a fault tolerant manner.
65 @param This The pointer to this protocol instance.
66 @param BlockSize A pointer to a caller allocated UINTN that is updated to
67 indicate the size of the largest block that can be updated.
69 @return EFI_SUCCESS The function completed successfully
75 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
79 EFI_FTW_DEVICE
*FtwDevice
;
81 if (!FeaturePcdGet(PcdFullFtwServiceEnable
)) {
82 return EFI_UNSUPPORTED
;
85 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
87 *BlockSize
= FtwDevice
->SpareAreaLength
;
93 Allocates space for the protocol to maintain information about writes.
94 Since writes must be completed in a fault tolerant manner and multiple
95 updates will require more resources to be successful, this function
96 enables the protocol to ensure that enough space exists to track
97 information about the upcoming writes.
99 All writes must be completed or aborted before another fault tolerant write can occur.
101 @param This The pointer to this protocol instance.
102 @param CallerId The GUID identifying the write.
103 @param PrivateDataSize The size of the caller's private data
104 that must be recorded for each write.
105 @param NumberOfWrites The number of fault tolerant block writes
106 that will need to occur.
108 @return EFI_SUCCESS The function completed successfully
109 @retval EFI_ABORTED The function could not complete successfully.
110 @retval EFI_ACCESS_DENIED All allocated writes have not been completed.
116 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
117 IN EFI_GUID
*CallerId
,
118 IN UINTN PrivateDataSize
,
119 IN UINTN NumberOfWrites
125 EFI_FTW_DEVICE
*FtwDevice
;
126 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
;
128 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
130 Status
= WorkSpaceRefresh (FtwDevice
);
131 if (EFI_ERROR (Status
)) {
135 // Check if there is enough space for the coming allocation
137 if (WRITE_TOTAL_SIZE (NumberOfWrites
, PrivateDataSize
) > FtwDevice
->FtwWorkSpaceHeader
->WriteQueueSize
) {
138 DEBUG ((EFI_D_ERROR
, "Ftw: Allocate() request exceed Workspace, Caller: %g\n", CallerId
));
139 return EFI_BUFFER_TOO_SMALL
;
142 // Find the last write header and record.
143 // If the FtwHeader is complete, skip the completed last write header/records
145 FtwHeader
= FtwDevice
->FtwLastWriteHeader
;
148 // Previous write has not completed, access denied.
150 if ((FtwHeader
->HeaderAllocated
== FTW_VALID_STATE
) || (FtwHeader
->WritesAllocated
== FTW_VALID_STATE
)) {
151 return EFI_ACCESS_DENIED
;
154 // If workspace is not enough, then reclaim workspace
156 Offset
= (UINT8
*) FtwHeader
- (UINT8
*) FtwDevice
->FtwWorkSpace
;
157 if (Offset
+ WRITE_TOTAL_SIZE (NumberOfWrites
, PrivateDataSize
) > FtwDevice
->FtwWorkSpaceSize
) {
158 Status
= FtwReclaimWorkSpace (FtwDevice
, TRUE
);
159 if (EFI_ERROR (Status
)) {
163 FtwHeader
= FtwDevice
->FtwLastWriteHeader
;
166 // Prepare FTW write header,
167 // overwrite the buffer and write to workspace.
169 FtwHeader
->WritesAllocated
= FTW_INVALID_STATE
;
170 FtwHeader
->Complete
= FTW_INVALID_STATE
;
171 CopyMem (&FtwHeader
->CallerId
, CallerId
, sizeof (EFI_GUID
));
172 FtwHeader
->NumberOfWrites
= NumberOfWrites
;
173 FtwHeader
->PrivateDataSize
= PrivateDataSize
;
174 FtwHeader
->HeaderAllocated
= FTW_VALID_STATE
;
176 Length
= sizeof (EFI_FAULT_TOLERANT_WRITE_HEADER
);
177 Status
= FtwDevice
->FtwFvBlock
->Write (
178 FtwDevice
->FtwFvBlock
,
179 FtwDevice
->FtwWorkSpaceLba
,
180 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
184 if (EFI_ERROR (Status
)) {
188 // Update Header->WriteAllocated as VALID
190 Status
= FtwUpdateFvState (
191 FtwDevice
->FtwFvBlock
,
192 FtwDevice
->FtwWorkSpaceLba
,
193 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
196 if (EFI_ERROR (Status
)) {
202 "Ftw: Allocate() success, Caller:%g, # %d\n",
212 Write a record with fault tolerant mannaer.
213 Since the content has already backuped in spare block, the write is
214 guaranteed to be completed with fault tolerant manner.
216 @param This The pointer to this protocol instance.
217 @param Fvb The FVB protocol that provides services for
218 reading, writing, and erasing the target block.
220 @retval EFI_SUCCESS The function completed successfully
221 @retval EFI_ABORTED The function could not complete successfully
226 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
227 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
231 EFI_FTW_DEVICE
*FtwDevice
;
232 EFI_FAULT_TOLERANT_WRITE_HEADER
*Header
;
233 EFI_FAULT_TOLERANT_WRITE_RECORD
*Record
;
236 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
239 // Spare Complete but Destination not complete,
240 // Recover the targt block with the spare block.
242 Header
= FtwDevice
->FtwLastWriteHeader
;
243 Record
= FtwDevice
->FtwLastWriteRecord
;
246 // IF target block is working block, THEN Flush Spare Block To Working Block;
247 // ELSE flush spare block to target block, which may be boot block after all.
249 if (IsWorkingBlock (FtwDevice
, Fvb
, Record
->Lba
)) {
251 // If target block is working block,
252 // it also need to set SPARE_COMPLETED to spare block.
254 Offset
= (UINT8
*) Record
- FtwDevice
->FtwWorkSpace
;
255 Status
= FtwUpdateFvState (
256 FtwDevice
->FtwBackupFvb
,
257 FtwDevice
->FtwWorkSpaceLba
,
258 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
261 if (EFI_ERROR (Status
)) {
265 Status
= FlushSpareBlockToWorkingBlock (FtwDevice
);
266 } else if (IsBootBlock (FtwDevice
, Fvb
, Record
->Lba
)) {
270 Status
= FlushSpareBlockToBootBlock (FtwDevice
);
273 // Update blocks other than working block or boot block
275 Status
= FlushSpareBlockToTargetBlock (FtwDevice
, Fvb
, Record
->Lba
);
278 if (EFI_ERROR (Status
)) {
282 // Record the DestionationComplete in record
284 Offset
= (UINT8
*) Record
- FtwDevice
->FtwWorkSpace
;
285 Status
= FtwUpdateFvState (
286 FtwDevice
->FtwFvBlock
,
287 FtwDevice
->FtwWorkSpaceLba
,
288 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
291 if (EFI_ERROR (Status
)) {
295 Record
->DestinationComplete
= FTW_VALID_STATE
;
298 // If this is the last Write in these write sequence,
299 // set the complete flag of write header.
301 if (IsLastRecordOfWrites (Header
, Record
)) {
302 Offset
= (UINT8
*) Header
- FtwDevice
->FtwWorkSpace
;
303 Status
= FtwUpdateFvState (
304 FtwDevice
->FtwFvBlock
,
305 FtwDevice
->FtwWorkSpaceLba
,
306 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
309 Header
->Complete
= FTW_VALID_STATE
;
310 if (EFI_ERROR (Status
)) {
319 Starts a target block update. This function will record data about write
320 in fault tolerant storage and will complete the write in a recoverable
321 manner, ensuring at all times that either the original contents or
322 the modified contents are available.
324 @param This The pointer to this protocol instance.
325 @param Lba The logical block address of the target block.
326 @param Offset The offset within the target block to place the data.
327 @param Length The number of bytes to write to the target block.
328 @param PrivateData A pointer to private data that the caller requires to
329 complete any pending writes in the event of a fault.
330 @param FvBlockHandle The handle of FVB protocol that provides services for
331 reading, writing, and erasing the target block.
332 @param Buffer The data to write.
334 @retval EFI_SUCCESS The function completed successfully
335 @retval EFI_ABORTED The function could not complete successfully.
336 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block.
337 Offset + *NumBytes > SpareAreaLength.
338 @retval EFI_ACCESS_DENIED No writes have been allocated.
339 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource.
340 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle.
346 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
350 IN VOID
*PrivateData
,
351 IN EFI_HANDLE FvBlockHandle
,
356 EFI_FTW_DEVICE
*FtwDevice
;
357 EFI_FAULT_TOLERANT_WRITE_HEADER
*Header
;
358 EFI_FAULT_TOLERANT_WRITE_RECORD
*Record
;
359 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
364 UINTN SpareBufferSize
;
368 EFI_PHYSICAL_ADDRESS FvbPhysicalAddress
;
370 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
372 Status
= WorkSpaceRefresh (FtwDevice
);
373 if (EFI_ERROR (Status
)) {
377 Header
= FtwDevice
->FtwLastWriteHeader
;
378 Record
= FtwDevice
->FtwLastWriteRecord
;
380 if (IsErasedFlashBuffer ((UINT8
*) Header
, sizeof (EFI_FAULT_TOLERANT_WRITE_HEADER
))) {
381 if (PrivateData
== NULL
) {
383 // Ftw Write Header is not allocated.
384 // No additional private data, the private data size is zero. Number of record can be set to 1.
386 Status
= FtwAllocate (This
, &gEfiCallerIdGuid
, 0, 1);
387 if (EFI_ERROR (Status
)) {
392 // Ftw Write Header is not allocated
393 // Additional private data is not NULL, the private data size can't be determined.
395 DEBUG ((EFI_D_ERROR
, "Ftw: no allocates space for write record!\n"));
396 DEBUG ((EFI_D_ERROR
, "Ftw: Allocate service should be called before Write service!\n"));
397 return EFI_NOT_READY
;
402 // If Record is out of the range of Header, return access denied.
404 if (((UINTN
)((UINT8
*) Record
- (UINT8
*) Header
)) > WRITE_TOTAL_SIZE (Header
->NumberOfWrites
- 1, Header
->PrivateDataSize
)) {
405 return EFI_ACCESS_DENIED
;
409 // Check the COMPLETE flag of last write header
411 if (Header
->Complete
== FTW_VALID_STATE
) {
412 return EFI_ACCESS_DENIED
;
415 if (Record
->DestinationComplete
== FTW_VALID_STATE
) {
416 return EFI_ACCESS_DENIED
;
419 if ((Record
->SpareComplete
== FTW_VALID_STATE
) && (Record
->DestinationComplete
!= FTW_VALID_STATE
)) {
420 return EFI_NOT_READY
;
423 // Check if the input data can fit within the target block
425 if ((Offset
+ Length
) > FtwDevice
->SpareAreaLength
) {
426 return EFI_BAD_BUFFER_SIZE
;
429 // Get the FVB protocol by handle
431 Status
= FtwGetFvbByHandle (FvBlockHandle
, &Fvb
);
432 if (EFI_ERROR (Status
)) {
433 return EFI_NOT_FOUND
;
436 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbPhysicalAddress
);
437 if (EFI_ERROR (Status
)) {
438 DEBUG ((EFI_D_ERROR
, "FtwLite: Get FVB physical address - %r\n", Status
));
443 // Set BootBlockUpdate FLAG if it's updating boot block.
445 if (IsBootBlock (FtwDevice
, Fvb
, Lba
)) {
446 Record
->BootBlockUpdate
= FTW_VALID_STATE
;
449 // Write the record to the work space.
452 Record
->Offset
= Offset
;
453 Record
->Length
= Length
;
454 Record
->FvBaseAddress
= FvbPhysicalAddress
;
455 if (PrivateData
!= NULL
) {
456 CopyMem ((Record
+ 1), PrivateData
, Header
->PrivateDataSize
);
459 MyOffset
= (UINT8
*) Record
- FtwDevice
->FtwWorkSpace
;
460 MyLength
= RECORD_SIZE (Header
->PrivateDataSize
);
462 Status
= FtwDevice
->FtwFvBlock
->Write (
463 FtwDevice
->FtwFvBlock
,
464 FtwDevice
->FtwWorkSpaceLba
,
465 FtwDevice
->FtwWorkSpaceBase
+ MyOffset
,
469 if (EFI_ERROR (Status
)) {
473 // Record has written to working block, then do the data.
476 // Allocate a memory buffer
478 MyBufferSize
= FtwDevice
->SpareAreaLength
;
479 MyBuffer
= AllocatePool (MyBufferSize
);
480 if (MyBuffer
== NULL
) {
481 return EFI_OUT_OF_RESOURCES
;
484 // Read all original data from target block to memory buffer
487 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
488 MyLength
= FtwDevice
->BlockSize
;
489 Status
= Fvb
->Read (Fvb
, Lba
+ Index
, 0, &MyLength
, Ptr
);
490 if (EFI_ERROR (Status
)) {
498 // Overwrite the updating range data with
499 // the input buffer content
501 CopyMem (MyBuffer
+ Offset
, Buffer
, Length
);
504 // Try to keep the content of spare block
505 // Save spare block into a spare backup memory buffer (Sparebuffer)
507 SpareBufferSize
= FtwDevice
->SpareAreaLength
;
508 SpareBuffer
= AllocatePool (SpareBufferSize
);
509 if (SpareBuffer
== NULL
) {
511 return EFI_OUT_OF_RESOURCES
;
515 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
516 MyLength
= FtwDevice
->BlockSize
;
517 Status
= FtwDevice
->FtwBackupFvb
->Read (
518 FtwDevice
->FtwBackupFvb
,
519 FtwDevice
->FtwSpareLba
+ Index
,
524 if (EFI_ERROR (Status
)) {
526 FreePool (SpareBuffer
);
533 // Write the memory buffer to spare block
535 Status
= FtwEraseSpareBlock (FtwDevice
);
537 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
538 MyLength
= FtwDevice
->BlockSize
;
539 Status
= FtwDevice
->FtwBackupFvb
->Write (
540 FtwDevice
->FtwBackupFvb
,
541 FtwDevice
->FtwSpareLba
+ Index
,
546 if (EFI_ERROR (Status
)) {
548 FreePool (SpareBuffer
);
560 // Set the SpareComplete in the FTW record,
562 MyOffset
= (UINT8
*) Record
- FtwDevice
->FtwWorkSpace
;
563 Status
= FtwUpdateFvState (
564 FtwDevice
->FtwFvBlock
,
565 FtwDevice
->FtwWorkSpaceLba
,
566 FtwDevice
->FtwWorkSpaceBase
+ MyOffset
,
569 if (EFI_ERROR (Status
)) {
570 FreePool (SpareBuffer
);
574 Record
->SpareComplete
= FTW_VALID_STATE
;
577 // Since the content has already backuped in spare block, the write is
578 // guaranteed to be completed with fault tolerant manner.
580 Status
= FtwWriteRecord (This
, Fvb
);
581 if (EFI_ERROR (Status
)) {
582 FreePool (SpareBuffer
);
586 // Restore spare backup buffer into spare block , if no failure happened during FtwWrite.
588 Status
= FtwEraseSpareBlock (FtwDevice
);
590 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
591 MyLength
= FtwDevice
->BlockSize
;
592 Status
= FtwDevice
->FtwBackupFvb
->Write (
593 FtwDevice
->FtwBackupFvb
,
594 FtwDevice
->FtwSpareLba
+ Index
,
599 if (EFI_ERROR (Status
)) {
600 FreePool (SpareBuffer
);
609 FreePool (SpareBuffer
);
613 "Ftw: Write() success, (Lba:Offset)=(%lx:0x%x), Length: 0x%x\n",
623 Restarts a previously interrupted write. The caller must provide the
624 block protocol needed to complete the interrupted write.
626 @param This The pointer to this protocol instance.
627 @param FvBlockHandle The handle of FVB protocol that provides services for
628 reading, writing, and erasing the target block.
630 @retval EFI_SUCCESS The function completed successfully
631 @retval EFI_ACCESS_DENIED No pending writes exist
632 @retval EFI_NOT_FOUND FVB protocol not found by the handle
633 @retval EFI_ABORTED The function could not complete successfully
639 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
640 IN EFI_HANDLE FvBlockHandle
644 EFI_FTW_DEVICE
*FtwDevice
;
645 EFI_FAULT_TOLERANT_WRITE_HEADER
*Header
;
646 EFI_FAULT_TOLERANT_WRITE_RECORD
*Record
;
647 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
649 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
651 Status
= WorkSpaceRefresh (FtwDevice
);
652 if (EFI_ERROR (Status
)) {
656 Header
= FtwDevice
->FtwLastWriteHeader
;
657 Record
= FtwDevice
->FtwLastWriteRecord
;
660 // Spare Complete but Destination not complete,
661 // Recover the targt block with the spare block.
663 Status
= FtwGetFvbByHandle (FvBlockHandle
, &Fvb
);
664 if (EFI_ERROR (Status
)) {
665 return EFI_NOT_FOUND
;
669 // Check the COMPLETE flag of last write header
671 if (Header
->Complete
== FTW_VALID_STATE
) {
672 return EFI_ACCESS_DENIED
;
676 // Check the flags of last write record
678 if (Record
->DestinationComplete
== FTW_VALID_STATE
) {
679 return EFI_ACCESS_DENIED
;
682 if ((Record
->SpareComplete
!= FTW_VALID_STATE
)) {
687 // Since the content has already backuped in spare block, the write is
688 // guaranteed to be completed with fault tolerant manner.
690 Status
= FtwWriteRecord (This
, Fvb
);
691 if (EFI_ERROR (Status
)) {
697 // This is restart, no need to keep spareblock content.
699 FtwEraseSpareBlock (FtwDevice
);
701 DEBUG ((EFI_D_ERROR
, "Ftw: Restart() success \n"));
706 Aborts all previous allocated writes.
708 @param This The pointer to this protocol instance.
710 @retval EFI_SUCCESS The function completed successfully
711 @retval EFI_ABORTED The function could not complete successfully.
712 @retval EFI_NOT_FOUND No allocated writes exist.
718 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
723 EFI_FTW_DEVICE
*FtwDevice
;
725 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
727 Status
= WorkSpaceRefresh (FtwDevice
);
728 if (EFI_ERROR (Status
)) {
732 if (FtwDevice
->FtwLastWriteHeader
->Complete
== FTW_VALID_STATE
) {
733 return EFI_NOT_FOUND
;
736 // Update the complete state of the header as VALID and abort.
738 Offset
= (UINT8
*) FtwDevice
->FtwLastWriteHeader
- FtwDevice
->FtwWorkSpace
;
739 Status
= FtwUpdateFvState (
740 FtwDevice
->FtwFvBlock
,
741 FtwDevice
->FtwWorkSpaceLba
,
742 FtwDevice
->FtwWorkSpaceBase
+ Offset
,
745 if (EFI_ERROR (Status
)) {
749 FtwDevice
->FtwLastWriteHeader
->Complete
= FTW_VALID_STATE
;
751 DEBUG ((EFI_D_ERROR
, "Ftw: Abort() success \n"));
756 Starts a target block update. This records information about the write
757 in fault tolerant storage and will complete the write in a recoverable
758 manner, ensuring at all times that either the original contents or
759 the modified contents are available.
761 @param This The pointer to this protocol instance.
762 @param CallerId The GUID identifying the last write.
763 @param Lba The logical block address of the last write.
764 @param Offset The offset within the block of the last write.
765 @param Length The length of the last write.
766 @param PrivateDataSize bytes from the private data
767 stored for this write.
768 @param PrivateData A pointer to a buffer. The function will copy
769 @param Complete A Boolean value with TRUE indicating
770 that the write was completed.
772 @retval EFI_SUCCESS The function completed successfully
773 @retval EFI_ABORTED The function could not complete successfully
774 @retval EFI_NOT_FOUND No allocated writes exist
775 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough
781 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
782 OUT EFI_GUID
*CallerId
,
786 IN OUT UINTN
*PrivateDataSize
,
787 OUT VOID
*PrivateData
,
788 OUT BOOLEAN
*Complete
792 EFI_FTW_DEVICE
*FtwDevice
;
793 EFI_FAULT_TOLERANT_WRITE_HEADER
*Header
;
794 EFI_FAULT_TOLERANT_WRITE_RECORD
*Record
;
796 if (!FeaturePcdGet(PcdFullFtwServiceEnable
)) {
797 return EFI_UNSUPPORTED
;
800 FtwDevice
= FTW_CONTEXT_FROM_THIS (This
);
802 Status
= WorkSpaceRefresh (FtwDevice
);
803 if (EFI_ERROR (Status
)) {
807 Header
= FtwDevice
->FtwLastWriteHeader
;
808 Record
= FtwDevice
->FtwLastWriteRecord
;
811 // If Header is incompleted and the last record has completed, then
812 // call Abort() to set the Header->Complete FLAG.
814 if ((Header
->Complete
!= FTW_VALID_STATE
) &&
815 (Record
->DestinationComplete
== FTW_VALID_STATE
) &&
816 IsLastRecordOfWrites (Header
, Record
)
819 Status
= FtwAbort (This
);
821 return EFI_NOT_FOUND
;
824 // If there is no write header/record, return not found.
826 if (Header
->HeaderAllocated
!= FTW_VALID_STATE
) {
828 return EFI_NOT_FOUND
;
831 // If this record SpareComplete has not set, then it can not restart.
833 if (Record
->SpareComplete
!= FTW_VALID_STATE
) {
834 Status
= GetPreviousRecordOfWrites (Header
, &Record
);
835 if (EFI_ERROR (Status
)) {
838 return EFI_NOT_FOUND
;
840 ASSERT (Record
!= NULL
);
844 // Fill all the requested values
846 CopyMem (CallerId
, &Header
->CallerId
, sizeof (EFI_GUID
));
848 *Offset
= Record
->Offset
;
849 *Length
= Record
->Length
;
850 *Complete
= (BOOLEAN
) (Record
->DestinationComplete
== FTW_VALID_STATE
);
852 if (*PrivateDataSize
< Header
->PrivateDataSize
) {
853 *PrivateDataSize
= Header
->PrivateDataSize
;
855 Status
= EFI_BUFFER_TOO_SMALL
;
857 *PrivateDataSize
= Header
->PrivateDataSize
;
858 CopyMem (PrivateData
, Record
+ 1, *PrivateDataSize
);
859 Status
= EFI_SUCCESS
;
862 DEBUG ((EFI_D_ERROR
, "Ftw: GetLasetWrite() success\n"));
868 Firmware Volume Block Protocol notification event handler.
870 Initialization for Fault Tolerant Write is done in this handler.
872 @param[in] Event Event whose notification function is being invoked.
873 @param[in] Context Pointer to the notification function's context.
877 FvbNotificationEvent (
883 EFI_HANDLE
*HandleBuffer
;
886 EFI_PHYSICAL_ADDRESS FvbBaseAddress
;
887 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
888 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
889 EFI_FVB_ATTRIBUTES_2 Attributes
;
890 EFI_FTW_DEVICE
*FtwDevice
;
891 EFI_FV_BLOCK_MAP_ENTRY
*FvbMapEntry
;
894 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
;
896 EFI_HANDLE FvbHandle
;
898 FtwDevice
= (EFI_FTW_DEVICE
*)Context
;
902 FtwDevice
->WorkSpaceAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet64 (PcdFlashNvStorageFtwWorkingBase64
);
903 if (FtwDevice
->WorkSpaceAddress
== 0) {
904 FtwDevice
->WorkSpaceAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet32 (PcdFlashNvStorageFtwWorkingBase
);
907 FtwDevice
->SpareAreaAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet64 (PcdFlashNvStorageFtwSpareBase64
);
908 if (FtwDevice
->SpareAreaAddress
== 0) {
909 FtwDevice
->SpareAreaAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet32 (PcdFlashNvStorageFtwSpareBase
);
914 // Locate all handles of Fvb protocol
916 Status
= gBS
->LocateHandleBuffer (
918 &gEfiFirmwareVolumeBlockProtocolGuid
,
923 if (EFI_ERROR (Status
)) {
928 // Get the FVB to access variable store
930 for (Index
= 0; Index
< HandleCount
; Index
+= 1) {
931 Status
= gBS
->HandleProtocol (
933 &gEfiFirmwareVolumeBlockProtocolGuid
,
936 if (EFI_ERROR (Status
)) {
937 Status
= EFI_NOT_FOUND
;
942 // Ensure this FVB protocol supported Write operation.
944 Status
= Fvb
->GetAttributes (Fvb
, &Attributes
);
945 if (EFI_ERROR (Status
) || ((Attributes
& EFI_FVB2_WRITE_STATUS
) == 0)) {
949 // Compare the address and select the right one
951 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
952 if (EFI_ERROR (Status
)) {
956 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) ((UINTN
) FvbBaseAddress
);
957 if ((FtwDevice
->FtwFvBlock
== NULL
) && (FtwDevice
->WorkSpaceAddress
>= FvbBaseAddress
) &&
958 ((FtwDevice
->WorkSpaceAddress
+ FtwDevice
->WorkSpaceLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
960 FtwDevice
->FtwFvBlock
= Fvb
;
962 // To get the LBA of work space
964 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
966 // Now, one FV has one type of BlockLength
968 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
969 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
970 if ((FtwDevice
->WorkSpaceAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
971 && (FtwDevice
->WorkSpaceAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
972 FtwDevice
->FtwWorkSpaceLba
= LbaIndex
- 1;
974 // Get the Work space size and Base(Offset)
976 FtwDevice
->FtwWorkSpaceSize
= FtwDevice
->WorkSpaceLength
;
977 FtwDevice
->FtwWorkSpaceBase
= (UINTN
) (FtwDevice
->WorkSpaceAddress
- (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)));
984 if ((FtwDevice
->FtwBackupFvb
== NULL
) && (FtwDevice
->SpareAreaAddress
>= FvbBaseAddress
) &&
985 ((FtwDevice
->SpareAreaAddress
+ FtwDevice
->SpareAreaLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
987 FtwDevice
->FtwBackupFvb
= Fvb
;
989 // To get the LBA of spare
991 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
993 // Now, one FV has one type of BlockLength
995 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
996 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
997 if ((FtwDevice
->SpareAreaAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
998 && (FtwDevice
->SpareAreaAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
1000 // Get the NumberOfSpareBlock and BlockSize
1002 FtwDevice
->FtwSpareLba
= LbaIndex
- 1;
1003 FtwDevice
->BlockSize
= FvbMapEntry
->Length
;
1004 FtwDevice
->NumberOfSpareBlock
= FtwDevice
->SpareAreaLength
/ FtwDevice
->BlockSize
;
1006 // Check the range of spare area to make sure that it's in FV range
1008 if ((FtwDevice
->FtwSpareLba
+ FtwDevice
->NumberOfSpareBlock
) > FvbMapEntry
->NumBlocks
) {
1009 DEBUG ((EFI_D_ERROR
, "Ftw: Spare area is out of FV range\n"));
1020 if ((FtwDevice
->FtwBackupFvb
== NULL
) || (FtwDevice
->FtwFvBlock
== NULL
) ||
1021 (FtwDevice
->FtwWorkSpaceLba
== (EFI_LBA
) (-1)) || (FtwDevice
->FtwSpareLba
== (EFI_LBA
) (-1))) {
1025 DEBUG ((EFI_D_INFO
, "Ftw: Working and spare FVB is ready\n"));
1027 // Calculate the start LBA of working block. Working block is an area which
1028 // contains working space in its last block and has the same size as spare
1029 // block, unless there are not enough blocks before the block that contains
1032 FtwDevice
->FtwWorkBlockLba
= FtwDevice
->FtwWorkSpaceLba
- FtwDevice
->NumberOfSpareBlock
+ 1;
1033 ASSERT ((INT64
) (FtwDevice
->FtwWorkBlockLba
) >= 0);
1036 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
1038 FtwDevice
->FtwWorkSpace
= (UINT8
*) (FtwDevice
+ 1);
1039 FtwDevice
->FtwWorkSpaceHeader
= (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*) FtwDevice
->FtwWorkSpace
;
1041 FtwDevice
->FtwLastWriteHeader
= NULL
;
1042 FtwDevice
->FtwLastWriteRecord
= NULL
;
1045 // Refresh the working space data from working block
1047 Status
= WorkSpaceRefresh (FtwDevice
);
1048 ASSERT_EFI_ERROR (Status
);
1050 // If the working block workspace is not valid, try the spare block
1052 if (!IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1054 // Read from spare block
1056 Length
= FtwDevice
->FtwWorkSpaceSize
;
1057 Status
= FtwDevice
->FtwBackupFvb
->Read (
1058 FtwDevice
->FtwBackupFvb
,
1059 FtwDevice
->FtwSpareLba
,
1060 FtwDevice
->FtwWorkSpaceBase
,
1062 FtwDevice
->FtwWorkSpace
1064 ASSERT_EFI_ERROR (Status
);
1067 // If spare block is valid, then replace working block content.
1069 if (IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1070 Status
= FlushSpareBlockToWorkingBlock (FtwDevice
);
1071 DEBUG ((EFI_D_ERROR
, "Ftw: Restart working block update in Init() - %r\n", Status
));
1072 FtwAbort (&FtwDevice
->FtwInstance
);
1074 // Refresh work space.
1076 Status
= WorkSpaceRefresh (FtwDevice
);
1077 ASSERT_EFI_ERROR (Status
);
1079 DEBUG ((EFI_D_ERROR
, "Ftw: Both are invalid, init workspace\n"));
1081 // If both are invalid, then initialize work space.
1084 FtwDevice
->FtwWorkSpace
,
1085 FtwDevice
->FtwWorkSpaceSize
,
1088 InitWorkSpaceHeader (FtwDevice
->FtwWorkSpaceHeader
);
1090 // Initialize the work space
1092 Status
= FtwReclaimWorkSpace (FtwDevice
, FALSE
);
1093 ASSERT_EFI_ERROR (Status
);
1097 // If the FtwDevice->FtwLastWriteRecord is 1st record of write header &&
1098 // (! SpareComplete) THEN call Abort().
1100 if ((FtwDevice
->FtwLastWriteHeader
->HeaderAllocated
== FTW_VALID_STATE
) &&
1101 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
!= FTW_VALID_STATE
) &&
1102 IsFirstRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1104 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find first record not SpareCompleted, abort()\n"));
1105 FtwAbort (&FtwDevice
->FtwInstance
);
1108 // If Header is incompleted and the last record has completed, then
1109 // call Abort() to set the Header->Complete FLAG.
1111 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1112 (FtwDevice
->FtwLastWriteRecord
->DestinationComplete
== FTW_VALID_STATE
) &&
1113 IsLastRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1115 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find last record completed but header not, abort()\n"));
1116 FtwAbort (&FtwDevice
->FtwInstance
);
1119 // To check the workspace buffer following last Write header/records is EMPTY or not.
1120 // If it's not EMPTY, FTW also need to call reclaim().
1122 FtwHeader
= FtwDevice
->FtwLastWriteHeader
;
1123 Offset
= (UINT8
*) FtwHeader
- FtwDevice
->FtwWorkSpace
;
1124 if (FtwDevice
->FtwWorkSpace
[Offset
] != FTW_ERASED_BYTE
) {
1125 Offset
+= WRITE_TOTAL_SIZE (FtwHeader
->NumberOfWrites
, FtwHeader
->PrivateDataSize
);
1128 if (!IsErasedFlashBuffer (FtwDevice
->FtwWorkSpace
+ Offset
, FtwDevice
->FtwWorkSpaceSize
- Offset
)) {
1129 Status
= FtwReclaimWorkSpace (FtwDevice
, TRUE
);
1130 ASSERT_EFI_ERROR (Status
);
1134 // Restart if it's boot block
1136 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1137 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
== FTW_VALID_STATE
)
1139 if (FtwDevice
->FtwLastWriteRecord
->BootBlockUpdate
== FTW_VALID_STATE
) {
1140 Status
= FlushSpareBlockToBootBlock (FtwDevice
);
1141 DEBUG ((EFI_D_ERROR
, "Ftw: Restart boot block update - %r\n", Status
));
1142 ASSERT_EFI_ERROR (Status
);
1143 FtwAbort (&FtwDevice
->FtwInstance
);
1146 // if (SpareCompleted) THEN Restart to fault tolerant write.
1148 FvbHandle
= GetFvbByAddress (FtwDevice
->FtwLastWriteRecord
->FvBaseAddress
, &Fvb
);
1149 if (FvbHandle
!= NULL
) {
1150 Status
= FtwRestart (&FtwDevice
->FtwInstance
, FvbHandle
);
1151 DEBUG ((EFI_D_ERROR
, "FtwLite: Restart last write - %r\n", Status
));
1152 ASSERT_EFI_ERROR (Status
);
1154 FtwAbort (&FtwDevice
->FtwInstance
);
1158 // Hook the protocol API
1160 FtwDevice
->FtwInstance
.GetMaxBlockSize
= FtwGetMaxBlockSize
;
1161 FtwDevice
->FtwInstance
.Allocate
= FtwAllocate
;
1162 FtwDevice
->FtwInstance
.Write
= FtwWrite
;
1163 FtwDevice
->FtwInstance
.Restart
= FtwRestart
;
1164 FtwDevice
->FtwInstance
.Abort
= FtwAbort
;
1165 FtwDevice
->FtwInstance
.GetLastWrite
= FtwGetLastWrite
;
1168 // Install protocol interface
1170 Status
= gBS
->InstallProtocolInterface (
1172 &gEfiFaultTolerantWriteProtocolGuid
,
1173 EFI_NATIVE_INTERFACE
,
1174 &FtwDevice
->FtwInstance
1177 ASSERT_EFI_ERROR (Status
);
1180 // Close the notify event to avoid install FaultTolerantWriteProtocol again.
1182 Status
= gBS
->CloseEvent (Event
);
1183 ASSERT_EFI_ERROR (Status
);
1189 This function is the entry point of the Fault Tolerant Write driver.
1191 @param ImageHandle A handle for the image that is initializing this driver
1192 @param SystemTable A pointer to the EFI system table
1194 @return EFI_SUCCESS FTW has finished the initialization
1195 @retval EFI_NOT_FOUND Locate FVB protocol error
1196 @retval EFI_OUT_OF_RESOURCES Allocate memory error
1197 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
1198 @retval EFI_ABORTED FTW initialization error
1203 InitializeFaultTolerantWrite (
1204 IN EFI_HANDLE ImageHandle
,
1205 IN EFI_SYSTEM_TABLE
*SystemTable
1208 EFI_FTW_DEVICE
*FtwDevice
;
1211 // Allocate Private data of this driver,
1212 // INCLUDING THE FtwWorkSpace[FTW_WORK_SPACE_SIZE].
1215 FtwDevice
= AllocateZeroPool (sizeof (EFI_FTW_DEVICE
) + PcdGet32 (PcdFlashNvStorageFtwWorkingSize
));
1216 if (FtwDevice
== NULL
) {
1217 return EFI_OUT_OF_RESOURCES
;
1220 ZeroMem (FtwDevice
, sizeof (EFI_FTW_DEVICE
));
1221 FtwDevice
->Signature
= FTW_DEVICE_SIGNATURE
;
1224 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
1227 FtwDevice
->WorkSpaceLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwWorkingSize
);
1229 FtwDevice
->SpareAreaLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwSpareSize
);
1231 if ((FtwDevice
->WorkSpaceLength
== 0) || (FtwDevice
->SpareAreaLength
== 0)) {
1232 DEBUG ((EFI_D_ERROR
, "Ftw: Workspace or Spare block does not exist!\n"));
1233 FreePool (FtwDevice
);
1234 return EFI_OUT_OF_RESOURCES
;
1236 FtwDevice
->FtwFvBlock
= NULL
;
1237 FtwDevice
->FtwBackupFvb
= NULL
;
1238 FtwDevice
->FtwWorkSpaceLba
= (EFI_LBA
) (-1);
1239 FtwDevice
->FtwSpareLba
= (EFI_LBA
) (-1);
1242 // Register FvbNotificationEvent () notify function.
1244 EfiCreateProtocolNotifyEvent (
1245 &gEfiFirmwareVolumeBlockProtocolGuid
,
1247 FvbNotificationEvent
,