3 Copyright (c) 2006, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 This is a simple fault tolerant write driver, based on PlatformFd library.
20 And it only supports write BufferSize <= SpareAreaLength.
22 This boot service only protocol provides fault tolerant write capability for
23 block devices. The protocol has internal non-volatile intermediate storage
24 of the data and private information. It should be able to recover
25 automatically from a critical fault, such as power failure.
29 #ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_
30 #define _EFI_FAULT_TOLERANT_WRITE_LITE_H_
35 #include <Protocol/PciRootBridgeIo.h>
36 #include <Guid/SystemNvDataGuid.h>
37 #include <Protocol/FaultTolerantWriteLite.h>
38 #include <Protocol/FirmwareVolumeBlock.h>
40 #include <Library/PcdLib.h>
41 #include <Library/DebugLib.h>
42 #include <Library/UefiDriverEntryPoint.h>
43 #include <Library/BaseMemoryLib.h>
44 #include <Library/MemoryAllocationLib.h>
45 #include <Library/UefiBootServicesTableLib.h>
47 #include <Common/WorkingBlockHeader.h>
49 #define EFI_D_FTW_LITE EFI_D_ERROR
50 #define EFI_D_FTW_INFO EFI_D_INFO
53 // Flash erase polarity is 1
55 #define FTW_ERASE_POLARITY 1
57 #define FTW_VALID_STATE 0
58 #define FTW_INVALID_STATE 1
60 #define FTW_ERASED_BYTE ((UINT8) (255))
61 #define FTW_POLARITY_REVERT ((UINT8) (255))
64 UINT8 WriteAllocated
: 1;
65 UINT8 SpareCompleted
: 1;
66 UINT8 WriteCompleted
: 1;
68 #define WRITE_ALLOCATED 0x1
69 #define SPARE_COMPLETED 0x2
70 #define WRITE_COMPLETED 0x4
77 // UINTN SpareAreaOffset;
79 } EFI_FTW_LITE_RECORD
;
81 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
84 // MACRO for Block size.
85 // Flash Erasing will do in block granularity.
88 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
90 #define FV_BLOCK_SIZE 0x10000
91 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
94 // MACRO for FTW WORK SPACE Base & Size
96 #ifdef EFI_FTW_WORKING_OFFSET
97 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
99 #define FTW_WORK_SPACE_BASE 0x00E000
102 #ifdef EFI_FTW_WORKING_LENGTH
103 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
105 #define FTW_WORK_SPACE_SIZE 0x002000
108 // MACRO for FTW header and record
110 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
111 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
112 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
115 // EFI Fault tolerant protocol private data structure
120 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
121 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
122 UINTN WorkSpaceLength
;
123 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
124 UINTN SpareAreaLength
;
125 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
126 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
127 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
128 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
129 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
130 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
132 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
133 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
134 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
135 UINTN FtwWorkSpaceSize
;
138 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
139 // Allocated with EFI_FTW_LITE_DEVICE.
141 } EFI_FTW_LITE_DEVICE
;
143 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
146 // Driver entry point
151 IN EFI_HANDLE ImageHandle
,
152 IN EFI_SYSTEM_TABLE
*SystemTable
157 This function is the entry point of the Fault Tolerant Write driver.
160 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
162 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
165 EFI_SUCCESS - FTW has finished the initialization
166 EFI_ABORTED - FTW initialization error
172 // Fault Tolerant Write Protocol API
177 IN EFI_FTW_LITE_PROTOCOL
*This
,
178 IN EFI_HANDLE FvbHandle
,
187 Starts a target block update. This function will record data about write
188 in fault tolerant storage and will complete the write in a recoverable
189 manner, ensuring at all times that either the original contents or
190 the modified contents are available.
193 This - Calling context
194 FvbHandle - The handle of FVB protocol that provides services for
195 reading, writing, and erasing the target block.
196 Lba - The logical block address of the target block.
197 Offset - The offset within the target block to place the data.
198 NumBytes - The number of bytes to write to the target block.
199 Buffer - The data to write.
202 EFI_SUCCESS - The function completed successfully
203 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
205 EFI_ACCESS_DENIED - No writes have been allocated.
206 EFI_NOT_FOUND - Cannot find FVB by handle.
207 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
208 EFI_ABORTED - The function could not complete successfully.
214 // Internal functions
218 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
223 Restarts a previously interrupted write. The caller must provide the
224 block protocol needed to complete the interrupted write.
227 FtwLiteDevice - The private data of FTW_LITE driver
228 FvbHandle - The handle of FVB protocol that provides services for
229 reading, writing, and erasing the target block.
232 EFI_SUCCESS - The function completed successfully
233 EFI_ACCESS_DENIED - No pending writes exist
234 EFI_NOT_FOUND - FVB protocol not found by the handle
235 EFI_ABORTED - The function could not complete successfully
242 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
247 Aborts all previous allocated writes.
250 FtwLiteDevice - The private data of FTW_LITE driver
253 EFI_SUCCESS - The function completed successfully
254 EFI_ABORTED - The function could not complete successfully.
255 EFI_NOT_FOUND - No allocated writes exist.
263 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
264 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
269 Write a record with fault tolerant mannaer.
270 Since the content has already backuped in spare block, the write is
271 guaranteed to be completed with fault tolerant manner.
274 FtwLiteDevice - The private data of FTW_LITE driver
275 Fvb - The FVB protocol that provides services for
276 reading, writing, and erasing the target block.
279 EFI_SUCCESS - The function completed successfully
280 EFI_ABORTED - The function could not complete successfully
287 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
288 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
294 To Erase one block. The size is FTW_BLOCK_SIZE
297 FtwLiteDevice - Calling context
298 FvBlock - FVB Protocol interface
299 Lba - Lba of the firmware block
302 EFI_SUCCESS - Block LBA is Erased successfully
303 Others - Error occurs
310 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
320 FtwLiteDevice - Calling context
331 IN EFI_HANDLE FvBlockHandle
,
332 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
337 Retrive the proper FVB protocol interface by HANDLE.
340 FvBlockHandle - The handle of FVB protocol that provides services for
341 reading, writing, and erasing the target block.
342 FvBlock - The interface of FVB protocol
345 EFI_SUCCESS - The function completed successfully
346 EFI_ABORTED - The function could not complete successfully
352 IN EFI_PHYSICAL_ADDRESS Address
,
353 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
359 Get firmware block by address.
363 Address - Address specified the block
364 FvBlock - The block caller wanted
370 EFI_NOT_FOUND - Block not found
377 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
378 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
385 Is it in working block?
389 FtwLiteDevice - Calling context
390 FvBlock - Fvb protocol instance
391 Lba - The block specified
395 In working block or not
402 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
403 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
410 Check whether the block is a boot block.
414 FtwLiteDevice - Calling context
415 FvBlock - Fvb protocol instance
420 Is a boot block or not
426 FlushSpareBlockToTargetBlock (
427 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
428 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
434 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
435 Spare block is accessed by FTW backup FVB protocol interface. LBA is
436 FtwLiteDevice->FtwSpareLba.
437 Target block is accessed by FvBlock protocol interface. LBA is Lba.
440 FtwLiteDevice - The private data of FTW_LITE driver
441 FvBlock - FVB Protocol interface to access target block
442 Lba - Lba of the target block
445 EFI_SUCCESS - Spare block content is copied to target block
446 EFI_INVALID_PARAMETER - Input parameter error
447 EFI_OUT_OF_RESOURCES - Allocate memory error
448 EFI_ABORTED - The function could not complete successfully
454 FlushSpareBlockToWorkingBlock (
455 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
460 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
461 Spare block is accessed by FTW backup FVB protocol interface. LBA is
462 FtwLiteDevice->FtwSpareLba.
463 Working block is accessed by FTW working FVB protocol interface. LBA is
464 FtwLiteDevice->FtwWorkBlockLba.
467 FtwLiteDevice - The private data of FTW_LITE driver
470 EFI_SUCCESS - Spare block content is copied to target block
471 EFI_OUT_OF_RESOURCES - Allocate memory error
472 EFI_ABORTED - The function could not complete successfully
475 Since the working block header is important when FTW initializes, the
476 state of the operation should be handled carefully. The Crc value is
477 calculated without STATE element.
483 FlushSpareBlockToBootBlock (
484 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
489 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
490 Spare block is accessed by FTW backup FVB protocol interface. LBA is
491 FtwLiteDevice->FtwSpareLba.
492 Boot block is accessed by BootFvb protocol interface. LBA is 0.
495 FtwLiteDevice - The private data of FTW_LITE driver
498 EFI_SUCCESS - Spare block content is copied to boot block
499 EFI_INVALID_PARAMETER - Input parameter error
500 EFI_OUT_OF_RESOURCES - Allocate memory error
501 EFI_ABORTED - The function could not complete successfully
510 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
518 Update a bit of state on a block device. The location of the bit is
519 calculated by the (Lba, Offset, bit). Here bit is determined by the
520 the name of a certain bit.
523 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
525 Offset - Offset on the Lba
526 NewBit - New value that will override the old value if it can be change
529 EFI_SUCCESS - A state bit has been updated successfully
530 Others - Access block device error.
533 Assume all bits of State are inside the same BYTE.
535 EFI_ABORTED - Read block fail
541 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
542 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
547 Get the last Write record pointer.
548 The last record is the record whose 'complete' state hasn't been set.
549 After all, this header may be a EMPTY header entry for next Allocate.
552 FtwLiteDevice - Private data of this driver
553 FtwLastRecord - Pointer to retrieve the last write record
556 EFI_SUCCESS - Get the last write record successfully
557 EFI_ABORTED - The FTW work space is damaged
563 IsErasedFlashBuffer (
572 Check whether a flash buffer is erased.
576 Polarity - All 1 or all 0
577 Buffer - Buffer to check
578 BufferSize - Size of the buffer
588 InitWorkSpaceHeader (
589 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
594 Initialize a work space when there is no work space.
597 WorkingHeader - Pointer of working block header
600 EFI_SUCCESS - The function completed successfully
601 EFI_ABORTED - The function could not complete successfully.
608 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
613 Read from working block to refresh the work space in memory.
616 FtwLiteDevice - Point to private data of FTW driver
619 EFI_SUCCESS - The function completed successfully
620 EFI_ABORTED - The function could not complete successfully.
627 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
632 Check to see if it is a valid work space.
635 WorkingHeader - Pointer of working block header
638 EFI_SUCCESS - The function completed successfully
639 EFI_ABORTED - The function could not complete successfully.
646 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
647 IN OUT UINT8
*BlockBuffer
,
653 Reclaim the work space. Get rid of all the completed write records
654 and write records in the Fault Tolerant work space.
657 FtwLiteDevice - Point to private data of FTW driver
658 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
659 BufferSize - Size of the FtwSpaceBuffer
662 EFI_SUCCESS - The function completed successfully
663 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
664 EFI_ABORTED - The function could not complete successfully.
670 FtwReclaimWorkSpace (
671 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
676 Reclaim the work space on the working block.
679 FtwLiteDevice - Point to private data of FTW driver
682 EFI_SUCCESS - The function completed successfully
683 EFI_OUT_OF_RESOURCES - Allocate memory error
684 EFI_ABORTED - The function could not complete successfully