3 The internal header file includes the common header files, defines
4 internal structure and functions used by FtwLite module.
6 Copyright (c) 2006 - 2013, 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
54 #define FTW_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'D')
57 // EFI Fault tolerant protocol private data structure
62 EFI_FAULT_TOLERANT_WRITE_PROTOCOL FtwInstance
;
63 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
64 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
65 UINTN WorkSpaceLength
; // Size of working space range in flash.
66 UINTN SpareAreaLength
; // Size of spare range in flash.
67 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
68 UINTN BlockSize
; // Block size in bytes of the blocks in flash
69 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
70 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwLastWriteHeader
;// Pointer to last record header in memory buffer
71 EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwLastWriteRecord
;// Pointer to last record in memory buffer
72 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
73 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
74 EFI_LBA FtwSpareLba
; // Start LBA of spare block
75 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
76 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
77 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
78 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
79 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
81 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
82 // Allocated with EFI_FTW_DEVICE.
86 #define FTW_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_DEVICE, FtwInstance, FTW_DEVICE_SIGNATURE)
92 This function is the entry point of the Fault Tolerant Write driver.
94 @param ImageHandle A handle for the image that is initializing this driver
95 @param SystemTable A pointer to the EFI system table
97 @return EFI_SUCCESS FTW has finished the initialization
98 @retval EFI_NOT_FOUND Locate FVB protocol error
99 @retval EFI_OUT_OF_RESOURCES Allocate memory error
100 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
101 @retval EFI_ABORTED FTW initialization error
106 InitializeFaultTolerantWrite (
107 IN EFI_HANDLE ImageHandle
,
108 IN EFI_SYSTEM_TABLE
*SystemTable
112 // Fault Tolerant Write Protocol API
116 Query the largest block that may be updated in a fault tolerant manner.
119 @param This Indicates a pointer to the calling context.
120 @param BlockSize A pointer to a caller allocated UINTN that is updated to
121 indicate the size of the largest block that can be updated.
123 @return EFI_SUCCESS The function completed successfully
129 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
134 Allocates space for the protocol to maintain information about writes.
135 Since writes must be completed in a fault tolerant manner and multiple
136 updates will require more resources to be successful, this function
137 enables the protocol to ensure that enough space exists to track
138 information about the upcoming writes.
140 All writes must be completed or aborted before another fault tolerant write can occur.
142 @param This Indicates a pointer to the calling context.
143 @param CallerId The GUID identifying the write.
144 @param PrivateDataSize The size of the caller's private data
145 that must be recorded for each write.
146 @param NumberOfWrites The number of fault tolerant block writes
147 that will need to occur.
149 @return EFI_SUCCESS The function completed successfully
150 @retval EFI_ABORTED The function could not complete successfully.
151 @retval EFI_ACCESS_DENIED All allocated writes have not been completed.
157 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
158 IN EFI_GUID
*CallerId
,
159 IN UINTN PrivateDataSize
,
160 IN UINTN NumberOfWrites
164 Starts a target block update. This function will record data about write
165 in fault tolerant storage and will complete the write in a recoverable
166 manner, ensuring at all times that either the original contents or
167 the modified contents are available.
170 @param This Calling context
171 @param Lba The logical block address of the target block.
172 @param Offset The offset within the target block to place the data.
173 @param Length The number of bytes to write to the target block.
174 @param PrivateData A pointer to private data that the caller requires to
175 complete any pending writes in the event of a fault.
176 @param FvBlockHandle The handle of FVB protocol that provides services for
177 reading, writing, and erasing the target block.
178 @param Buffer The data to write.
180 @retval EFI_SUCCESS The function completed successfully
181 @retval EFI_ABORTED The function could not complete successfully.
182 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block.
183 Offset + *NumBytes > SpareAreaLength.
184 @retval EFI_ACCESS_DENIED No writes have been allocated.
185 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource.
186 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle.
192 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
196 IN VOID
*PrivateData
,
197 IN EFI_HANDLE FvBlockHandle
,
202 Restarts a previously interrupted write. The caller must provide the
203 block protocol needed to complete the interrupted write.
205 @param This Calling context.
206 @param FvBlockHandle The handle of FVB protocol that provides services for
207 reading, writing, and erasing the target block.
209 @retval EFI_SUCCESS The function completed successfully
210 @retval EFI_ACCESS_DENIED No pending writes exist
211 @retval EFI_NOT_FOUND FVB protocol not found by the handle
212 @retval EFI_ABORTED The function could not complete successfully
218 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
219 IN EFI_HANDLE FvBlockHandle
223 Aborts all previous allocated writes.
225 @param This Calling context
227 @retval EFI_SUCCESS The function completed successfully
228 @retval EFI_ABORTED The function could not complete successfully.
229 @retval EFI_NOT_FOUND No allocated writes exist.
235 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
239 Starts a target block update. This records information about the write
240 in fault tolerant storage and will complete the write in a recoverable
241 manner, ensuring at all times that either the original contents or
242 the modified contents are available.
244 @param This Indicates a pointer to the calling context.
245 @param CallerId The GUID identifying the last write.
246 @param Lba The logical block address of the last write.
247 @param Offset The offset within the block of the last write.
248 @param Length The length of the last write.
249 @param PrivateDataSize bytes from the private data
250 stored for this write.
251 @param PrivateData A pointer to a buffer. The function will copy
252 @param Complete A Boolean value with TRUE indicating
253 that the write was completed.
255 @retval EFI_SUCCESS The function completed successfully
256 @retval EFI_ABORTED The function could not complete successfully
257 @retval EFI_NOT_FOUND No allocated writes exist
258 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough
264 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
265 OUT EFI_GUID
*CallerId
,
269 IN OUT UINTN
*PrivateDataSize
,
270 OUT VOID
*PrivateData
,
271 OUT BOOLEAN
*Complete
277 @param FtwDevice The private data of FTW driver
279 @retval EFI_SUCCESS The erase request was successfully completed.
280 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
281 @retval EFI_DEVICE_ERROR The block device is not functioning
282 correctly and could not be written.
283 The firmware device may have been
285 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
286 in the variable argument list do
287 not exist in the firmware volume.
293 IN EFI_FTW_DEVICE
*FtwDevice
297 Retrive the proper FVB protocol interface by HANDLE.
300 @param FvBlockHandle The handle of FVB protocol that provides services for
301 reading, writing, and erasing the target block.
302 @param FvBlock The interface of FVB protocol
304 @retval EFI_SUCCESS The function completed successfully
305 @retval EFI_ABORTED The function could not complete successfully
310 IN EFI_HANDLE FvBlockHandle
,
311 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
316 Is it in working block?
318 @param FtwDevice The private data of FTW driver
319 @param FvBlock Fvb protocol instance
320 @param Lba The block specified
322 @return A BOOLEAN value indicating in working block or not.
327 EFI_FTW_DEVICE
*FtwDevice
,
328 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
336 @param FtwDevice The private data of FTW driver
337 @param FvBlock Fvb protocol instance
338 @param Lba The block specified
340 @return A BOOLEAN value indicating in boot block or not.
345 EFI_FTW_DEVICE
*FtwDevice
,
346 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
351 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
352 Spare block is accessed by FTW backup FVB protocol interface. LBA is 1.
353 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
356 @param FtwDevice The private data of FTW driver
357 @param FvBlock FVB Protocol interface to access target block
358 @param Lba Lba of the target block
360 @retval EFI_SUCCESS Spare block content is copied to target block
361 @retval EFI_INVALID_PARAMETER Input parameter error
362 @retval EFI_OUT_OF_RESOURCES Allocate memory error
363 @retval EFI_ABORTED The function could not complete successfully
367 FlushSpareBlockToTargetBlock (
368 EFI_FTW_DEVICE
*FtwDevice
,
369 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
374 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
375 Spare block is accessed by FTW backup FVB protocol interface. LBA is
376 FtwDevice->FtwSpareLba.
377 Working block is accessed by FTW working FVB protocol interface. LBA is
378 FtwDevice->FtwWorkBlockLba.
380 Since the working block header is important when FTW initializes, the
381 state of the operation should be handled carefully. The Crc value is
382 calculated without STATE element.
384 @param FtwDevice The private data of FTW driver
386 @retval EFI_SUCCESS Spare block content is copied to target block
387 @retval EFI_OUT_OF_RESOURCES Allocate memory error
388 @retval EFI_ABORTED The function could not complete successfully
392 FlushSpareBlockToWorkingBlock (
393 EFI_FTW_DEVICE
*FtwDevice
397 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
398 Spare block is accessed by FTW working FVB protocol interface. LBA is 1.
399 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
401 FTW will do extra work on boot block update.
402 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL,
403 which is produced by a chipset driver.
404 FTW updating boot block steps may be:
405 1. GetRangeLocation(), if the Range is inside the boot block, FTW know
406 that boot block will be update. It shall add a FLAG in the working block.
407 2. When spare block is ready,
408 3. SetSwapState(EFI_SWAPPED)
409 4. erasing boot block,
410 5. programming boot block until the boot block is ok.
411 6. SetSwapState(UNSWAPPED)
412 FTW shall not allow to update boot block when battery state is error.
414 @param FtwDevice The private data of FTW driver
416 @retval EFI_SUCCESS Spare block content is copied to boot block
417 @retval EFI_INVALID_PARAMETER Input parameter error
418 @retval EFI_OUT_OF_RESOURCES Allocate memory error
419 @retval EFI_ABORTED The function could not complete successfully
423 FlushSpareBlockToBootBlock (
424 EFI_FTW_DEVICE
*FtwDevice
428 Update a bit of state on a block device. The location of the bit is
429 calculated by the (Lba, Offset, bit). Here bit is determined by the
430 the name of a certain bit.
433 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
434 @param Lba Lba of a block
435 @param Offset Offset on the Lba
436 @param NewBit New value that will override the old value if it can be change
438 @retval EFI_SUCCESS A state bit has been updated successfully
439 @retval Others Access block device error.
441 Assume all bits of State are inside the same BYTE.
442 @retval EFI_ABORTED Read block fail
447 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
454 Get the last Write Header pointer.
455 The last write header is the header whose 'complete' state hasn't been set.
456 After all, this header may be a EMPTY header entry for next Allocate.
459 @param FtwWorkSpaceHeader Pointer of the working block header
460 @param FtwWorkSpaceSize Size of the work space
461 @param FtwWriteHeader Pointer to retrieve the last write header
463 @retval EFI_SUCCESS Get the last write record successfully
464 @retval EFI_ABORTED The FTW work space is damaged
468 FtwGetLastWriteHeader (
469 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
,
470 IN UINTN FtwWorkSpaceSize
,
471 OUT EFI_FAULT_TOLERANT_WRITE_HEADER
**FtwWriteHeader
475 Get the last Write Record pointer. The last write Record is the Record
476 whose DestinationCompleted state hasn't been set. After all, this Record
477 may be a EMPTY record entry for next write.
480 @param FtwWriteHeader Pointer to the write record header
481 @param FtwWriteRecord Pointer to retrieve the last write record
483 @retval EFI_SUCCESS Get the last write record successfully
484 @retval EFI_ABORTED The FTW work space is damaged
488 FtwGetLastWriteRecord (
489 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwWriteHeader
,
490 OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwWriteRecord
494 To check if FtwRecord is the first record of FtwHeader.
496 @param FtwHeader Pointer to the write record header
497 @param FtwRecord Pointer to the write record
499 @retval TRUE FtwRecord is the first Record of the FtwHeader
500 @retval FALSE FtwRecord is not the first Record of the FtwHeader
504 IsFirstRecordOfWrites (
505 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
506 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
510 To check if FtwRecord is the last record of FtwHeader. Because the
511 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be
512 determined if it is the last record of FtwHeader.
514 @param FtwHeader Pointer to the write record header
515 @param FtwRecord Pointer to the write record
517 @retval TRUE FtwRecord is the last Record of the FtwHeader
518 @retval FALSE FtwRecord is not the last Record of the FtwHeader
522 IsLastRecordOfWrites (
523 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
524 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
528 To check if FtwRecord is the first record of FtwHeader.
530 @param FtwHeader Pointer to the write record header
531 @param FtwRecord Pointer to retrieve the previous write record
533 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return.
534 @retval EFI_SUCCESS The previous write record is found.
538 GetPreviousRecordOfWrites (
539 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
540 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwRecord
545 Check whether a flash buffer is erased.
547 @param Buffer Buffer to check
548 @param BufferSize Size of the buffer
550 @return A BOOLEAN value indicating erased or not.
554 IsErasedFlashBuffer (
559 Initialize a work space when there is no work space.
561 @param WorkingHeader Pointer of working block header
563 @retval EFI_SUCCESS The function completed successfully
564 @retval EFI_ABORTED The function could not complete successfully.
568 InitWorkSpaceHeader (
569 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
572 Read from working block to refresh the work space in memory.
574 @param FtwDevice Point to private data of FTW driver
576 @retval EFI_SUCCESS The function completed successfully
577 @retval EFI_ABORTED The function could not complete successfully.
582 IN EFI_FTW_DEVICE
*FtwDevice
585 Check to see if it is a valid work space.
588 @param WorkingHeader Pointer of working block header
590 @retval EFI_SUCCESS The function completed successfully
591 @retval EFI_ABORTED The function could not complete successfully.
596 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
599 Reclaim the work space on the working block.
601 @param FtwDevice Point to private data of FTW driver
602 @param PreserveRecord Whether to preserve the working record is needed
604 @retval EFI_SUCCESS The function completed successfully
605 @retval EFI_OUT_OF_RESOURCES Allocate memory error
606 @retval EFI_ABORTED The function could not complete successfully
610 FtwReclaimWorkSpace (
611 IN EFI_FTW_DEVICE
*FtwDevice
,
612 IN BOOLEAN PreserveRecord
617 Get firmware block by address.
620 @param Address Address specified the block
621 @param FvBlock The block caller wanted
623 @retval EFI_SUCCESS The protocol instance if found.
624 @retval EFI_NOT_FOUND Block not found
629 IN EFI_PHYSICAL_ADDRESS Address
,
630 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
634 Retrive the proper Swap Address Range protocol interface.
636 @param[out] SarProtocol The interface of SAR protocol
638 @retval EFI_SUCCESS The SAR protocol instance was found and returned in SarProtocol.
639 @retval EFI_NOT_FOUND The SAR protocol instance was not found.
640 @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
645 OUT VOID
**SarProtocol
649 Function returns an array of handles that support the FVB protocol
650 in a buffer allocated from pool.
652 @param[out] NumberHandles The number of handles returned in Buffer.
653 @param[out] Buffer A pointer to the buffer to return the requested
654 array of handles that support FVB protocol.
656 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of
657 handles in Buffer was returned in NumberHandles.
658 @retval EFI_NOT_FOUND No FVB handle was found.
659 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results.
660 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
664 GetFvbCountAndBuffer (
665 OUT UINTN
*NumberHandles
,
666 OUT EFI_HANDLE
**Buffer
671 Allocate private data for FTW driver and initialize it.
673 @param[out] FtwData Pointer to the FTW device structure
675 @retval EFI_SUCCESS Initialize the FTW device successfully.
676 @retval EFI_OUT_OF_RESOURCES Allocate memory error
677 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
682 OUT EFI_FTW_DEVICE
**FtwData
687 Initialization for Fault Tolerant Write is done in this handler.
689 @param[in, out] FtwDevice Pointer to the FTW device structure
691 @retval EFI_SUCCESS Initialize the FTW protocol successfully.
692 @retval EFI_NOT_FOUND No proper FVB protocol was found.
697 IN OUT EFI_FTW_DEVICE
*FtwDevice
701 Initialize a local work space header.
703 Since Signature and WriteQueueSize have been known, Crc can be calculated out,
704 then the work space header will be fixed.
707 InitializeLocalWorkSpaceHeader (