MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Include / Protocol / FaultTolerantWrite.h

/** @file\r
  Fault Tolerant Write protocol provides boot-time service for fault tolerant\r
  write capability for block devices.  The protocol provides for non-volatile\r
  storage of the intermediate data and private information a caller would need to\r
  recover from a critical fault, such as a power failure.\r
\r
Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_\r
#define _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_\r
\r
#define EFI_FAULT_TOLERANT_WRITE_PROTOCOL_GUID \\r
  { \\r
    0x3ebd9e82, 0x2c78, 0x4de6, {0x97, 0x86, 0x8d, 0x4b, 0xfc, 0xb7, 0xc8, 0x81 } \\r
  }\r
\r
//\r
// Forward reference for pure ANSI compatability\r
//\r
typedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL  EFI_FAULT_TOLERANT_WRITE_PROTOCOL;\r
\r
/**\r
  Get the size of the largest block that can be updated in a fault-tolerant manner.\r
\r
  @param  This                 Indicates a pointer to the calling context.\r
  @param  BlockSize            A pointer to a caller-allocated UINTN that is\r
                               updated to indicate the size of the largest block\r
                               that can be updated.\r
\r
  @retval EFI_SUCCESS          The function completed successfully.\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    * This,\r
  OUT UINTN                               *BlockSize\r
  );\r
\r
/**\r
  Allocates space for the protocol to maintain information about writes.\r
  Since writes must be completed in a fault-tolerant manner and multiple\r
  writes require more resources to be successful, this function\r
  enables the protocol to ensure that enough space exists to track\r
  information about upcoming writes.\r
\r
  @param  This                 A pointer to the calling context.\r
  @param  CallerId             The GUID identifying the write.\r
  @param  PrivateDataSize      The size of the caller's private data  that must be\r
                               recorded for each write.\r
  @param  NumberOfWrites       The number of fault tolerant block writes that will\r
                               need to occur.\r
\r
  @retval EFI_SUCCESS          The function completed successfully\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
  @retval EFI_ACCESS_DENIED    Not all allocated writes have been completed.  All\r
                               writes must be completed or aborted before another\r
                               fault tolerant write can occur.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL    * This,\r
  IN EFI_GUID                             * CallerId,\r
  IN UINTN                                PrivateDataSize,\r
  IN UINTN                                NumberOfWrites\r
  );\r
\r
/**\r
  Starts a target block update. This records information about the write\r
  in fault tolerant storage, and will complete the write in a recoverable\r
  manner, ensuring at all times that either the original contents or\r
  the modified contents are available.\r
\r
  @param  This                 The calling context.\r
  @param  Lba                  The logical block address of the target block.\r
  @param  Offset               The offset within the target block to place the\r
                               data.\r
  @param  Length               The number of bytes to write to the target block.\r
  @param  PrivateData          A pointer to private data that the caller requires\r
                               to complete any pending writes in the event of a\r
                               fault.\r
  @param  FvBlockHandle        The handle of FVB protocol that provides services\r
                               for reading, writing, and erasing the target block.\r
  @param  Buffer               The data to write.\r
\r
  @retval EFI_SUCCESS          The function completed successfully.\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
  @retval EFI_BAD_BUFFER_SIZE  The write would span a block boundary, which is not\r
                               a valid action.\r
  @retval EFI_ACCESS_DENIED    No writes have been allocated.\r
  @retval EFI_NOT_READY        The last write has not been completed. Restart()\r
                               must be called to complete it.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,\r
  IN EFI_LBA                               Lba,\r
  IN UINTN                                 Offset,\r
  IN UINTN                                 Length,\r
  IN VOID                                  *PrivateData,\r
  IN EFI_HANDLE                            FvbHandle,\r
  IN VOID                                  *Buffer\r
  );\r
\r
/**\r
  Restarts a previously interrupted write. The caller must provide the\r
  block protocol needed to complete the interrupted write.\r
\r
  @param  This                 The calling context.\r
  @param  FvBlockProtocol      The handle of FVB protocol that provides services.\r
                               for reading, writing, and erasing the target block.\r
\r
  @retval EFI_SUCCESS          The function completed successfully.\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
  @retval EFI_ACCESS_DENIED    No pending writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,\r
  IN EFI_HANDLE                            FvbHandle\r
  );\r
\r
/**\r
  Aborts all previously allocated writes.\r
\r
  @param  This                 The calling context.\r
\r
  @retval EFI_SUCCESS          The function completed successfully.\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
  @retval EFI_NOT_FOUND        No allocated writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This\r
  );\r
\r
/**\r
  Starts a target block update. This function records information about the write\r
  in fault-tolerant storage and completes the write in a recoverable\r
  manner, ensuring at all times that either the original contents or\r
  the modified contents are available.\r
\r
  @param  This                 Indicates a pointer to the calling context.\r
  @param  CallerId             The GUID identifying the last write.\r
  @param  Lba                  The logical block address of the last write.\r
  @param  Offset               The offset within the block of the last write.\r
  @param  Length               The length of the last write.\r
  @param  PrivateDataSize      On input, the size of the PrivateData buffer. On\r
                               output, the size of the private data stored for\r
                               this write.\r
  @param  PrivateData          A pointer to a buffer. The function will copy\r
                               PrivateDataSize bytes from the private data stored\r
                               for this write.\r
  @param  Complete             A Boolean value with TRUE indicating that the write\r
                               was completed.\r
\r
  @retval EFI_SUCCESS          The function completed successfully.\r
  @retval EFI_ABORTED          The function could not complete successfully.\r
  @retval EFI_NOT_FOUND        No allocated writes exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE)(\r
  IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL     * This,\r
  OUT EFI_GUID                             * CallerId,\r
  OUT EFI_LBA                              *Lba,\r
  OUT UINTN                                *Offset,\r
  OUT UINTN                                *Length,\r
  IN OUT UINTN                             *PrivateDataSize,\r
  OUT VOID                                 *PrivateData,\r
  OUT BOOLEAN                              *Complete\r
  );\r
\r
//\r
// Protocol declaration\r
//\r
struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL {\r
  EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE GetMaxBlockSize;\r
  EFI_FAULT_TOLERANT_WRITE_ALLOCATE           Allocate;\r
  EFI_FAULT_TOLERANT_WRITE_WRITE              Write;\r
  EFI_FAULT_TOLERANT_WRITE_RESTART            Restart;\r
  EFI_FAULT_TOLERANT_WRITE_ABORT              Abort;\r
  EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE     GetLastWrite;\r
};\r
\r
extern EFI_GUID gEfiFaultTolerantWriteProtocolGuid;\r
\r
#endif\r