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