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_
32 #include <Common/FlashMap.h>
33 #include <Common/WorkingBlockHeader.h>
35 #define EFI_D_FTW_LITE EFI_D_ERROR
36 #define EFI_D_FTW_INFO EFI_D_INFO
39 // Flash erase polarity is 1
41 #define FTW_ERASE_POLARITY 1
43 #define FTW_VALID_STATE 0
44 #define FTW_INVALID_STATE 1
46 #define FTW_ERASED_BYTE ((UINT8) (255))
47 #define FTW_POLARITY_REVERT ((UINT8) (255))
50 UINT8 WriteAllocated
: 1;
51 UINT8 SpareCompleted
: 1;
52 UINT8 WriteCompleted
: 1;
54 #define WRITE_ALLOCATED 0x1
55 #define SPARE_COMPLETED 0x2
56 #define WRITE_COMPLETED 0x4
63 // UINTN SpareAreaOffset;
65 } EFI_FTW_LITE_RECORD
;
67 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
70 // MACRO for Block size.
71 // Flash Erasing will do in block granularity.
74 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
76 #define FV_BLOCK_SIZE 0x10000
77 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
80 // MACRO for FTW WORK SPACE Base & Size
82 #ifdef EFI_FTW_WORKING_OFFSET
83 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
85 #define FTW_WORK_SPACE_BASE 0x00E000
88 #ifdef EFI_FTW_WORKING_LENGTH
89 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
91 #define FTW_WORK_SPACE_SIZE 0x002000
94 // MACRO for FTW header and record
96 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
97 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
98 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
101 // EFI Fault tolerant protocol private data structure
106 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
107 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
108 UINTN WorkSpaceLength
;
109 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
110 UINTN SpareAreaLength
;
111 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
112 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
113 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
114 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
115 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
116 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
118 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
119 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
120 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
121 UINTN FtwWorkSpaceSize
;
124 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
125 // Allocated with EFI_FTW_LITE_DEVICE.
127 } EFI_FTW_LITE_DEVICE
;
129 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
132 // Driver entry point
137 IN EFI_HANDLE ImageHandle
,
138 IN EFI_SYSTEM_TABLE
*SystemTable
143 This function is the entry point of the Fault Tolerant Write driver.
146 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
148 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
151 EFI_SUCCESS - FTW has finished the initialization
152 EFI_ABORTED - FTW initialization error
158 // Fault Tolerant Write Protocol API
163 IN EFI_FTW_LITE_PROTOCOL
*This
,
164 IN EFI_HANDLE FvbHandle
,
173 Starts a target block update. This function will record data about write
174 in fault tolerant storage and will complete the write in a recoverable
175 manner, ensuring at all times that either the original contents or
176 the modified contents are available.
179 This - Calling context
180 FvbHandle - The handle of FVB protocol that provides services for
181 reading, writing, and erasing the target block.
182 Lba - The logical block address of the target block.
183 Offset - The offset within the target block to place the data.
184 NumBytes - The number of bytes to write to the target block.
185 Buffer - The data to write.
188 EFI_SUCCESS - The function completed successfully
189 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
191 EFI_ACCESS_DENIED - No writes have been allocated.
192 EFI_NOT_FOUND - Cannot find FVB by handle.
193 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
194 EFI_ABORTED - The function could not complete successfully.
200 // Internal functions
204 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
209 Restarts a previously interrupted write. The caller must provide the
210 block protocol needed to complete the interrupted write.
213 FtwLiteDevice - The private data of FTW_LITE driver
214 FvbHandle - The handle of FVB protocol that provides services for
215 reading, writing, and erasing the target block.
218 EFI_SUCCESS - The function completed successfully
219 EFI_ACCESS_DENIED - No pending writes exist
220 EFI_NOT_FOUND - FVB protocol not found by the handle
221 EFI_ABORTED - The function could not complete successfully
228 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
233 Aborts all previous allocated writes.
236 FtwLiteDevice - The private data of FTW_LITE driver
239 EFI_SUCCESS - The function completed successfully
240 EFI_ABORTED - The function could not complete successfully.
241 EFI_NOT_FOUND - No allocated writes exist.
249 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
250 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
255 Write a record with fault tolerant mannaer.
256 Since the content has already backuped in spare block, the write is
257 guaranteed to be completed with fault tolerant manner.
260 FtwLiteDevice - The private data of FTW_LITE driver
261 Fvb - The FVB protocol that provides services for
262 reading, writing, and erasing the target block.
265 EFI_SUCCESS - The function completed successfully
266 EFI_ABORTED - The function could not complete successfully
273 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
274 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
280 To Erase one block. The size is FTW_BLOCK_SIZE
283 FtwLiteDevice - Calling context
284 FvBlock - FVB Protocol interface
285 Lba - Lba of the firmware block
288 EFI_SUCCESS - Block LBA is Erased successfully
289 Others - Error occurs
296 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
306 FtwLiteDevice - Calling context
317 IN EFI_HANDLE FvBlockHandle
,
318 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
323 Retrive the proper FVB protocol interface by HANDLE.
326 FvBlockHandle - The handle of FVB protocol that provides services for
327 reading, writing, and erasing the target block.
328 FvBlock - The interface of FVB protocol
331 EFI_SUCCESS - The function completed successfully
332 EFI_ABORTED - The function could not complete successfully
338 IN EFI_PHYSICAL_ADDRESS Address
,
339 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
345 Get firmware block by address.
349 Address - Address specified the block
350 FvBlock - The block caller wanted
356 EFI_NOT_FOUND - Block not found
363 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
364 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
371 Is it in working block?
375 FtwLiteDevice - Calling context
376 FvBlock - Fvb protocol instance
377 Lba - The block specified
381 In working block or not
388 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
389 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
396 Check whether the block is a boot block.
400 FtwLiteDevice - Calling context
401 FvBlock - Fvb protocol instance
406 Is a boot block or not
412 FlushSpareBlockToTargetBlock (
413 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
414 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
420 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
421 Spare block is accessed by FTW backup FVB protocol interface. LBA is
422 FtwLiteDevice->FtwSpareLba.
423 Target block is accessed by FvBlock protocol interface. LBA is Lba.
426 FtwLiteDevice - The private data of FTW_LITE driver
427 FvBlock - FVB Protocol interface to access target block
428 Lba - Lba of the target block
431 EFI_SUCCESS - Spare block content is copied to target block
432 EFI_INVALID_PARAMETER - Input parameter error
433 EFI_OUT_OF_RESOURCES - Allocate memory error
434 EFI_ABORTED - The function could not complete successfully
440 FlushSpareBlockToWorkingBlock (
441 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
446 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
447 Spare block is accessed by FTW backup FVB protocol interface. LBA is
448 FtwLiteDevice->FtwSpareLba.
449 Working block is accessed by FTW working FVB protocol interface. LBA is
450 FtwLiteDevice->FtwWorkBlockLba.
453 FtwLiteDevice - The private data of FTW_LITE driver
456 EFI_SUCCESS - Spare block content is copied to target block
457 EFI_OUT_OF_RESOURCES - Allocate memory error
458 EFI_ABORTED - The function could not complete successfully
461 Since the working block header is important when FTW initializes, the
462 state of the operation should be handled carefully. The Crc value is
463 calculated without STATE element.
469 FlushSpareBlockToBootBlock (
470 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
475 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
476 Spare block is accessed by FTW backup FVB protocol interface. LBA is
477 FtwLiteDevice->FtwSpareLba.
478 Boot block is accessed by BootFvb protocol interface. LBA is 0.
481 FtwLiteDevice - The private data of FTW_LITE driver
484 EFI_SUCCESS - Spare block content is copied to boot block
485 EFI_INVALID_PARAMETER - Input parameter error
486 EFI_OUT_OF_RESOURCES - Allocate memory error
487 EFI_ABORTED - The function could not complete successfully
496 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
504 Update a bit of state on a block device. The location of the bit is
505 calculated by the (Lba, Offset, bit). Here bit is determined by the
506 the name of a certain bit.
509 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
511 Offset - Offset on the Lba
512 NewBit - New value that will override the old value if it can be change
515 EFI_SUCCESS - A state bit has been updated successfully
516 Others - Access block device error.
519 Assume all bits of State are inside the same BYTE.
521 EFI_ABORTED - Read block fail
527 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
528 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
533 Get the last Write record pointer.
534 The last record is the record whose 'complete' state hasn't been set.
535 After all, this header may be a EMPTY header entry for next Allocate.
538 FtwLiteDevice - Private data of this driver
539 FtwLastRecord - Pointer to retrieve the last write record
542 EFI_SUCCESS - Get the last write record successfully
543 EFI_ABORTED - The FTW work space is damaged
549 IsErasedFlashBuffer (
558 Check whether a flash buffer is erased.
562 Polarity - All 1 or all 0
563 Buffer - Buffer to check
564 BufferSize - Size of the buffer
574 InitWorkSpaceHeader (
575 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
580 Initialize a work space when there is no work space.
583 WorkingHeader - Pointer of working block header
586 EFI_SUCCESS - The function completed successfully
587 EFI_ABORTED - The function could not complete successfully.
594 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
599 Read from working block to refresh the work space in memory.
602 FtwLiteDevice - Point to private data of FTW driver
605 EFI_SUCCESS - The function completed successfully
606 EFI_ABORTED - The function could not complete successfully.
613 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
618 Check to see if it is a valid work space.
621 WorkingHeader - Pointer of working block header
624 EFI_SUCCESS - The function completed successfully
625 EFI_ABORTED - The function could not complete successfully.
632 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
633 IN OUT UINT8
*BlockBuffer
,
639 Reclaim the work space. Get rid of all the completed write records
640 and write records in the Fault Tolerant work space.
643 FtwLiteDevice - Point to private data of FTW driver
644 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
645 BufferSize - Size of the FtwSpaceBuffer
648 EFI_SUCCESS - The function completed successfully
649 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
650 EFI_ABORTED - The function could not complete successfully.
656 FtwReclaimWorkSpace (
657 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
662 Reclaim the work space on the working block.
665 FtwLiteDevice - Point to private data of FTW driver
668 EFI_SUCCESS - The function completed successfully
669 EFI_OUT_OF_RESOURCES - Allocate memory error
670 EFI_ABORTED - The function could not complete successfully