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_
33 // The package level header files this module uses
37 // The protocols, PPI and GUID defintions for this module
39 #include <Protocol/PciRootBridgeIo.h>
40 #include <Guid/SystemNvDataGuid.h>
41 #include <Protocol/FaultTolerantWriteLite.h>
42 #include <Protocol/FirmwareVolumeBlock.h>
44 // The Library classes this module consumes
46 #include <Library/PcdLib.h>
47 #include <Library/DebugLib.h>
48 #include <Library/UefiDriverEntryPoint.h>
49 #include <Library/BaseMemoryLib.h>
50 #include <Library/MemoryAllocationLib.h>
51 #include <Library/UefiBootServicesTableLib.h>
53 #include <Common/WorkingBlockHeader.h>
55 #define EFI_D_FTW_LITE EFI_D_ERROR
56 #define EFI_D_FTW_INFO EFI_D_INFO
59 // Flash erase polarity is 1
61 #define FTW_ERASE_POLARITY 1
63 #define FTW_VALID_STATE 0
64 #define FTW_INVALID_STATE 1
66 #define FTW_ERASED_BYTE ((UINT8) (255))
67 #define FTW_POLARITY_REVERT ((UINT8) (255))
70 UINT8 WriteAllocated
: 1;
71 UINT8 SpareCompleted
: 1;
72 UINT8 WriteCompleted
: 1;
74 #define WRITE_ALLOCATED 0x1
75 #define SPARE_COMPLETED 0x2
76 #define WRITE_COMPLETED 0x4
83 // UINTN SpareAreaOffset;
85 } EFI_FTW_LITE_RECORD
;
87 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
90 // MACRO for Block size.
91 // Flash Erasing will do in block granularity.
94 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
96 #define FV_BLOCK_SIZE 0x10000
97 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
100 // MACRO for FTW WORK SPACE Base & Size
102 #ifdef EFI_FTW_WORKING_OFFSET
103 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
105 #define FTW_WORK_SPACE_BASE 0x00E000
108 #ifdef EFI_FTW_WORKING_LENGTH
109 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
111 #define FTW_WORK_SPACE_SIZE 0x002000
114 // MACRO for FTW header and record
116 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
117 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
118 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
121 // EFI Fault tolerant protocol private data structure
126 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
127 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
128 UINTN WorkSpaceLength
;
129 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
130 UINTN SpareAreaLength
;
131 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
132 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
133 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
134 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
135 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
136 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
138 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
139 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
140 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
141 UINTN FtwWorkSpaceSize
;
144 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
145 // Allocated with EFI_FTW_LITE_DEVICE.
147 } EFI_FTW_LITE_DEVICE
;
149 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
152 // Driver entry point
157 IN EFI_HANDLE ImageHandle
,
158 IN EFI_SYSTEM_TABLE
*SystemTable
163 This function is the entry point of the Fault Tolerant Write driver.
166 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
168 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
171 EFI_SUCCESS - FTW has finished the initialization
172 EFI_ABORTED - FTW initialization error
178 // Fault Tolerant Write Protocol API
183 IN EFI_FTW_LITE_PROTOCOL
*This
,
184 IN EFI_HANDLE FvbHandle
,
193 Starts a target block update. This function will record data about write
194 in fault tolerant storage and will complete the write in a recoverable
195 manner, ensuring at all times that either the original contents or
196 the modified contents are available.
199 This - Calling context
200 FvbHandle - The handle of FVB protocol that provides services for
201 reading, writing, and erasing the target block.
202 Lba - The logical block address of the target block.
203 Offset - The offset within the target block to place the data.
204 NumBytes - The number of bytes to write to the target block.
205 Buffer - The data to write.
208 EFI_SUCCESS - The function completed successfully
209 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
211 EFI_ACCESS_DENIED - No writes have been allocated.
212 EFI_NOT_FOUND - Cannot find FVB by handle.
213 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
214 EFI_ABORTED - The function could not complete successfully.
220 // Internal functions
224 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
229 Restarts a previously interrupted write. The caller must provide the
230 block protocol needed to complete the interrupted write.
233 FtwLiteDevice - The private data of FTW_LITE driver
234 FvbHandle - The handle of FVB protocol that provides services for
235 reading, writing, and erasing the target block.
238 EFI_SUCCESS - The function completed successfully
239 EFI_ACCESS_DENIED - No pending writes exist
240 EFI_NOT_FOUND - FVB protocol not found by the handle
241 EFI_ABORTED - The function could not complete successfully
248 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
253 Aborts all previous allocated writes.
256 FtwLiteDevice - The private data of FTW_LITE driver
259 EFI_SUCCESS - The function completed successfully
260 EFI_ABORTED - The function could not complete successfully.
261 EFI_NOT_FOUND - No allocated writes exist.
269 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
270 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
275 Write a record with fault tolerant mannaer.
276 Since the content has already backuped in spare block, the write is
277 guaranteed to be completed with fault tolerant manner.
280 FtwLiteDevice - The private data of FTW_LITE driver
281 Fvb - The FVB protocol that provides services for
282 reading, writing, and erasing the target block.
285 EFI_SUCCESS - The function completed successfully
286 EFI_ABORTED - The function could not complete successfully
293 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
294 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
300 To Erase one block. The size is FTW_BLOCK_SIZE
303 FtwLiteDevice - Calling context
304 FvBlock - FVB Protocol interface
305 Lba - Lba of the firmware block
308 EFI_SUCCESS - Block LBA is Erased successfully
309 Others - Error occurs
316 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
326 FtwLiteDevice - Calling context
337 IN EFI_HANDLE FvBlockHandle
,
338 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
343 Retrive the proper FVB protocol interface by HANDLE.
346 FvBlockHandle - The handle of FVB protocol that provides services for
347 reading, writing, and erasing the target block.
348 FvBlock - The interface of FVB protocol
351 EFI_SUCCESS - The function completed successfully
352 EFI_ABORTED - The function could not complete successfully
358 IN EFI_PHYSICAL_ADDRESS Address
,
359 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
365 Get firmware block by address.
369 Address - Address specified the block
370 FvBlock - The block caller wanted
376 EFI_NOT_FOUND - Block not found
383 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
384 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
391 Is it in working block?
395 FtwLiteDevice - Calling context
396 FvBlock - Fvb protocol instance
397 Lba - The block specified
401 In working block or not
408 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
409 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
416 Check whether the block is a boot block.
420 FtwLiteDevice - Calling context
421 FvBlock - Fvb protocol instance
426 Is a boot block or not
432 FlushSpareBlockToTargetBlock (
433 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
434 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
440 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
441 Spare block is accessed by FTW backup FVB protocol interface. LBA is
442 FtwLiteDevice->FtwSpareLba.
443 Target block is accessed by FvBlock protocol interface. LBA is Lba.
446 FtwLiteDevice - The private data of FTW_LITE driver
447 FvBlock - FVB Protocol interface to access target block
448 Lba - Lba of the target block
451 EFI_SUCCESS - Spare block content is copied to target block
452 EFI_INVALID_PARAMETER - Input parameter error
453 EFI_OUT_OF_RESOURCES - Allocate memory error
454 EFI_ABORTED - The function could not complete successfully
460 FlushSpareBlockToWorkingBlock (
461 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
466 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
467 Spare block is accessed by FTW backup FVB protocol interface. LBA is
468 FtwLiteDevice->FtwSpareLba.
469 Working block is accessed by FTW working FVB protocol interface. LBA is
470 FtwLiteDevice->FtwWorkBlockLba.
473 FtwLiteDevice - The private data of FTW_LITE driver
476 EFI_SUCCESS - Spare block content is copied to target block
477 EFI_OUT_OF_RESOURCES - Allocate memory error
478 EFI_ABORTED - The function could not complete successfully
481 Since the working block header is important when FTW initializes, the
482 state of the operation should be handled carefully. The Crc value is
483 calculated without STATE element.
489 FlushSpareBlockToBootBlock (
490 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
495 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
496 Spare block is accessed by FTW backup FVB protocol interface. LBA is
497 FtwLiteDevice->FtwSpareLba.
498 Boot block is accessed by BootFvb protocol interface. LBA is 0.
501 FtwLiteDevice - The private data of FTW_LITE driver
504 EFI_SUCCESS - Spare block content is copied to boot block
505 EFI_INVALID_PARAMETER - Input parameter error
506 EFI_OUT_OF_RESOURCES - Allocate memory error
507 EFI_ABORTED - The function could not complete successfully
516 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
524 Update a bit of state on a block device. The location of the bit is
525 calculated by the (Lba, Offset, bit). Here bit is determined by the
526 the name of a certain bit.
529 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
531 Offset - Offset on the Lba
532 NewBit - New value that will override the old value if it can be change
535 EFI_SUCCESS - A state bit has been updated successfully
536 Others - Access block device error.
539 Assume all bits of State are inside the same BYTE.
541 EFI_ABORTED - Read block fail
547 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
548 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
553 Get the last Write record pointer.
554 The last record is the record whose 'complete' state hasn't been set.
555 After all, this header may be a EMPTY header entry for next Allocate.
558 FtwLiteDevice - Private data of this driver
559 FtwLastRecord - Pointer to retrieve the last write record
562 EFI_SUCCESS - Get the last write record successfully
563 EFI_ABORTED - The FTW work space is damaged
569 IsErasedFlashBuffer (
578 Check whether a flash buffer is erased.
582 Polarity - All 1 or all 0
583 Buffer - Buffer to check
584 BufferSize - Size of the buffer
594 InitWorkSpaceHeader (
595 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
600 Initialize a work space when there is no work space.
603 WorkingHeader - Pointer of working block header
606 EFI_SUCCESS - The function completed successfully
607 EFI_ABORTED - The function could not complete successfully.
614 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
619 Read from working block to refresh the work space in memory.
622 FtwLiteDevice - Point to private data of FTW driver
625 EFI_SUCCESS - The function completed successfully
626 EFI_ABORTED - The function could not complete successfully.
633 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
638 Check to see if it is a valid work space.
641 WorkingHeader - Pointer of working block header
644 EFI_SUCCESS - The function completed successfully
645 EFI_ABORTED - The function could not complete successfully.
652 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
653 IN OUT UINT8
*BlockBuffer
,
659 Reclaim the work space. Get rid of all the completed write records
660 and write records in the Fault Tolerant work space.
663 FtwLiteDevice - Point to private data of FTW driver
664 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
665 BufferSize - Size of the FtwSpaceBuffer
668 EFI_SUCCESS - The function completed successfully
669 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
670 EFI_ABORTED - The function could not complete successfully.
676 FtwReclaimWorkSpace (
677 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
682 Reclaim the work space on the working block.
685 FtwLiteDevice - Point to private data of FTW driver
688 EFI_SUCCESS - The function completed successfully
689 EFI_OUT_OF_RESOURCES - Allocate memory error
690 EFI_ABORTED - The function could not complete successfully