MdeModulePkg/Core/Dxe/FwVolBlock/FwVolBlock.h

   1 /** @file
   2   Firmware Volume Block protocol functions.
   3   Consumes FV hobs and creates appropriate block protocols.
   4
   5 Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _FWVOL_BLOCK_H_
  17 #define _FWVOL_BLOCK_H_
  18
  19
  20 #define FVB_DEVICE_SIGNATURE       SIGNATURE_32('_','F','V','B')
  21
  22
  23 typedef struct {
  24   UINTN                       Base;
  25   UINTN                       Length;
  26 } LBA_CACHE;
  27
  28 typedef struct {
  29   MEMMAP_DEVICE_PATH          MemMapDevPath;
  30   EFI_DEVICE_PATH_PROTOCOL    EndDevPath;
  31 } FV_MEMMAP_DEVICE_PATH;
  32
  33 //
  34 // UEFI Specification define FV device path format if FV provide name guid in extension header
  35 //
  36 typedef struct {
  37   MEDIA_FW_VOL_DEVICE_PATH    FvDevPath;
  38   EFI_DEVICE_PATH_PROTOCOL    EndDevPath;
  39 } FV_PIWG_DEVICE_PATH;
  40
  41 typedef struct {
  42   UINTN                                 Signature;
  43   EFI_HANDLE                            Handle;
  44   EFI_DEVICE_PATH_PROTOCOL              *DevicePath;
  45   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    FwVolBlockInstance;
  46   UINTN                                 NumBlocks;
  47   LBA_CACHE                             *LbaCache;
  48   UINT32                                FvbAttributes;
  49   EFI_PHYSICAL_ADDRESS                  BaseAddress;
  50   UINT32                                AuthenticationStatus;
  51 } EFI_FW_VOL_BLOCK_DEVICE;
  52
  53
  54 #define FVB_DEVICE_FROM_THIS(a) \
  55   CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)
  56
  57
  58 /**
  59   Retrieves Volume attributes.  No polarity translations are done.
  60
  61   @param  This                   Calling context
  62   @param  Attributes             output buffer which contains attributes
  63
  64   @retval EFI_SUCCESS            The firmware volume attributes were returned.
  65
  66 **/
  67 EFI_STATUS
  68 EFIAPI
  69 FwVolBlockGetAttributes (
  70   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  71   OUT       EFI_FVB_ATTRIBUTES_2                *Attributes
  72   );
  73
  74
  75
  76 /**
  77   Modifies the current settings of the firmware volume according to the input parameter.
  78
  79   @param  This                   Calling context
  80   @param  Attributes             input buffer which contains attributes
  81
  82   @retval EFI_SUCCESS            The firmware volume attributes were returned.
  83   @retval EFI_INVALID_PARAMETER  The attributes requested are in conflict with
  84                                  the capabilities as declared in the firmware
  85                                  volume header.
  86   @retval EFI_UNSUPPORTED        Not supported.
  87
  88 **/
  89 EFI_STATUS
  90 EFIAPI
  91 FwVolBlockSetAttributes (
  92   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  93   IN CONST  EFI_FVB_ATTRIBUTES_2                *Attributes
  94   );
  95
  96
  97
  98 /**
  99   The EraseBlock() function erases one or more blocks as denoted by the
 100   variable argument list. The entire parameter list of blocks must be verified
 101   prior to erasing any blocks.  If a block is requested that does not exist
 102   within the associated firmware volume (it has a larger index than the last
 103   block of the firmware volume), the EraseBlock() function must return
 104   EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
 105
 106   @param  This                   Calling context
 107   @param  ...                    Starting LBA followed by Number of Lba to erase.
 108                                  a -1 to terminate the list.
 109
 110   @retval EFI_SUCCESS            The erase request was successfully completed.
 111   @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
 112                                  state.
 113   @retval EFI_DEVICE_ERROR       The block device is not functioning correctly
 114                                  and could not be written. The firmware device
 115                                  may have been partially erased.
 116   @retval EFI_INVALID_PARAMETER  One or more of the LBAs listed in the variable
 117                                  argument list do
 118   @retval EFI_UNSUPPORTED        Not supported.
 119
 120 **/
 121 EFI_STATUS
 122 EFIAPI
 123 FwVolBlockEraseBlock (
 124   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *This,
 125   ...
 126   );
 127
 128
 129
 130 /**
 131   Read the specified number of bytes from the block to the input buffer.
 132
 133   @param  This                   Indicates the calling context.
 134   @param  Lba                    The starting logical block index to read.
 135   @param  Offset                 Offset into the block at which to begin reading.
 136   @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
 137                                  contains the total size of the buffer. At exit,
 138                                  *NumBytes contains the total number of bytes
 139                                  actually read.
 140   @param  Buffer                 Pinter to a caller-allocated buffer that
 141                                  contains the destine for the read.
 142
 143   @retval EFI_SUCCESS            The firmware volume was read successfully.
 144   @retval EFI_BAD_BUFFER_SIZE    The read was attempted across an LBA boundary.
 145   @retval EFI_ACCESS_DENIED      Access denied.
 146   @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
 147                                  be read.
 148
 149 **/
 150 EFI_STATUS
 151 EFIAPI
 152 FwVolBlockReadBlock (
 153   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
 154   IN CONST  EFI_LBA                              Lba,
 155   IN CONST  UINTN                                Offset,
 156   IN OUT    UINTN                                *NumBytes,
 157   IN OUT    UINT8                                *Buffer
 158   );
 159
 160
 161
 162 /**
 163   Writes the specified number of bytes from the input buffer to the block.
 164
 165   @param  This                   Indicates the calling context.
 166   @param  Lba                    The starting logical block index to write to.
 167   @param  Offset                 Offset into the block at which to begin writing.
 168   @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
 169                                  contains the total size of the buffer. At exit,
 170                                  *NumBytes contains the total number of bytes
 171                                  actually written.
 172   @param  Buffer                 Pinter to a caller-allocated buffer that
 173                                  contains the source for the write.
 174
 175   @retval EFI_SUCCESS            The firmware volume was written successfully.
 176   @retval EFI_BAD_BUFFER_SIZE    The write was attempted across an LBA boundary.
 177                                  On output, NumBytes contains the total number of
 178                                  bytes actually written.
 179   @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
 180                                  state.
 181   @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
 182                                  be written.
 183   @retval EFI_UNSUPPORTED        Not supported.
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 FwVolBlockWriteBlock (
 189   IN     EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
 190   IN     EFI_LBA                              Lba,
 191   IN     UINTN                                Offset,
 192   IN OUT UINTN                                *NumBytes,
 193   IN     UINT8                                *Buffer
 194   );
 195
 196
 197
 198 /**
 199   Get Fvb's base address.
 200
 201   @param  This                   Indicates the calling context.
 202   @param  Address                Fvb device base address.
 203
 204   @retval EFI_SUCCESS            Successfully got Fvb's base address.
 205   @retval EFI_UNSUPPORTED        Not supported.
 206
 207 **/
 208 EFI_STATUS
 209 EFIAPI
 210 FwVolBlockGetPhysicalAddress (
 211   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 212   OUT       EFI_PHYSICAL_ADDRESS                *Address
 213   );
 214
 215
 216
 217 /**
 218   Retrieves the size in bytes of a specific block within a firmware volume.
 219
 220   @param  This                   Indicates the calling context.
 221   @param  Lba                    Indicates the block for which to return the
 222                                  size.
 223   @param  BlockSize              Pointer to a caller-allocated UINTN in which the
 224                                  size of the block is returned.
 225   @param  NumberOfBlocks         Pointer to a caller-allocated UINTN in which the
 226                                  number of consecutive blocks starting with Lba
 227                                  is returned. All blocks in this range have a
 228                                  size of BlockSize.
 229
 230   @retval EFI_SUCCESS            The firmware volume base address is returned.
 231   @retval EFI_INVALID_PARAMETER  The requested LBA is out of range.
 232
 233 **/
 234 EFI_STATUS
 235 EFIAPI
 236 FwVolBlockGetBlockSize (
 237   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 238   IN CONST  EFI_LBA                             Lba,
 239   IN OUT    UINTN                               *BlockSize,
 240   IN OUT    UINTN                               *NumberOfBlocks
 241   );
 242
 243
 244 #endif