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