3 The internal header file includes the common header files, defines
4 internal structure and functions used by Ftw module.
6 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #ifndef _EFI_FAULT_TOLERANT_WRITE_H_
12 #define _EFI_FAULT_TOLERANT_WRITE_H_
16 #include <Guid/SystemNvDataGuid.h>
17 #include <Guid/ZeroGuid.h>
18 #include <Protocol/FaultTolerantWrite.h>
19 #include <Protocol/FirmwareVolumeBlock.h>
20 #include <Protocol/SwapAddressRange.h>
22 #include <Library/PcdLib.h>
23 #include <Library/DebugLib.h>
24 #include <Library/UefiLib.h>
25 #include <Library/UefiDriverEntryPoint.h>
26 #include <Library/BaseMemoryLib.h>
27 #include <Library/MemoryAllocationLib.h>
28 #include <Library/ReportStatusCodeLib.h>
31 // Flash erase polarity is 1
33 #define FTW_ERASE_POLARITY 1
35 #define FTW_ERASED_BYTE ((UINT8) (255))
36 #define FTW_POLARITY_REVERT ((UINT8) (255))
38 #define HEADER_ALLOCATED 0x1
39 #define WRITES_ALLOCATED 0x2
40 #define WRITES_COMPLETED 0x4
42 #define BOOT_BLOCK_UPDATE 0x1
43 #define SPARE_COMPLETED 0x2
44 #define DEST_COMPLETED 0x4
46 #define FTW_BLOCKS(Length, BlockSize) ((UINTN) ((Length) / (BlockSize) + (((Length) & ((BlockSize) - 1)) ? 1 : 0)))
48 #define FTW_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'D')
51 // EFI Fault tolerant protocol private data structure
56 EFI_FAULT_TOLERANT_WRITE_PROTOCOL FtwInstance
;
57 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
58 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
59 UINTN WorkSpaceLength
; // Size of working space range in flash.
60 UINTN NumberOfWorkSpaceBlock
; // Number of the blocks in work block for work space.
61 UINTN WorkBlockSize
; // Block size in bytes of the work blocks in flash
62 UINTN SpareAreaLength
; // Size of spare range in flash.
63 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
64 UINTN SpareBlockSize
; // Block size in bytes of the spare blocks in flash
65 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
66 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwLastWriteHeader
;// Pointer to last record header in memory buffer
67 EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwLastWriteRecord
;// Pointer to last record in memory buffer
68 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
69 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
70 EFI_LBA FtwSpareLba
; // Start LBA of spare block
71 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
72 UINTN NumberOfWorkBlock
; // Number of the blocks in work block.
73 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
74 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
75 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
76 EFI_LBA FtwWorkSpaceLbaInSpare
; // Start LBA of working space in spare block.
77 UINTN FtwWorkSpaceBaseInSpare
;// Offset into the FtwWorkSpaceLbaInSpare block.
78 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
80 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
81 // Allocated with EFI_FTW_DEVICE.
85 #define FTW_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_DEVICE, FtwInstance, FTW_DEVICE_SIGNATURE)
91 This function is the entry point of the Fault Tolerant Write driver.
93 @param ImageHandle A handle for the image that is initializing this driver
94 @param SystemTable A pointer to the EFI system table
96 @return EFI_SUCCESS FTW has finished the initialization
97 @retval EFI_NOT_FOUND Locate FVB protocol error
98 @retval EFI_OUT_OF_RESOURCES Allocate memory error
99 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
100 @retval EFI_ABORTED FTW initialization error
105 InitializeFaultTolerantWrite (
106 IN EFI_HANDLE ImageHandle
,
107 IN EFI_SYSTEM_TABLE
*SystemTable
111 // Fault Tolerant Write Protocol API
115 Query the largest block that may be updated in a fault tolerant manner.
118 @param This Indicates a pointer to the calling context.
119 @param BlockSize A pointer to a caller allocated UINTN that is updated to
120 indicate the size of the largest block that can be updated.
122 @return EFI_SUCCESS The function completed successfully
128 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
133 Allocates space for the protocol to maintain information about writes.
134 Since writes must be completed in a fault tolerant manner and multiple
135 updates will require more resources to be successful, this function
136 enables the protocol to ensure that enough space exists to track
137 information about the upcoming writes.
139 All writes must be completed or aborted before another fault tolerant write can occur.
141 @param This Indicates a pointer to the calling context.
142 @param CallerId The GUID identifying the write.
143 @param PrivateDataSize The size of the caller's private data
144 that must be recorded for each write.
145 @param NumberOfWrites The number of fault tolerant block writes
146 that will need to occur.
148 @return EFI_SUCCESS The function completed successfully
149 @retval EFI_ABORTED The function could not complete successfully.
150 @retval EFI_ACCESS_DENIED All allocated writes have not been completed.
156 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
157 IN EFI_GUID
*CallerId
,
158 IN UINTN PrivateDataSize
,
159 IN UINTN NumberOfWrites
163 Starts a target block update. This function will record data about write
164 in fault tolerant storage and will complete the write in a recoverable
165 manner, ensuring at all times that either the original contents or
166 the modified contents are available.
169 @param This Calling context
170 @param Lba The logical block address of the target block.
171 @param Offset The offset within the target block to place the data.
172 @param Length The number of bytes to write to the target block.
173 @param PrivateData A pointer to private data that the caller requires to
174 complete any pending writes in the event of a fault.
175 @param FvBlockHandle The handle of FVB protocol that provides services for
176 reading, writing, and erasing the target block.
177 @param Buffer The data to write.
179 @retval EFI_SUCCESS The function completed successfully
180 @retval EFI_ABORTED The function could not complete successfully.
181 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block.
182 Offset + *NumBytes > SpareAreaLength.
183 @retval EFI_ACCESS_DENIED No writes have been allocated.
184 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource.
185 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle.
191 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
195 IN VOID
*PrivateData
,
196 IN EFI_HANDLE FvBlockHandle
,
201 Restarts a previously interrupted write. The caller must provide the
202 block protocol needed to complete the interrupted write.
204 @param This Calling context.
205 @param FvBlockHandle The handle of FVB protocol that provides services for
206 reading, writing, and erasing the target block.
208 @retval EFI_SUCCESS The function completed successfully
209 @retval EFI_ACCESS_DENIED No pending writes exist
210 @retval EFI_NOT_FOUND FVB protocol not found by the handle
211 @retval EFI_ABORTED The function could not complete successfully
217 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
218 IN EFI_HANDLE FvBlockHandle
222 Aborts all previous allocated writes.
224 @param This Calling context
226 @retval EFI_SUCCESS The function completed successfully
227 @retval EFI_ABORTED The function could not complete successfully.
228 @retval EFI_NOT_FOUND No allocated writes exist.
234 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
238 Starts a target block update. This records information about the write
239 in fault tolerant storage and will complete the write in a recoverable
240 manner, ensuring at all times that either the original contents or
241 the modified contents are available.
243 @param This Indicates a pointer to the calling context.
244 @param CallerId The GUID identifying the last write.
245 @param Lba The logical block address of the last write.
246 @param Offset The offset within the block of the last write.
247 @param Length The length of the last write.
248 @param PrivateDataSize bytes from the private data
249 stored for this write.
250 @param PrivateData A pointer to a buffer. The function will copy
251 @param Complete A Boolean value with TRUE indicating
252 that the write was completed.
254 @retval EFI_SUCCESS The function completed successfully
255 @retval EFI_ABORTED The function could not complete successfully
256 @retval EFI_NOT_FOUND No allocated writes exist
257 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough
263 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
264 OUT EFI_GUID
*CallerId
,
268 IN OUT UINTN
*PrivateDataSize
,
269 OUT VOID
*PrivateData
,
270 OUT BOOLEAN
*Complete
276 @param FtwDevice The private data of FTW driver
278 @retval EFI_SUCCESS The erase request was successfully completed.
279 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
280 @retval EFI_DEVICE_ERROR The block device is not functioning
281 correctly and could not be written.
282 The firmware device may have been
284 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
285 in the variable argument list do
286 not exist in the firmware volume.
292 IN EFI_FTW_DEVICE
*FtwDevice
296 Retrieve the proper FVB protocol interface by HANDLE.
299 @param FvBlockHandle The handle of FVB protocol that provides services for
300 reading, writing, and erasing the target block.
301 @param FvBlock The interface of FVB protocol
303 @retval EFI_SUCCESS The function completed successfully
304 @retval EFI_ABORTED The function could not complete successfully
309 IN EFI_HANDLE FvBlockHandle
,
310 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
315 Is it in working block?
317 @param FtwDevice The private data of FTW driver
318 @param FvBlock Fvb protocol instance
319 @param Lba The block specified
321 @return A BOOLEAN value indicating in working block or not.
326 EFI_FTW_DEVICE
*FtwDevice
,
327 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
335 @param FtwDevice The private data of FTW driver
336 @param FvBlock Fvb protocol instance
338 @return A BOOLEAN value indicating in boot block or not.
343 EFI_FTW_DEVICE
*FtwDevice
,
344 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
348 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
349 Spare block is accessed by FTW backup FVB protocol interface.
350 Target block is accessed by FvBlock protocol interface.
353 @param FtwDevice The private data of FTW driver
354 @param FvBlock FVB Protocol interface to access target block
355 @param Lba Lba of the target block
356 @param BlockSize The size of the block
357 @param NumberOfBlocks The number of consecutive blocks starting with Lba
359 @retval EFI_SUCCESS Spare block content is copied to target block
360 @retval EFI_INVALID_PARAMETER Input parameter error
361 @retval EFI_OUT_OF_RESOURCES Allocate memory error
362 @retval EFI_ABORTED The function could not complete successfully
366 FlushSpareBlockToTargetBlock (
367 EFI_FTW_DEVICE
*FtwDevice
,
368 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
375 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
376 Spare block is accessed by FTW backup FVB protocol interface. LBA is
377 FtwDevice->FtwSpareLba.
378 Working block is accessed by FTW working FVB protocol interface. LBA is
379 FtwDevice->FtwWorkBlockLba.
381 Since the working block header is important when FTW initializes, the
382 state of the operation should be handled carefully. The Crc value is
383 calculated without STATE element.
385 @param FtwDevice The private data of FTW driver
387 @retval EFI_SUCCESS Spare block content is copied to target block
388 @retval EFI_OUT_OF_RESOURCES Allocate memory error
389 @retval EFI_ABORTED The function could not complete successfully
393 FlushSpareBlockToWorkingBlock (
394 EFI_FTW_DEVICE
*FtwDevice
398 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
399 Spare block is accessed by FTW working FVB protocol interface.
400 Target block is accessed by FvBlock protocol interface.
402 FTW will do extra work on boot block update.
403 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL,
404 which is produced by a chipset driver.
405 FTW updating boot block steps may be:
406 1. GetRangeLocation(), if the Range is inside the boot block, FTW know
407 that boot block will be update. It shall add a FLAG in the working block.
408 2. When spare block is ready,
409 3. SetSwapState(SWAPPED)
410 4. erasing boot block,
411 5. programming boot block until the boot block is ok.
412 6. SetSwapState(UNSWAPPED)
413 FTW shall not allow to update boot block when battery state is error.
415 @param FtwDevice The private data of FTW driver
417 @retval EFI_SUCCESS Spare block content is copied to boot block
418 @retval EFI_INVALID_PARAMETER Input parameter error
419 @retval EFI_OUT_OF_RESOURCES Allocate memory error
420 @retval EFI_ABORTED The function could not complete successfully
424 FlushSpareBlockToBootBlock (
425 EFI_FTW_DEVICE
*FtwDevice
429 Update a bit of state on a block device. The location of the bit is
430 calculated by the (Lba, Offset, bit). Here bit is determined by the
431 the name of a certain bit.
434 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
435 @param BlockSize The size of the block
436 @param Lba Lba of a block
437 @param Offset Offset on the Lba
438 @param NewBit New value that will override the old value if it can be change
440 @retval EFI_SUCCESS A state bit has been updated successfully
441 @retval Others Access block device error.
443 Assume all bits of State are inside the same BYTE.
444 @retval EFI_ABORTED Read block fail
449 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
457 Get the last Write Header pointer.
458 The last write header is the header whose 'complete' state hasn't been set.
459 After all, this header may be a EMPTY header entry for next Allocate.
462 @param FtwWorkSpaceHeader Pointer of the working block header
463 @param FtwWorkSpaceSize Size of the work space
464 @param FtwWriteHeader Pointer to retrieve the last write header
466 @retval EFI_SUCCESS Get the last write record successfully
467 @retval EFI_ABORTED The FTW work space is damaged
471 FtwGetLastWriteHeader (
472 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
,
473 IN UINTN FtwWorkSpaceSize
,
474 OUT EFI_FAULT_TOLERANT_WRITE_HEADER
**FtwWriteHeader
478 Get the last Write Record pointer. The last write Record is the Record
479 whose DestinationCompleted state hasn't been set. After all, this Record
480 may be a EMPTY record entry for next write.
483 @param FtwWriteHeader Pointer to the write record header
484 @param FtwWriteRecord Pointer to retrieve the last write record
486 @retval EFI_SUCCESS Get the last write record successfully
487 @retval EFI_ABORTED The FTW work space is damaged
491 FtwGetLastWriteRecord (
492 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwWriteHeader
,
493 OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwWriteRecord
497 To check if FtwRecord is the first record of FtwHeader.
499 @param FtwHeader Pointer to the write record header
500 @param FtwRecord Pointer to the write record
502 @retval TRUE FtwRecord is the first Record of the FtwHeader
503 @retval FALSE FtwRecord is not the first Record of the FtwHeader
507 IsFirstRecordOfWrites (
508 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
509 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
513 To check if FtwRecord is the last record of FtwHeader. Because the
514 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be
515 determined if it is the last record of FtwHeader.
517 @param FtwHeader Pointer to the write record header
518 @param FtwRecord Pointer to the write record
520 @retval TRUE FtwRecord is the last Record of the FtwHeader
521 @retval FALSE FtwRecord is not the last Record of the FtwHeader
525 IsLastRecordOfWrites (
526 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
527 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
531 To check if FtwRecord is the first record of FtwHeader.
533 @param FtwHeader Pointer to the write record header
534 @param FtwRecord Pointer to retrieve the previous write record
536 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return.
537 @retval EFI_SUCCESS The previous write record is found.
541 GetPreviousRecordOfWrites (
542 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
543 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwRecord
548 Check whether a flash buffer is erased.
550 @param Buffer Buffer to check
551 @param BufferSize Size of the buffer
553 @return A BOOLEAN value indicating erased or not.
557 IsErasedFlashBuffer (
562 Initialize a work space when there is no work space.
564 @param WorkingHeader Pointer of working block header
566 @retval EFI_SUCCESS The function completed successfully
567 @retval EFI_ABORTED The function could not complete successfully.
571 InitWorkSpaceHeader (
572 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
575 Read from working block to refresh the work space in memory.
577 @param FtwDevice Point to private data of FTW driver
579 @retval EFI_SUCCESS The function completed successfully
580 @retval EFI_ABORTED The function could not complete successfully.
585 IN EFI_FTW_DEVICE
*FtwDevice
588 Check to see if it is a valid work space.
591 @param WorkingHeader Pointer of working block header
593 @retval EFI_SUCCESS The function completed successfully
594 @retval EFI_ABORTED The function could not complete successfully.
599 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
602 Reclaim the work space on the working block.
604 @param FtwDevice Point to private data of FTW driver
605 @param PreserveRecord Whether to preserve the working record is needed
607 @retval EFI_SUCCESS The function completed successfully
608 @retval EFI_OUT_OF_RESOURCES Allocate memory error
609 @retval EFI_ABORTED The function could not complete successfully
613 FtwReclaimWorkSpace (
614 IN EFI_FTW_DEVICE
*FtwDevice
,
615 IN BOOLEAN PreserveRecord
620 Get firmware volume block by address.
623 @param Address Address specified the block
624 @param FvBlock The block caller wanted
626 @retval EFI_SUCCESS The protocol instance if found.
627 @retval EFI_NOT_FOUND Block not found
632 IN EFI_PHYSICAL_ADDRESS Address
,
633 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
637 Retrieve the proper Swap Address Range protocol interface.
639 @param[out] SarProtocol The interface of SAR protocol
641 @retval EFI_SUCCESS The SAR protocol instance was found and returned in SarProtocol.
642 @retval EFI_NOT_FOUND The SAR protocol instance was not found.
643 @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
648 OUT VOID
**SarProtocol
652 Function returns an array of handles that support the FVB protocol
653 in a buffer allocated from pool.
655 @param[out] NumberHandles The number of handles returned in Buffer.
656 @param[out] Buffer A pointer to the buffer to return the requested
657 array of handles that support FVB protocol.
659 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of
660 handles in Buffer was returned in NumberHandles.
661 @retval EFI_NOT_FOUND No FVB handle was found.
662 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results.
663 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
667 GetFvbCountAndBuffer (
668 OUT UINTN
*NumberHandles
,
669 OUT EFI_HANDLE
**Buffer
674 Allocate private data for FTW driver and initialize it.
676 @param[out] FtwData Pointer to the FTW device structure
678 @retval EFI_SUCCESS Initialize the FTW device successfully.
679 @retval EFI_OUT_OF_RESOURCES Allocate memory error
680 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
685 OUT EFI_FTW_DEVICE
**FtwData
690 Initialization for Fault Tolerant Write is done in this handler.
692 @param[in, out] FtwDevice Pointer to the FTW device structure
694 @retval EFI_SUCCESS Initialize the FTW protocol successfully.
695 @retval EFI_NOT_FOUND No proper FVB protocol was found.
700 IN OUT EFI_FTW_DEVICE
*FtwDevice
704 Initialize a local work space header.
706 Since Signature and WriteQueueSize have been known, Crc can be calculated out,
707 then the work space header will be fixed.
710 InitializeLocalWorkSpaceHeader (
715 Read work space data from work block or spare block.
717 @param FvBlock FVB Protocol interface to access the block.
718 @param BlockSize The size of the block.
719 @param Lba Lba of the block.
720 @param Offset The offset within the block.
721 @param Length The number of bytes to read from the block.
722 @param Buffer The data is read.
724 @retval EFI_SUCCESS The function completed successfully.
725 @retval EFI_ABORTED The function could not complete successfully.
730 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
739 Write data to work block.
741 @param FvBlock FVB Protocol interface to access the block.
742 @param BlockSize The size of the block.
743 @param Lba Lba of the block.
744 @param Offset The offset within the block to place the data.
745 @param Length The number of bytes to write to the block.
746 @param Buffer The data to write.
748 @retval EFI_SUCCESS The function completed successfully.
749 @retval EFI_ABORTED The function could not complete successfully.
754 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
763 Internal implementation of CRC32. Depending on the execution context
764 (traditional SMM or DXE vs standalone MM), this function is implemented
765 via a call to the CalculateCrc32 () boot service, or via a library
768 If Buffer is NULL, then ASSERT().
769 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
771 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is
773 @param[in] Length The number of bytes in the buffer Data.
775 @retval Crc32 The 32-bit CRC was computed for the data buffer.