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