Update the release notes:

[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / FirmwareVolumeBlock.h

/** @file\r
  This file declares Firmware Volume Block protocol.\r
\r
  Low level firmware device access routines to abstract firmware device\r
  hardware.\r
\r
  Copyright (c) 2007, Intel Corporation\r
  All rights reserved. This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
  Module Name:  FirmwareVolumeBlock.h\r
\r
  @par Revision Reference:\r
  This protocol is defined in Framework of EFI Firmware Volume Block specification.\r
  Version 0.9\r
\r
**/\r
\r
#ifndef _FIRMWARE_VOLUME_BLOCK_H_\r
#define _FIRMWARE_VOLUME_BLOCK_H_\r
\r
#include <PiDxe.h>\r
\r
#define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \\r
  { \\r
    0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD, 0xB5, 0x8D, 0xA1 } \\r
  }\r
\r
typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;\r
\r
/**\r
  Retrieves Volume attributes.  No polarity translations are done.\r
\r
  @param  This                  Calling context\r
  @param  Attributes            output buffer which contains attributes\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_GET_ATTRIBUTES) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  OUT EFI_FVB_ATTRIBUTES                          *Attributes\r
  )\r
;\r
\r
/**\r
  Sets Volume attributes.  No polarity translations are done.\r
\r
  @param  This                  Calling context\r
  @param  Attributes            On input: contains new attributes\r
                                On output: contains current attributes of FV\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_SET_ATTRIBUTES) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  IN OUT EFI_FVB_ATTRIBUTES                       *Attributes\r
  )\r
;\r
\r
/**\r
  Retrieves the physical address of a memory mapped FV.\r
\r
  @param  This                  Calling context\r
  @param  Attributes            Address is a pointer to a caller allocated EFI_PHYSICAL_ADDRESS\r
                                that on successful return from GetPhysicalAddress() contains the\r
                                base address of the firmware volume.\r
\r
  @retval EFI_UNSUPPORTED\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_GET_PHYSICAL_ADDRESS) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  OUT EFI_PHYSICAL_ADDRESS                        *Address\r
  )\r
;\r
\r
/**\r
  Retrieves the size in bytes of a specific block within an FV.\r
\r
  @param  This                  Calling context.\r
  @param  Lba                   Indicates which block to return the size for.\r
  @param  BlockSize             BlockSize is a pointer to a caller allocated\r
                                UINTN in which the size of the block is returned.\r
  @param  NumberOfBlocks        NumberOfBlocks is a pointer to a caller allocated\r
                                UINTN in which the number of consecutive blocks\r
                                starting with Lba is returned. All blocks in this\r
                                range have a size of BlockSize.\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_GET_BLOCK_SIZE) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  IN EFI_LBA                                      Lba,\r
  OUT UINTN                                       *BlockSize,\r
  OUT UINTN                                       *NumberOfBlocks\r
  )\r
;\r
\r
/**\r
  Reads data beginning at Lba:Offset from FV and places the data in Buffer.\r
  The read terminates either when *NumBytes of data have been read, or when\r
  a block boundary is reached.  *NumBytes is updated to reflect the actual\r
  number of bytes read.\r
\r
  @param  This                  Calling context\r
  @param  Lba                   Block in which to begin read\r
  @param  Offset                Offset in the block at which to begin read\r
  @param  NumBytes              At input, indicates the requested read size. At output, indicates\r
                                the actual number of bytes read.\r
  @param  Buffer                Data buffer in which to place data read.\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_NOT_FOUND\r
  @retval EFI_DEVICE_ERROR\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_READ) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  IN EFI_LBA                                      Lba,\r
  IN UINTN                                        Offset,\r
  IN OUT UINTN                                    *NumBytes,\r
  OUT UINT8                                       *Buffer\r
  )\r
;\r
\r
/**\r
  Writes data beginning at Lba:Offset from FV. The write terminates either\r
  when *NumBytes of data have been written, or when a block boundary is\r
  reached.  *NumBytes is updated to reflect the actual number of bytes\r
  written.\r
\r
  @param  This                  Calling context\r
  @param  Lba                   Block in which to begin write\r
  @param  Offset                Offset in the block at which to begin write\r
  @param  NumBytes              At input, indicates the requested write size. At output, indicates\r
                                the actual number of bytes written.\r
  @param  Buffer                Buffer containing source data for the write.\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_NOT_FOUND\r
  @retval EFI_DEVICE_ERROR\r
  @retval EFI_SUCCESS\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_WRITE) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  IN EFI_LBA                                      Lba,\r
  IN UINTN                                        Offset,\r
  IN OUT UINTN                                    *NumBytes,\r
  IN UINT8                                        *Buffer\r
  )\r
;\r
\r
#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL\r
\r
/**\r
  The EraseBlock() function erases one or more blocks as denoted by the\r
  variable argument list. The entire parameter list of blocks must be verified\r
  prior to erasing any blocks.  If a block is requested that does not exist\r
  within the associated firmware volume (it has a larger index than the last\r
  block of the firmware volume), the EraseBlock() function must return\r
  EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.\r
\r
  @param  This                  Calling context\r
  @param  ...                   Starting LBA followed by Number of Lba to erase. a -1 to terminate\r
                                the list.\r
\r
  @retval EFI_INVALID_PARAMETER\r
  @retval EFI_DEVICE_ERROR\r
  @retval EFI_SUCCESS\r
  @retval EFI_ACCESS_DENIED\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_ERASE_BLOCKS) (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,\r
  ...\r
  )\r
;\r
\r
/**\r
  @par Protocol Description:\r
  This protocol provides control over block-oriented firmware devices.\r
  Typically, the FFS (or an alternate file system) driver consumes the\r
  Firmware Volume Block Protocol and produces the Firmware Volume Protocol.\r
\r
  @param GetAttributes\r
  Retrieves the current volume attributes.\r
\r
  @param SetAttributes\r
  Sets the current volume attributes.\r
\r
  @param GetPhysicalAddress\r
  Retrieves the memory-mapped address of the firmware volume.\r
\r
  @param GetBlockSize\r
  Retrieves the size for a specific block.\r
\r
  @param Read\r
  Reads n bytes into a buffer from the firmware volume hardware.\r
\r
  @param Write\r
  Writes n bytes from a buffer into the firmware volume hardware.\r
\r
  @param EraseBlocks\r
  Erases specified block(s) and sets all values as indicated by\r
  the EFI_FVB_ERASE_POLARITY bit.\r
\r
  @param ParentHandle\r
  Handle of the parent firmware volume.\r
\r
**/\r
struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {\r
  EFI_FVB_GET_ATTRIBUTES        GetVolumeAttributes;\r
  EFI_FVB_SET_ATTRIBUTES        SetVolumeAttributes;\r
  EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;\r
  EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;\r
  EFI_FVB_READ                  Read;\r
  EFI_FVB_WRITE                 Write;\r
  EFI_FVB_ERASE_BLOCKS          EraseBlocks;\r
  EFI_HANDLE                    ParentHandle;\r
};\r
\r
extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;\r
\r
#endif\r