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