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>
36 // Flash erase polarity is 1
38 #define FTW_ERASE_POLARITY 1
40 #define FTW_VALID_STATE 0
41 #define FTW_INVALID_STATE 1
43 #define FTW_ERASED_BYTE ((UINT8) (255))
44 #define FTW_POLARITY_REVERT ((UINT8) (255))
47 UINT8 WriteAllocated
: 1;
48 UINT8 SpareCompleted
: 1;
49 UINT8 WriteCompleted
: 1;
51 #define WRITE_ALLOCATED 0x1
52 #define SPARE_COMPLETED 0x2
53 #define WRITE_COMPLETED 0x4
60 // UINTN SpareAreaOffset;
62 } EFI_FTW_LITE_RECORD
;
64 #define FTW_LITE_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'L')
67 // MACRO for FTW header and record
69 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
72 // EFI Fault tolerant protocol private data structure
77 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
78 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
; // Base address of working space range in flash.
79 UINTN WorkSpaceLength
; // Size of working space range in flash.
80 EFI_PHYSICAL_ADDRESS SpareAreaAddress
; // Base address of spare range in flash.
81 UINTN SpareAreaLength
; // Size of spare range in flash.
82 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block.
83 UINTN BlockSize
; // Block size in bytes of the blocks in flash
84 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;// Pointer to Working Space Header in memory buffer
85 EFI_FTW_LITE_RECORD
*FtwLastRecord
; // Pointer to last record in memory buffer
86 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
87 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
88 EFI_LBA FtwSpareLba
; // Start LBA of spare block
89 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block that contains working space in its last block.
90 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
91 UINTN FtwWorkSpaceBase
; // Offset into the FtwWorkSpaceLba block.
92 UINTN FtwWorkSpaceSize
; // Size of working space range that stores write record.
93 UINT8
*FtwWorkSpace
; // Point to Work Space in memory buffer
95 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
96 // Allocated with EFI_FTW_LITE_DEVICE.
98 } EFI_FTW_LITE_DEVICE
;
100 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
103 // Driver entry point
106 This function is the entry point of the Fault Tolerant Write driver.
109 @param ImageHandle A handle for the image that is initializing
111 @param SystemTable A pointer to the EFI system table
113 @retval EFI_SUCCESS FTW has finished the initialization
114 @retval EFI_ABORTED FTW initialization error
120 IN EFI_HANDLE ImageHandle
,
121 IN EFI_SYSTEM_TABLE
*SystemTable
125 // Fault Tolerant Write Protocol API
128 Starts a target block update. This function will record data about write
129 in fault tolerant storage and will complete the write in a recoverable
130 manner, ensuring at all times that either the original contents or
131 the modified contents are available.
134 @param This Calling context
135 @param FvbHandle The handle of FVB protocol that provides services for
136 reading, writing, and erasing the target block.
137 @param Lba The logical block address of the target block.
138 @param Offset The offset within the target block to place the data.
139 @param NumBytes The number of bytes to write to the target block.
140 @param Buffer The data to write.
142 @retval EFI_SUCCESS The function completed successfully
143 @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not
145 @retval EFI_ACCESS_DENIED No writes have been allocated.
146 @retval EFI_NOT_FOUND Cannot find FVB by handle.
147 @retval EFI_OUT_OF_RESOURCES Cannot allocate memory.
148 @retval EFI_ABORTED The function could not complete successfully.
154 IN EFI_FTW_LITE_PROTOCOL
*This
,
155 IN EFI_HANDLE FvbHandle
,
158 IN OUT UINTN
*NumBytes
,
163 // Internal functions
166 Restarts a previously interrupted write. The caller must provide the
167 block protocol needed to complete the interrupted write.
170 @param FtwLiteDevice The private data of FTW_LITE driver
171 FvbHandle - The handle of FVB protocol that provides services for
172 reading, writing, and erasing the target block.
174 @retval EFI_SUCCESS The function completed successfully
175 @retval EFI_ACCESS_DENIED No pending writes exist
176 @retval EFI_NOT_FOUND FVB protocol not found by the handle
177 @retval EFI_ABORTED The function could not complete successfully
182 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
186 Aborts all previous allocated writes.
189 @param FtwLiteDevice The private data of FTW_LITE driver
191 @retval EFI_SUCCESS The function completed successfully
192 @retval EFI_ABORTED The function could not complete successfully.
193 @retval EFI_NOT_FOUND No allocated writes exist.
198 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
203 Write a record with fault tolerant mannaer.
204 Since the content has already backuped in spare block, the write is
205 guaranteed to be completed with fault tolerant manner.
208 @param FtwLiteDevice The private data of FTW_LITE driver
209 @param Fvb The FVB protocol that provides services for
210 reading, writing, and erasing the target block.
212 @retval EFI_SUCCESS The function completed successfully
213 @retval EFI_ABORTED The function could not complete successfully
218 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
219 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
223 To erase the block with the spare block size.
226 @param FtwLiteDevice Calling context
227 @param FvBlock FVB Protocol interface
228 @param Lba Lba of the firmware block
230 @retval EFI_SUCCESS Block LBA is Erased successfully
231 @retval Others Error occurs
236 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
237 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
246 @param FtwLiteDevice Calling context
248 @retval EFI_SUCCESS The erase request was successfully
251 @retval EFI_ACCESS_DENIED The firmware volume is in the
253 @retval EFI_DEVICE_ERROR The block device is not functioning
254 correctly and could not be written.
255 The firmware device may have been
257 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
258 in the variable argument list do
259 not exist in the firmware volume.
264 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
268 Retrive the proper FVB protocol interface by HANDLE.
271 @param FvBlockHandle The handle of FVB protocol that provides services for
272 reading, writing, and erasing the target block.
273 @param FvBlock The interface of FVB protocol
275 @retval EFI_SUCCESS The function completed successfully
276 @retval EFI_ABORTED The function could not complete successfully
281 IN EFI_HANDLE FvBlockHandle
,
282 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
287 Get firmware block by address.
290 @param Address Address specified the block
291 @param FvBlock The block caller wanted
293 @retval EFI_SUCCESS The protocol instance if found.
294 @retval EFI_NOT_FOUND Block not found
299 IN EFI_PHYSICAL_ADDRESS Address
,
300 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
305 Is it in working block?
308 @param FtwLiteDevice Calling context
309 @param FvBlock Fvb protocol instance
310 @param Lba The block specified
312 @return A BOOLEAN value indicating in working block or not.
317 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
318 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
323 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
324 Spare block is accessed by FTW backup FVB protocol interface. LBA is
325 FtwLiteDevice->FtwSpareLba.
326 Target block is accessed by FvBlock protocol interface. LBA is Lba.
329 @param FtwLiteDevice The private data of FTW_LITE driver
330 @param FvBlock FVB Protocol interface to access target block
331 @param Lba Lba of the target block
333 @retval EFI_SUCCESS Spare block content is copied to target block
334 @retval EFI_INVALID_PARAMETER Input parameter error
335 @retval EFI_OUT_OF_RESOURCES Allocate memory error
336 @retval EFI_ABORTED The function could not complete successfully
340 FlushSpareBlockToTargetBlock (
341 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
342 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
347 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
348 Spare block is accessed by FTW backup FVB protocol interface. LBA is
349 FtwLiteDevice->FtwSpareLba.
350 Working block is accessed by FTW working FVB protocol interface. LBA is
351 FtwLiteDevice->FtwWorkBlockLba.
354 @param FtwLiteDevice The private data of FTW_LITE driver
356 @retval EFI_SUCCESS Spare block content is copied to target block
357 @retval EFI_OUT_OF_RESOURCES Allocate memory error
358 @retval EFI_ABORTED The function could not complete successfully
360 Since the working block header is important when FTW initializes, the
361 state of the operation should be handled carefully. The Crc value is
362 calculated without STATE element.
366 FlushSpareBlockToWorkingBlock (
367 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
371 Update a bit of state on a block device. The location of the bit is
372 calculated by the (Lba, Offset, bit). Here bit is determined by the
373 the name of a certain bit.
376 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock
377 @param Lba Lba of a block
378 @param Offset Offset on the Lba
379 @param NewBit New value that will override the old value if it can be change
381 @retval EFI_SUCCESS A state bit has been updated successfully
382 @retval Others Access block device error.
384 Assume all bits of State are inside the same BYTE.
385 @retval EFI_ABORTED Read block fail
390 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
397 Get the last Write record pointer.
398 The last record is the record whose 'complete' state hasn't been set.
399 After all, this header may be a EMPTY header entry for next Allocate.
402 @param FtwLiteDevice Private data of this driver
403 @param FtwLastRecord Pointer to retrieve the last write record
405 @retval EFI_SUCCESS Get the last write record successfully
406 @retval EFI_ABORTED The FTW work space is damaged
411 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
412 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
417 Check whether a flash buffer is erased.
420 @param Polarity All 1 or all 0
421 @param Buffer Buffer to check
422 @param BufferSize Size of the buffer
424 @return A BOOLEAN value indicating erased or not.
428 IsErasedFlashBuffer (
435 Initialize a work space when there is no work space.
438 @param WorkingHeader Pointer of working block header
440 @retval EFI_SUCCESS The function completed successfully
441 @retval EFI_ABORTED The function could not complete successfully.
445 InitWorkSpaceHeader (
446 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
450 Read from working block to refresh the work space in memory.
453 @param FtwLiteDevice Point to private data of FTW driver
455 @retval EFI_SUCCESS The function completed successfully
456 @retval EFI_ABORTED The function could not complete successfully.
461 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
465 Check to see if it is a valid work space.
468 @param WorkingHeader Pointer of working block header
470 @retval EFI_SUCCESS The function completed successfully
471 @retval EFI_ABORTED The function could not complete successfully.
476 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
480 Reclaim the work space on the working block.
483 @param FtwLiteDevice Point to private data of FTW driver
484 @param PreserveRecord Whether to preserve the working record is needed
486 @retval EFI_SUCCESS The function completed successfully
487 @retval EFI_OUT_OF_RESOURCES Allocate memory error
488 @retval EFI_ABORTED The function could not complete successfully
492 FtwReclaimWorkSpace (
493 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
494 IN BOOLEAN PreserveRecord