3 Internal generic functions to operate flash block.
5 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #include "FaultTolerantWrite.h"
20 Check whether a flash buffer is erased.
22 @param Buffer Buffer to check
23 @param BufferSize Size of the buffer
25 @return A BOOLEAN value indicating erased or not.
40 for (Index
= 0; Index
< BufferSize
; Index
+= 1) {
41 if (*Ptr
++ != FTW_ERASED_BYTE
) {
51 To erase the block with the spare block size.
54 @param FtwDevice The private data of FTW driver
55 @param FvBlock FVB Protocol interface
56 @param Lba Lba of the firmware block
58 @retval EFI_SUCCESS Block LBA is Erased successfully
59 @retval Others Error occurs
64 IN EFI_FTW_DEVICE
*FtwDevice
,
65 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
69 return FvBlock
->EraseBlocks (
72 FtwDevice
->NumberOfSpareBlock
,
73 EFI_LBA_LIST_TERMINATOR
80 @param FtwDevice The private data of FTW driver
82 @retval EFI_SUCCESS The erase request was successfully completed.
83 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
84 @retval EFI_DEVICE_ERROR The block device is not functioning
85 correctly and could not be written.
86 The firmware device may have been
88 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
89 in the variable argument list do
90 not exist in the firmware volume.
96 IN EFI_FTW_DEVICE
*FtwDevice
99 return FtwDevice
->FtwBackupFvb
->EraseBlocks (
100 FtwDevice
->FtwBackupFvb
,
101 FtwDevice
->FtwSpareLba
,
102 FtwDevice
->NumberOfSpareBlock
,
103 EFI_LBA_LIST_TERMINATOR
109 Is it in working block?
111 @param FtwDevice The private data of FTW driver
112 @param FvBlock Fvb protocol instance
113 @param Lba The block specified
115 @return A BOOLEAN value indicating in working block or not.
120 EFI_FTW_DEVICE
*FtwDevice
,
121 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
126 // If matching the following condition, the target block is in working block.
127 // 1. Target block is on the FV of working block (Using the same FVB protocol instance).
128 // 2. Lba falls into the range of working block.
132 (FvBlock
== FtwDevice
->FtwFvBlock
) &&
133 (Lba
>= FtwDevice
->FtwWorkBlockLba
) &&
134 (Lba
<= FtwDevice
->FtwWorkSpaceLba
)
140 Get firmware block by address.
143 @param Address Address specified the block
144 @param FvBlock The block caller wanted
146 @retval EFI_SUCCESS The protocol instance if found.
147 @retval EFI_NOT_FOUND Block not found
152 IN EFI_PHYSICAL_ADDRESS Address
,
153 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
157 EFI_HANDLE
*HandleBuffer
;
160 EFI_PHYSICAL_ADDRESS FvbBaseAddress
;
161 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
162 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
163 EFI_HANDLE FvbHandle
;
169 // Locate all handles of Fvb protocol
171 Status
= GetFvbCountAndBuffer (&HandleCount
, &HandleBuffer
);
172 if (EFI_ERROR (Status
)) {
176 // Get the FVB to access variable store
178 for (Index
= 0; Index
< HandleCount
; Index
+= 1) {
179 Status
= FtwGetFvbByHandle (HandleBuffer
[Index
], &Fvb
);
180 if (EFI_ERROR (Status
)) {
184 // Compare the address and select the right one
186 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
187 if (EFI_ERROR (Status
)) {
191 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) ((UINTN
) FvbBaseAddress
);
192 if ((Address
>= FvbBaseAddress
) && (Address
<= (FvbBaseAddress
+ (FwVolHeader
->FvLength
- 1)))) {
194 FvbHandle
= HandleBuffer
[Index
];
199 FreePool (HandleBuffer
);
207 @param FtwDevice The private data of FTW driver
208 @param FvBlock Fvb protocol instance
209 @param Lba The block specified
211 @return A BOOLEAN value indicating in boot block or not.
216 EFI_FTW_DEVICE
*FtwDevice
,
217 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
222 EFI_SWAP_ADDRESS_RANGE_PROTOCOL
*SarProtocol
;
223 EFI_PHYSICAL_ADDRESS BootBlockBase
;
225 EFI_PHYSICAL_ADDRESS BackupBlockBase
;
226 UINTN BackupBlockSize
;
227 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*BootFvb
;
229 EFI_HANDLE FvbHandle
;
231 if (!FeaturePcdGet(PcdFullFtwServiceEnable
)) {
235 Status
= FtwGetSarProtocol ((VOID
**) &SarProtocol
);
236 if (EFI_ERROR (Status
)) {
240 // Get the boot block range
242 Status
= SarProtocol
->GetRangeLocation (
249 if (EFI_ERROR (Status
)) {
253 Status
= SarProtocol
->GetSwapState (SarProtocol
, &IsSwapped
);
254 if (EFI_ERROR (Status
)) {
258 // Get FVB by address
261 FvbHandle
= GetFvbByAddress (BootBlockBase
, &BootFvb
);
263 FvbHandle
= GetFvbByAddress (BackupBlockBase
, &BootFvb
);
266 if (FvbHandle
== NULL
) {
272 return (BOOLEAN
) (FvBlock
== BootFvb
);
276 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
277 Spare block is accessed by FTW working FVB protocol interface. LBA is 1.
278 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
280 FTW will do extra work on boot block update.
281 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL,
282 which is produced by a chipset driver.
283 FTW updating boot block steps may be:
284 1. GetRangeLocation(), if the Range is inside the boot block, FTW know
285 that boot block will be update. It shall add a FLAG in the working block.
286 2. When spare block is ready,
287 3. SetSwapState(EFI_SWAPPED)
288 4. erasing boot block,
289 5. programming boot block until the boot block is ok.
290 6. SetSwapState(UNSWAPPED)
291 FTW shall not allow to update boot block when battery state is error.
293 @param FtwDevice The private data of FTW driver
295 @retval EFI_SUCCESS Spare block content is copied to boot block
296 @retval EFI_INVALID_PARAMETER Input parameter error
297 @retval EFI_OUT_OF_RESOURCES Allocate memory error
298 @retval EFI_ABORTED The function could not complete successfully
302 FlushSpareBlockToBootBlock (
303 EFI_FTW_DEVICE
*FtwDevice
313 EFI_SWAP_ADDRESS_RANGE_PROTOCOL
*SarProtocol
;
314 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*BootFvb
;
317 if (!FeaturePcdGet(PcdFullFtwServiceEnable
)) {
318 return EFI_UNSUPPORTED
;
322 // Locate swap address range protocol
324 Status
= FtwGetSarProtocol ((VOID
**) &SarProtocol
);
325 if (EFI_ERROR (Status
)) {
329 // Allocate a memory buffer
331 Length
= FtwDevice
->SpareAreaLength
;
332 Buffer
= AllocatePool (Length
);
333 if (Buffer
== NULL
) {
334 return EFI_OUT_OF_RESOURCES
;
337 // Get TopSwap bit state
339 Status
= SarProtocol
->GetSwapState (SarProtocol
, &TopSwap
);
340 if (EFI_ERROR (Status
)) {
341 DEBUG ((EFI_D_ERROR
, "Ftw: Get Top Swapped status - %r\n", Status
));
348 // Get FVB of current boot block
350 if (GetFvbByAddress (FtwDevice
->SpareAreaAddress
+ FtwDevice
->SpareAreaLength
, &BootFvb
) == NULL
) {
355 // Read data from current boot block
359 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
360 Count
= FtwDevice
->BlockSize
;
361 Status
= BootFvb
->Read (
368 if (EFI_ERROR (Status
)) {
377 // Read data from spare block
380 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
381 Count
= FtwDevice
->BlockSize
;
382 Status
= FtwDevice
->FtwBackupFvb
->Read (
383 FtwDevice
->FtwBackupFvb
,
384 FtwDevice
->FtwSpareLba
+ Index
,
389 if (EFI_ERROR (Status
)) {
399 Status
= SarProtocol
->SetSwapState (SarProtocol
, TRUE
);
400 if (EFI_ERROR (Status
)) {
406 // Erase current spare block
407 // Because TopSwap is set, this actually erase the top block (boot block)!
409 Status
= FtwEraseSpareBlock (FtwDevice
);
410 if (EFI_ERROR (Status
)) {
415 // Write memory buffer to current spare block. Still top block.
418 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
419 Count
= FtwDevice
->BlockSize
;
420 Status
= FtwDevice
->FtwBackupFvb
->Write (
421 FtwDevice
->FtwBackupFvb
,
422 FtwDevice
->FtwSpareLba
+ Index
,
427 if (EFI_ERROR (Status
)) {
428 DEBUG ((EFI_D_ERROR
, "Ftw: FVB Write boot block - %r\n", Status
));
441 Status
= SarProtocol
->SetSwapState (SarProtocol
, FALSE
);
447 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
448 Spare block is accessed by FTW backup FVB protocol interface. LBA is 1.
449 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
452 @param FtwDevice The private data of FTW driver
453 @param FvBlock FVB Protocol interface to access target block
454 @param Lba Lba of the target block
456 @retval EFI_SUCCESS Spare block content is copied to target block
457 @retval EFI_INVALID_PARAMETER Input parameter error
458 @retval EFI_OUT_OF_RESOURCES Allocate memory error
459 @retval EFI_ABORTED The function could not complete successfully
463 FlushSpareBlockToTargetBlock (
464 EFI_FTW_DEVICE
*FtwDevice
,
465 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
476 if ((FtwDevice
== NULL
) || (FvBlock
== NULL
)) {
477 return EFI_INVALID_PARAMETER
;
480 // Allocate a memory buffer
482 Length
= FtwDevice
->SpareAreaLength
;
483 Buffer
= AllocatePool (Length
);
484 if (Buffer
== NULL
) {
485 return EFI_OUT_OF_RESOURCES
;
488 // Read all content of spare block to memory buffer
491 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
492 Count
= FtwDevice
->BlockSize
;
493 Status
= FtwDevice
->FtwBackupFvb
->Read (
494 FtwDevice
->FtwBackupFvb
,
495 FtwDevice
->FtwSpareLba
+ Index
,
500 if (EFI_ERROR (Status
)) {
508 // Erase the target block
510 Status
= FtwEraseBlock (FtwDevice
, FvBlock
, Lba
);
511 if (EFI_ERROR (Status
)) {
516 // Write memory buffer to block, using the FvbBlock protocol interface
519 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
520 Count
= FtwDevice
->BlockSize
;
521 Status
= FvBlock
->Write (FvBlock
, Lba
+ Index
, 0, &Count
, Ptr
);
522 if (EFI_ERROR (Status
)) {
523 DEBUG ((EFI_D_ERROR
, "Ftw: FVB Write block - %r\n", Status
));
537 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
538 Spare block is accessed by FTW backup FVB protocol interface. LBA is
539 FtwDevice->FtwSpareLba.
540 Working block is accessed by FTW working FVB protocol interface. LBA is
541 FtwDevice->FtwWorkBlockLba.
543 Since the working block header is important when FTW initializes, the
544 state of the operation should be handled carefully. The Crc value is
545 calculated without STATE element.
547 @param FtwDevice The private data of FTW driver
549 @retval EFI_SUCCESS Spare block content is copied to target block
550 @retval EFI_OUT_OF_RESOURCES Allocate memory error
551 @retval EFI_ABORTED The function could not complete successfully
555 FlushSpareBlockToWorkingBlock (
556 EFI_FTW_DEVICE
*FtwDevice
562 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingBlockHeader
;
566 EFI_LBA WorkSpaceLbaOffset
;
569 // Allocate a memory buffer
571 Length
= FtwDevice
->SpareAreaLength
;
572 Buffer
= AllocatePool (Length
);
573 if (Buffer
== NULL
) {
574 return EFI_OUT_OF_RESOURCES
;
577 WorkSpaceLbaOffset
= FtwDevice
->FtwWorkSpaceLba
- FtwDevice
->FtwWorkBlockLba
;
580 // To guarantee that the WorkingBlockValid is set on spare block
582 // Offset = OFFSET_OF(EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER,
583 // WorkingBlockValid);
584 // To skip Signature and Crc: sizeof(EFI_GUID)+sizeof(UINT32).
587 FtwDevice
->FtwBackupFvb
,
588 FtwDevice
->FtwSpareLba
+ WorkSpaceLbaOffset
,
589 FtwDevice
->FtwWorkSpaceBase
+ sizeof (EFI_GUID
) + sizeof (UINT32
),
593 // Read from spare block to memory buffer
596 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
597 Count
= FtwDevice
->BlockSize
;
598 Status
= FtwDevice
->FtwBackupFvb
->Read (
599 FtwDevice
->FtwBackupFvb
,
600 FtwDevice
->FtwSpareLba
+ Index
,
605 if (EFI_ERROR (Status
)) {
613 // Clear the CRC and STATE, copy data from spare to working block.
615 WorkingBlockHeader
= (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*) (Buffer
+ (UINTN
) WorkSpaceLbaOffset
* FtwDevice
->BlockSize
+ FtwDevice
->FtwWorkSpaceBase
);
616 InitWorkSpaceHeader (WorkingBlockHeader
);
617 WorkingBlockHeader
->WorkingBlockValid
= FTW_ERASE_POLARITY
;
618 WorkingBlockHeader
->WorkingBlockInvalid
= FTW_ERASE_POLARITY
;
621 // target block is working block, then
622 // Set WorkingBlockInvalid in EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
623 // before erase the working block.
625 // Offset = OFFSET_OF(EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER,
626 // WorkingBlockInvalid);
627 // So hardcode offset as sizeof(EFI_GUID)+sizeof(UINT32) to
628 // skip Signature and Crc.
630 Status
= FtwUpdateFvState (
631 FtwDevice
->FtwFvBlock
,
632 FtwDevice
->FtwWorkSpaceLba
,
633 FtwDevice
->FtwWorkSpaceBase
+ sizeof (EFI_GUID
) + sizeof (UINT32
),
634 WORKING_BLOCK_INVALID
636 if (EFI_ERROR (Status
)) {
641 FtwDevice
->FtwWorkSpaceHeader
->WorkingBlockInvalid
= FTW_VALID_STATE
;
644 // Erase the working block
646 Status
= FtwEraseBlock (FtwDevice
, FtwDevice
->FtwFvBlock
, FtwDevice
->FtwWorkBlockLba
);
647 if (EFI_ERROR (Status
)) {
652 // Write memory buffer to working block, using the FvbBlock protocol interface
655 for (Index
= 0; Index
< FtwDevice
->NumberOfSpareBlock
; Index
+= 1) {
656 Count
= FtwDevice
->BlockSize
;
657 Status
= FtwDevice
->FtwFvBlock
->Write (
658 FtwDevice
->FtwFvBlock
,
659 FtwDevice
->FtwWorkBlockLba
+ Index
,
664 if (EFI_ERROR (Status
)) {
665 DEBUG ((EFI_D_ERROR
, "Ftw: FVB Write block - %r\n", Status
));
673 // Since the memory buffer will not be used, free memory Buffer.
678 // Update the VALID of the working block
680 // Offset = OFFSET_OF(EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER, WorkingBlockValid);
681 // So hardcode offset as sizeof(EFI_GUID)+sizeof(UINT32) to skip Signature and Crc.
683 Status
= FtwUpdateFvState (
684 FtwDevice
->FtwFvBlock
,
685 FtwDevice
->FtwWorkSpaceLba
,
686 FtwDevice
->FtwWorkSpaceBase
+ sizeof (EFI_GUID
) + sizeof (UINT32
),
689 if (EFI_ERROR (Status
)) {
693 FtwDevice
->FtwWorkSpaceHeader
->WorkingBlockInvalid
= FTW_INVALID_STATE
;
694 FtwDevice
->FtwWorkSpaceHeader
->WorkingBlockValid
= FTW_VALID_STATE
;
700 Update a bit of state on a block device. The location of the bit is
701 calculated by the (Lba, Offset, bit). Here bit is determined by the
702 the name of a certain bit.
705 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
706 @param Lba Lba of a block
707 @param Offset Offset on the Lba
708 @param NewBit New value that will override the old value if it can be change
710 @retval EFI_SUCCESS A state bit has been updated successfully
711 @retval Others Access block device error.
713 Assume all bits of State are inside the same BYTE.
714 @retval EFI_ABORTED Read block fail
719 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
730 // Read state from device, assume State is only one byte.
732 Length
= sizeof (UINT8
);
733 Status
= FvBlock
->Read (FvBlock
, Lba
, Offset
, &Length
, &State
);
734 if (EFI_ERROR (Status
)) {
738 State
^= FTW_POLARITY_REVERT
;
739 State
= (UINT8
) (State
| NewBit
);
740 State
^= FTW_POLARITY_REVERT
;
743 // Write state back to device
745 Length
= sizeof (UINT8
);
746 Status
= FvBlock
->Write (FvBlock
, Lba
, Offset
, &Length
, &State
);
752 Get the last Write Header pointer.
753 The last write header is the header whose 'complete' state hasn't been set.
754 After all, this header may be a EMPTY header entry for next Allocate.
757 @param FtwWorkSpaceHeader Pointer of the working block header
758 @param FtwWorkSpaceSize Size of the work space
759 @param FtwWriteHeader Pointer to retrieve the last write header
761 @retval EFI_SUCCESS Get the last write record successfully
762 @retval EFI_ABORTED The FTW work space is damaged
766 FtwGetLastWriteHeader (
767 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
,
768 IN UINTN FtwWorkSpaceSize
,
769 OUT EFI_FAULT_TOLERANT_WRITE_HEADER
**FtwWriteHeader
773 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
;
775 *FtwWriteHeader
= NULL
;
776 FtwHeader
= (EFI_FAULT_TOLERANT_WRITE_HEADER
*) (FtwWorkSpaceHeader
+ 1);
777 Offset
= sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
);
779 while (FtwHeader
->Complete
== FTW_VALID_STATE
) {
780 Offset
+= FTW_WRITE_TOTAL_SIZE (FtwHeader
->NumberOfWrites
, FtwHeader
->PrivateDataSize
);
782 // If Offset exceed the FTW work space boudary, return error.
784 if (Offset
>= FtwWorkSpaceSize
) {
785 *FtwWriteHeader
= FtwHeader
;
789 FtwHeader
= (EFI_FAULT_TOLERANT_WRITE_HEADER
*) ((UINT8
*) FtwWorkSpaceHeader
+ Offset
);
792 // Last write header is found
794 *FtwWriteHeader
= FtwHeader
;
800 Get the last Write Record pointer. The last write Record is the Record
801 whose DestinationCompleted state hasn't been set. After all, this Record
802 may be a EMPTY record entry for next write.
805 @param FtwWriteHeader Pointer to the write record header
806 @param FtwWriteRecord Pointer to retrieve the last write record
808 @retval EFI_SUCCESS Get the last write record successfully
809 @retval EFI_ABORTED The FTW work space is damaged
813 FtwGetLastWriteRecord (
814 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwWriteHeader
,
815 OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwWriteRecord
819 EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
;
821 *FtwWriteRecord
= NULL
;
822 FtwRecord
= (EFI_FAULT_TOLERANT_WRITE_RECORD
*) (FtwWriteHeader
+ 1);
825 // Try to find the last write record "that has not completed"
827 for (Index
= 0; Index
< FtwWriteHeader
->NumberOfWrites
; Index
+= 1) {
828 if (FtwRecord
->DestinationComplete
!= FTW_VALID_STATE
) {
830 // The last write record is found
832 *FtwWriteRecord
= FtwRecord
;
838 if (FtwWriteHeader
->PrivateDataSize
!= 0) {
839 FtwRecord
= (EFI_FAULT_TOLERANT_WRITE_RECORD
*) ((UINTN
) FtwRecord
+ (UINTN
) FtwWriteHeader
->PrivateDataSize
);
843 // if Index == NumberOfWrites, then
844 // the last record has been written successfully,
845 // but the Header->Complete Flag has not been set.
846 // also return the last record.
848 if (Index
== FtwWriteHeader
->NumberOfWrites
) {
849 *FtwWriteRecord
= (EFI_FAULT_TOLERANT_WRITE_RECORD
*) ((UINTN
) FtwRecord
- FTW_RECORD_SIZE (FtwWriteHeader
->PrivateDataSize
));
857 To check if FtwRecord is the first record of FtwHeader.
859 @param FtwHeader Pointer to the write record header
860 @param FtwRecord Pointer to the write record
862 @retval TRUE FtwRecord is the first Record of the FtwHeader
863 @retval FALSE FtwRecord is not the first Record of the FtwHeader
867 IsFirstRecordOfWrites (
868 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
869 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
875 Head
= (UINT8
*) FtwHeader
;
876 Ptr
= (UINT8
*) FtwRecord
;
878 Head
+= sizeof (EFI_FAULT_TOLERANT_WRITE_HEADER
);
879 return (BOOLEAN
) (Head
== Ptr
);
883 To check if FtwRecord is the last record of FtwHeader. Because the
884 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be
885 determined if it is the last record of FtwHeader.
887 @param FtwHeader Pointer to the write record header
888 @param FtwRecord Pointer to the write record
890 @retval TRUE FtwRecord is the last Record of the FtwHeader
891 @retval FALSE FtwRecord is not the last Record of the FtwHeader
895 IsLastRecordOfWrites (
896 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
897 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
903 Head
= (UINT8
*) FtwHeader
;
904 Ptr
= (UINT8
*) FtwRecord
;
906 Head
+= FTW_WRITE_TOTAL_SIZE (FtwHeader
->NumberOfWrites
- 1, FtwHeader
->PrivateDataSize
);
907 return (BOOLEAN
) (Head
== Ptr
);
911 To check if FtwRecord is the first record of FtwHeader.
913 @param FtwHeader Pointer to the write record header
914 @param FtwRecord Pointer to retrieve the previous write record
916 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return.
917 @retval EFI_SUCCESS The previous write record is found.
921 GetPreviousRecordOfWrites (
922 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
923 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwRecord
928 if (IsFirstRecordOfWrites (FtwHeader
, *FtwRecord
)) {
930 return EFI_ACCESS_DENIED
;
933 Ptr
= (UINT8
*) (*FtwRecord
);
934 Ptr
-= FTW_RECORD_SIZE (FtwHeader
->PrivateDataSize
);
935 *FtwRecord
= (EFI_FAULT_TOLERANT_WRITE_RECORD
*) Ptr
;
940 Allocate private data for FTW driver and initialize it.
942 @param[out] FtwData Pointer to the FTW device structure
944 @retval EFI_SUCCESS Initialize the FTW device successfully.
945 @retval EFI_OUT_OF_RESOURCES Allocate memory error
946 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
951 OUT EFI_FTW_DEVICE
**FtwData
954 EFI_FTW_DEVICE
*FtwDevice
;
957 // Allocate private data of this driver,
958 // Including the FtwWorkSpace[FTW_WORK_SPACE_SIZE].
960 FtwDevice
= AllocateZeroPool (sizeof (EFI_FTW_DEVICE
) + PcdGet32 (PcdFlashNvStorageFtwWorkingSize
));
961 if (FtwDevice
== NULL
) {
962 return EFI_OUT_OF_RESOURCES
;
966 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
968 FtwDevice
->WorkSpaceLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwWorkingSize
);
969 FtwDevice
->SpareAreaLength
= (UINTN
) PcdGet32 (PcdFlashNvStorageFtwSpareSize
);
970 if ((FtwDevice
->WorkSpaceLength
== 0) || (FtwDevice
->SpareAreaLength
== 0)) {
971 DEBUG ((EFI_D_ERROR
, "Ftw: Workspace or Spare block does not exist!\n"));
972 FreePool (FtwDevice
);
973 return EFI_INVALID_PARAMETER
;
976 FtwDevice
->Signature
= FTW_DEVICE_SIGNATURE
;
977 FtwDevice
->FtwFvBlock
= NULL
;
978 FtwDevice
->FtwBackupFvb
= NULL
;
979 FtwDevice
->FtwWorkSpaceLba
= (EFI_LBA
) (-1);
980 FtwDevice
->FtwSpareLba
= (EFI_LBA
) (-1);
982 FtwDevice
->WorkSpaceAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet64 (PcdFlashNvStorageFtwWorkingBase64
);
983 if (FtwDevice
->WorkSpaceAddress
== 0) {
984 FtwDevice
->WorkSpaceAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet32 (PcdFlashNvStorageFtwWorkingBase
);
987 FtwDevice
->SpareAreaAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet64 (PcdFlashNvStorageFtwSpareBase64
);
988 if (FtwDevice
->SpareAreaAddress
== 0) {
989 FtwDevice
->SpareAreaAddress
= (EFI_PHYSICAL_ADDRESS
) PcdGet32 (PcdFlashNvStorageFtwSpareBase
);
992 *FtwData
= FtwDevice
;
998 Find the proper Firmware Volume Block protocol for FTW operation.
1000 @param[in, out] FtwDevice Pointer to the FTW device structure
1002 @retval EFI_SUCCESS Find the FVB protocol successfully.
1003 @retval EFI_NOT_FOUND No proper FVB protocol was found.
1004 @retval EFI_ABORTED Some data can not be got or be invalid.
1009 IN OUT EFI_FTW_DEVICE
*FtwDevice
1013 EFI_HANDLE
*HandleBuffer
;
1016 EFI_PHYSICAL_ADDRESS FvbBaseAddress
;
1017 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
1018 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
1019 EFI_FVB_ATTRIBUTES_2 Attributes
;
1020 EFI_FV_BLOCK_MAP_ENTRY
*FvbMapEntry
;
1023 HandleBuffer
= NULL
;
1026 // Get all FVB handle.
1028 Status
= GetFvbCountAndBuffer (&HandleCount
, &HandleBuffer
);
1029 if (EFI_ERROR (Status
)) {
1030 return EFI_NOT_FOUND
;
1034 // Get the FVB to access variable store
1037 for (Index
= 0; Index
< HandleCount
; Index
+= 1) {
1038 Status
= FtwGetFvbByHandle (HandleBuffer
[Index
], &Fvb
);
1039 if (EFI_ERROR (Status
)) {
1040 Status
= EFI_NOT_FOUND
;
1045 // Ensure this FVB protocol support Write operation.
1047 Status
= Fvb
->GetAttributes (Fvb
, &Attributes
);
1048 if (EFI_ERROR (Status
) || ((Attributes
& EFI_FVB2_WRITE_STATUS
) == 0)) {
1052 // Compare the address and select the right one
1054 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
1055 if (EFI_ERROR (Status
)) {
1059 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) ((UINTN
) FvbBaseAddress
);
1060 if ((FtwDevice
->FtwFvBlock
== NULL
) && (FtwDevice
->WorkSpaceAddress
>= FvbBaseAddress
) &&
1061 ((FtwDevice
->WorkSpaceAddress
+ FtwDevice
->WorkSpaceLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
1063 FtwDevice
->FtwFvBlock
= Fvb
;
1065 // To get the LBA of work space
1067 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
1069 // Now, one FV has one type of BlockLength
1071 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
1072 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
1073 if ((FtwDevice
->WorkSpaceAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
1074 && (FtwDevice
->WorkSpaceAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
1075 FtwDevice
->FtwWorkSpaceLba
= LbaIndex
- 1;
1077 // Get the Work space size and Base(Offset)
1079 FtwDevice
->FtwWorkSpaceSize
= FtwDevice
->WorkSpaceLength
;
1080 FtwDevice
->FtwWorkSpaceBase
= (UINTN
) (FtwDevice
->WorkSpaceAddress
- (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)));
1087 if ((FtwDevice
->FtwBackupFvb
== NULL
) && (FtwDevice
->SpareAreaAddress
>= FvbBaseAddress
) &&
1088 ((FtwDevice
->SpareAreaAddress
+ FtwDevice
->SpareAreaLength
) <= (FvbBaseAddress
+ FwVolHeader
->FvLength
))
1090 FtwDevice
->FtwBackupFvb
= Fvb
;
1092 // To get the LBA of spare
1094 if ((FwVolHeader
->FvLength
) > (FwVolHeader
->HeaderLength
)) {
1096 // Now, one FV has one type of BlockLength
1098 FvbMapEntry
= &FwVolHeader
->BlockMap
[0];
1099 for (LbaIndex
= 1; LbaIndex
<= FvbMapEntry
->NumBlocks
; LbaIndex
+= 1) {
1100 if ((FtwDevice
->SpareAreaAddress
>= (FvbBaseAddress
+ FvbMapEntry
->Length
* (LbaIndex
- 1)))
1101 && (FtwDevice
->SpareAreaAddress
< (FvbBaseAddress
+ FvbMapEntry
->Length
* LbaIndex
))) {
1103 // Get the NumberOfSpareBlock and BlockSize
1105 FtwDevice
->FtwSpareLba
= LbaIndex
- 1;
1106 FtwDevice
->BlockSize
= FvbMapEntry
->Length
;
1107 FtwDevice
->NumberOfSpareBlock
= FtwDevice
->SpareAreaLength
/ FtwDevice
->BlockSize
;
1109 // Check the range of spare area to make sure that it's in FV range
1111 if ((FtwDevice
->FtwSpareLba
+ FtwDevice
->NumberOfSpareBlock
) > FvbMapEntry
->NumBlocks
) {
1112 DEBUG ((EFI_D_ERROR
, "Ftw: Spare area is out of FV range\n"));
1113 FreePool (HandleBuffer
);
1118 // Check the alignment of spare area address and length, they should be block size aligned
1120 if (((FtwDevice
->SpareAreaAddress
& (FtwDevice
->BlockSize
- 1)) != 0) ||
1121 ((FtwDevice
->SpareAreaLength
& (FtwDevice
->BlockSize
- 1)) != 0)) {
1122 DEBUG ((EFI_D_ERROR
, "Ftw: Spare area address or length is not block size aligned\n"));
1123 FreePool (HandleBuffer
);
1125 // Report Status Code EFI_SW_EC_ABORTED.
1127 REPORT_STATUS_CODE ( (EFI_ERROR_CODE
| EFI_ERROR_UNRECOVERED
), (EFI_SOFTWARE_DXE_BS_DRIVER
| EFI_SW_EC_ABORTED
));
1137 FreePool (HandleBuffer
);
1139 if ((FtwDevice
->FtwBackupFvb
== NULL
) || (FtwDevice
->FtwFvBlock
== NULL
) ||
1140 (FtwDevice
->FtwWorkSpaceLba
== (EFI_LBA
) (-1)) || (FtwDevice
->FtwSpareLba
== (EFI_LBA
) (-1))) {
1149 Initialization for Fault Tolerant Write protocol.
1151 @param[in, out] FtwDevice Pointer to the FTW device structure
1153 @retval EFI_SUCCESS Initialize the FTW protocol successfully.
1154 @retval EFI_NOT_FOUND No proper FVB protocol was found.
1159 IN OUT EFI_FTW_DEVICE
*FtwDevice
1163 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
1165 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
;
1167 EFI_HANDLE FvbHandle
;
1168 EFI_LBA WorkSpaceLbaOffset
;
1171 // Find the right SMM Fvb protocol instance for FTW.
1173 Status
= FindFvbForFtw (FtwDevice
);
1174 if (EFI_ERROR (Status
)) {
1175 return EFI_NOT_FOUND
;
1179 // Calculate the start LBA of working block. Working block is an area which
1180 // contains working space in its last block and has the same size as spare
1181 // block, unless there are not enough blocks before the block that contains
1184 FtwDevice
->FtwWorkBlockLba
= FtwDevice
->FtwWorkSpaceLba
- FtwDevice
->NumberOfSpareBlock
+ 1;
1185 ASSERT ((INT64
) (FtwDevice
->FtwWorkBlockLba
) >= 0);
1188 // Initialize other parameters, and set WorkSpace as FTW_ERASED_BYTE.
1190 FtwDevice
->FtwWorkSpace
= (UINT8
*) (FtwDevice
+ 1);
1191 FtwDevice
->FtwWorkSpaceHeader
= (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*) FtwDevice
->FtwWorkSpace
;
1193 FtwDevice
->FtwLastWriteHeader
= NULL
;
1194 FtwDevice
->FtwLastWriteRecord
= NULL
;
1196 InitializeLocalWorkSpaceHeader ();
1199 // Refresh the working space data from working block
1201 Status
= WorkSpaceRefresh (FtwDevice
);
1202 ASSERT_EFI_ERROR (Status
);
1204 // If the working block workspace is not valid, try the spare block
1206 if (!IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1208 // Read from spare block
1210 WorkSpaceLbaOffset
= FtwDevice
->FtwWorkSpaceLba
- FtwDevice
->FtwWorkBlockLba
;
1211 Length
= FtwDevice
->FtwWorkSpaceSize
;
1212 Status
= FtwDevice
->FtwBackupFvb
->Read (
1213 FtwDevice
->FtwBackupFvb
,
1214 FtwDevice
->FtwSpareLba
+ WorkSpaceLbaOffset
,
1215 FtwDevice
->FtwWorkSpaceBase
,
1217 FtwDevice
->FtwWorkSpace
1219 ASSERT_EFI_ERROR (Status
);
1222 // If spare block is valid, then replace working block content.
1224 if (IsValidWorkSpace (FtwDevice
->FtwWorkSpaceHeader
)) {
1225 Status
= FlushSpareBlockToWorkingBlock (FtwDevice
);
1226 DEBUG ((EFI_D_ERROR
, "Ftw: Restart working block update in InitFtwProtocol() - %r\n", Status
));
1227 FtwAbort (&FtwDevice
->FtwInstance
);
1229 // Refresh work space.
1231 Status
= WorkSpaceRefresh (FtwDevice
);
1232 ASSERT_EFI_ERROR (Status
);
1234 DEBUG ((EFI_D_ERROR
, "Ftw: Both are invalid, init workspace\n"));
1236 // If both are invalid, then initialize work space.
1239 FtwDevice
->FtwWorkSpace
,
1240 FtwDevice
->FtwWorkSpaceSize
,
1243 InitWorkSpaceHeader (FtwDevice
->FtwWorkSpaceHeader
);
1245 // Initialize the work space
1247 Status
= FtwReclaimWorkSpace (FtwDevice
, FALSE
);
1248 ASSERT_EFI_ERROR (Status
);
1252 // If the FtwDevice->FtwLastWriteRecord is 1st record of write header &&
1253 // (! SpareComplete) THEN call Abort().
1255 if ((FtwDevice
->FtwLastWriteHeader
->HeaderAllocated
== FTW_VALID_STATE
) &&
1256 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
!= FTW_VALID_STATE
) &&
1257 IsFirstRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1259 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find first record not SpareCompleted, abort()\n"));
1260 FtwAbort (&FtwDevice
->FtwInstance
);
1263 // If Header is incompleted and the last record has completed, then
1264 // call Abort() to set the Header->Complete FLAG.
1266 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1267 (FtwDevice
->FtwLastWriteRecord
->DestinationComplete
== FTW_VALID_STATE
) &&
1268 IsLastRecordOfWrites (FtwDevice
->FtwLastWriteHeader
, FtwDevice
->FtwLastWriteRecord
)
1270 DEBUG ((EFI_D_ERROR
, "Ftw: Init.. find last record completed but header not, abort()\n"));
1271 FtwAbort (&FtwDevice
->FtwInstance
);
1274 // To check the workspace buffer following last Write header/records is EMPTY or not.
1275 // If it's not EMPTY, FTW also need to call reclaim().
1277 FtwHeader
= FtwDevice
->FtwLastWriteHeader
;
1278 Offset
= (UINT8
*) FtwHeader
- FtwDevice
->FtwWorkSpace
;
1279 if (FtwDevice
->FtwWorkSpace
[Offset
] != FTW_ERASED_BYTE
) {
1280 Offset
+= FTW_WRITE_TOTAL_SIZE (FtwHeader
->NumberOfWrites
, FtwHeader
->PrivateDataSize
);
1283 if (!IsErasedFlashBuffer (FtwDevice
->FtwWorkSpace
+ Offset
, FtwDevice
->FtwWorkSpaceSize
- Offset
)) {
1284 Status
= FtwReclaimWorkSpace (FtwDevice
, TRUE
);
1285 ASSERT_EFI_ERROR (Status
);
1289 // Restart if it's boot block
1291 if ((FtwDevice
->FtwLastWriteHeader
->Complete
!= FTW_VALID_STATE
) &&
1292 (FtwDevice
->FtwLastWriteRecord
->SpareComplete
== FTW_VALID_STATE
)
1294 if (FtwDevice
->FtwLastWriteRecord
->BootBlockUpdate
== FTW_VALID_STATE
) {
1295 Status
= FlushSpareBlockToBootBlock (FtwDevice
);
1296 DEBUG ((EFI_D_ERROR
, "Ftw: Restart boot block update - %r\n", Status
));
1297 ASSERT_EFI_ERROR (Status
);
1298 FtwAbort (&FtwDevice
->FtwInstance
);
1301 // if (SpareCompleted) THEN Restart to fault tolerant write.
1304 FvbHandle
= GetFvbByAddress ((EFI_PHYSICAL_ADDRESS
) (UINTN
) ((INT64
) FtwDevice
->SpareAreaAddress
+ FtwDevice
->FtwLastWriteRecord
->RelativeOffset
), &Fvb
);
1305 if (FvbHandle
!= NULL
) {
1306 Status
= FtwRestart (&FtwDevice
->FtwInstance
, FvbHandle
);
1307 DEBUG ((EFI_D_ERROR
, "FtwLite: Restart last write - %r\n", Status
));
1308 ASSERT_EFI_ERROR (Status
);
1310 FtwAbort (&FtwDevice
->FtwInstance
);
1314 // Hook the protocol API
1316 FtwDevice
->FtwInstance
.GetMaxBlockSize
= FtwGetMaxBlockSize
;
1317 FtwDevice
->FtwInstance
.Allocate
= FtwAllocate
;
1318 FtwDevice
->FtwInstance
.Write
= FtwWrite
;
1319 FtwDevice
->FtwInstance
.Restart
= FtwRestart
;
1320 FtwDevice
->FtwInstance
.Abort
= FtwAbort
;
1321 FtwDevice
->FtwInstance
.GetLastWrite
= FtwGetLastWrite
;