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>
38 // Flash erase polarity is 1
40 #define FTW_ERASE_POLARITY 1
42 #define FTW_VALID_STATE 0
43 #define FTW_INVALID_STATE 1
45 #define FTW_ERASED_BYTE ((UINT8) (255))
46 #define FTW_POLARITY_REVERT ((UINT8) (255))
49 UINT8 WriteAllocated
: 1;
50 UINT8 SpareCompleted
: 1;
51 UINT8 WriteCompleted
: 1;
53 #define WRITE_ALLOCATED 0x1
54 #define SPARE_COMPLETED 0x2
55 #define WRITE_COMPLETED 0x4
62 // UINTN SpareAreaOffset;
64 } EFI_FTW_LITE_RECORD
;
66 #define FTW_LITE_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'L')
69 // MACRO for FTW header and record
71 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
74 // EFI Fault tolerant protocol private data structure
79 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
80 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
81 UINTN WorkSpaceLength
; // Size of working space range in flash.
82 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
83 UINTN SpareAreaLength
; // Size of spare range in flash.
84 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
85 UINTN BlockSize
; // Block size in bytes of the blocks in flash
86 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
87 EFI_FTW_LITE_RECORD
*FtwLastRecord
; // Pointer to last record in memory buffer
88 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
89 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
90 EFI_LBA FtwSpareLba
; // Start LBA of spare block
91 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
92 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
93 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
94 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
95 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
97 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
98 // Allocated with EFI_FTW_LITE_DEVICE.
100 } EFI_FTW_LITE_DEVICE
;
102 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
105 // Driver entry point
108 This function is the entry point of the Fault Tolerant Write driver.
111 @param ImageHandle A handle for the image that is initializing
113 @param SystemTable A pointer to the EFI system table
115 @retval EFI_SUCCESS FTW has finished the initialization
116 @retval EFI_ABORTED FTW initialization error
122 IN EFI_HANDLE ImageHandle
,
123 IN EFI_SYSTEM_TABLE
*SystemTable
127 // Fault Tolerant Write Protocol API
130 Starts a target block update. This function will record data about write
131 in fault tolerant storage and will complete the write in a recoverable
132 manner, ensuring at all times that either the original contents or
133 the modified contents are available.
136 @param This Calling context
137 @param FvbHandle The handle of FVB protocol that provides services for
138 reading, writing, and erasing the target block.
139 @param Lba The logical block address of the target block.
140 @param Offset The offset within the target block to place the data.
141 @param NumBytes The number of bytes to write to the target block.
142 @param Buffer The data to write.
144 @retval EFI_SUCCESS The function completed successfully
145 @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not
147 @retval EFI_ACCESS_DENIED No writes have been allocated.
148 @retval EFI_NOT_FOUND Cannot find FVB by handle.
149 @retval EFI_OUT_OF_RESOURCES Cannot allocate memory.
150 @retval EFI_ABORTED The function could not complete successfully.
156 IN EFI_FTW_LITE_PROTOCOL
*This
,
157 IN EFI_HANDLE FvbHandle
,
160 IN OUT UINTN
*NumBytes
,
165 // Internal functions
168 Restarts a previously interrupted write. The caller must provide the
169 block protocol needed to complete the interrupted write.
172 @param FtwLiteDevice The private data of FTW_LITE driver
173 FvbHandle - The handle of FVB protocol that provides services for
174 reading, writing, and erasing the target block.
176 @retval EFI_SUCCESS The function completed successfully
177 @retval EFI_ACCESS_DENIED No pending writes exist
178 @retval EFI_NOT_FOUND FVB protocol not found by the handle
179 @retval EFI_ABORTED The function could not complete successfully
184 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
188 Aborts all previous allocated writes.
191 @param FtwLiteDevice The private data of FTW_LITE driver
193 @retval EFI_SUCCESS The function completed successfully
194 @retval EFI_ABORTED The function could not complete successfully.
195 @retval EFI_NOT_FOUND No allocated writes exist.
200 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
205 Write a record with fault tolerant mannaer.
206 Since the content has already backuped in spare block, the write is
207 guaranteed to be completed with fault tolerant manner.
210 @param FtwLiteDevice The private data of FTW_LITE driver
211 @param Fvb The FVB protocol that provides services for
212 reading, writing, and erasing the target block.
214 @retval EFI_SUCCESS The function completed successfully
215 @retval EFI_ABORTED The function could not complete successfully
220 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
221 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
225 To erase the block with the spare block size.
228 @param FtwLiteDevice Calling context
229 @param FvBlock FVB Protocol interface
230 @param Lba Lba of the firmware block
232 @retval EFI_SUCCESS Block LBA is Erased successfully
233 @retval Others Error occurs
238 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
239 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
248 @param FtwLiteDevice Calling context
250 @retval EFI_SUCCESS The erase request was successfully
253 @retval EFI_ACCESS_DENIED The firmware volume is in the
255 @retval EFI_DEVICE_ERROR The block device is not functioning
256 correctly and could not be written.
257 The firmware device may have been
259 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
260 in the variable argument list do
261 not exist in the firmware volume.
266 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
270 Retrive the proper FVB protocol interface by HANDLE.
273 @param FvBlockHandle The handle of FVB protocol that provides services for
274 reading, writing, and erasing the target block.
275 @param FvBlock The interface of FVB protocol
277 @retval EFI_SUCCESS The function completed successfully
278 @retval EFI_ABORTED The function could not complete successfully
283 IN EFI_HANDLE FvBlockHandle
,
284 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
289 Get firmware block by address.
292 @param Address Address specified the block
293 @param FvBlock The block caller wanted
295 @retval EFI_SUCCESS The protocol instance if found.
296 @retval EFI_NOT_FOUND Block not found
301 IN EFI_PHYSICAL_ADDRESS Address
,
302 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
307 Is it in working block?
310 @param FtwLiteDevice Calling context
311 @param FvBlock Fvb protocol instance
312 @param Lba The block specified
314 @return A BOOLEAN value indicating in working block or not.
319 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
320 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
325 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
326 Spare block is accessed by FTW backup FVB protocol interface. LBA is
327 FtwLiteDevice->FtwSpareLba.
328 Target block is accessed by FvBlock protocol interface. LBA is Lba.
331 @param FtwLiteDevice The private data of FTW_LITE driver
332 @param FvBlock FVB Protocol interface to access target block
333 @param Lba Lba of the target block
335 @retval EFI_SUCCESS Spare block content is copied to target block
336 @retval EFI_INVALID_PARAMETER Input parameter error
337 @retval EFI_OUT_OF_RESOURCES Allocate memory error
338 @retval EFI_ABORTED The function could not complete successfully
342 FlushSpareBlockToTargetBlock (
343 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
344 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
349 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
350 Spare block is accessed by FTW backup FVB protocol interface. LBA is
351 FtwLiteDevice->FtwSpareLba.
352 Working block is accessed by FTW working FVB protocol interface. LBA is
353 FtwLiteDevice->FtwWorkBlockLba.
356 @param FtwLiteDevice The private data of FTW_LITE driver
358 @retval EFI_SUCCESS Spare block content is copied to target block
359 @retval EFI_OUT_OF_RESOURCES Allocate memory error
360 @retval EFI_ABORTED The function could not complete successfully
362 Since the working block header is important when FTW initializes, the
363 state of the operation should be handled carefully. The Crc value is
364 calculated without STATE element.
368 FlushSpareBlockToWorkingBlock (
369 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
373 Update a bit of state on a block device. The location of the bit is
374 calculated by the (Lba, Offset, bit). Here bit is determined by the
375 the name of a certain bit.
378 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
379 @param Lba Lba of a block
380 @param Offset Offset on the Lba
381 @param NewBit New value that will override the old value if it can be change
383 @retval EFI_SUCCESS A state bit has been updated successfully
384 @retval Others Access block device error.
386 Assume all bits of State are inside the same BYTE.
387 @retval EFI_ABORTED Read block fail
392 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
399 Get the last Write record pointer.
400 The last record is the record whose 'complete' state hasn't been set.
401 After all, this header may be a EMPTY header entry for next Allocate.
404 @param FtwLiteDevice Private data of this driver
405 @param FtwLastRecord Pointer to retrieve the last write record
407 @retval EFI_SUCCESS Get the last write record successfully
408 @retval EFI_ABORTED The FTW work space is damaged
413 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
414 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
419 Check whether a flash buffer is erased.
422 @param Polarity All 1 or all 0
423 @param Buffer Buffer to check
424 @param BufferSize Size of the buffer
426 @return A BOOLEAN value indicating erased or not.
430 IsErasedFlashBuffer (
437 Initialize a work space when there is no work space.
440 @param WorkingHeader Pointer of working block header
442 @retval EFI_SUCCESS The function completed successfully
443 @retval EFI_ABORTED The function could not complete successfully.
447 InitWorkSpaceHeader (
448 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
452 Read from working block to refresh the work space in memory.
455 @param FtwLiteDevice Point to private data of FTW driver
457 @retval EFI_SUCCESS The function completed successfully
458 @retval EFI_ABORTED The function could not complete successfully.
463 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
467 Check to see if it is a valid work space.
470 @param WorkingHeader Pointer of working block header
472 @retval EFI_SUCCESS The function completed successfully
473 @retval EFI_ABORTED The function could not complete successfully.
478 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
482 Reclaim the work space on the working block.
485 @param FtwLiteDevice Point to private data of FTW driver
486 @param PreserveRecord Whether to preserve the working record is needed
488 @retval EFI_SUCCESS The function completed successfully
489 @retval EFI_OUT_OF_RESOURCES Allocate memory error
490 @retval EFI_ABORTED The function could not complete successfully
494 FtwReclaimWorkSpace (
495 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
496 IN BOOLEAN PreserveRecord