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   Allocates space for the protocol to maintain information about writes.
  51   Since writes must be completed in a fault-tolerant manner and multiple
  52   writes require more resources to be successful, this function
  53   enables the protocol to ensure that enough space exists to track
  54   information about upcoming writes.
  55
  56   @param[in]  This             A pointer to the calling context.
  57   @param[in]  CallerId         The GUID identifying the write.
  58   @param[in]  PrivateDataSize  The size of the caller's private data  that must be
  59                                recorded for each write.
  60   @param[in]  NumberOfWrites   The number of fault tolerant block writes that will
  61                                need to occur.
  62
  63   @retval EFI_SUCCESS          The function completed successfully
  64   @retval EFI_ABORTED          The function could not complete successfully.
  65   @retval EFI_ACCESS_DENIED    Not all allocated writes have been completed.  All
  66                                writes must be completed or aborted before another
  67                                fault tolerant write can occur.
  68
  69 **/
  70 EFI_STATUS
  71 EFIAPI
  72 FtwAllocate (
  73   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
  74   IN EFI_GUID                           *CallerId,
  75   IN UINTN                              PrivateDataSize,
  76   IN UINTN                              NumberOfWrites
  77   );
  78
  79 /**
  80   Starts a target block update. This records information about the write
  81   in fault tolerant storage, and will complete the write in a recoverable
  82   manner, ensuring at all times that either the original contents or
  83   the modified contents are available.
  84
  85   @param[in]  This             The calling context.
  86   @param[in]  Lba              The logical block address of the target block.
  87   @param[in]  Offset           The offset within the target block to place the
  88                                data.
  89   @param[in]  Length           The number of bytes to write to the target block.
  90   @param[in]  PrivateData      A pointer to private data that the caller requires
  91                                to complete any pending writes in the event of a
  92                                fault.
  93   @param[in]  FvBlockHandle    The handle of FVB protocol that provides services
  94                                for reading, writing, and erasing the target block.
  95   @param[in]  Buffer           The data to write.
  96
  97   @retval EFI_SUCCESS          The function completed successfully.
  98   @retval EFI_ABORTED          The function could not complete successfully.
  99   @retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary, which is not
 100                                a valid action.
 101   @retval EFI_ACCESS_DENIED    No writes have been allocated.
 102   @retval EFI_NOT_READY        The last write has not been completed. Restart()
 103                                must be called to complete it.
 104
 105 **/
 106 EFI_STATUS
 107 EFIAPI
 108 FtwWrite (
 109   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
 110   IN EFI_LBA                            Lba,
 111   IN UINTN                              Offset,
 112   IN UINTN                              Length,
 113   IN VOID                               *PrivateData,
 114   IN EFI_HANDLE                         FvBlockHandle,
 115   IN VOID                               *Buffer
 116   );
 117
 118 /**
 119   Restarts a previously interrupted write. The caller must provide the
 120   block protocol needed to complete the interrupted write.
 121
 122   @param[in]  This             The calling context.
 123   @param[in]  FvBlockHandle    The handle of FVB protocol that provides services.
 124
 125   @retval EFI_SUCCESS          The function completed successfully.
 126   @retval EFI_ABORTED          The function could not complete successfully.
 127   @retval EFI_ACCESS_DENIED    No pending writes exist.
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 FtwRestart (
 133   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
 134   IN EFI_HANDLE                         FvBlockHandle
 135   );
 136
 137 /**
 138   Aborts all previously allocated writes.
 139
 140   @param  This                 The calling context.
 141
 142   @retval EFI_SUCCESS          The function completed successfully.
 143   @retval EFI_ABORTED          The function could not complete successfully.
 144   @retval EFI_NOT_FOUND        No allocated writes exist.
 145
 146 **/
 147 EFI_STATUS
 148 EFIAPI
 149 FtwAbort (
 150   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This
 151   );
 152
 153 /**
 154   Starts a target block update. This function records information about the write
 155   in fault-tolerant storage and completes the write in a recoverable
 156   manner, ensuring at all times that either the original contents or
 157   the modified contents are available.
 158
 159   @param[in]      This            Indicates a pointer to the calling context.
 160   @param[out]     CallerId        The GUID identifying the last write.
 161   @param[out]     Lba             The logical block address of the last write.
 162   @param[out]     Offset          The offset within the block of the last write.
 163   @param[out]     Length          The length of the last write.
 164   @param[in, out] PrivateDataSize On input, the size of the PrivateData buffer. On
 165                                   output, the size of the private data stored for
 166                                   this write.
 167   @param[out]     PrivateData     A pointer to a buffer. The function will copy
 168                                   PrivateDataSize bytes from the private data stored
 169                                   for this write.
 170   @param[out]     Complete        A Boolean value with TRUE indicating that the write
 171                                   was completed.
 172
 173   @retval EFI_SUCCESS             The function completed successfully.
 174   @retval EFI_ABORTED             The function could not complete successfully.
 175   @retval EFI_NOT_FOUND           No allocated writes exist.
 176
 177 **/
 178 EFI_STATUS
 179 EFIAPI
 180 FtwGetLastWrite (
 181   IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL  *This,
 182   OUT EFI_GUID                          *CallerId,
 183   OUT EFI_LBA                           *Lba,
 184   OUT UINTN                             *Offset,
 185   OUT UINTN                             *Length,
 186   IN OUT UINTN                          *PrivateDataSize,
 187   OUT VOID                              *PrivateData,
 188   OUT BOOLEAN                           *Complete
 189   );
 190
 191 #endif