feat: add ftw usecases to the fvbdxe module

Add FTW usecases to the fvbdxe module. Signed-off-by: Girish Mahadevan <gmahadevan@nvidia.com> Reviewed-by: Jeff Brasen <jbrasen@nvidia.com>
NVIDIA · Jan 15, 2025 · ec9a7d5 · ec9a7d5
1 parent 09a3918
commit ec9a7d5
Show file tree

Hide file tree

Showing 2 changed files with 364 additions and 4 deletions.
diff --git a/Silicon/NVIDIA/Drivers/FvbDxe/UnitTest/FvbDxeTestPrivate.h b/Silicon/NVIDIA/Drivers/FvbDxe/UnitTest/FvbDxeTestPrivate.h
@@ -1,8 +1,7 @@
 /** @file
   Unit test definitions for the Fvb driver.
 
-  Copyright (c) 2020-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-
+  SPDX-FileCopyrightText: Copyright (c) 2018-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
   SPDX-License-Identifier: BSD-2-Clause-Patent
 
 **/
@@ -347,4 +346,166 @@ ValidateFvHeader (
   IN EFI_FIRMWARE_VOLUME_HEADER  *FwVolHeader
   );
 
+/**
+  Get the size of the largest block that can be updated in a fault-tolerant manner.
+
+  @param  This                 Indicates a pointer to the calling context.
+  @param  BlockSize            A pointer to a caller-allocated UINTN that is
+                               updated to indicate the size of the largest block
+                               that can be updated.
+
+  @retval EFI_SUCCESS          The function completed successfully.
+  @retval EFI_ABORTED          The function could not complete successfully.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwGetMaxBlockSize (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
+  OUT UINTN                             *BlockSize
+  );
+
+/**
+Starts a target block update. This records information about the write
+in fault tolerant storage, and will complete the write in a recoverable
+manner, ensuring at all times that either the original contents or
+the modified contents are available.
+
+@param  This                 The calling context.
+@param  Lba                  The logical block address of the target block.
+@param  Offset               The offset within the target block to place the
+                             data.
+@param  Length               The number of bytes to write to the target block.
+@param  PrivateData          A pointer to private data that the caller requires
+                             to complete any pending writes in the event of a
+                             fault.
+@param  FvBlockHandle        The handle of FVB protocol that provides services
+                             for reading, writing, and erasing the target block.
+@param  Buffer               The data to write.
+
+@retval EFI_SUCCESS          The function completed successfully.
+@retval EFI_ABORTED          The function could not complete successfully.
+@retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary, which is not
+                             a valid action.
+@retval EFI_ACCESS_DENIED    No writes have been allocated.
+@retval EFI_NOT_READY        The last write has not been completed. Restart()
+                             must be called to complete it.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwWrite (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
+  IN EFI_LBA                            Lba,
+  IN UINTN                              Offset,
+  IN UINTN                              Length,
+  IN VOID                               *PrivateData,
+  IN EFI_HANDLE                         FvbHandle,
+  IN VOID                               *Buffer
+  );
+
+/**
+  Allocates space for the protocol to maintain information about writes.
+  Since writes must be completed in a fault-tolerant manner and multiple
+  writes require more resources to be successful, this function
+  enables the protocol to ensure that enough space exists to track
+  information about upcoming writes.
+
+  @param  This                 A pointer to the calling context.
+  @param  CallerId             The GUID identifying the write.
+  @param  PrivateDataSize      The size of the caller's private data  that must be
+                               recorded for each write.
+  @param  NumberOfWrites       The number of fault tolerant block writes that will
+                               need to occur.
+
+  @retval EFI_SUCCESS          The function completed successfully
+  @retval EFI_ABORTED          The function could not complete successfully.
+  @retval EFI_ACCESS_DENIED    Not all allocated writes have been completed.  All
+                               writes must be completed or aborted before another
+                               fault tolerant write can occur.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwAllocate (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
+  IN EFI_GUID                           *CallerId,
+  IN UINTN                              PrivateDataSize,
+  IN UINTN                              NumberOfWrites
+  );
+
+/**
+  Restarts a previously interrupted write. The caller must provide the
+  block protocol needed to complete the interrupted write.
+
+  @param  This                 The calling context.
+  @param  FvBlockProtocol      The handle of FVB protocol that provides services.
+                               for reading, writing, and erasing the target block.
+
+  @retval EFI_SUCCESS          The function completed successfully.
+  @retval EFI_ABORTED          The function could not complete successfully.
+  @retval EFI_ACCESS_DENIED    No pending writes exist.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwRestart (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
+  IN EFI_HANDLE                         FvbHandle
+  );
+
+/**
+  Starts a target block update. This function records information about the write
+  in fault-tolerant storage and completes the write in a recoverable
+  manner, ensuring at all times that either the original contents or
+  the modified contents are available.
+
+  @param  This                 Indicates a pointer to the calling context.
+  @param  CallerId             The GUID identifying the last write.
+  @param  Lba                  The logical block address of the last write.
+  @param  Offset               The offset within the block of the last write.
+  @param  Length               The length of the last write.
+  @param  PrivateDataSize      On input, the size of the PrivateData buffer. On
+                               output, the size of the private data stored for
+                               this write.
+  @param  PrivateData          A pointer to a buffer. The function will copy
+                               PrivateDataSize bytes from the private data stored
+                               for this write.
+  @param  Complete             A Boolean value with TRUE indicating that the write
+                               was completed.
+
+  @retval EFI_SUCCESS          The function completed successfully.
+  @retval EFI_ABORTED          The function could not complete successfully.
+  @retval EFI_NOT_FOUND        No allocated writes exist.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwGetLastWrite (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
+  OUT EFI_GUID                          *CallerId,
+  OUT EFI_LBA                           *Lba,
+  OUT UINTN                             *Offset,
+  OUT UINTN                             *Length,
+  IN OUT UINTN                          *PrivateDataSize,
+  OUT VOID                              *PrivateData,
+  OUT BOOLEAN                           *Complete
+  );
+
+/**
+  Aborts all previously allocated writes.
+
+  @param  This                 The calling context.
+
+  @retval EFI_SUCCESS          The function completed successfully.
+  @retval EFI_ABORTED          The function could not complete successfully.
+  @retval EFI_NOT_FOUND        No allocated writes exist.
+
+**/
+EFI_STATUS
+EFIAPI
+FtwAbort (
+  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This
+  );
+
 #endif