1 /** @file 2 3 The internal header file includes the common header files, defines 4 internal structure and functions used by Ftw module. 5 6 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> 7 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 11 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. 14 15 **/ 16 17 #ifndef _EFI_FAULT_TOLERANT_WRITE_H_ 18 #define _EFI_FAULT_TOLERANT_WRITE_H_ 19 20 #include <PiDxe.h> 21 22 #include <Guid/SystemNvDataGuid.h> 23 #include <Guid/ZeroGuid.h> 24 #include <Protocol/FaultTolerantWrite.h> 25 #include <Protocol/FirmwareVolumeBlock.h> 26 #include <Protocol/SwapAddressRange.h> 27 28 #include <Library/PcdLib.h> 29 #include <Library/DebugLib.h> 30 #include <Library/UefiLib.h> 31 #include <Library/UefiDriverEntryPoint.h> 32 #include <Library/BaseMemoryLib.h> 33 #include <Library/MemoryAllocationLib.h> 34 #include <Library/UefiBootServicesTableLib.h> 35 #include <Library/ReportStatusCodeLib.h> 36 37 // 38 // Flash erase polarity is 1 39 // 40 #define FTW_ERASE_POLARITY 1 41 42 #define FTW_ERASED_BYTE ((UINT8) (255)) 43 #define FTW_POLARITY_REVERT ((UINT8) (255)) 44 45 #define HEADER_ALLOCATED 0x1 46 #define WRITES_ALLOCATED 0x2 47 #define WRITES_COMPLETED 0x4 48 49 #define BOOT_BLOCK_UPDATE 0x1 50 #define SPARE_COMPLETED 0x2 51 #define DEST_COMPLETED 0x4 52 53 #define FTW_BLOCKS(Length, BlockSize) ((UINTN) ((Length) / (BlockSize) + (((Length) & ((BlockSize) - 1)) ? 1 : 0))) 54 55 #define FTW_DEVICE_SIGNATURE SIGNATURE_32 ('F', 'T', 'W', 'D') 56 57 // 58 // EFI Fault tolerant protocol private data structure 59 // 60 typedef struct { 61 UINTN Signature; 62 EFI_HANDLE Handle; 63 EFI_FAULT_TOLERANT_WRITE_PROTOCOL FtwInstance; 64 EFI_PHYSICAL_ADDRESS WorkSpaceAddress; // Base address of working space range in flash. 65 EFI_PHYSICAL_ADDRESS SpareAreaAddress; // Base address of spare range in flash. 66 UINTN WorkSpaceLength; // Size of working space range in flash. 67 UINTN NumberOfWorkSpaceBlock; // Number of the blocks in work block for work space. 68 UINTN WorkBlockSize; // Block size in bytes of the work blocks in flash 69 UINTN SpareAreaLength; // Size of spare range in flash. 70 UINTN NumberOfSpareBlock; // Number of the blocks in spare block. 71 UINTN SpareBlockSize; // Block size in bytes of the spare blocks in flash 72 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;// Pointer to Working Space Header in memory buffer 73 EFI_FAULT_TOLERANT_WRITE_HEADER *FtwLastWriteHeader;// Pointer to last record header in memory buffer 74 EFI_FAULT_TOLERANT_WRITE_RECORD *FtwLastWriteRecord;// Pointer to last record in memory buffer 75 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwFvBlock; // FVB of working block 76 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwBackupFvb; // FVB of spare block 77 EFI_LBA FtwSpareLba; // Start LBA of spare block 78 EFI_LBA FtwWorkBlockLba; // Start LBA of working block that contains working space in its last block. 79 UINTN NumberOfWorkBlock; // Number of the blocks in work block. 80 EFI_LBA FtwWorkSpaceLba; // Start LBA of working space 81 UINTN FtwWorkSpaceBase; // Offset into the FtwWorkSpaceLba block. 82 UINTN FtwWorkSpaceSize; // Size of working space range that stores write record. 83 EFI_LBA FtwWorkSpaceLbaInSpare; // Start LBA of working space in spare block. 84 UINTN FtwWorkSpaceBaseInSpare;// Offset into the FtwWorkSpaceLbaInSpare block. 85 UINT8 *FtwWorkSpace; // Point to Work Space in memory buffer 86 // 87 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE], 88 // Allocated with EFI_FTW_DEVICE. 89 // 90 } EFI_FTW_DEVICE; 91 92 #define FTW_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_DEVICE, FtwInstance, FTW_DEVICE_SIGNATURE) 93 94 // 95 // Driver entry point 96 // 97 /** 98 This function is the entry point of the Fault Tolerant Write driver. 99 100 @param ImageHandle A handle for the image that is initializing this driver 101 @param SystemTable A pointer to the EFI system table 102 103 @return EFI_SUCCESS FTW has finished the initialization 104 @retval EFI_NOT_FOUND Locate FVB protocol error 105 @retval EFI_OUT_OF_RESOURCES Allocate memory error 106 @retval EFI_VOLUME_CORRUPTED Firmware volume is error 107 @retval EFI_ABORTED FTW initialization error 108 109 **/ 110 EFI_STATUS 111 EFIAPI 112 InitializeFaultTolerantWrite ( 113 IN EFI_HANDLE ImageHandle, 114 IN EFI_SYSTEM_TABLE *SystemTable 115 ); 116 117 // 118 // Fault Tolerant Write Protocol API 119 // 120 121 /** 122 Query the largest block that may be updated in a fault tolerant manner. 123 124 125 @param This Indicates a pointer to the calling context. 126 @param BlockSize A pointer to a caller allocated UINTN that is updated to 127 indicate the size of the largest block that can be updated. 128 129 @return EFI_SUCCESS The function completed successfully 130 131 **/ 132 EFI_STATUS 133 EFIAPI 134 FtwGetMaxBlockSize ( 135 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This, 136 OUT UINTN *BlockSize 137 ); 138 139 /** 140 Allocates space for the protocol to maintain information about writes. 141 Since writes must be completed in a fault tolerant manner and multiple 142 updates will require more resources to be successful, this function 143 enables the protocol to ensure that enough space exists to track 144 information about the upcoming writes. 145 146 All writes must be completed or aborted before another fault tolerant write can occur. 147 148 @param This Indicates a pointer to the calling context. 149 @param CallerId The GUID identifying the write. 150 @param PrivateDataSize The size of the caller's private data 151 that must be recorded for each write. 152 @param NumberOfWrites The number of fault tolerant block writes 153 that will need to occur. 154 155 @return EFI_SUCCESS The function completed successfully 156 @retval EFI_ABORTED The function could not complete successfully. 157 @retval EFI_ACCESS_DENIED All allocated writes have not been completed. 158 159 **/ 160 EFI_STATUS 161 EFIAPI 162 FtwAllocate ( 163 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This, 164 IN EFI_GUID *CallerId, 165 IN UINTN PrivateDataSize, 166 IN UINTN NumberOfWrites 167 ); 168 169 /** 170 Starts a target block update. This function will record data about write 171 in fault tolerant storage and will complete the write in a recoverable 172 manner, ensuring at all times that either the original contents or 173 the modified contents are available. 174 175 176 @param This Calling context 177 @param Lba The logical block address of the target block. 178 @param Offset The offset within the target block to place the data. 179 @param Length The number of bytes to write to the target block. 180 @param PrivateData A pointer to private data that the caller requires to 181 complete any pending writes in the event of a fault. 182 @param FvBlockHandle The handle of FVB protocol that provides services for 183 reading, writing, and erasing the target block. 184 @param Buffer The data to write. 185 186 @retval EFI_SUCCESS The function completed successfully 187 @retval EFI_ABORTED The function could not complete successfully. 188 @retval EFI_BAD_BUFFER_SIZE The input data can't fit within the spare block. 189 Offset + *NumBytes > SpareAreaLength. 190 @retval EFI_ACCESS_DENIED No writes have been allocated. 191 @retval EFI_OUT_OF_RESOURCES Cannot allocate enough memory resource. 192 @retval EFI_NOT_FOUND Cannot find FVB protocol by handle. 193 194 **/ 195 EFI_STATUS 196 EFIAPI 197 FtwWrite ( 198 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This, 199 IN EFI_LBA Lba, 200 IN UINTN Offset, 201 IN UINTN Length, 202 IN VOID *PrivateData, 203 IN EFI_HANDLE FvBlockHandle, 204 IN VOID *Buffer 205 ); 206 207 /** 208 Restarts a previously interrupted write. The caller must provide the 209 block protocol needed to complete the interrupted write. 210 211 @param This Calling context. 212 @param FvBlockHandle The handle of FVB protocol that provides services for 213 reading, writing, and erasing the target block. 214 215 @retval EFI_SUCCESS The function completed successfully 216 @retval EFI_ACCESS_DENIED No pending writes exist 217 @retval EFI_NOT_FOUND FVB protocol not found by the handle 218 @retval EFI_ABORTED The function could not complete successfully 219 220 **/ 221 EFI_STATUS 222 EFIAPI 223 FtwRestart ( 224 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This, 225 IN EFI_HANDLE FvBlockHandle 226 ); 227 228 /** 229 Aborts all previous allocated writes. 230 231 @param This Calling context 232 233 @retval EFI_SUCCESS The function completed successfully 234 @retval EFI_ABORTED The function could not complete successfully. 235 @retval EFI_NOT_FOUND No allocated writes exist. 236 237 **/ 238 EFI_STATUS 239 EFIAPI 240 FtwAbort ( 241 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This 242 ); 243 244 /** 245 Starts a target block update. This records information about the write 246 in fault tolerant storage and will complete the write in a recoverable 247 manner, ensuring at all times that either the original contents or 248 the modified contents are available. 249 250 @param This Indicates a pointer to the calling context. 251 @param CallerId The GUID identifying the last write. 252 @param Lba The logical block address of the last write. 253 @param Offset The offset within the block of the last write. 254 @param Length The length of the last write. 255 @param PrivateDataSize bytes from the private data 256 stored for this write. 257 @param PrivateData A pointer to a buffer. The function will copy 258 @param Complete A Boolean value with TRUE indicating 259 that the write was completed. 260 261 @retval EFI_SUCCESS The function completed successfully 262 @retval EFI_ABORTED The function could not complete successfully 263 @retval EFI_NOT_FOUND No allocated writes exist 264 @retval EFI_BUFFER_TOO_SMALL Input buffer is not larget enough 265 266 **/ 267 EFI_STATUS 268 EFIAPI 269 FtwGetLastWrite ( 270 IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL *This, 271 OUT EFI_GUID *CallerId, 272 OUT EFI_LBA *Lba, 273 OUT UINTN *Offset, 274 OUT UINTN *Length, 275 IN OUT UINTN *PrivateDataSize, 276 OUT VOID *PrivateData, 277 OUT BOOLEAN *Complete 278 ); 279 280 /** 281 Erase spare block. 282 283 @param FtwDevice The private data of FTW driver 284 285 @retval EFI_SUCCESS The erase request was successfully completed. 286 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. 287 @retval EFI_DEVICE_ERROR The block device is not functioning 288 correctly and could not be written. 289 The firmware device may have been 290 partially erased. 291 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed 292 in the variable argument list do 293 not exist in the firmware volume. 294 295 296 **/ 297 EFI_STATUS 298 FtwEraseSpareBlock ( 299 IN EFI_FTW_DEVICE *FtwDevice 300 ); 301 302 /** 303 Retrieve the proper FVB protocol interface by HANDLE. 304 305 306 @param FvBlockHandle The handle of FVB protocol that provides services for 307 reading, writing, and erasing the target block. 308 @param FvBlock The interface of FVB protocol 309 310 @retval EFI_SUCCESS The function completed successfully 311 @retval EFI_ABORTED The function could not complete successfully 312 313 **/ 314 EFI_STATUS 315 FtwGetFvbByHandle ( 316 IN EFI_HANDLE FvBlockHandle, 317 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock 318 ); 319 320 /** 321 322 Is it in working block? 323 324 @param FtwDevice The private data of FTW driver 325 @param FvBlock Fvb protocol instance 326 @param Lba The block specified 327 328 @return A BOOLEAN value indicating in working block or not. 329 330 **/ 331 BOOLEAN 332 IsWorkingBlock ( 333 EFI_FTW_DEVICE *FtwDevice, 334 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, 335 EFI_LBA Lba 336 ); 337 338 /** 339 340 Is it in boot block? 341 342 @param FtwDevice The private data of FTW driver 343 @param FvBlock Fvb protocol instance 344 345 @return A BOOLEAN value indicating in boot block or not. 346 347 **/ 348 BOOLEAN 349 IsBootBlock ( 350 EFI_FTW_DEVICE *FtwDevice, 351 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock 352 ); 353 354 /** 355 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE. 356 Spare block is accessed by FTW backup FVB protocol interface. 357 Target block is accessed by FvBlock protocol interface. 358 359 360 @param FtwDevice The private data of FTW driver 361 @param FvBlock FVB Protocol interface to access target block 362 @param Lba Lba of the target block 363 @param BlockSize The size of the block 364 @param NumberOfBlocks The number of consecutive blocks starting with Lba 365 366 @retval EFI_SUCCESS Spare block content is copied to target block 367 @retval EFI_INVALID_PARAMETER Input parameter error 368 @retval EFI_OUT_OF_RESOURCES Allocate memory error 369 @retval EFI_ABORTED The function could not complete successfully 370 371 **/ 372 EFI_STATUS 373 FlushSpareBlockToTargetBlock ( 374 EFI_FTW_DEVICE *FtwDevice, 375 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, 376 EFI_LBA Lba, 377 UINTN BlockSize, 378 UINTN NumberOfBlocks 379 ); 380 381 /** 382 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. 383 Spare block is accessed by FTW backup FVB protocol interface. LBA is 384 FtwDevice->FtwSpareLba. 385 Working block is accessed by FTW working FVB protocol interface. LBA is 386 FtwDevice->FtwWorkBlockLba. 387 388 Since the working block header is important when FTW initializes, the 389 state of the operation should be handled carefully. The Crc value is 390 calculated without STATE element. 391 392 @param FtwDevice The private data of FTW driver 393 394 @retval EFI_SUCCESS Spare block content is copied to target block 395 @retval EFI_OUT_OF_RESOURCES Allocate memory error 396 @retval EFI_ABORTED The function could not complete successfully 397 398 **/ 399 EFI_STATUS 400 FlushSpareBlockToWorkingBlock ( 401 EFI_FTW_DEVICE *FtwDevice 402 ); 403 404 /** 405 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. 406 Spare block is accessed by FTW working FVB protocol interface. 407 Target block is accessed by FvBlock protocol interface. 408 409 FTW will do extra work on boot block update. 410 FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL, 411 which is produced by a chipset driver. 412 FTW updating boot block steps may be: 413 1. GetRangeLocation(), if the Range is inside the boot block, FTW know 414 that boot block will be update. It shall add a FLAG in the working block. 415 2. When spare block is ready, 416 3. SetSwapState(SWAPPED) 417 4. erasing boot block, 418 5. programming boot block until the boot block is ok. 419 6. SetSwapState(UNSWAPPED) 420 FTW shall not allow to update boot block when battery state is error. 421 422 @param FtwDevice The private data of FTW driver 423 424 @retval EFI_SUCCESS Spare block content is copied to boot block 425 @retval EFI_INVALID_PARAMETER Input parameter error 426 @retval EFI_OUT_OF_RESOURCES Allocate memory error 427 @retval EFI_ABORTED The function could not complete successfully 428 429 **/ 430 EFI_STATUS 431 FlushSpareBlockToBootBlock ( 432 EFI_FTW_DEVICE *FtwDevice 433 ); 434 435 /** 436 Update a bit of state on a block device. The location of the bit is 437 calculated by the (Lba, Offset, bit). Here bit is determined by the 438 the name of a certain bit. 439 440 441 @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock 442 @param BlockSize The size of the block 443 @param Lba Lba of a block 444 @param Offset Offset on the Lba 445 @param NewBit New value that will override the old value if it can be change 446 447 @retval EFI_SUCCESS A state bit has been updated successfully 448 @retval Others Access block device error. 449 Notes: 450 Assume all bits of State are inside the same BYTE. 451 @retval EFI_ABORTED Read block fail 452 453 **/ 454 EFI_STATUS 455 FtwUpdateFvState ( 456 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, 457 IN UINTN BlockSize, 458 IN EFI_LBA Lba, 459 IN UINTN Offset, 460 IN UINT8 NewBit 461 ); 462 463 /** 464 Get the last Write Header pointer. 465 The last write header is the header whose 'complete' state hasn't been set. 466 After all, this header may be a EMPTY header entry for next Allocate. 467 468 469 @param FtwWorkSpaceHeader Pointer of the working block header 470 @param FtwWorkSpaceSize Size of the work space 471 @param FtwWriteHeader Pointer to retrieve the last write header 472 473 @retval EFI_SUCCESS Get the last write record successfully 474 @retval EFI_ABORTED The FTW work space is damaged 475 476 **/ 477 EFI_STATUS 478 FtwGetLastWriteHeader ( 479 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader, 480 IN UINTN FtwWorkSpaceSize, 481 OUT EFI_FAULT_TOLERANT_WRITE_HEADER **FtwWriteHeader 482 ); 483 484 /** 485 Get the last Write Record pointer. The last write Record is the Record 486 whose DestinationCompleted state hasn't been set. After all, this Record 487 may be a EMPTY record entry for next write. 488 489 490 @param FtwWriteHeader Pointer to the write record header 491 @param FtwWriteRecord Pointer to retrieve the last write record 492 493 @retval EFI_SUCCESS Get the last write record successfully 494 @retval EFI_ABORTED The FTW work space is damaged 495 496 **/ 497 EFI_STATUS 498 FtwGetLastWriteRecord ( 499 IN EFI_FAULT_TOLERANT_WRITE_HEADER *FtwWriteHeader, 500 OUT EFI_FAULT_TOLERANT_WRITE_RECORD **FtwWriteRecord 501 ); 502 503 /** 504 To check if FtwRecord is the first record of FtwHeader. 505 506 @param FtwHeader Pointer to the write record header 507 @param FtwRecord Pointer to the write record 508 509 @retval TRUE FtwRecord is the first Record of the FtwHeader 510 @retval FALSE FtwRecord is not the first Record of the FtwHeader 511 512 **/ 513 BOOLEAN 514 IsFirstRecordOfWrites ( 515 IN EFI_FAULT_TOLERANT_WRITE_HEADER *FtwHeader, 516 IN EFI_FAULT_TOLERANT_WRITE_RECORD *FtwRecord 517 ); 518 519 /** 520 To check if FtwRecord is the last record of FtwHeader. Because the 521 FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be 522 determined if it is the last record of FtwHeader. 523 524 @param FtwHeader Pointer to the write record header 525 @param FtwRecord Pointer to the write record 526 527 @retval TRUE FtwRecord is the last Record of the FtwHeader 528 @retval FALSE FtwRecord is not the last Record of the FtwHeader 529 530 **/ 531 BOOLEAN 532 IsLastRecordOfWrites ( 533 IN EFI_FAULT_TOLERANT_WRITE_HEADER *FtwHeader, 534 IN EFI_FAULT_TOLERANT_WRITE_RECORD *FtwRecord 535 ); 536 537 /** 538 To check if FtwRecord is the first record of FtwHeader. 539 540 @param FtwHeader Pointer to the write record header 541 @param FtwRecord Pointer to retrieve the previous write record 542 543 @retval EFI_ACCESS_DENIED Input record is the first record, no previous record is return. 544 @retval EFI_SUCCESS The previous write record is found. 545 546 **/ 547 EFI_STATUS 548 GetPreviousRecordOfWrites ( 549 IN EFI_FAULT_TOLERANT_WRITE_HEADER *FtwHeader, 550 IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD **FtwRecord 551 ); 552 553 /** 554 555 Check whether a flash buffer is erased. 556 557 @param Buffer Buffer to check 558 @param BufferSize Size of the buffer 559 560 @return A BOOLEAN value indicating erased or not. 561 562 **/ 563 BOOLEAN 564 IsErasedFlashBuffer ( 565 IN UINT8 *Buffer, 566 IN UINTN BufferSize 567 ); 568 /** 569 Initialize a work space when there is no work space. 570 571 @param WorkingHeader Pointer of working block header 572 573 @retval EFI_SUCCESS The function completed successfully 574 @retval EFI_ABORTED The function could not complete successfully. 575 576 **/ 577 EFI_STATUS 578 InitWorkSpaceHeader ( 579 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader 580 ); 581 /** 582 Read from working block to refresh the work space in memory. 583 584 @param FtwDevice Point to private data of FTW driver 585 586 @retval EFI_SUCCESS The function completed successfully 587 @retval EFI_ABORTED The function could not complete successfully. 588 589 **/ 590 EFI_STATUS 591 WorkSpaceRefresh ( 592 IN EFI_FTW_DEVICE *FtwDevice 593 ); 594 /** 595 Check to see if it is a valid work space. 596 597 598 @param WorkingHeader Pointer of working block header 599 600 @retval EFI_SUCCESS The function completed successfully 601 @retval EFI_ABORTED The function could not complete successfully. 602 603 **/ 604 BOOLEAN 605 IsValidWorkSpace ( 606 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader 607 ); 608 /** 609 Reclaim the work space on the working block. 610 611 @param FtwDevice Point to private data of FTW driver 612 @param PreserveRecord Whether to preserve the working record is needed 613 614 @retval EFI_SUCCESS The function completed successfully 615 @retval EFI_OUT_OF_RESOURCES Allocate memory error 616 @retval EFI_ABORTED The function could not complete successfully 617 618 **/ 619 EFI_STATUS 620 FtwReclaimWorkSpace ( 621 IN EFI_FTW_DEVICE *FtwDevice, 622 IN BOOLEAN PreserveRecord 623 ); 624 625 /** 626 627 Get firmware volume block by address. 628 629 630 @param Address Address specified the block 631 @param FvBlock The block caller wanted 632 633 @retval EFI_SUCCESS The protocol instance if found. 634 @retval EFI_NOT_FOUND Block not found 635 636 **/ 637 EFI_HANDLE 638 GetFvbByAddress ( 639 IN EFI_PHYSICAL_ADDRESS Address, 640 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock 641 ); 642 643 /** 644 Retrieve the proper Swap Address Range protocol interface. 645 646 @param[out] SarProtocol The interface of SAR protocol 647 648 @retval EFI_SUCCESS The SAR protocol instance was found and returned in SarProtocol. 649 @retval EFI_NOT_FOUND The SAR protocol instance was not found. 650 @retval EFI_INVALID_PARAMETER SarProtocol is NULL. 651 652 **/ 653 EFI_STATUS 654 FtwGetSarProtocol ( 655 OUT VOID **SarProtocol 656 ); 657 658 /** 659 Function returns an array of handles that support the FVB protocol 660 in a buffer allocated from pool. 661 662 @param[out] NumberHandles The number of handles returned in Buffer. 663 @param[out] Buffer A pointer to the buffer to return the requested 664 array of handles that support FVB protocol. 665 666 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of 667 handles in Buffer was returned in NumberHandles. 668 @retval EFI_NOT_FOUND No FVB handle was found. 669 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results. 670 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL. 671 672 **/ 673 EFI_STATUS 674 GetFvbCountAndBuffer ( 675 OUT UINTN *NumberHandles, 676 OUT EFI_HANDLE **Buffer 677 ); 678 679 680 /** 681 Allocate private data for FTW driver and initialize it. 682 683 @param[out] FtwData Pointer to the FTW device structure 684 685 @retval EFI_SUCCESS Initialize the FTW device successfully. 686 @retval EFI_OUT_OF_RESOURCES Allocate memory error 687 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist 688 689 **/ 690 EFI_STATUS 691 InitFtwDevice ( 692 OUT EFI_FTW_DEVICE **FtwData 693 ); 694 695 696 /** 697 Initialization for Fault Tolerant Write is done in this handler. 698 699 @param[in, out] FtwDevice Pointer to the FTW device structure 700 701 @retval EFI_SUCCESS Initialize the FTW protocol successfully. 702 @retval EFI_NOT_FOUND No proper FVB protocol was found. 703 704 **/ 705 EFI_STATUS 706 InitFtwProtocol ( 707 IN OUT EFI_FTW_DEVICE *FtwDevice 708 ); 709 710 /** 711 Initialize a local work space header. 712 713 Since Signature and WriteQueueSize have been known, Crc can be calculated out, 714 then the work space header will be fixed. 715 **/ 716 VOID 717 InitializeLocalWorkSpaceHeader ( 718 VOID 719 ); 720 721 /** 722 Read work space data from work block or spare block. 723 724 @param FvBlock FVB Protocol interface to access the block. 725 @param BlockSize The size of the block. 726 @param Lba Lba of the block. 727 @param Offset The offset within the block. 728 @param Length The number of bytes to read from the block. 729 @param Buffer The data is read. 730 731 @retval EFI_SUCCESS The function completed successfully. 732 @retval EFI_ABORTED The function could not complete successfully. 733 734 **/ 735 EFI_STATUS 736 ReadWorkSpaceData ( 737 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, 738 IN UINTN BlockSize, 739 IN EFI_LBA Lba, 740 IN UINTN Offset, 741 IN UINTN Length, 742 OUT UINT8 *Buffer 743 ); 744 745 /** 746 Write data to work block. 747 748 @param FvBlock FVB Protocol interface to access the block. 749 @param BlockSize The size of the block. 750 @param Lba Lba of the block. 751 @param Offset The offset within the block to place the data. 752 @param Length The number of bytes to write to the block. 753 @param Buffer The data to write. 754 755 @retval EFI_SUCCESS The function completed successfully. 756 @retval EFI_ABORTED The function could not complete successfully. 757 758 **/ 759 EFI_STATUS 760 WriteWorkSpaceData ( 761 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, 762 IN UINTN BlockSize, 763 IN EFI_LBA Lba, 764 IN UINTN Offset, 765 IN UINTN Length, 766 IN UINT8 *Buffer 767 ); 768 769 #endif 770