3 The internal header file includes the common header files, defines
4 internal structure and functions used by FtwLite module.
6 Copyright (c) 2006 - 2012, 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>
37 // Flash erase polarity is 1
39 #define FTW_ERASE_POLARITY 1
41 #define FTW_VALID_STATE 0
42 #define FTW_INVALID_STATE 1
44 #define FTW_ERASED_BYTE ((UINT8) (255))
45 #define FTW_POLARITY_REVERT ((UINT8) (255))
48 // EFI Fault tolerant block update write queue entry
51 UINT8 HeaderAllocated
: 1;
52 UINT8 WritesAllocated
: 1;
54 #define HEADER_ALLOCATED 0x1
55 #define WRITES_ALLOCATED 0x2
56 #define WRITES_COMPLETED 0x4
60 UINTN PrivateDataSize
;
61 } EFI_FAULT_TOLERANT_WRITE_HEADER
;
64 // EFI Fault tolerant block update write queue record
67 UINT8 BootBlockUpdate
: 1;
68 UINT8 SpareComplete
: 1;
69 UINT8 DestinationComplete
: 1;
70 #define BOOT_BLOCK_UPDATE 0x1
71 #define SPARE_COMPLETED 0x2
72 #define DEST_COMPLETED 0x4
77 EFI_PHYSICAL_ADDRESS FvBaseAddress
;
79 // UINT8 PrivateData[PrivateDataSize]
81 } EFI_FAULT_TOLERANT_WRITE_RECORD
;
84 #define RECORD_SIZE(PrivateDataSize) (sizeof (EFI_FAULT_TOLERANT_WRITE_RECORD) + PrivateDataSize)
86 #define RECORD_TOTAL_SIZE(NumberOfWrites, PrivateDataSize) \
87 ((NumberOfWrites) * (sizeof (EFI_FAULT_TOLERANT_WRITE_RECORD) + PrivateDataSize))
89 #define WRITE_TOTAL_SIZE(NumberOfWrites, PrivateDataSize) \
91 sizeof (EFI_FAULT_TOLERANT_WRITE_HEADER) + (NumberOfWrites) * \
92 (sizeof (EFI_FAULT_TOLERANT_WRITE_RECORD) + PrivateDataSize) \
95 #define FTW_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'D')
98 // EFI Fault tolerant protocol private data structure
103 EFI_FAULT_TOLERANT_WRITE_PROTOCOL FtwInstance
;
104 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
105 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
106 UINTN WorkSpaceLength
; // Size of working space range in flash.
107 UINTN SpareAreaLength
; // Size of spare range in flash.
108 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
109 UINTN BlockSize
; // Block size in bytes of the blocks in flash
110 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
111 EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwLastWriteHeader
;// Pointer to last record header in memory buffer
112 EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwLastWriteRecord
;// Pointer to last record in memory buffer
113 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
114 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
115 EFI_LBA FtwSpareLba
; // Start LBA of spare block
116 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
117 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
118 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
119 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
120 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
122 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
123 // Allocated with EFI_FTW_DEVICE.
127 #define FTW_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_DEVICE, FtwInstance, FTW_DEVICE_SIGNATURE)
130 // Driver entry point
133 This function is the entry point of the Fault Tolerant Write driver.
135 @param ImageHandle A handle for the image that is initializing this driver
136 @param SystemTable A pointer to the EFI system table
138 @return EFI_SUCCESS FTW has finished the initialization
139 @retval EFI_NOT_FOUND Locate FVB protocol error
140 @retval EFI_OUT_OF_RESOURCES Allocate memory error
141 @retval EFI_VOLUME_CORRUPTED Firmware volume is error
142 @retval EFI_ABORTED FTW initialization error
147 InitializeFaultTolerantWrite (
148 IN EFI_HANDLE ImageHandle
,
149 IN EFI_SYSTEM_TABLE
*SystemTable
153 // Fault Tolerant Write Protocol API
157 Query the largest block that may be updated in a fault tolerant manner.
160 @param This Indicates a pointer to the calling context.
161 @param BlockSize A pointer to a caller allocated UINTN that is updated to
162 indicate the size of the largest block that can be updated.
164 @return EFI_SUCCESS The function completed successfully
170 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
175 Allocates space for the protocol to maintain information about writes.
176 Since writes must be completed in a fault tolerant manner and multiple
177 updates will require more resources to be successful, this function
178 enables the protocol to ensure that enough space exists to track
179 information about the upcoming writes.
181 All writes must be completed or aborted before another fault tolerant write can occur.
183 @param This Indicates a pointer to the calling context.
184 @param CallerId The GUID identifying the write.
185 @param PrivateDataSize The size of the caller's private data
186 that must be recorded for each write.
187 @param NumberOfWrites The number of fault tolerant block writes
188 that will need to occur.
190 @return EFI_SUCCESS The function completed successfully
191 @retval EFI_ABORTED The function could not complete successfully.
192 @retval EFI_ACCESS_DENIED All allocated writes have not been completed.
198 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
199 IN EFI_GUID
*CallerId
,
200 IN UINTN PrivateDataSize
,
201 IN UINTN NumberOfWrites
205 Starts a target block update. This function will record data about write
206 in fault tolerant storage and will complete the write in a recoverable
207 manner, ensuring at all times that either the original contents or
208 the modified contents are available.
211 @param This Calling context
212 @param Lba The logical block address of the target block.
213 @param Offset The offset within the target block to place the data.
214 @param Length The number of bytes to write to the target block.
215 @param PrivateData A pointer to private data that the caller requires to
216 complete any pending writes in the event of a fault.
217 @param FvBlockHandle The handle of FVB protocol that provides services for
218 reading, writing, and erasing the target block.
219 @param Buffer The data to write.
221 @retval EFI_SUCCESS The function completed successfully
222 @retval EFI_ABORTED The function could not complete successfully.
223 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block.
224 Offset + *NumBytes > SpareAreaLength.
225 @retval EFI_ACCESS_DENIED No writes have been allocated.
226 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource.
227 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle.
233 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
237 IN VOID
*PrivateData
,
238 IN EFI_HANDLE FvBlockHandle
,
243 Restarts a previously interrupted write. The caller must provide the
244 block protocol needed to complete the interrupted write.
246 @param This Calling context.
247 @param FvBlockHandle The handle of FVB protocol that provides services for
248 reading, writing, and erasing the target block.
250 @retval EFI_SUCCESS The function completed successfully
251 @retval EFI_ACCESS_DENIED No pending writes exist
252 @retval EFI_NOT_FOUND FVB protocol not found by the handle
253 @retval EFI_ABORTED The function could not complete successfully
259 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
260 IN EFI_HANDLE FvBlockHandle
264 Aborts all previous allocated writes.
266 @param This Calling context
268 @retval EFI_SUCCESS The function completed successfully
269 @retval EFI_ABORTED The function could not complete successfully.
270 @retval EFI_NOT_FOUND No allocated writes exist.
276 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
280 Starts a target block update. This records information about the write
281 in fault tolerant storage and will complete the write in a recoverable
282 manner, ensuring at all times that either the original contents or
283 the modified contents are available.
285 @param This Indicates a pointer to the calling context.
286 @param CallerId The GUID identifying the last write.
287 @param Lba The logical block address of the last write.
288 @param Offset The offset within the block of the last write.
289 @param Length The length of the last write.
290 @param PrivateDataSize bytes from the private data
291 stored for this write.
292 @param PrivateData A pointer to a buffer. The function will copy
293 @param Complete A Boolean value with TRUE indicating
294 that the write was completed.
296 @retval EFI_SUCCESS The function completed successfully
297 @retval EFI_ABORTED The function could not complete successfully
298 @retval EFI_NOT_FOUND No allocated writes exist
299 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough
305 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL
*This
,
306 OUT EFI_GUID
*CallerId
,
310 IN OUT UINTN
*PrivateDataSize
,
311 OUT VOID
*PrivateData
,
312 OUT BOOLEAN
*Complete
318 @param FtwDevice The private data of FTW driver
320 @retval EFI_SUCCESS The erase request was successfully completed.
321 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
322 @retval EFI_DEVICE_ERROR The block device is not functioning
323 correctly and could not be written.
324 The firmware device may have been
326 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
327 in the variable argument list do
328 not exist in the firmware volume.
334 IN EFI_FTW_DEVICE
*FtwDevice
338 Retrive the proper FVB protocol interface by HANDLE.
341 @param FvBlockHandle The handle of FVB protocol that provides services for
342 reading, writing, and erasing the target block.
343 @param FvBlock The interface of FVB protocol
345 @retval EFI_SUCCESS The function completed successfully
346 @retval EFI_ABORTED The function could not complete successfully
351 IN EFI_HANDLE FvBlockHandle
,
352 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
357 Is it in working block?
359 @param FtwDevice The private data of FTW driver
360 @param FvBlock Fvb protocol instance
361 @param Lba The block specified
363 @return A BOOLEAN value indicating in working block or not.
368 EFI_FTW_DEVICE
*FtwDevice
,
369 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
377 @param FtwDevice The private data of FTW driver
378 @param FvBlock Fvb protocol instance
379 @param Lba The block specified
381 @return A BOOLEAN value indicating in boot block or not.
386 EFI_FTW_DEVICE
*FtwDevice
,
387 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
392 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
393 Spare block is accessed by FTW backup FVB protocol interface. LBA is 1.
394 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
397 @param FtwDevice The private data of FTW driver
398 @param FvBlock FVB Protocol interface to access target block
399 @param Lba Lba of the target block
401 @retval EFI_SUCCESS Spare block content is copied to target block
402 @retval EFI_INVALID_PARAMETER Input parameter error
403 @retval EFI_OUT_OF_RESOURCES Allocate memory error
404 @retval EFI_ABORTED The function could not complete successfully
408 FlushSpareBlockToTargetBlock (
409 EFI_FTW_DEVICE
*FtwDevice
,
410 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
415 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
416 Spare block is accessed by FTW backup FVB protocol interface. LBA is
417 FtwDevice->FtwSpareLba.
418 Working block is accessed by FTW working FVB protocol interface. LBA is
419 FtwDevice->FtwWorkBlockLba.
421 Since the working block header is important when FTW initializes, the
422 state of the operation should be handled carefully. The Crc value is
423 calculated without STATE element.
425 @param FtwDevice The private data of FTW driver
427 @retval EFI_SUCCESS Spare block content is copied to target block
428 @retval EFI_OUT_OF_RESOURCES Allocate memory error
429 @retval EFI_ABORTED The function could not complete successfully
433 FlushSpareBlockToWorkingBlock (
434 EFI_FTW_DEVICE
*FtwDevice
438 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
439 Spare block is accessed by FTW working FVB protocol interface. LBA is 1.
440 Target block is accessed by FvbBlock protocol interface. LBA is Lba.
442 FTW will do extra work on boot block update.
443 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL,
444 which is produced by a chipset driver.
445 FTW updating boot block steps may be:
446 1. GetRangeLocation(), if the Range is inside the boot block, FTW know
447 that boot block will be update. It shall add a FLAG in the working block.
448 2. When spare block is ready,
449 3. SetSwapState(EFI_SWAPPED)
450 4. erasing boot block,
451 5. programming boot block until the boot block is ok.
452 6. SetSwapState(UNSWAPPED)
453 FTW shall not allow to update boot block when battery state is error.
455 @param FtwDevice The private data of FTW driver
457 @retval EFI_SUCCESS Spare block content is copied to boot block
458 @retval EFI_INVALID_PARAMETER Input parameter error
459 @retval EFI_OUT_OF_RESOURCES Allocate memory error
460 @retval EFI_ABORTED The function could not complete successfully
464 FlushSpareBlockToBootBlock (
465 EFI_FTW_DEVICE
*FtwDevice
469 Update a bit of state on a block device. The location of the bit is
470 calculated by the (Lba, Offset, bit). Here bit is determined by the
471 the name of a certain bit.
474 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
475 @param Lba Lba of a block
476 @param Offset Offset on the Lba
477 @param NewBit New value that will override the old value if it can be change
479 @retval EFI_SUCCESS A state bit has been updated successfully
480 @retval Others Access block device error.
482 Assume all bits of State are inside the same BYTE.
483 @retval EFI_ABORTED Read block fail
488 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
495 Get the last Write Header pointer.
496 The last write header is the header whose 'complete' state hasn't been set.
497 After all, this header may be a EMPTY header entry for next Allocate.
500 @param FtwWorkSpaceHeader Pointer of the working block header
501 @param FtwWorkSpaceSize Size of the work space
502 @param FtwWriteHeader Pointer to retrieve the last write header
504 @retval EFI_SUCCESS Get the last write record successfully
505 @retval EFI_ABORTED The FTW work space is damaged
509 FtwGetLastWriteHeader (
510 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
,
511 IN UINTN FtwWorkSpaceSize
,
512 OUT EFI_FAULT_TOLERANT_WRITE_HEADER
**FtwWriteHeader
516 Get the last Write Record pointer. The last write Record is the Record
517 whose DestinationCompleted state hasn't been set. After all, this Record
518 may be a EMPTY record entry for next write.
521 @param FtwWriteHeader Pointer to the write record header
522 @param FtwWriteRecord Pointer to retrieve the last write record
524 @retval EFI_SUCCESS Get the last write record successfully
525 @retval EFI_ABORTED The FTW work space is damaged
529 FtwGetLastWriteRecord (
530 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwWriteHeader
,
531 OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwWriteRecord
535 To check if FtwRecord is the first record of FtwHeader.
537 @param FtwHeader Pointer to the write record header
538 @param FtwRecord Pointer to the write record
540 @retval TRUE FtwRecord is the first Record of the FtwHeader
541 @retval FALSE FtwRecord is not the first Record of the FtwHeader
545 IsFirstRecordOfWrites (
546 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
547 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
551 To check if FtwRecord is the last record of FtwHeader. Because the
552 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be
553 determined if it is the last record of FtwHeader.
555 @param FtwHeader Pointer to the write record header
556 @param FtwRecord Pointer to the write record
558 @retval TRUE FtwRecord is the last Record of the FtwHeader
559 @retval FALSE FtwRecord is not the last Record of the FtwHeader
563 IsLastRecordOfWrites (
564 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
565 IN EFI_FAULT_TOLERANT_WRITE_RECORD
*FtwRecord
569 To check if FtwRecord is the first record of FtwHeader.
571 @param FtwHeader Pointer to the write record header
572 @param FtwRecord Pointer to retrieve the previous write record
574 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return.
575 @retval EFI_SUCCESS The previous write record is found.
579 GetPreviousRecordOfWrites (
580 IN EFI_FAULT_TOLERANT_WRITE_HEADER
*FtwHeader
,
581 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD
**FtwRecord
586 Check whether a flash buffer is erased.
588 @param Buffer Buffer to check
589 @param BufferSize Size of the buffer
591 @return A BOOLEAN value indicating erased or not.
595 IsErasedFlashBuffer (
600 Initialize a work space when there is no work space.
602 @param WorkingHeader Pointer of working block header
604 @retval EFI_SUCCESS The function completed successfully
605 @retval EFI_ABORTED The function could not complete successfully.
609 InitWorkSpaceHeader (
610 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
613 Read from working block to refresh the work space in memory.
615 @param FtwDevice Point to private data of FTW driver
617 @retval EFI_SUCCESS The function completed successfully
618 @retval EFI_ABORTED The function could not complete successfully.
623 IN EFI_FTW_DEVICE
*FtwDevice
626 Check to see if it is a valid work space.
629 @param WorkingHeader Pointer of working block header
631 @retval EFI_SUCCESS The function completed successfully
632 @retval EFI_ABORTED The function could not complete successfully.
637 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
640 Reclaim the work space on the working block.
642 @param FtwDevice Point to private data of FTW driver
643 @param PreserveRecord Whether to preserve the working record is needed
645 @retval EFI_SUCCESS The function completed successfully
646 @retval EFI_OUT_OF_RESOURCES Allocate memory error
647 @retval EFI_ABORTED The function could not complete successfully
651 FtwReclaimWorkSpace (
652 IN EFI_FTW_DEVICE
*FtwDevice
,
653 IN BOOLEAN PreserveRecord
658 Get firmware block by address.
661 @param Address Address specified the block
662 @param FvBlock The block caller wanted
664 @retval EFI_SUCCESS The protocol instance if found.
665 @retval EFI_NOT_FOUND Block not found
670 IN EFI_PHYSICAL_ADDRESS Address
,
671 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
675 Retrive the proper Swap Address Range protocol interface.
677 @param[out] SarProtocol The interface of SAR protocol
679 @retval EFI_SUCCESS The SAR protocol instance was found and returned in SarProtocol.
680 @retval EFI_NOT_FOUND The SAR protocol instance was not found.
681 @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
686 OUT VOID
**SarProtocol
690 Function returns an array of handles that support the FVB protocol
691 in a buffer allocated from pool.
693 @param[out] NumberHandles The number of handles returned in Buffer.
694 @param[out] Buffer A pointer to the buffer to return the requested
695 array of handles that support FVB protocol.
697 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of
698 handles in Buffer was returned in NumberHandles.
699 @retval EFI_NOT_FOUND No FVB handle was found.
700 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results.
701 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
705 GetFvbCountAndBuffer (
706 OUT UINTN
*NumberHandles
,
707 OUT EFI_HANDLE
**Buffer
712 Allocate private data for FTW driver and initialize it.
714 @param[out] FtwData Pointer to the FTW device structure
716 @retval EFI_SUCCESS Initialize the FTW device successfully.
717 @retval EFI_OUT_OF_RESOURCES Allocate memory error
718 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
723 OUT EFI_FTW_DEVICE
**FtwData
728 Initialization for Fault Tolerant Write is done in this handler.
730 @param[in, out] FtwDevice Pointer to the FTW device structure
732 @retval EFI_SUCCESS Initialize the FTW protocol successfully.
733 @retval EFI_NOT_FOUND No proper FVB protocol was found.
738 IN OUT EFI_FTW_DEVICE
*FtwDevice
742 Initialize a local work space header.
744 Since Signature and WriteQueueSize have been known, Crc can be calculated out,
745 then the work space header will be fixed.
748 InitializeLocalWorkSpaceHeader (