FtwLite.h

   1 /*++
   2
   3 Copyright (c) 2006, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12
  13 Module Name:
  14
  15   FtwLite.h
  16
  17 Abstract:
  18
  19   This is a simple fault tolerant write driver, based on PlatformFd library.
  20   And it only supports write BufferSize <= SpareAreaLength.
  21
  22   This boot service only protocol provides fault tolerant write capability for
  23   block devices.  The protocol has internal non-volatile intermediate storage
  24   of the data and private information. It should be able to recover
  25   automatically from a critical fault, such as power failure.
  26
  27 --*/
  28
  29 #ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_
  30 #define _EFI_FAULT_TOLERANT_WRITE_LITE_H_
  31
  32
  33 #include <PiDxe.h>
  34
  35 #include <Protocol/PciRootBridgeIo.h>
  36 #include <Guid/SystemNvDataGuid.h>
  37 #include <Protocol/FaultTolerantWriteLite.h>
  38 #include <Protocol/FirmwareVolumeBlock.h>
  39
  40 #include <Library/PcdLib.h>
  41 #include <Library/DebugLib.h>
  42 #include <Library/UefiDriverEntryPoint.h>
  43 #include <Library/BaseMemoryLib.h>
  44 #include <Library/MemoryAllocationLib.h>
  45 #include <Library/UefiBootServicesTableLib.h>
  46
  47 #include <WorkingBlockHeader.h>
  48
  49 #define EFI_D_FTW_LITE  EFI_D_ERROR
  50 #define EFI_D_FTW_INFO  EFI_D_INFO
  51
  52 //
  53 // Flash erase polarity is 1
  54 //
  55 #define FTW_ERASE_POLARITY  1
  56
  57 #define FTW_VALID_STATE     0
  58 #define FTW_INVALID_STATE   1
  59
  60 #define FTW_ERASED_BYTE     ((UINT8) (255))
  61 #define FTW_POLARITY_REVERT ((UINT8) (255))
  62
  63 typedef struct {
  64   UINT8         WriteAllocated : 1;
  65   UINT8         SpareCompleted : 1;
  66   UINT8         WriteCompleted : 1;
  67   UINT8         Reserved : 5;
  68 #define WRITE_ALLOCATED 0x1
  69 #define SPARE_COMPLETED 0x2
  70 #define WRITE_COMPLETED 0x4
  71
  72   EFI_DEV_PATH  DevPath;
  73   EFI_LBA       Lba;
  74   UINTN         Offset;
  75   UINTN         NumBytes;
  76   //
  77   // UINTN           SpareAreaOffset;
  78   //
  79 } EFI_FTW_LITE_RECORD;
  80
  81 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
  82
  83 //
  84 // MACRO for Block size.
  85 // Flash Erasing will do in block granularity.
  86 //
  87 #ifdef FV_BLOCK_SIZE
  88 #define FTW_BLOCK_SIZE  FV_BLOCK_SIZE
  89 #else
  90 #define FV_BLOCK_SIZE   0x10000
  91 #define FTW_BLOCK_SIZE  FV_BLOCK_SIZE
  92 #endif
  93 //
  94 // MACRO for FTW WORK SPACE Base & Size
  95 //
  96 #ifdef EFI_FTW_WORKING_OFFSET
  97 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
  98 #else
  99 #define FTW_WORK_SPACE_BASE 0x00E000
 100 #endif
 101
 102 #ifdef EFI_FTW_WORKING_LENGTH
 103 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
 104 #else
 105 #define FTW_WORK_SPACE_SIZE 0x002000
 106 #endif
 107 //
 108 // MACRO for FTW header and record
 109 //
 110 #define FTW_WORKING_QUEUE_SIZE  (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
 111 #define FTW_LITE_RECORD_SIZE    (sizeof (EFI_FTW_LITE_RECORD))
 112 #define WRITE_TOTAL_SIZE        FTW_LITE_RECORD_SIZE
 113
 114 //
 115 // EFI Fault tolerant protocol private data structure
 116 //
 117 typedef struct {
 118   UINTN                                   Signature;
 119   EFI_HANDLE                              Handle;
 120   EFI_FTW_LITE_PROTOCOL                   FtwLiteInstance;
 121   EFI_PHYSICAL_ADDRESS                    WorkSpaceAddress;
 122   UINTN                                   WorkSpaceLength;
 123   EFI_PHYSICAL_ADDRESS                    SpareAreaAddress;
 124   UINTN                                   SpareAreaLength;
 125   UINTN                                   NumberOfSpareBlock; // Number of the blocks in spare block
 126   UINTN                                   SizeOfSpareBlock;   // Block size in bytes of the blocks in spare block
 127   EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;
 128   EFI_FTW_LITE_RECORD                     *FtwLastRecord;
 129   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *FtwFvBlock;        // FVB of working block
 130   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *FtwBackupFvb;      // FVB of spare block
 131   EFI_LBA                                 FtwSpareLba;
 132   EFI_LBA                                 FtwWorkBlockLba;    // Start LBA of working block
 133   EFI_LBA                                 FtwWorkSpaceLba;    // Start LBA of working space
 134   UINTN                                   FtwWorkSpaceBase;   // Offset from LBA start addr
 135   UINTN                                   FtwWorkSpaceSize;
 136   UINT8                                   *FtwWorkSpace;
 137   //
 138   // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
 139   // Allocated with EFI_FTW_LITE_DEVICE.
 140   //
 141 } EFI_FTW_LITE_DEVICE;
 142
 143 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
 144
 145 //
 146 // Driver entry point
 147 //
 148 EFI_STATUS
 149 EFIAPI
 150 InitializeFtwLite (
 151   IN EFI_HANDLE                 ImageHandle,
 152   IN EFI_SYSTEM_TABLE           *SystemTable
 153   )
 154 /*++
 155
 156 Routine Description:
 157     This function is the entry point of the Fault Tolerant Write driver.
 158
 159 Arguments:
 160     ImageHandle   - EFI_HANDLE: A handle for the image that is initializing
 161                     this driver
 162     SystemTable   - EFI_SYSTEM_TABLE: A pointer to the EFI system table
 163
 164 Returns:
 165     EFI_SUCCESS           - FTW has finished the initialization
 166     EFI_ABORTED           - FTW initialization error
 167
 168 --*/
 169 ;
 170
 171 //
 172 // Fault Tolerant Write Protocol API
 173 //
 174 EFI_STATUS
 175 EFIAPI
 176 FtwLiteWrite (
 177   IN EFI_FTW_LITE_PROTOCOL                 *This,
 178   IN EFI_HANDLE                            FvbHandle,
 179   IN EFI_LBA                               Lba,
 180   IN UINTN                                 Offset,
 181   IN UINTN                                 *NumBytes,
 182   IN VOID                                  *Buffer
 183   )
 184 /*++
 185
 186 Routine Description:
 187     Starts a target block update. This function will record data about write
 188     in fault tolerant storage and will complete the write in a recoverable
 189     manner, ensuring at all times that either the original contents or
 190     the modified contents are available.
 191
 192 Arguments:
 193     This             - Calling context
 194     FvbHandle        - The handle of FVB protocol that provides services for
 195                        reading, writing, and erasing the target block.
 196     Lba              - The logical block address of the target block.
 197     Offset           - The offset within the target block to place the data.
 198     NumBytes         - The number of bytes to write to the target block.
 199     Buffer           - The data to write.
 200
 201 Returns:
 202     EFI_SUCCESS          - The function completed successfully
 203     EFI_BAD_BUFFER_SIZE  - The write would span a target block, which is not
 204                            a valid action.
 205     EFI_ACCESS_DENIED    - No writes have been allocated.
 206     EFI_NOT_FOUND        - Cannot find FVB by handle.
 207     EFI_OUT_OF_RESOURCES - Cannot allocate memory.
 208     EFI_ABORTED          - The function could not complete successfully.
 209
 210 --*/
 211 ;
 212
 213 //
 214 // Internal functions
 215 //
 216 EFI_STATUS
 217 FtwRestart (
 218   IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice
 219   )
 220 /*++
 221
 222 Routine Description:
 223     Restarts a previously interrupted write. The caller must provide the
 224     block protocol needed to complete the interrupted write.
 225
 226 Arguments:
 227     FtwLiteDevice       - The private data of FTW_LITE driver
 228     FvbHandle           - The handle of FVB protocol that provides services for
 229                           reading, writing, and erasing the target block.
 230
 231 Returns:
 232     EFI_SUCCESS         - The function completed successfully
 233     EFI_ACCESS_DENIED   - No pending writes exist
 234     EFI_NOT_FOUND       - FVB protocol not found by the handle
 235     EFI_ABORTED         - The function could not complete successfully
 236
 237 --*/
 238 ;
 239
 240 EFI_STATUS
 241 FtwAbort (
 242   IN EFI_FTW_LITE_DEVICE    *FtwLiteDevice
 243   )
 244 /*++
 245
 246 Routine Description:
 247     Aborts all previous allocated writes.
 248
 249 Arguments:
 250     FtwLiteDevice    - The private data of FTW_LITE driver
 251
 252 Returns:
 253     EFI_SUCCESS      - The function completed successfully
 254     EFI_ABORTED      - The function could not complete successfully.
 255     EFI_NOT_FOUND    - No allocated writes exist.
 256
 257 --*/
 258 ;
 259
 260
 261 EFI_STATUS
 262 FtwWriteRecord (
 263   IN EFI_FTW_LITE_DEVICE                   *FtwLiteDevice,
 264   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *Fvb
 265   )
 266 /*++
 267
 268 Routine Description:
 269     Write a record with fault tolerant mannaer.
 270     Since the content has already backuped in spare block, the write is
 271     guaranteed to be completed with fault tolerant manner.
 272
 273 Arguments:
 274     FtwLiteDevice       - The private data of FTW_LITE driver
 275     Fvb                 - The FVB protocol that provides services for
 276                           reading, writing, and erasing the target block.
 277
 278 Returns:
 279     EFI_SUCCESS         - The function completed successfully
 280     EFI_ABORTED         - The function could not complete successfully
 281
 282 --*/
 283 ;
 284
 285 EFI_STATUS
 286 FtwEraseBlock (
 287   IN EFI_FTW_LITE_DEVICE              *FtwLiteDevice,
 288   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,
 289   EFI_LBA                             Lba
 290   )
 291 /*++
 292
 293 Routine Description:
 294     To Erase one block. The size is FTW_BLOCK_SIZE
 295
 296 Arguments:
 297     FtwLiteDevice - Calling context
 298     FvBlock       - FVB Protocol interface
 299     Lba           - Lba of the firmware block
 300
 301 Returns:
 302     EFI_SUCCESS   - Block LBA is Erased successfully
 303     Others        - Error occurs
 304
 305 --*/
 306 ;
 307
 308 EFI_STATUS
 309 FtwEraseSpareBlock (
 310   IN EFI_FTW_LITE_DEVICE   *FtwLiteDevice
 311   )
 312 /*++
 313
 314 Routine Description:
 315
 316   Erase spare block.
 317
 318 Arguments:
 319
 320   FtwLiteDevice - Calling context
 321
 322 Returns:
 323
 324   Status code
 325
 326 --*/
 327 ;
 328
 329 EFI_STATUS
 330 FtwGetFvbByHandle (
 331   IN EFI_HANDLE                           FvBlockHandle,
 332   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 333   )
 334 /*++
 335
 336 Routine Description:
 337     Retrive the proper FVB protocol interface by HANDLE.
 338
 339 Arguments:
 340     FvBlockHandle       - The handle of FVB protocol that provides services for
 341                           reading, writing, and erasing the target block.
 342     FvBlock             - The interface of FVB protocol
 343
 344 Returns:
 345     EFI_SUCCESS         - The function completed successfully
 346     EFI_ABORTED         - The function could not complete successfully
 347 --*/
 348 ;
 349
 350 EFI_STATUS
 351 GetFvbByAddress (
 352   IN  EFI_PHYSICAL_ADDRESS               Address,
 353   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock
 354   )
 355 /*++
 356
 357 Routine Description:
 358
 359   Get firmware block by address.
 360
 361 Arguments:
 362
 363   Address - Address specified the block
 364   FvBlock - The block caller wanted
 365
 366 Returns:
 367
 368   Status code
 369
 370   EFI_NOT_FOUND - Block not found
 371
 372 --*/
 373 ;
 374
 375 BOOLEAN
 376 IsInWorkingBlock (
 377   EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,
 378   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,
 379   EFI_LBA                             Lba
 380   )
 381 /*++
 382
 383 Routine Description:
 384
 385   Is it in working block?
 386
 387 Arguments:
 388
 389   FtwLiteDevice - Calling context
 390   FvBlock       - Fvb protocol instance
 391   Lba           - The block specified
 392
 393 Returns:
 394
 395   In working block or not
 396
 397 --*/
 398 ;
 399
 400 BOOLEAN
 401 IsBootBlock (
 402   EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,
 403   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,
 404   EFI_LBA                             Lba
 405   )
 406 /*++
 407
 408 Routine Description:
 409
 410   Check whether the block is a boot block.
 411
 412 Arguments:
 413
 414   FtwLiteDevice - Calling context
 415   FvBlock       - Fvb protocol instance
 416   Lba           - Lba value
 417
 418 Returns:
 419
 420   Is a boot block or not
 421
 422 --*/
 423 ;
 424
 425 EFI_STATUS
 426 FlushSpareBlockToTargetBlock (
 427   EFI_FTW_LITE_DEVICE                 *FtwLiteDevice,
 428   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,
 429   EFI_LBA                             Lba
 430   )
 431 /*++
 432
 433 Routine Description:
 434     Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
 435     Spare block is accessed by FTW backup FVB protocol interface. LBA is
 436     FtwLiteDevice->FtwSpareLba.
 437     Target block is accessed by FvBlock protocol interface. LBA is Lba.
 438
 439 Arguments:
 440     FtwLiteDevice  - The private data of FTW_LITE driver
 441     FvBlock        - FVB Protocol interface to access target block
 442     Lba            - Lba of the target block
 443
 444 Returns:
 445     EFI_SUCCESS              - Spare block content is copied to target block
 446     EFI_INVALID_PARAMETER    - Input parameter error
 447     EFI_OUT_OF_RESOURCES     - Allocate memory error
 448     EFI_ABORTED              - The function could not complete successfully
 449
 450 --*/
 451 ;
 452
 453 EFI_STATUS
 454 FlushSpareBlockToWorkingBlock (
 455   EFI_FTW_LITE_DEVICE                 *FtwLiteDevice
 456   )
 457 /*++
 458
 459 Routine Description:
 460     Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
 461     Spare block is accessed by FTW backup FVB protocol interface. LBA is
 462     FtwLiteDevice->FtwSpareLba.
 463     Working block is accessed by FTW working FVB protocol interface. LBA is
 464     FtwLiteDevice->FtwWorkBlockLba.
 465
 466 Arguments:
 467     FtwLiteDevice  - The private data of FTW_LITE driver
 468
 469 Returns:
 470     EFI_SUCCESS              - Spare block content is copied to target block
 471     EFI_OUT_OF_RESOURCES     - Allocate memory error
 472     EFI_ABORTED              - The function could not complete successfully
 473
 474 Notes:
 475     Since the working block header is important when FTW initializes, the
 476     state of the operation should be handled carefully. The Crc value is
 477     calculated without STATE element.
 478
 479 --*/
 480 ;
 481
 482 EFI_STATUS
 483 FlushSpareBlockToBootBlock (
 484   EFI_FTW_LITE_DEVICE                 *FtwLiteDevice
 485   )
 486 /*++
 487
 488 Routine Description:
 489     Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
 490     Spare block is accessed by FTW backup FVB protocol interface. LBA is
 491     FtwLiteDevice->FtwSpareLba.
 492     Boot block is accessed by BootFvb protocol interface. LBA is 0.
 493
 494 Arguments:
 495     FtwLiteDevice  - The private data of FTW_LITE driver
 496
 497 Returns:
 498     EFI_SUCCESS              - Spare block content is copied to boot block
 499     EFI_INVALID_PARAMETER    - Input parameter error
 500     EFI_OUT_OF_RESOURCES     - Allocate memory error
 501     EFI_ABORTED              - The function could not complete successfully
 502
 503 Notes:
 504
 505 --*/
 506 ;
 507
 508 EFI_STATUS
 509 FtwUpdateFvState (
 510   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *FvBlock,
 511   IN EFI_LBA                             Lba,
 512   IN UINTN                               Offset,
 513   IN UINT8                               NewBit
 514   )
 515 /*++
 516
 517 Routine Description:
 518     Update a bit of state on a block device. The location of the bit is
 519     calculated by the (Lba, Offset, bit). Here bit is determined by the
 520     the name of a certain bit.
 521
 522 Arguments:
 523     FvBlock    - FVB Protocol interface to access SrcBlock and DestBlock
 524     Lba        - Lba of a block
 525     Offset     - Offset on the Lba
 526     NewBit     - New value that will override the old value if it can be change
 527
 528 Returns:
 529     EFI_SUCCESS   - A state bit has been updated successfully
 530     Others        - Access block device error.
 531
 532 Notes:
 533     Assume all bits of State are inside the same BYTE.
 534
 535     EFI_ABORTED   - Read block fail
 536 --*/
 537 ;
 538
 539 EFI_STATUS
 540 FtwGetLastRecord (
 541   IN  EFI_FTW_LITE_DEVICE  *FtwLiteDevice,
 542   OUT EFI_FTW_LITE_RECORD  **FtwLastRecord
 543   )
 544 /*++
 545
 546 Routine Description:
 547     Get the last Write record pointer.
 548     The last record is the record whose 'complete' state hasn't been set.
 549     After all, this header may be a EMPTY header entry for next Allocate.
 550
 551 Arguments:
 552     FtwLiteDevice   - Private data of this driver
 553     FtwLastRecord   - Pointer to retrieve the last write record
 554
 555 Returns:
 556     EFI_SUCCESS     - Get the last write record successfully
 557     EFI_ABORTED     - The FTW work space is damaged
 558
 559 --*/
 560 ;
 561
 562 BOOLEAN
 563 IsErasedFlashBuffer (
 564   IN BOOLEAN         Polarity,
 565   IN UINT8           *Buffer,
 566   IN UINTN           BufferSize
 567   )
 568 /*++
 569
 570 Routine Description:
 571
 572   Check whether a flash buffer is erased.
 573
 574 Arguments:
 575
 576   Polarity    - All 1 or all 0
 577   Buffer      - Buffer to check
 578   BufferSize  - Size of the buffer
 579
 580 Returns:
 581
 582   Erased or not.
 583
 584 --*/
 585 ;
 586
 587 EFI_STATUS
 588 InitWorkSpaceHeader (
 589   IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader
 590   )
 591 /*++
 592
 593 Routine Description:
 594     Initialize a work space when there is no work space.
 595
 596 Arguments:
 597     WorkingHeader - Pointer of working block header
 598
 599 Returns:
 600     EFI_SUCCESS   - The function completed successfully
 601     EFI_ABORTED   - The function could not complete successfully.
 602
 603 --*/
 604 ;
 605
 606 EFI_STATUS
 607 WorkSpaceRefresh (
 608   IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice
 609   )
 610 /*++
 611
 612 Routine Description:
 613     Read from working block to refresh the work space in memory.
 614
 615 Arguments:
 616     FtwLiteDevice     - Point to private data of FTW driver
 617
 618 Returns:
 619     EFI_SUCCESS   - The function completed successfully
 620     EFI_ABORTED   - The function could not complete successfully.
 621
 622 --*/
 623 ;
 624
 625 BOOLEAN
 626 IsValidWorkSpace (
 627   IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader
 628   )
 629 /*++
 630
 631 Routine Description:
 632     Check to see if it is a valid work space.
 633
 634 Arguments:
 635     WorkingHeader - Pointer of working block header
 636
 637 Returns:
 638     EFI_SUCCESS   - The function completed successfully
 639     EFI_ABORTED   - The function could not complete successfully.
 640
 641 --*/
 642 ;
 643
 644 EFI_STATUS
 645 CleanupWorkSpace (
 646   IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice,
 647   IN OUT UINT8            *BlockBuffer,
 648   IN UINTN                BufferSize
 649   )
 650 /*++
 651
 652 Routine Description:
 653     Reclaim the work space. Get rid of all the completed write records
 654     and write records in the Fault Tolerant work space.
 655
 656 Arguments:
 657     FtwLiteDevice   - Point to private data of FTW driver
 658     FtwSpaceBuffer  - Buffer to contain the reclaimed clean data
 659     BufferSize      - Size of the FtwSpaceBuffer
 660
 661 Returns:
 662     EFI_SUCCESS           - The function completed successfully
 663     EFI_BUFFER_TOO_SMALL  - The FtwSpaceBuffer is too small
 664     EFI_ABORTED           - The function could not complete successfully.
 665
 666 --*/
 667 ;
 668
 669 EFI_STATUS
 670 FtwReclaimWorkSpace (
 671   IN EFI_FTW_LITE_DEVICE  *FtwLiteDevice
 672   )
 673 /*++
 674
 675 Routine Description:
 676     Reclaim the work space on the working block.
 677
 678 Arguments:
 679     FtwLiteDevice     - Point to private data of FTW driver
 680
 681 Returns:
 682     EFI_SUCCESS           - The function completed successfully
 683     EFI_OUT_OF_RESOURCES  - Allocate memory error
 684     EFI_ABORTED           - The function could not complete successfully
 685
 686 --*/
 687 ;
 688
 689 #endif