IntelFrameworkPkg/Include/Protocol/FirmwareVolumeBlock.h

   1 /** @file
   2   This file declares Firmware Volume Block protocol.
   3
   4   Low level firmware device access routines to abstract firmware device
   5   hardware.
   6
   7   Copyright (c) 2007, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16   Module Name:  FirmwareVolumeBlock.h
  17
  18   @par Revision Reference:
  19   This protocol is defined in Framework of EFI Firmware Volume Block specification.
  20   Version 0.9
  21
  22 **/
  23
  24 #ifndef _FIRMWARE_VOLUME_BLOCK_H_
  25 #define _FIRMWARE_VOLUME_BLOCK_H_
  26
  27
  28 #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
  29   { \
  30     0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD, 0xB5, 0x8D, 0xA1 } \
  31   }
  32
  33 typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  34
  35 /**
  36   Retrieves Volume attributes.  No polarity translations are done.
  37
  38   @param  This                  Calling context
  39   @param  Attributes            output buffer which contains attributes
  40
  41   @retval EFI_INVALID_PARAMETER
  42   @retval EFI_SUCCESS
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EFI_FVB_GET_ATTRIBUTES) (
  48   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
  49   OUT EFI_FVB_ATTRIBUTES                          *Attributes
  50   )
  51 ;
  52
  53 /**
  54   Sets Volume attributes.  No polarity translations are done.
  55
  56   @param  This                  Calling context
  57   @param  Attributes            On input: contains new attributes
  58                                 On output: contains current attributes of FV
  59
  60   @retval EFI_INVALID_PARAMETER
  61   @retval EFI_SUCCESS
  62
  63 **/
  64 typedef
  65 EFI_STATUS
  66 (EFIAPI *EFI_FVB_SET_ATTRIBUTES) (
  67   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
  68   IN OUT EFI_FVB_ATTRIBUTES                       *Attributes
  69   )
  70 ;
  71
  72 /**
  73   Retrieves the physical address of a memory mapped FV.
  74
  75   @param  This                  Calling context
  76   @param  Attributes            Address is a pointer to a caller allocated EFI_PHYSICAL_ADDRESS
  77                                 that on successful return from GetPhysicalAddress() contains the
  78                                 base address of the firmware volume.
  79
  80   @retval EFI_UNSUPPORTED
  81   @retval EFI_SUCCESS
  82
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_FVB_GET_PHYSICAL_ADDRESS) (
  87   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
  88   OUT EFI_PHYSICAL_ADDRESS                        *Address
  89   )
  90 ;
  91
  92 /**
  93   Retrieves the size in bytes of a specific block within an FV.
  94
  95   @param  This                  Calling context.
  96   @param  Lba                   Indicates which block to return the size for.
  97   @param  BlockSize             BlockSize is a pointer to a caller allocated
  98                                 UINTN in which the size of the block is returned.
  99   @param  NumberOfBlocks        NumberOfBlocks is a pointer to a caller allocated
 100                                 UINTN in which the number of consecutive blocks
 101                                 starting with Lba is returned. All blocks in this
 102                                 range have a size of BlockSize.
 103
 104   @retval EFI_INVALID_PARAMETER
 105   @retval EFI_SUCCESS
 106
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *EFI_FVB_GET_BLOCK_SIZE) (
 111   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
 112   IN EFI_LBA                                      Lba,
 113   OUT UINTN                                       *BlockSize,
 114   OUT UINTN                                       *NumberOfBlocks
 115   )
 116 ;
 117
 118 /**
 119   Reads data beginning at Lba:Offset from FV and places the data in Buffer.
 120   The read terminates either when *NumBytes of data have been read, or when
 121   a block boundary is reached.  *NumBytes is updated to reflect the actual
 122   number of bytes read.
 123
 124   @param  This                  Calling context
 125   @param  Lba                   Block in which to begin read
 126   @param  Offset                Offset in the block at which to begin read
 127   @param  NumBytes              At input, indicates the requested read size. At output, indicates
 128                                 the actual number of bytes read.
 129   @param  Buffer                Data buffer in which to place data read.
 130
 131   @retval EFI_INVALID_PARAMETER
 132   @retval EFI_NOT_FOUND
 133   @retval EFI_DEVICE_ERROR
 134   @retval EFI_SUCCESS
 135
 136 **/
 137 typedef
 138 EFI_STATUS
 139 (EFIAPI *EFI_FVB_READ) (
 140   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
 141   IN EFI_LBA                                      Lba,
 142   IN UINTN                                        Offset,
 143   IN OUT UINTN                                    *NumBytes,
 144   OUT UINT8                                       *Buffer
 145   )
 146 ;
 147
 148 /**
 149   Writes data beginning at Lba:Offset from FV. The write terminates either
 150   when *NumBytes of data have been written, or when a block boundary is
 151   reached.  *NumBytes is updated to reflect the actual number of bytes
 152   written.
 153
 154   @param  This                  Calling context
 155   @param  Lba                   Block in which to begin write
 156   @param  Offset                Offset in the block at which to begin write
 157   @param  NumBytes              At input, indicates the requested write size. At output, indicates
 158                                 the actual number of bytes written.
 159   @param  Buffer                Buffer containing source data for the write.
 160
 161   @retval EFI_INVALID_PARAMETER
 162   @retval EFI_NOT_FOUND
 163   @retval EFI_DEVICE_ERROR
 164   @retval EFI_SUCCESS
 165
 166 **/
 167 typedef
 168 EFI_STATUS
 169 (EFIAPI *EFI_FVB_WRITE) (
 170   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
 171   IN EFI_LBA                                      Lba,
 172   IN UINTN                                        Offset,
 173   IN OUT UINTN                                    *NumBytes,
 174   IN UINT8                                        *Buffer
 175   )
 176 ;
 177
 178 #define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL
 179
 180 /**
 181   The EraseBlock() function erases one or more blocks as denoted by the
 182   variable argument list. The entire parameter list of blocks must be verified
 183   prior to erasing any blocks.  If a block is requested that does not exist
 184   within the associated firmware volume (it has a larger index than the last
 185   block of the firmware volume), the EraseBlock() function must return
 186   EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
 187
 188   @param  This                  Calling context
 189   @param  ...                   Starting LBA followed by Number of Lba to erase. a -1 to terminate
 190                                 the list.
 191
 192   @retval EFI_INVALID_PARAMETER
 193   @retval EFI_DEVICE_ERROR
 194   @retval EFI_SUCCESS
 195   @retval EFI_ACCESS_DENIED
 196
 197 **/
 198 typedef
 199 EFI_STATUS
 200 (EFIAPI *EFI_FVB_ERASE_BLOCKS) (
 201   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL           *This,
 202   ...
 203   )
 204 ;
 205
 206 /**
 207   @par Protocol Description:
 208   This protocol provides control over block-oriented firmware devices.
 209   Typically, the FFS (or an alternate file system) driver consumes the
 210   Firmware Volume Block Protocol and produces the Firmware Volume Protocol.
 211
 212   @param GetAttributes
 213   Retrieves the current volume attributes.
 214
 215   @param SetAttributes
 216   Sets the current volume attributes.
 217
 218   @param GetPhysicalAddress
 219   Retrieves the memory-mapped address of the firmware volume.
 220
 221   @param GetBlockSize
 222   Retrieves the size for a specific block.
 223
 224   @param Read
 225   Reads n bytes into a buffer from the firmware volume hardware.
 226
 227   @param Write
 228   Writes n bytes from a buffer into the firmware volume hardware.
 229
 230   @param EraseBlocks
 231   Erases specified block(s) and sets all values as indicated by
 232   the EFI_FVB_ERASE_POLARITY bit.
 233
 234   @param ParentHandle
 235   Handle of the parent firmware volume.
 236
 237 **/
 238 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 239   EFI_FVB_GET_ATTRIBUTES        GetVolumeAttributes;
 240   EFI_FVB_SET_ATTRIBUTES        SetVolumeAttributes;
 241   EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 242   EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 243   EFI_FVB_READ                  Read;
 244   EFI_FVB_WRITE                 Write;
 245   EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 246   EFI_HANDLE                    ParentHandle;
 247 };
 248
 249 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;
 250
 251 #endif