MdeModulePkg/Include/Protocol/FaultTolerantWrite.h

   1 /** @file
   2   Fault Tolerant Write protocol provides boot-time service for fault tolerant
   3   write capability for block devices.  The protocol provides for non-volatile
   4   storage of the intermediate data and private information a caller would need to
   5   recover from a critical fault, such as a power failure.
   6
   7 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_
  13 #define _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_
  14
  15 #define EFI_FAULT_TOLERANT_WRITE_PROTOCOL_GUID \
  16   { \
  17     0x3ebd9e82, 0x2c78, 0x4de6, {0x97, 0x86, 0x8d, 0x4b, 0xfc, 0xb7, 0xc8, 0x81 } \
  18   }
  19
  20 //
  21 // Forward reference for pure ANSI compatability
  22 //
  23 typedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL EFI_FAULT_TOLERANT_WRITE_PROTOCOL;
  24
  25 /**
  26   Get the size of the largest block that can be updated in a fault-tolerant manner.
  27
  28   @param  This                 Indicates a pointer to the calling context.
  29   @param  BlockSize            A pointer to a caller-allocated UINTN that is
  30                                updated to indicate the size of the largest block
  31                                that can be updated.
  32
  33   @retval EFI_SUCCESS          The function completed successfully.
  34   @retval EFI_ABORTED          The function could not complete successfully.
  35
  36 **/
  37 typedef
  38 EFI_STATUS
  39 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE)(
  40   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    *This,
  41   OUT UINTN                               *BlockSize
  42   );
  43
  44 /**
  45   Allocates space for the protocol to maintain information about writes.
  46   Since writes must be completed in a fault-tolerant manner and multiple
  47   writes require more resources to be successful, this function
  48   enables the protocol to ensure that enough space exists to track
  49   information about upcoming writes.
  50
  51   @param  This                 A pointer to the calling context.
  52   @param  CallerId             The GUID identifying the write.
  53   @param  PrivateDataSize      The size of the caller's private data  that must be
  54                                recorded for each write.
  55   @param  NumberOfWrites       The number of fault tolerant block writes that will
  56                                need to occur.
  57
  58   @retval EFI_SUCCESS          The function completed successfully
  59   @retval EFI_ABORTED          The function could not complete successfully.
  60   @retval EFI_ACCESS_DENIED    Not all allocated writes have been completed.  All
  61                                writes must be completed or aborted before another
  62                                fault tolerant write can occur.
  63
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE)(
  68   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    *This,
  69   IN EFI_GUID                             *CallerId,
  70   IN UINTN                                PrivateDataSize,
  71   IN UINTN                                NumberOfWrites
  72   );
  73
  74 /**
  75   Starts a target block update. This records information about the write
  76   in fault tolerant storage, and will complete the write in a recoverable
  77   manner, ensuring at all times that either the original contents or
  78   the modified contents are available.
  79
  80   @param  This                 The calling context.
  81   @param  Lba                  The logical block address of the target block.
  82   @param  Offset               The offset within the target block to place the
  83                                data.
  84   @param  Length               The number of bytes to write to the target block.
  85   @param  PrivateData          A pointer to private data that the caller requires
  86                                to complete any pending writes in the event of a
  87                                fault.
  88   @param  FvBlockHandle        The handle of FVB protocol that provides services
  89                                for reading, writing, and erasing the target block.
  90   @param  Buffer               The data to write.
  91
  92   @retval EFI_SUCCESS          The function completed successfully.
  93   @retval EFI_ABORTED          The function could not complete successfully.
  94   @retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary, which is not
  95                                a valid action.
  96   @retval EFI_ACCESS_DENIED    No writes have been allocated.
  97   @retval EFI_NOT_READY        The last write has not been completed. Restart()
  98                                must be called to complete it.
  99
 100 **/
 101 typedef
 102 EFI_STATUS
 103 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE)(
 104   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     *This,
 105   IN EFI_LBA                               Lba,
 106   IN UINTN                                 Offset,
 107   IN UINTN                                 Length,
 108   IN VOID                                  *PrivateData,
 109   IN EFI_HANDLE                            FvbHandle,
 110   IN VOID                                  *Buffer
 111   );
 112
 113 /**
 114   Restarts a previously interrupted write. The caller must provide the
 115   block protocol needed to complete the interrupted write.
 116
 117   @param  This                 The calling context.
 118   @param  FvBlockProtocol      The handle of FVB protocol that provides services.
 119                                for reading, writing, and erasing the target block.
 120
 121   @retval EFI_SUCCESS          The function completed successfully.
 122   @retval EFI_ABORTED          The function could not complete successfully.
 123   @retval EFI_ACCESS_DENIED    No pending writes exist.
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART)(
 129   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     *This,
 130   IN EFI_HANDLE                            FvbHandle
 131   );
 132
 133 /**
 134   Aborts all previously allocated writes.
 135
 136   @param  This                 The calling context.
 137
 138   @retval EFI_SUCCESS          The function completed successfully.
 139   @retval EFI_ABORTED          The function could not complete successfully.
 140   @retval EFI_NOT_FOUND        No allocated writes exist.
 141
 142 **/
 143 typedef
 144 EFI_STATUS
 145 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT)(
 146   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     *This
 147   );
 148
 149 /**
 150   Starts a target block update. This function records information about the write
 151   in fault-tolerant storage and completes the write in a recoverable
 152   manner, ensuring at all times that either the original contents or
 153   the modified contents are available.
 154
 155   @param  This                 Indicates a pointer to the calling context.
 156   @param  CallerId             The GUID identifying the last write.
 157   @param  Lba                  The logical block address of the last write.
 158   @param  Offset               The offset within the block of the last write.
 159   @param  Length               The length of the last write.
 160   @param  PrivateDataSize      On input, the size of the PrivateData buffer. On
 161                                output, the size of the private data stored for
 162                                this write.
 163   @param  PrivateData          A pointer to a buffer. The function will copy
 164                                PrivateDataSize bytes from the private data stored
 165                                for this write.
 166   @param  Complete             A Boolean value with TRUE indicating that the write
 167                                was completed.
 168
 169   @retval EFI_SUCCESS          The function completed successfully.
 170   @retval EFI_ABORTED          The function could not complete successfully.
 171   @retval EFI_NOT_FOUND        No allocated writes exist.
 172
 173 **/
 174 typedef
 175 EFI_STATUS
 176 (EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE)(
 177   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     *This,
 178   OUT EFI_GUID                             *CallerId,
 179   OUT EFI_LBA                              *Lba,
 180   OUT UINTN                                *Offset,
 181   OUT UINTN                                *Length,
 182   IN OUT UINTN                             *PrivateDataSize,
 183   OUT VOID                                 *PrivateData,
 184   OUT BOOLEAN                              *Complete
 185   );
 186
 187 //
 188 // Protocol declaration
 189 //
 190 struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL {
 191   EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE    GetMaxBlockSize;
 192   EFI_FAULT_TOLERANT_WRITE_ALLOCATE              Allocate;
 193   EFI_FAULT_TOLERANT_WRITE_WRITE                 Write;
 194   EFI_FAULT_TOLERANT_WRITE_RESTART               Restart;
 195   EFI_FAULT_TOLERANT_WRITE_ABORT                 Abort;
 196   EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE        GetLastWrite;
 197 };
 198
 199 extern EFI_GUID  gEfiFaultTolerantWriteProtocolGuid;
 200
 201 #endif