MdeModulePkg/Include/Protocol/FaultTolerantWrite.h

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