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 <Protocol/PciRootBridgeIo.h>
24 #include <Guid/SystemNvDataGuid.h>
25 #include <Protocol/FaultTolerantWriteLite.h>
26 #include <Protocol/FirmwareVolumeBlock.h>
28 #include <Library/PcdLib.h>
29 #include <Library/DebugLib.h>
30 #include <Library/UefiDriverEntryPoint.h>
31 #include <Library/BaseMemoryLib.h>
32 #include <Library/MemoryAllocationLib.h>
33 #include <Library/UefiBootServicesTableLib.h>
34 #include <Library/DevicePathLib.h>
36 #include <WorkingBlockHeader.h>
38 #define EFI_D_FTW_LITE EFI_D_ERROR
39 #define EFI_D_FTW_INFO EFI_D_INFO
42 // Flash erase polarity is 1
44 #define FTW_ERASE_POLARITY 1
46 #define FTW_VALID_STATE 0
47 #define FTW_INVALID_STATE 1
49 #define FTW_ERASED_BYTE ((UINT8) (255))
50 #define FTW_POLARITY_REVERT ((UINT8) (255))
53 UINT8 WriteAllocated
: 1;
54 UINT8 SpareCompleted
: 1;
55 UINT8 WriteCompleted
: 1;
57 #define WRITE_ALLOCATED 0x1
58 #define SPARE_COMPLETED 0x2
59 #define WRITE_COMPLETED 0x4
66 // UINTN SpareAreaOffset;
68 } EFI_FTW_LITE_RECORD
;
70 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
73 // MACRO for Block size.
74 // Flash Erasing will do in block granularity.
77 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
79 #define FV_BLOCK_SIZE 0x10000
80 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
83 // MACRO for FTW WORK SPACE Base & Size
85 #ifdef EFI_FTW_WORKING_OFFSET
86 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
88 #define FTW_WORK_SPACE_BASE 0x00E000
91 #ifdef EFI_FTW_WORKING_LENGTH
92 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
94 #define FTW_WORK_SPACE_SIZE 0x002000
97 // MACRO for FTW header and record
99 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
100 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
101 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
104 // EFI Fault tolerant protocol private data structure
109 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
110 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
111 UINTN WorkSpaceLength
;
112 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
113 UINTN SpareAreaLength
;
114 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
115 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
116 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
117 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
118 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
119 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
121 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
122 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
123 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
124 UINTN FtwWorkSpaceSize
;
127 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
128 // Allocated with EFI_FTW_LITE_DEVICE.
130 } EFI_FTW_LITE_DEVICE
;
132 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
135 // Driver entry point
138 This function is the entry point of the Fault Tolerant Write driver.
141 @param ImageHandle EFI_HANDLE: A handle for the image that is initializing
143 @param SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table
145 @retval EFI_SUCCESS FTW has finished the initialization
146 @retval EFI_ABORTED FTW initialization error
152 IN EFI_HANDLE ImageHandle
,
153 IN EFI_SYSTEM_TABLE
*SystemTable
157 // Fault Tolerant Write Protocol API
160 Starts a target block update. This function will record data about write
161 in fault tolerant storage and will complete the write in a recoverable
162 manner, ensuring at all times that either the original contents or
163 the modified contents are available.
166 @param This Calling context
167 @param FvbHandle The handle of FVB protocol that provides services for
168 reading, writing, and erasing the target block.
169 @param Lba The logical block address of the target block.
170 @param Offset The offset within the target block to place the data.
171 @param NumBytes The number of bytes to write to the target block.
172 @param Buffer The data to write.
174 @retval EFI_SUCCESS The function completed successfully
175 @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not
177 @retval EFI_ACCESS_DENIED No writes have been allocated.
178 @retval EFI_NOT_FOUND Cannot find FVB by handle.
179 @retval EFI_OUT_OF_RESOURCES Cannot allocate memory.
180 @retval EFI_ABORTED The function could not complete successfully.
186 IN EFI_FTW_LITE_PROTOCOL
*This
,
187 IN EFI_HANDLE FvbHandle
,
190 IN OUT UINTN
*NumBytes
,
195 // Internal functions
198 Restarts a previously interrupted write. The caller must provide the
199 block protocol needed to complete the interrupted write.
202 @param FtwLiteDevice The private data of FTW_LITE driver
203 FvbHandle - The handle of FVB protocol that provides services for
204 reading, writing, and erasing the target block.
206 @retval EFI_SUCCESS The function completed successfully
207 @retval EFI_ACCESS_DENIED No pending writes exist
208 @retval EFI_NOT_FOUND FVB protocol not found by the handle
209 @retval EFI_ABORTED The function could not complete successfully
214 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
218 Aborts all previous allocated writes.
221 @param FtwLiteDevice The private data of FTW_LITE driver
223 @retval EFI_SUCCESS The function completed successfully
224 @retval EFI_ABORTED The function could not complete successfully.
225 @retval EFI_NOT_FOUND No allocated writes exist.
230 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
235 Write a record with fault tolerant mannaer.
236 Since the content has already backuped in spare block, the write is
237 guaranteed to be completed with fault tolerant manner.
240 @param FtwLiteDevice The private data of FTW_LITE driver
241 @param Fvb The FVB protocol that provides services for
242 reading, writing, and erasing the target block.
244 @retval EFI_SUCCESS The function completed successfully
245 @retval EFI_ABORTED The function could not complete successfully
250 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
251 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
255 To Erase one block. The size is FTW_BLOCK_SIZE
258 @param FtwLiteDevice Calling context
259 @param FvBlock FVB Protocol interface
260 @param Lba Lba of the firmware block
262 @retval EFI_SUCCESS Block LBA is Erased successfully
263 @retval Others Error occurs
268 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
269 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
278 @param FtwLiteDevice Calling context
280 @retval EFI_SUCCESS The erase request was successfully
283 @retval EFI_ACCESS_DENIED The firmware volume is in the
285 @retval EFI_DEVICE_ERROR The block device is not functioning
286 correctly and could not be written.
287 The firmware device may have been
289 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
290 in the variable argument list do
291 not exist in the firmware volume.
296 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
300 Retrive the proper FVB protocol interface by HANDLE.
303 @param FvBlockHandle The handle of FVB protocol that provides services for
304 reading, writing, and erasing the target block.
305 @param FvBlock The interface of FVB protocol
307 @retval EFI_SUCCESS The function completed successfully
308 @retval EFI_ABORTED The function could not complete successfully
313 IN EFI_HANDLE FvBlockHandle
,
314 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
319 Get firmware block by address.
322 @param Address Address specified the block
323 @param FvBlock The block caller wanted
325 @retval EFI_SUCCESS The protocol instance if found.
326 @retval EFI_NOT_FOUND Block not found
331 IN EFI_PHYSICAL_ADDRESS Address
,
332 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
337 Is it in working block?
340 @param FtwLiteDevice Calling context
341 @param FvBlock Fvb protocol instance
342 @param Lba The block specified
344 @return A BOOLEAN value indicating in working block or not.
349 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
350 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
356 Check whether the block is a boot block.
359 @param FtwLiteDevice Calling context
360 @param FvBlock Fvb protocol instance
363 @retval FALSE This is a boot block.
364 @retval TRUE This is not a boot block.
369 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
370 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
375 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
376 Spare block is accessed by FTW backup FVB protocol interface. LBA is
377 FtwLiteDevice->FtwSpareLba.
378 Target block is accessed by FvBlock protocol interface. LBA is Lba.
381 @param FtwLiteDevice The private data of FTW_LITE driver
382 @param FvBlock FVB Protocol interface to access target block
383 @param Lba Lba of the target block
385 @retval EFI_SUCCESS Spare block content is copied to target block
386 @retval EFI_INVALID_PARAMETER Input parameter error
387 @retval EFI_OUT_OF_RESOURCES Allocate memory error
388 @retval EFI_ABORTED The function could not complete successfully
392 FlushSpareBlockToTargetBlock (
393 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
394 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
399 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
400 Spare block is accessed by FTW backup FVB protocol interface. LBA is
401 FtwLiteDevice->FtwSpareLba.
402 Working block is accessed by FTW working FVB protocol interface. LBA is
403 FtwLiteDevice->FtwWorkBlockLba.
406 @param FtwLiteDevice The private data of FTW_LITE driver
408 @retval EFI_SUCCESS Spare block content is copied to target block
409 @retval EFI_OUT_OF_RESOURCES Allocate memory error
410 @retval EFI_ABORTED The function could not complete successfully
412 Since the working block header is important when FTW initializes, the
413 state of the operation should be handled carefully. The Crc value is
414 calculated without STATE element.
418 FlushSpareBlockToWorkingBlock (
419 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
423 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
424 Spare block is accessed by FTW backup FVB protocol interface. LBA is
425 FtwLiteDevice->FtwSpareLba.
426 Boot block is accessed by BootFvb protocol interface. LBA is 0.
429 @param FtwLiteDevice The private data of FTW_LITE driver
431 @retval EFI_SUCCESS Spare block content is copied to boot block
432 @retval EFI_INVALID_PARAMETER Input parameter error
433 @retval EFI_OUT_OF_RESOURCES Allocate memory error
434 @retval EFI_ABORTED The function could not complete successfully
439 FlushSpareBlockToBootBlock (
440 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
444 Update a bit of state on a block device. The location of the bit is
445 calculated by the (Lba, Offset, bit). Here bit is determined by the
446 the name of a certain bit.
449 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
450 @param Lba Lba of a block
451 @param Offset Offset on the Lba
452 @param NewBit New value that will override the old value if it can be change
454 @retval EFI_SUCCESS A state bit has been updated successfully
455 @retval Others Access block device error.
457 Assume all bits of State are inside the same BYTE.
458 @retval EFI_ABORTED Read block fail
463 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
470 Get the last Write record pointer.
471 The last record is the record whose 'complete' state hasn't been set.
472 After all, this header may be a EMPTY header entry for next Allocate.
475 @param FtwLiteDevice Private data of this driver
476 @param FtwLastRecord Pointer to retrieve the last write record
478 @retval EFI_SUCCESS Get the last write record successfully
479 @retval EFI_ABORTED The FTW work space is damaged
484 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
485 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
490 Check whether a flash buffer is erased.
493 @param Polarity All 1 or all 0
494 @param Buffer Buffer to check
495 @param BufferSize Size of the buffer
497 @return A BOOLEAN value indicating erased or not.
501 IsErasedFlashBuffer (
508 Initialize a work space when there is no work space.
511 @param WorkingHeader Pointer of working block header
513 @retval EFI_SUCCESS The function completed successfully
514 @retval EFI_ABORTED The function could not complete successfully.
518 InitWorkSpaceHeader (
519 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
523 Read from working block to refresh the work space in memory.
526 @param FtwLiteDevice Point to private data of FTW driver
528 @retval EFI_SUCCESS The function completed successfully
529 @retval EFI_ABORTED The function could not complete successfully.
534 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
538 Check to see if it is a valid work space.
541 @param WorkingHeader Pointer of working block header
543 @retval EFI_SUCCESS The function completed successfully
544 @retval EFI_ABORTED The function could not complete successfully.
549 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
553 Reclaim the work space on the working block.
556 @param FtwLiteDevice Point to private data of FTW driver
557 @param PreserveRecord Whether to preserve the working record is needed
559 @retval EFI_SUCCESS The function completed successfully
560 @retval EFI_OUT_OF_RESOURCES Allocate memory error
561 @retval EFI_ABORTED The function could not complete successfully
565 FtwReclaimWorkSpace (
566 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
567 IN BOOLEAN PreserveRecord