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 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 #ifndef _EFI_FAULT_TOLERANT_WRITE_H_
18 #define _EFI_FAULT_TOLERANT_WRITE_H_
22 #include <Guid/SystemNvDataGuid.h>
23 #include <Guid/ZeroGuid.h>
24 #include <Protocol/FaultTolerantWrite.h>
25 #include <Protocol/FirmwareVolumeBlock.h>
26 #include <Protocol/SwapAddressRange.h>
28 #include <Library/PcdLib.h>
29 #include <Library/DebugLib.h>
30 #include <Library/UefiLib.h>
31 #include <Library/UefiDriverEntryPoint.h>
32 #include <Library/BaseMemoryLib.h>
33 #include <Library/MemoryAllocationLib.h>
34 #include <Library/UefiBootServicesTableLib.h>
35 #include <Library/ReportStatusCodeLib.h>
38 // Flash erase polarity is 1
40 #define FTW_ERASE_POLARITY 1
42 #define FTW_ERASED_BYTE ((UINT8) (255))
43 #define FTW_POLARITY_REVERT ((UINT8) (255))
45 #define HEADER_ALLOCATED 0x1
46 #define WRITES_ALLOCATED 0x2
47 #define WRITES_COMPLETED 0x4
49 #define BOOT_BLOCK_UPDATE 0x1
50 #define SPARE_COMPLETED 0x2
51 #define DEST_COMPLETED 0x4
53 #define FTW_BLOCKS(Length, BlockSize) ((UINTN) ((Length) / (BlockSize) + (((Length) & ((BlockSize) - 1)) ? 1 : 0)))
55 #define FTW_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'D')
58 // EFI Fault tolerant protocol private data structure
63 EFI_FAULT_TOLERANT_WRITE_PROTOCOL FtwInstance
;
64 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
65 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
66 UINTN WorkSpaceLength
; // Size of working space range in flash.
67 UINTN NumberOfWorkSpaceBlock
; // Number of the blocks in work block for work space.
68 UINTN WorkBlockSize
; // Block size in bytes of the work blocks in flash
69 UINTN SpareAreaLength
; // Size of spare range in flash.
70 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
71 UINTN SpareBlockSize
; // Block size in bytes of the spare blocks in flash
72 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
73 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwLastWriteHeader
;// Pointer to last record header in memory buffer
74 EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwLastWriteRecord
;// Pointer to last record in memory buffer
75 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
76 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
77 EFI_LBA FtwSpareLba
; // Start LBA of spare block
78 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
79 UINTN NumberOfWorkBlock
; // Number of the blocks in work block.
80 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
81 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
82 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
83 EFI_LBA FtwWorkSpaceLbaInSpare
; // Start LBA of working space in spare block.
84 UINTN FtwWorkSpaceBaseInSpare
;// Offset into the FtwWorkSpaceLbaInSpare block.
85 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
87 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
88 // Allocated with EFI_FTW_DEVICE.
92 #define FTW_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_DEVICE, FtwInstance, FTW_DEVICE_SIGNATURE)
98 This function is the entry point of the Fault Tolerant Write driver.
100 @param ImageHandle A handle for the image that is initializing this driver
101 @param SystemTable A pointer to the EFI system table
103 @return EFI_SUCCESS FTW has finished the initialization
104 @retval EFI_NOT_FOUND Locate FVB protocol error
105 @retval EFI_OUT_OF_RESOURCES Allocate memory error
106 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
107 @retval EFI_ABORTED FTW initialization error
112 InitializeFaultTolerantWrite (
113 IN EFI_HANDLE ImageHandle
,
114 IN EFI_SYSTEM_TABLE
*SystemTable
118 // Fault Tolerant Write Protocol API
122 Query the largest block that may be updated in a fault tolerant manner.
125 @param This Indicates a pointer to the calling context.
126 @param BlockSize A pointer to a caller allocated UINTN that is updated to
127 indicate the size of the largest block that can be updated.
129 @return EFI_SUCCESS The function completed successfully
135 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
140 Allocates space for the protocol to maintain information about writes.
141 Since writes must be completed in a fault tolerant manner and multiple
142 updates will require more resources to be successful, this function
143 enables the protocol to ensure that enough space exists to track
144 information about the upcoming writes.
146 All writes must be completed or aborted before another fault tolerant write can occur.
148 @param This Indicates a pointer to the calling context.
149 @param CallerId The GUID identifying the write.
150 @param PrivateDataSize The size of the caller's private data
151 that must be recorded for each write.
152 @param NumberOfWrites The number of fault tolerant block writes
153 that will need to occur.
155 @return EFI_SUCCESS The function completed successfully
156 @retval EFI_ABORTED The function could not complete successfully.
157 @retval EFI_ACCESS_DENIED All allocated writes have not been completed.
163 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
164 IN EFI_GUID
*CallerId
,
165 IN UINTN PrivateDataSize
,
166 IN UINTN NumberOfWrites
170 Starts a target block update. This function will record data about write
171 in fault tolerant storage and will complete the write in a recoverable
172 manner, ensuring at all times that either the original contents or
173 the modified contents are available.
176 @param This Calling context
177 @param Lba The logical block address of the target block.
178 @param Offset The offset within the target block to place the data.
179 @param Length The number of bytes to write to the target block.
180 @param PrivateData A pointer to private data that the caller requires to
181 complete any pending writes in the event of a fault.
182 @param FvBlockHandle The handle of FVB protocol that provides services for
183 reading, writing, and erasing the target block.
184 @param Buffer The data to write.
186 @retval EFI_SUCCESS The function completed successfully
187 @retval EFI_ABORTED The function could not complete successfully.
188 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block.
189 Offset + *NumBytes > SpareAreaLength.
190 @retval EFI_ACCESS_DENIED No writes have been allocated.
191 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource.
192 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle.
198 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
202 IN VOID
*PrivateData
,
203 IN EFI_HANDLE FvBlockHandle
,
208 Restarts a previously interrupted write. The caller must provide the
209 block protocol needed to complete the interrupted write.
211 @param This Calling context.
212 @param FvBlockHandle The handle of FVB protocol that provides services for
213 reading, writing, and erasing the target block.
215 @retval EFI_SUCCESS The function completed successfully
216 @retval EFI_ACCESS_DENIED No pending writes exist
217 @retval EFI_NOT_FOUND FVB protocol not found by the handle
218 @retval EFI_ABORTED The function could not complete successfully
224 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
225 IN EFI_HANDLE FvBlockHandle
229 Aborts all previous allocated writes.
231 @param This Calling context
233 @retval EFI_SUCCESS The function completed successfully
234 @retval EFI_ABORTED The function could not complete successfully.
235 @retval EFI_NOT_FOUND No allocated writes exist.
241 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
245 Starts a target block update. This records information about the write
246 in fault tolerant storage and will complete the write in a recoverable
247 manner, ensuring at all times that either the original contents or
248 the modified contents are available.
250 @param This Indicates a pointer to the calling context.
251 @param CallerId The GUID identifying the last write.
252 @param Lba The logical block address of the last write.
253 @param Offset The offset within the block of the last write.
254 @param Length The length of the last write.
255 @param PrivateDataSize bytes from the private data
256 stored for this write.
257 @param PrivateData A pointer to a buffer. The function will copy
258 @param Complete A Boolean value with TRUE indicating
259 that the write was completed.
261 @retval EFI_SUCCESS The function completed successfully
262 @retval EFI_ABORTED The function could not complete successfully
263 @retval EFI_NOT_FOUND No allocated writes exist
264 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough
270 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
271 OUT EFI_GUID
*CallerId
,
275 IN OUT UINTN
*PrivateDataSize
,
276 OUT VOID
*PrivateData
,
277 OUT BOOLEAN
*Complete
283 @param FtwDevice The private data of FTW driver
285 @retval EFI_SUCCESS The erase request was successfully completed.
286 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
287 @retval EFI_DEVICE_ERROR The block device is not functioning
288 correctly and could not be written.
289 The firmware device may have been
291 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
292 in the variable argument list do
293 not exist in the firmware volume.
299 IN EFI_FTW_DEVICE
*FtwDevice
303 Retrieve the proper FVB protocol interface by HANDLE.
306 @param FvBlockHandle The handle of FVB protocol that provides services for
307 reading, writing, and erasing the target block.
308 @param FvBlock The interface of FVB protocol
310 @retval EFI_SUCCESS The function completed successfully
311 @retval EFI_ABORTED The function could not complete successfully
316 IN EFI_HANDLE FvBlockHandle
,
317 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
322 Is it in working block?
324 @param FtwDevice The private data of FTW driver
325 @param FvBlock Fvb protocol instance
326 @param Lba The block specified
328 @return A BOOLEAN value indicating in working block or not.
333 EFI_FTW_DEVICE
*FtwDevice
,
334 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
342 @param FtwDevice The private data of FTW driver
343 @param FvBlock Fvb protocol instance
345 @return A BOOLEAN value indicating in boot block or not.
350 EFI_FTW_DEVICE
*FtwDevice
,
351 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
355 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
356 Spare block is accessed by FTW backup FVB protocol interface.
357 Target block is accessed by FvBlock protocol interface.
360 @param FtwDevice The private data of FTW driver
361 @param FvBlock FVB Protocol interface to access target block
362 @param Lba Lba of the target block
363 @param BlockSize The size of the block
364 @param NumberOfBlocks The number of consecutive blocks starting with Lba
366 @retval EFI_SUCCESS Spare block content is copied to target block
367 @retval EFI_INVALID_PARAMETER Input parameter error
368 @retval EFI_OUT_OF_RESOURCES Allocate memory error
369 @retval EFI_ABORTED The function could not complete successfully
373 FlushSpareBlockToTargetBlock (
374 EFI_FTW_DEVICE
*FtwDevice
,
375 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
382 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
383 Spare block is accessed by FTW backup FVB protocol interface. LBA is
384 FtwDevice->FtwSpareLba.
385 Working block is accessed by FTW working FVB protocol interface. LBA is
386 FtwDevice->FtwWorkBlockLba.
388 Since the working block header is important when FTW initializes, the
389 state of the operation should be handled carefully. The Crc value is
390 calculated without STATE element.
392 @param FtwDevice The private data of FTW driver
394 @retval EFI_SUCCESS Spare block content is copied to target block
395 @retval EFI_OUT_OF_RESOURCES Allocate memory error
396 @retval EFI_ABORTED The function could not complete successfully
400 FlushSpareBlockToWorkingBlock (
401 EFI_FTW_DEVICE
*FtwDevice
405 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
406 Spare block is accessed by FTW working FVB protocol interface.
407 Target block is accessed by FvBlock protocol interface.
409 FTW will do extra work on boot block update.
410 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL,
411 which is produced by a chipset driver.
412 FTW updating boot block steps may be:
413 1. GetRangeLocation(), if the Range is inside the boot block, FTW know
414 that boot block will be update. It shall add a FLAG in the working block.
415 2. When spare block is ready,
416 3. SetSwapState(SWAPPED)
417 4. erasing boot block,
418 5. programming boot block until the boot block is ok.
419 6. SetSwapState(UNSWAPPED)
420 FTW shall not allow to update boot block when battery state is error.
422 @param FtwDevice The private data of FTW driver
424 @retval EFI_SUCCESS Spare block content is copied to boot block
425 @retval EFI_INVALID_PARAMETER Input parameter error
426 @retval EFI_OUT_OF_RESOURCES Allocate memory error
427 @retval EFI_ABORTED The function could not complete successfully
431 FlushSpareBlockToBootBlock (
432 EFI_FTW_DEVICE
*FtwDevice
436 Update a bit of state on a block device. The location of the bit is
437 calculated by the (Lba, Offset, bit). Here bit is determined by the
438 the name of a certain bit.
441 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
442 @param BlockSize The size of the block
443 @param Lba Lba of a block
444 @param Offset Offset on the Lba
445 @param NewBit New value that will override the old value if it can be change
447 @retval EFI_SUCCESS A state bit has been updated successfully
448 @retval Others Access block device error.
450 Assume all bits of State are inside the same BYTE.
451 @retval EFI_ABORTED Read block fail
456 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
464 Get the last Write Header pointer.
465 The last write header is the header whose 'complete' state hasn't been set.
466 After all, this header may be a EMPTY header entry for next Allocate.
469 @param FtwWorkSpaceHeader Pointer of the working block header
470 @param FtwWorkSpaceSize Size of the work space
471 @param FtwWriteHeader Pointer to retrieve the last write header
473 @retval EFI_SUCCESS Get the last write record successfully
474 @retval EFI_ABORTED The FTW work space is damaged
478 FtwGetLastWriteHeader (
479 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
,
480 IN UINTN FtwWorkSpaceSize
,
481 OUT EFI_FAULT_TOLERANT_WRITE_HEADER
**FtwWriteHeader
485 Get the last Write Record pointer. The last write Record is the Record
486 whose DestinationCompleted state hasn't been set. After all, this Record
487 may be a EMPTY record entry for next write.
490 @param FtwWriteHeader Pointer to the write record header
491 @param FtwWriteRecord Pointer to retrieve the last write record
493 @retval EFI_SUCCESS Get the last write record successfully
494 @retval EFI_ABORTED The FTW work space is damaged
498 FtwGetLastWriteRecord (
499 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwWriteHeader
,
500 OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwWriteRecord
504 To check if FtwRecord is the first record of FtwHeader.
506 @param FtwHeader Pointer to the write record header
507 @param FtwRecord Pointer to the write record
509 @retval TRUE FtwRecord is the first Record of the FtwHeader
510 @retval FALSE FtwRecord is not the first Record of the FtwHeader
514 IsFirstRecordOfWrites (
515 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
516 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
520 To check if FtwRecord is the last record of FtwHeader. Because the
521 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be
522 determined if it is the last record of FtwHeader.
524 @param FtwHeader Pointer to the write record header
525 @param FtwRecord Pointer to the write record
527 @retval TRUE FtwRecord is the last Record of the FtwHeader
528 @retval FALSE FtwRecord is not the last Record of the FtwHeader
532 IsLastRecordOfWrites (
533 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
534 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
538 To check if FtwRecord is the first record of FtwHeader.
540 @param FtwHeader Pointer to the write record header
541 @param FtwRecord Pointer to retrieve the previous write record
543 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return.
544 @retval EFI_SUCCESS The previous write record is found.
548 GetPreviousRecordOfWrites (
549 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
550 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwRecord
555 Check whether a flash buffer is erased.
557 @param Buffer Buffer to check
558 @param BufferSize Size of the buffer
560 @return A BOOLEAN value indicating erased or not.
564 IsErasedFlashBuffer (
569 Initialize a work space when there is no work space.
571 @param WorkingHeader Pointer of working block header
573 @retval EFI_SUCCESS The function completed successfully
574 @retval EFI_ABORTED The function could not complete successfully.
578 InitWorkSpaceHeader (
579 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
582 Read from working block to refresh the work space in memory.
584 @param FtwDevice Point to private data of FTW driver
586 @retval EFI_SUCCESS The function completed successfully
587 @retval EFI_ABORTED The function could not complete successfully.
592 IN EFI_FTW_DEVICE
*FtwDevice
595 Check to see if it is a valid work space.
598 @param WorkingHeader Pointer of working block header
600 @retval EFI_SUCCESS The function completed successfully
601 @retval EFI_ABORTED The function could not complete successfully.
606 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
609 Reclaim the work space on the working block.
611 @param FtwDevice Point to private data of FTW driver
612 @param PreserveRecord Whether to preserve the working record is needed
614 @retval EFI_SUCCESS The function completed successfully
615 @retval EFI_OUT_OF_RESOURCES Allocate memory error
616 @retval EFI_ABORTED The function could not complete successfully
620 FtwReclaimWorkSpace (
621 IN EFI_FTW_DEVICE
*FtwDevice
,
622 IN BOOLEAN PreserveRecord
627 Get firmware volume block by address.
630 @param Address Address specified the block
631 @param FvBlock The block caller wanted
633 @retval EFI_SUCCESS The protocol instance if found.
634 @retval EFI_NOT_FOUND Block not found
639 IN EFI_PHYSICAL_ADDRESS Address
,
640 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
644 Retrieve the proper Swap Address Range protocol interface.
646 @param[out] SarProtocol The interface of SAR protocol
648 @retval EFI_SUCCESS The SAR protocol instance was found and returned in SarProtocol.
649 @retval EFI_NOT_FOUND The SAR protocol instance was not found.
650 @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
655 OUT VOID
**SarProtocol
659 Function returns an array of handles that support the FVB protocol
660 in a buffer allocated from pool.
662 @param[out] NumberHandles The number of handles returned in Buffer.
663 @param[out] Buffer A pointer to the buffer to return the requested
664 array of handles that support FVB protocol.
666 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of
667 handles in Buffer was returned in NumberHandles.
668 @retval EFI_NOT_FOUND No FVB handle was found.
669 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results.
670 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
674 GetFvbCountAndBuffer (
675 OUT UINTN
*NumberHandles
,
676 OUT EFI_HANDLE
**Buffer
681 Allocate private data for FTW driver and initialize it.
683 @param[out] FtwData Pointer to the FTW device structure
685 @retval EFI_SUCCESS Initialize the FTW device successfully.
686 @retval EFI_OUT_OF_RESOURCES Allocate memory error
687 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
692 OUT EFI_FTW_DEVICE
**FtwData
697 Initialization for Fault Tolerant Write is done in this handler.
699 @param[in, out] FtwDevice Pointer to the FTW device structure
701 @retval EFI_SUCCESS Initialize the FTW protocol successfully.
702 @retval EFI_NOT_FOUND No proper FVB protocol was found.
707 IN OUT EFI_FTW_DEVICE
*FtwDevice
711 Initialize a local work space header.
713 Since Signature and WriteQueueSize have been known, Crc can be calculated out,
714 then the work space header will be fixed.
717 InitializeLocalWorkSpaceHeader (
722 Read work space data from work block or spare block.
724 @param FvBlock FVB Protocol interface to access the block.
725 @param BlockSize The size of the block.
726 @param Lba Lba of the block.
727 @param Offset The offset within the block.
728 @param Length The number of bytes to read from the block.
729 @param Buffer The data is read.
731 @retval EFI_SUCCESS The function completed successfully.
732 @retval EFI_ABORTED The function could not complete successfully.
737 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
746 Write data to work block.
748 @param FvBlock FVB Protocol interface to access the block.
749 @param BlockSize The size of the block.
750 @param Lba Lba of the block.
751 @param Offset The offset within the block to place the data.
752 @param Length The number of bytes to write to the block.
753 @param Buffer The data to write.
755 @retval EFI_SUCCESS The function completed successfully.
756 @retval EFI_ABORTED The function could not complete successfully.
761 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,