3 The internal header file includes the common header files, defines
4 internal structure and functions used by FtwLite module.
6 Copyright (c) 2006 - 2008, Intel Corporation
7 All rights reserved. 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_LITE_H_
18 #define _EFI_FAULT_TOLERANT_WRITE_LITE_H_
23 #include <Guid/SystemNvDataGuid.h>
24 #include <Protocol/FaultTolerantWriteLite.h>
25 #include <Protocol/FirmwareVolumeBlock.h>
27 #include <Library/PcdLib.h>
28 #include <Library/DebugLib.h>
29 #include <Library/UefiDriverEntryPoint.h>
30 #include <Library/BaseMemoryLib.h>
31 #include <Library/MemoryAllocationLib.h>
32 #include <Library/UefiBootServicesTableLib.h>
33 #include <Library/DevicePathLib.h>
35 #include <WorkingBlockHeader.h>
37 #define EFI_D_FTW_LITE EFI_D_ERROR
38 #define EFI_D_FTW_INFO EFI_D_INFO
41 // Flash erase polarity is 1
43 #define FTW_ERASE_POLARITY 1
45 #define FTW_VALID_STATE 0
46 #define FTW_INVALID_STATE 1
48 #define FTW_ERASED_BYTE ((UINT8) (255))
49 #define FTW_POLARITY_REVERT ((UINT8) (255))
52 UINT8 WriteAllocated
: 1;
53 UINT8 SpareCompleted
: 1;
54 UINT8 WriteCompleted
: 1;
56 #define WRITE_ALLOCATED 0x1
57 #define SPARE_COMPLETED 0x2
58 #define WRITE_COMPLETED 0x4
65 // UINTN SpareAreaOffset;
67 } EFI_FTW_LITE_RECORD
;
69 #define FTW_LITE_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'L')
72 // MACRO for Block size.
73 // Flash Erasing will do in block granularity.
76 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
78 #define FV_BLOCK_SIZE 0x10000
79 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
82 // MACRO for FTW WORK SPACE Base & Size
84 #ifdef EFI_FTW_WORKING_OFFSET
85 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
87 #define FTW_WORK_SPACE_BASE 0x00E000
90 #ifdef EFI_FTW_WORKING_LENGTH
91 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
93 #define FTW_WORK_SPACE_SIZE 0x002000
96 // MACRO for FTW header and record
98 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
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
135 This function is the entry point of the Fault Tolerant Write driver.
138 @param ImageHandle A handle for the image that is initializing
140 @param SystemTable A pointer to the EFI system table
142 @retval EFI_SUCCESS FTW has finished the initialization
143 @retval EFI_ABORTED FTW initialization error
149 IN EFI_HANDLE ImageHandle
,
150 IN EFI_SYSTEM_TABLE
*SystemTable
154 // Fault Tolerant Write Protocol API
157 Starts a target block update. This function will record data about write
158 in fault tolerant storage and will complete the write in a recoverable
159 manner, ensuring at all times that either the original contents or
160 the modified contents are available.
163 @param This Calling context
164 @param FvbHandle The handle of FVB protocol that provides services for
165 reading, writing, and erasing the target block.
166 @param Lba The logical block address of the target block.
167 @param Offset The offset within the target block to place the data.
168 @param NumBytes The number of bytes to write to the target block.
169 @param Buffer The data to write.
171 @retval EFI_SUCCESS The function completed successfully
172 @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not
174 @retval EFI_ACCESS_DENIED No writes have been allocated.
175 @retval EFI_NOT_FOUND Cannot find FVB by handle.
176 @retval EFI_OUT_OF_RESOURCES Cannot allocate memory.
177 @retval EFI_ABORTED The function could not complete successfully.
183 IN EFI_FTW_LITE_PROTOCOL
*This
,
184 IN EFI_HANDLE FvbHandle
,
187 IN OUT UINTN
*NumBytes
,
192 // Internal functions
195 Restarts a previously interrupted write. The caller must provide the
196 block protocol needed to complete the interrupted write.
199 @param FtwLiteDevice The private data of FTW_LITE driver
200 FvbHandle - The handle of FVB protocol that provides services for
201 reading, writing, and erasing the target block.
203 @retval EFI_SUCCESS The function completed successfully
204 @retval EFI_ACCESS_DENIED No pending writes exist
205 @retval EFI_NOT_FOUND FVB protocol not found by the handle
206 @retval EFI_ABORTED The function could not complete successfully
211 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
215 Aborts all previous allocated writes.
218 @param FtwLiteDevice The private data of FTW_LITE driver
220 @retval EFI_SUCCESS The function completed successfully
221 @retval EFI_ABORTED The function could not complete successfully.
222 @retval EFI_NOT_FOUND No allocated writes exist.
227 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
232 Write a record with fault tolerant mannaer.
233 Since the content has already backuped in spare block, the write is
234 guaranteed to be completed with fault tolerant manner.
237 @param FtwLiteDevice The private data of FTW_LITE driver
238 @param Fvb The FVB protocol that provides services for
239 reading, writing, and erasing the target block.
241 @retval EFI_SUCCESS The function completed successfully
242 @retval EFI_ABORTED The function could not complete successfully
247 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
248 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
252 To Erase one block. The size is FTW_BLOCK_SIZE
255 @param FtwLiteDevice Calling context
256 @param FvBlock FVB Protocol interface
257 @param Lba Lba of the firmware block
259 @retval EFI_SUCCESS Block LBA is Erased successfully
260 @retval Others Error occurs
265 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
266 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
275 @param FtwLiteDevice Calling context
277 @retval EFI_SUCCESS The erase request was successfully
280 @retval EFI_ACCESS_DENIED The firmware volume is in the
282 @retval EFI_DEVICE_ERROR The block device is not functioning
283 correctly and could not be written.
284 The firmware device may have been
286 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
287 in the variable argument list do
288 not exist in the firmware volume.
293 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
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 Get firmware block by address.
319 @param Address Address specified the block
320 @param FvBlock The block caller wanted
322 @retval EFI_SUCCESS The protocol instance if found.
323 @retval EFI_NOT_FOUND Block not found
328 IN EFI_PHYSICAL_ADDRESS Address
,
329 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
334 Is it in working block?
337 @param FtwLiteDevice Calling context
338 @param FvBlock Fvb protocol instance
339 @param Lba The block specified
341 @return A BOOLEAN value indicating in working block or not.
346 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
347 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
353 Check whether the block is a boot block.
356 @param FtwLiteDevice Calling context
357 @param FvBlock Fvb protocol instance
360 @retval FALSE This is a boot block.
361 @retval TRUE This is not a boot block.
366 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
367 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
372 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
373 Spare block is accessed by FTW backup FVB protocol interface. LBA is
374 FtwLiteDevice->FtwSpareLba.
375 Target block is accessed by FvBlock protocol interface. LBA is Lba.
378 @param FtwLiteDevice The private data of FTW_LITE driver
379 @param FvBlock FVB Protocol interface to access target block
380 @param Lba Lba of the target block
382 @retval EFI_SUCCESS Spare block content is copied to target block
383 @retval EFI_INVALID_PARAMETER Input parameter error
384 @retval EFI_OUT_OF_RESOURCES Allocate memory error
385 @retval EFI_ABORTED The function could not complete successfully
389 FlushSpareBlockToTargetBlock (
390 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
391 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
396 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
397 Spare block is accessed by FTW backup FVB protocol interface. LBA is
398 FtwLiteDevice->FtwSpareLba.
399 Working block is accessed by FTW working FVB protocol interface. LBA is
400 FtwLiteDevice->FtwWorkBlockLba.
403 @param FtwLiteDevice The private data of FTW_LITE driver
405 @retval EFI_SUCCESS Spare block content is copied to target block
406 @retval EFI_OUT_OF_RESOURCES Allocate memory error
407 @retval EFI_ABORTED The function could not complete successfully
409 Since the working block header is important when FTW initializes, the
410 state of the operation should be handled carefully. The Crc value is
411 calculated without STATE element.
415 FlushSpareBlockToWorkingBlock (
416 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
420 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
421 Spare block is accessed by FTW backup FVB protocol interface. LBA is
422 FtwLiteDevice->FtwSpareLba.
423 Boot block is accessed by BootFvb protocol interface. LBA is 0.
426 @param FtwLiteDevice The private data of FTW_LITE driver
428 @retval EFI_SUCCESS Spare block content is copied to boot block
429 @retval EFI_INVALID_PARAMETER Input parameter error
430 @retval EFI_OUT_OF_RESOURCES Allocate memory error
431 @retval EFI_ABORTED The function could not complete successfully
436 FlushSpareBlockToBootBlock (
437 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
441 Update a bit of state on a block device. The location of the bit is
442 calculated by the (Lba, Offset, bit). Here bit is determined by the
443 the name of a certain bit.
446 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
447 @param Lba Lba of a block
448 @param Offset Offset on the Lba
449 @param NewBit New value that will override the old value if it can be change
451 @retval EFI_SUCCESS A state bit has been updated successfully
452 @retval Others Access block device error.
454 Assume all bits of State are inside the same BYTE.
455 @retval EFI_ABORTED Read block fail
460 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
467 Get the last Write record pointer.
468 The last record is the record whose 'complete' state hasn't been set.
469 After all, this header may be a EMPTY header entry for next Allocate.
472 @param FtwLiteDevice Private data of this driver
473 @param FtwLastRecord Pointer to retrieve the last write record
475 @retval EFI_SUCCESS Get the last write record successfully
476 @retval EFI_ABORTED The FTW work space is damaged
481 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
482 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
487 Check whether a flash buffer is erased.
490 @param Polarity All 1 or all 0
491 @param Buffer Buffer to check
492 @param BufferSize Size of the buffer
494 @return A BOOLEAN value indicating erased or not.
498 IsErasedFlashBuffer (
505 Initialize a work space when there is no work space.
508 @param WorkingHeader Pointer of working block header
510 @retval EFI_SUCCESS The function completed successfully
511 @retval EFI_ABORTED The function could not complete successfully.
515 InitWorkSpaceHeader (
516 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
520 Read from working block to refresh the work space in memory.
523 @param FtwLiteDevice Point to private data of FTW driver
525 @retval EFI_SUCCESS The function completed successfully
526 @retval EFI_ABORTED The function could not complete successfully.
531 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
535 Check to see if it is a valid work space.
538 @param WorkingHeader Pointer of working block header
540 @retval EFI_SUCCESS The function completed successfully
541 @retval EFI_ABORTED The function could not complete successfully.
546 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
550 Reclaim the work space on the working block.
553 @param FtwLiteDevice Point to private data of FTW driver
554 @param PreserveRecord Whether to preserve the working record is needed
556 @retval EFI_SUCCESS The function completed successfully
557 @retval EFI_OUT_OF_RESOURCES Allocate memory error
558 @retval EFI_ABORTED The function could not complete successfully
562 FtwReclaimWorkSpace (
563 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
564 IN BOOLEAN PreserveRecord