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>
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 EFI_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_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
99 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
100 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
103 // EFI Fault tolerant protocol private data structure
108 EFI_FTW_LITE_PROTOCOL FtwLiteInstance
;
109 EFI_PHYSICAL_ADDRESS WorkSpaceAddress
;
110 UINTN WorkSpaceLength
;
111 EFI_PHYSICAL_ADDRESS SpareAreaAddress
;
112 UINTN SpareAreaLength
;
113 UINTN NumberOfSpareBlock
; // Number of the blocks in spare block
114 UINTN SizeOfSpareBlock
; // Block size in bytes of the blocks in spare block
115 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*FtwWorkSpaceHeader
;
116 EFI_FTW_LITE_RECORD
*FtwLastRecord
;
117 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwFvBlock
; // FVB of working block
118 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FtwBackupFvb
; // FVB of spare block
120 EFI_LBA FtwWorkBlockLba
; // Start LBA of working block
121 EFI_LBA FtwWorkSpaceLba
; // Start LBA of working space
122 UINTN FtwWorkSpaceBase
; // Offset from LBA start addr
123 UINTN FtwWorkSpaceSize
;
126 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
127 // Allocated with EFI_FTW_LITE_DEVICE.
129 } EFI_FTW_LITE_DEVICE
;
131 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
134 // Driver entry point
139 IN EFI_HANDLE ImageHandle
,
140 IN EFI_SYSTEM_TABLE
*SystemTable
145 This function is the entry point of the Fault Tolerant Write driver.
148 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
150 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
153 EFI_SUCCESS - FTW has finished the initialization
154 EFI_ABORTED - FTW initialization error
160 // Fault Tolerant Write Protocol API
165 IN EFI_FTW_LITE_PROTOCOL
*This
,
166 IN EFI_HANDLE FvbHandle
,
175 Starts a target block update. This function will record data about write
176 in fault tolerant storage and will complete the write in a recoverable
177 manner, ensuring at all times that either the original contents or
178 the modified contents are available.
181 This - Calling context
182 FvbHandle - The handle of FVB protocol that provides services for
183 reading, writing, and erasing the target block.
184 Lba - The logical block address of the target block.
185 Offset - The offset within the target block to place the data.
186 NumBytes - The number of bytes to write to the target block.
187 Buffer - The data to write.
190 EFI_SUCCESS - The function completed successfully
191 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
193 EFI_ACCESS_DENIED - No writes have been allocated.
194 EFI_NOT_FOUND - Cannot find FVB by handle.
195 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
196 EFI_ABORTED - The function could not complete successfully.
202 // Internal functions
206 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
211 Restarts a previously interrupted write. The caller must provide the
212 block protocol needed to complete the interrupted write.
215 FtwLiteDevice - The private data of FTW_LITE driver
216 FvbHandle - The handle of FVB protocol that provides services for
217 reading, writing, and erasing the target block.
220 EFI_SUCCESS - The function completed successfully
221 EFI_ACCESS_DENIED - No pending writes exist
222 EFI_NOT_FOUND - FVB protocol not found by the handle
223 EFI_ABORTED - The function could not complete successfully
230 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
235 Aborts all previous allocated writes.
238 FtwLiteDevice - The private data of FTW_LITE driver
241 EFI_SUCCESS - The function completed successfully
242 EFI_ABORTED - The function could not complete successfully.
243 EFI_NOT_FOUND - No allocated writes exist.
251 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
252 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
257 Write a record with fault tolerant mannaer.
258 Since the content has already backuped in spare block, the write is
259 guaranteed to be completed with fault tolerant manner.
262 FtwLiteDevice - The private data of FTW_LITE driver
263 Fvb - The FVB protocol that provides services for
264 reading, writing, and erasing the target block.
267 EFI_SUCCESS - The function completed successfully
268 EFI_ABORTED - The function could not complete successfully
275 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
276 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
282 To Erase one block. The size is FTW_BLOCK_SIZE
285 FtwLiteDevice - Calling context
286 FvBlock - FVB Protocol interface
287 Lba - Lba of the firmware block
290 EFI_SUCCESS - Block LBA is Erased successfully
291 Others - Error occurs
298 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
308 FtwLiteDevice - Calling context
319 IN EFI_HANDLE FvBlockHandle
,
320 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
325 Retrive the proper FVB protocol interface by HANDLE.
328 FvBlockHandle - The handle of FVB protocol that provides services for
329 reading, writing, and erasing the target block.
330 FvBlock - The interface of FVB protocol
333 EFI_SUCCESS - The function completed successfully
334 EFI_ABORTED - The function could not complete successfully
340 IN EFI_PHYSICAL_ADDRESS Address
,
341 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
347 Get firmware block by address.
351 Address - Address specified the block
352 FvBlock - The block caller wanted
358 EFI_NOT_FOUND - Block not found
365 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
366 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
373 Is it in working block?
377 FtwLiteDevice - Calling context
378 FvBlock - Fvb protocol instance
379 Lba - The block specified
383 In working block or not
390 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
391 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
398 Check whether the block is a boot block.
402 FtwLiteDevice - Calling context
403 FvBlock - Fvb protocol instance
408 Is a boot block or not
414 FlushSpareBlockToTargetBlock (
415 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
416 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
422 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
423 Spare block is accessed by FTW backup FVB protocol interface. LBA is
424 FtwLiteDevice->FtwSpareLba.
425 Target block is accessed by FvBlock protocol interface. LBA is Lba.
428 FtwLiteDevice - The private data of FTW_LITE driver
429 FvBlock - FVB Protocol interface to access target block
430 Lba - Lba of the target block
433 EFI_SUCCESS - Spare block content is copied to target block
434 EFI_INVALID_PARAMETER - Input parameter error
435 EFI_OUT_OF_RESOURCES - Allocate memory error
436 EFI_ABORTED - The function could not complete successfully
442 FlushSpareBlockToWorkingBlock (
443 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
448 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
449 Spare block is accessed by FTW backup FVB protocol interface. LBA is
450 FtwLiteDevice->FtwSpareLba.
451 Working block is accessed by FTW working FVB protocol interface. LBA is
452 FtwLiteDevice->FtwWorkBlockLba.
455 FtwLiteDevice - The private data of FTW_LITE driver
458 EFI_SUCCESS - Spare block content is copied to target block
459 EFI_OUT_OF_RESOURCES - Allocate memory error
460 EFI_ABORTED - The function could not complete successfully
463 Since the working block header is important when FTW initializes, the
464 state of the operation should be handled carefully. The Crc value is
465 calculated without STATE element.
471 FlushSpareBlockToBootBlock (
472 EFI_FTW_LITE_DEVICE
*FtwLiteDevice
477 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
478 Spare block is accessed by FTW backup FVB protocol interface. LBA is
479 FtwLiteDevice->FtwSpareLba.
480 Boot block is accessed by BootFvb protocol interface. LBA is 0.
483 FtwLiteDevice - The private data of FTW_LITE driver
486 EFI_SUCCESS - Spare block content is copied to boot block
487 EFI_INVALID_PARAMETER - Input parameter error
488 EFI_OUT_OF_RESOURCES - Allocate memory error
489 EFI_ABORTED - The function could not complete successfully
498 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvBlock
,
506 Update a bit of state on a block device. The location of the bit is
507 calculated by the (Lba, Offset, bit). Here bit is determined by the
508 the name of a certain bit.
511 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
513 Offset - Offset on the Lba
514 NewBit - New value that will override the old value if it can be change
517 EFI_SUCCESS - A state bit has been updated successfully
518 Others - Access block device error.
521 Assume all bits of State are inside the same BYTE.
523 EFI_ABORTED - Read block fail
529 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
530 OUT EFI_FTW_LITE_RECORD
**FtwLastRecord
535 Get the last Write record pointer.
536 The last record is the record whose 'complete' state hasn't been set.
537 After all, this header may be a EMPTY header entry for next Allocate.
540 FtwLiteDevice - Private data of this driver
541 FtwLastRecord - Pointer to retrieve the last write record
544 EFI_SUCCESS - Get the last write record successfully
545 EFI_ABORTED - The FTW work space is damaged
551 IsErasedFlashBuffer (
560 Check whether a flash buffer is erased.
564 Polarity - All 1 or all 0
565 Buffer - Buffer to check
566 BufferSize - Size of the buffer
576 InitWorkSpaceHeader (
577 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
582 Initialize a work space when there is no work space.
585 WorkingHeader - Pointer of working block header
588 EFI_SUCCESS - The function completed successfully
589 EFI_ABORTED - The function could not complete successfully.
596 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
601 Read from working block to refresh the work space in memory.
604 FtwLiteDevice - Point to private data of FTW driver
607 EFI_SUCCESS - The function completed successfully
608 EFI_ABORTED - The function could not complete successfully.
615 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER
*WorkingHeader
620 Check to see if it is a valid work space.
623 WorkingHeader - Pointer of working block header
626 EFI_SUCCESS - The function completed successfully
627 EFI_ABORTED - The function could not complete successfully.
634 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
,
635 IN OUT UINT8
*BlockBuffer
,
641 Reclaim the work space. Get rid of all the completed write records
642 and write records in the Fault Tolerant work space.
645 FtwLiteDevice - Point to private data of FTW driver
646 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
647 BufferSize - Size of the FtwSpaceBuffer
650 EFI_SUCCESS - The function completed successfully
651 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
652 EFI_ABORTED - The function could not complete successfully.
658 FtwReclaimWorkSpace (
659 IN EFI_FTW_LITE_DEVICE
*FtwLiteDevice
664 Reclaim the work space on the working block.
667 FtwLiteDevice - Point to private data of FTW driver
670 EFI_SUCCESS - The function completed successfully
671 EFI_OUT_OF_RESOURCES - Allocate memory error
672 EFI_ABORTED - The function could not complete successfully