MdeModulePkg/Universal/FaultTolerantWriteDxe/FaultTolerantWriteSmmDxe.h

   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) 2011 - 2018, Intel Corporation. All rights reserved. <BR>
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __SMM_FTW_DXE_H__
  12 #define __SMM_FTW_DXE_H__
  13
  14 #include <PiDxe.h>
  15
  16 #include <Protocol/MmCommunication2.h>
  17
  18 #include <Library/UefiBootServicesTableLib.h>
  19 #include <Library/UefiDriverEntryPoint.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/BaseMemoryLib.h>
  22 #include <Library/UefiLib.h>
  23 #include <Library/BaseLib.h>
  24 #include <Library/MemoryAllocationLib.h>
  25
  26 #include <Guid/EventGroup.h>
  27
  28 #include "FaultTolerantWriteSmmCommon.h"
  29
  30 /**
  31   Get the size of the largest block that can be updated in a fault-tolerant manner.
  32
  33   @param[in]  This             Indicates a pointer to the calling context.
  34   @param[out] BlockSize        A pointer to a caller-allocated UINTN that is
  35                                updated to indicate the size of the largest block
  36                                that can be updated.
  37
  38   @retval EFI_SUCCESS          The function completed successfully.
  39   @retval EFI_ABORTED          The function could not complete successfully.
  40
  41 **/
  42 EFI_STATUS
  43 EFIAPI
  44 FtwGetMaxBlockSize (
  45   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL      *This,
  46   OUT UINTN                                 *BlockSize
  47   );
  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   writes require more resources to be successful, this function
  54   enables the protocol to ensure that enough space exists to track
  55   information about upcoming writes.
  56
  57   @param[in]  This             A pointer to the calling context.
  58   @param[in]  CallerId         The GUID identifying the write.
  59   @param[in]  PrivateDataSize  The size of the caller's private data  that must be
  60                                recorded for each write.
  61   @param[in]  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    Not all allocated writes have been completed.  All
  67                                writes must be completed or aborted before another
  68                                fault tolerant write can occur.
  69
  70 **/
  71 EFI_STATUS
  72 EFIAPI
  73 FtwAllocate (
  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 /**
  82   Starts a target block update. This records information about the write
  83   in fault tolerant storage, and will complete the write in a recoverable
  84   manner, ensuring at all times that either the original contents or
  85   the modified contents are available.
  86
  87   @param[in]  This             The calling context.
  88   @param[in]  Lba              The logical block address of the target block.
  89   @param[in]  Offset           The offset within the target block to place the
  90                                data.
  91   @param[in]  Length           The number of bytes to write to the target block.
  92   @param[in]  PrivateData      A pointer to private data that the caller requires
  93                                to complete any pending writes in the event of a
  94                                fault.
  95   @param[in]  FvBlockHandle    The handle of FVB protocol that provides services
  96                                for reading, writing, and erasing the target block.
  97   @param[in]  Buffer           The data to write.
  98
  99   @retval EFI_SUCCESS          The function completed successfully.
 100   @retval EFI_ABORTED          The function could not complete successfully.
 101   @retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary, which is not
 102                                a valid action.
 103   @retval EFI_ACCESS_DENIED    No writes have been allocated.
 104   @retval EFI_NOT_READY        The last write has not been completed. Restart()
 105                                must be called to complete it.
 106
 107 **/
 108 EFI_STATUS
 109 EFIAPI
 110 FtwWrite (
 111   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL      *This,
 112   IN EFI_LBA                                Lba,
 113   IN UINTN                                  Offset,
 114   IN UINTN                                  Length,
 115   IN VOID                                   *PrivateData,
 116   IN EFI_HANDLE                             FvBlockHandle,
 117   IN VOID                                   *Buffer
 118   );
 119
 120
 121 /**
 122   Restarts a previously interrupted write. The caller must provide the
 123   block protocol needed to complete the interrupted write.
 124
 125   @param[in]  This             The calling context.
 126   @param[in]  FvBlockHandle    The handle of FVB protocol that provides services.
 127
 128   @retval EFI_SUCCESS          The function completed successfully.
 129   @retval EFI_ABORTED          The function could not complete successfully.
 130   @retval EFI_ACCESS_DENIED    No pending writes exist.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 FtwRestart (
 136   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL      *This,
 137   IN EFI_HANDLE                             FvBlockHandle
 138   );
 139
 140
 141 /**
 142   Aborts all previously allocated writes.
 143
 144   @param  This                 The calling context.
 145
 146   @retval EFI_SUCCESS          The function completed successfully.
 147   @retval EFI_ABORTED          The function could not complete successfully.
 148   @retval EFI_NOT_FOUND        No allocated writes exist.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 FtwAbort (
 154   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL      *This
 155   );
 156
 157
 158 /**
 159   Starts a target block update. This function records information about the write
 160   in fault-tolerant storage and completes the write in a recoverable
 161   manner, ensuring at all times that either the original contents or
 162   the modified contents are available.
 163
 164   @param[in]      This            Indicates a pointer to the calling context.
 165   @param[out]     CallerId        The GUID identifying the last write.
 166   @param[out]     Lba             The logical block address of the last write.
 167   @param[out]     Offset          The offset within the block of the last write.
 168   @param[out]     Length          The length of the last write.
 169   @param[in, out] PrivateDataSize On input, the size of the PrivateData buffer. On
 170                                   output, the size of the private data stored for
 171                                   this write.
 172   @param[out]     PrivateData     A pointer to a buffer. The function will copy
 173                                   PrivateDataSize bytes from the private data stored
 174                                   for this write.
 175   @param[out]     Complete        A Boolean value with TRUE indicating that the write
 176                                   was completed.
 177
 178   @retval EFI_SUCCESS             The function completed successfully.
 179   @retval EFI_ABORTED             The function could not complete successfully.
 180   @retval EFI_NOT_FOUND           No allocated writes exist.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 FtwGetLastWrite (
 186   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL      *This,
 187   OUT EFI_GUID                              *CallerId,
 188   OUT EFI_LBA                               *Lba,
 189   OUT UINTN                                 *Offset,
 190   OUT UINTN                                 *Length,
 191   IN OUT UINTN                              *PrivateDataSize,
 192   OUT VOID                                  *PrivateData,
 193   OUT BOOLEAN                               *Complete
 194   );
 195
 196 #endif