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
) PcdGet32 (PcdFlashNvStorageFtwWorkingBase
);
903 FtwDevice
->SpareAreaAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet32 (PcdFlashNvStorageFtwSpareBase
);
906 // Locate all handles of Fvb protocol
908 Status
= gBS
->LocateHandleBuffer (
910 &gEfiFirmwareVolumeBlockProtocolGuid
,
915 if (EFI_ERROR (Status
)) {
920 // Get the FVB to access variable store
922 for (Index
= 0; Index
< HandleCount
; Index
+= 1) {
923 Status
= gBS
->HandleProtocol (
925 &gEfiFirmwareVolumeBlockProtocolGuid
,
928 if (EFI_ERROR (Status
)) {
929 Status
= EFI_NOT_FOUND
;
934 // Ensure this FVB protocol supported Write operation.
936 Status
= Fvb
->GetAttributes (Fvb
, &Attributes
);
937 if (EFI_ERROR (Status
) || ((Attributes
& EFI_FVB2_WRITE_STATUS
) == 0)) {
941 // Compare the address and select the right one
943 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
944 if (EFI_ERROR (Status
)) {
948 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) ((UINTN
) FvbBaseAddress
);
949 if ((FtwDevice
->FtwFvBlock
== NULL
) && (FtwDevice
->WorkSpaceAddress
>= FvbBaseAddress
) &&
950 ((FtwDevice
->WorkSpaceAddress
+ FtwDevice
->WorkSpaceLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
952 FtwDevice
->FtwFvBlock
= Fvb
;
954 // To get the LBA of work space
956 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
958 // Now, one FV has one type of BlockLength
960 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
961 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
962 if ((FtwDevice
->WorkSpaceAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
963 && (FtwDevice
->WorkSpaceAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
964 FtwDevice
->FtwWorkSpaceLba
= LbaIndex
- 1;
966 // Get the Work space size and Base(Offset)
968 FtwDevice
->FtwWorkSpaceSize
= FtwDevice
->WorkSpaceLength
;
969 FtwDevice
->FtwWorkSpaceBase
= (UINTN
) (FtwDevice
->WorkSpaceAddress
- (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)));
976 if ((FtwDevice
->FtwBackupFvb
== NULL
) && (FtwDevice
->SpareAreaAddress
>= FvbBaseAddress
) &&
977 ((FtwDevice
->SpareAreaAddress
+ FtwDevice
->SpareAreaLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
979 FtwDevice
->FtwBackupFvb
= Fvb
;
981 // To get the LBA of spare
983 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
985 // Now, one FV has one type of BlockLength
987 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
988 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
989 if ((FtwDevice
->SpareAreaAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
990 && (FtwDevice
->SpareAreaAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
992 // Get the NumberOfSpareBlock and BlockSize
994 FtwDevice
->FtwSpareLba
= LbaIndex
- 1;
995 FtwDevice
->BlockSize
= FvbMapEntry
->Length
;
996 FtwDevice
->NumberOfSpareBlock
= FtwDevice
->SpareAreaLength
/ FtwDevice
->BlockSize
;
998 // Check the range of spare area to make sure that it's in FV range
1000 if ((FtwDevice
->FtwSpareLba
+ FtwDevice
->NumberOfSpareBlock
) > FvbMapEntry
->NumBlocks
) {
1001 DEBUG ((EFI_D_ERROR
, "Ftw: Spare area is out of FV range\n"));
1012 if ((FtwDevice
->FtwBackupFvb
== NULL
) || (FtwDevice
->FtwFvBlock
== NULL
) ||
1013 (FtwDevice
->FtwWorkSpaceLba
== (EFI_LBA
) (-1)) || (FtwDevice
->FtwSpareLba
== (EFI_LBA
) (-1))) {
1017 DEBUG ((EFI_D_INFO
, "Ftw: Working and spare FVB is ready\n"));
1019 // Calculate the start LBA of working block. Working block is an area which
1020 // contains working space in its last block and has the same size as spare
1021 // block, unless there are not enough blocks before the block that contains
1024 FtwDevice
->FtwWorkBlockLba
= FtwDevice
->FtwWorkSpaceLba
- FtwDevice
->NumberOfSpareBlock
+ 1;
1025 ASSERT ((INT64
) (FtwDevice
->FtwWorkBlockLba
) >= 0);
1028 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
1030 FtwDevice
->FtwWorkSpace
= (UINT8
*) (FtwDevice
+ 1);
1031 FtwDevice
->FtwWorkSpaceHeader
= (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*) FtwDevice
->FtwWorkSpace
;
1033 FtwDevice
->FtwLastWriteHeader
= NULL
;
1034 FtwDevice
->FtwLastWriteRecord
= NULL
;
1037 // Refresh the working space data from working block
1039 Status
= WorkSpaceRefresh (FtwDevice
);
1040 ASSERT_EFI_ERROR (Status
);
1042 // If the working block workspace is not valid, try the spare block
1044 if (!IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1046 // Read from spare block
1048 Length
= FtwDevice
->FtwWorkSpaceSize
;
1049 Status
= FtwDevice
->FtwBackupFvb
->Read (
1050 FtwDevice
->FtwBackupFvb
,
1051 FtwDevice
->FtwSpareLba
,
1052 FtwDevice
->FtwWorkSpaceBase
,
1054 FtwDevice
->FtwWorkSpace
1056 ASSERT_EFI_ERROR (Status
);
1059 // If spare block is valid, then replace working block content.
1061 if (IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1062 Status
= FlushSpareBlockToWorkingBlock (FtwDevice
);
1063 DEBUG ((EFI_D_ERROR
, "Ftw: Restart working block update in Init() - %r\n", Status
));
1064 FtwAbort (&FtwDevice
->FtwInstance
);
1066 // Refresh work space.
1068 Status
= WorkSpaceRefresh (FtwDevice
);
1069 ASSERT_EFI_ERROR (Status
);
1071 DEBUG ((EFI_D_ERROR
, "Ftw: Both are invalid, init workspace\n"));
1073 // If both are invalid, then initialize work space.
1076 FtwDevice
->FtwWorkSpace
,
1077 FtwDevice
->FtwWorkSpaceSize
,
1080 InitWorkSpaceHeader (FtwDevice
->FtwWorkSpaceHeader
);
1082 // Initialize the work space
1084 Status
= FtwReclaimWorkSpace (FtwDevice
, FALSE
);
1085 ASSERT_EFI_ERROR (Status
);
1089 // If the FtwDevice->FtwLastWriteRecord is 1st record of write header &&
1090 // (! SpareComplete) THEN call Abort().
1092 if ((FtwDevice
->FtwLastWriteHeader
->HeaderAllocated
== FTW_VALID_STATE
) &&
1093 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
!= FTW_VALID_STATE
) &&
1094 IsFirstRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1096 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find first record not SpareCompleted, abort()\n"));
1097 FtwAbort (&FtwDevice
->FtwInstance
);
1100 // If Header is incompleted and the last record has completed, then
1101 // call Abort() to set the Header->Complete FLAG.
1103 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1104 (FtwDevice
->FtwLastWriteRecord
->DestinationComplete
== FTW_VALID_STATE
) &&
1105 IsLastRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1107 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find last record completed but header not, abort()\n"));
1108 FtwAbort (&FtwDevice
->FtwInstance
);
1111 // To check the workspace buffer following last Write header/records is EMPTY or not.
1112 // If it's not EMPTY, FTW also need to call reclaim().
1114 FtwHeader
= FtwDevice
->FtwLastWriteHeader
;
1115 Offset
= (UINT8
*) FtwHeader
- FtwDevice
->FtwWorkSpace
;
1116 if (FtwDevice
->FtwWorkSpace
[Offset
] != FTW_ERASED_BYTE
) {
1117 Offset
+= WRITE_TOTAL_SIZE (FtwHeader
->NumberOfWrites
, FtwHeader
->PrivateDataSize
);
1120 if (!IsErasedFlashBuffer (FtwDevice
->FtwWorkSpace
+ Offset
, FtwDevice
->FtwWorkSpaceSize
- Offset
)) {
1121 Status
= FtwReclaimWorkSpace (FtwDevice
, TRUE
);
1122 ASSERT_EFI_ERROR (Status
);
1126 // Restart if it's boot block
1128 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1129 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
== FTW_VALID_STATE
)
1131 if (FtwDevice
->FtwLastWriteRecord
->BootBlockUpdate
== FTW_VALID_STATE
) {
1132 Status
= FlushSpareBlockToBootBlock (FtwDevice
);
1133 DEBUG ((EFI_D_ERROR
, "Ftw: Restart boot block update - %r\n", Status
));
1134 ASSERT_EFI_ERROR (Status
);
1135 FtwAbort (&FtwDevice
->FtwInstance
);
1138 // if (SpareCompleted) THEN Restart to fault tolerant write.
1140 FvbHandle
= GetFvbByAddress (FtwDevice
->FtwLastWriteRecord
->FvBaseAddress
, &Fvb
);
1141 if (FvbHandle
!= NULL
) {
1142 Status
= FtwRestart (&FtwDevice
->FtwInstance
, FvbHandle
);
1143 DEBUG ((EFI_D_ERROR
, "FtwLite: Restart last write - %r\n", Status
));
1144 ASSERT_EFI_ERROR (Status
);
1146 FtwAbort (&FtwDevice
->FtwInstance
);
1150 // Hook the protocol API
1152 FtwDevice
->FtwInstance
.GetMaxBlockSize
= FtwGetMaxBlockSize
;
1153 FtwDevice
->FtwInstance
.Allocate
= FtwAllocate
;
1154 FtwDevice
->FtwInstance
.Write
= FtwWrite
;
1155 FtwDevice
->FtwInstance
.Restart
= FtwRestart
;
1156 FtwDevice
->FtwInstance
.Abort
= FtwAbort
;
1157 FtwDevice
->FtwInstance
.GetLastWrite
= FtwGetLastWrite
;
1160 // Install protocol interface
1162 Status
= gBS
->InstallProtocolInterface (
1164 &gEfiFaultTolerantWriteProtocolGuid
,
1165 EFI_NATIVE_INTERFACE
,
1166 &FtwDevice
->FtwInstance
1169 ASSERT_EFI_ERROR (Status
);
1172 // Close the notify event to avoid install FaultTolerantWriteProtocol again.
1174 Status
= gBS
->CloseEvent (Event
);
1175 ASSERT_EFI_ERROR (Status
);
1181 This function is the entry point of the Fault Tolerant Write driver.
1183 @param ImageHandle A handle for the image that is initializing this driver
1184 @param SystemTable A pointer to the EFI system table
1186 @return EFI_SUCCESS FTW has finished the initialization
1187 @retval EFI_NOT_FOUND Locate FVB protocol error
1188 @retval EFI_OUT_OF_RESOURCES Allocate memory error
1189 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
1190 @retval EFI_ABORTED FTW initialization error
1195 InitializeFaultTolerantWrite (
1196 IN EFI_HANDLE ImageHandle
,
1197 IN EFI_SYSTEM_TABLE
*SystemTable
1200 EFI_FTW_DEVICE
*FtwDevice
;
1203 // Allocate Private data of this driver,
1204 // INCLUDING THE FtwWorkSpace[FTW_WORK_SPACE_SIZE].
1207 FtwDevice
= AllocateZeroPool (sizeof (EFI_FTW_DEVICE
) + PcdGet32 (PcdFlashNvStorageFtwWorkingSize
));
1208 if (FtwDevice
== NULL
) {
1209 return EFI_OUT_OF_RESOURCES
;
1212 ZeroMem (FtwDevice
, sizeof (EFI_FTW_DEVICE
));
1213 FtwDevice
->Signature
= FTW_DEVICE_SIGNATURE
;
1216 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
1219 FtwDevice
->WorkSpaceLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwWorkingSize
);
1221 FtwDevice
->SpareAreaLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwSpareSize
);
1223 if ((FtwDevice
->WorkSpaceLength
== 0) || (FtwDevice
->SpareAreaLength
== 0)) {
1224 DEBUG ((EFI_D_ERROR
, "Ftw: Workspace or Spare block does not exist!\n"));
1225 FreePool (FtwDevice
);
1226 return EFI_OUT_OF_RESOURCES
;
1228 FtwDevice
->FtwFvBlock
= NULL
;
1229 FtwDevice
->FtwBackupFvb
= NULL
;
1230 FtwDevice
->FtwWorkSpaceLba
= (EFI_LBA
) (-1);
1231 FtwDevice
->FtwSpareLba
= (EFI_LBA
) (-1);
1234 // Register FvbNotificationEvent () notify function.
1236 EfiCreateProtocolNotifyEvent (
1237 &gEfiFirmwareVolumeBlockProtocolGuid
,
1239 FvbNotificationEvent
,