MdeModulePkg/Core/Dxe/FwVolBlock.h

   1 /** @file
   2   Firmware Volume Block protocol functions.
   3   Consumes FV hobs and creates appropriate block protocols.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
   6 All rights reserved. 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       EFI_SIGNATURE_32('_','F','V','B')
  21
  22 typedef struct {
  23   UINTN                       Base;
  24   UINTN                       Length;
  25 } LBA_CACHE;
  26
  27 typedef struct {
  28   MEMMAP_DEVICE_PATH          MemMapDevPath;
  29   EFI_DEVICE_PATH_PROTOCOL    EndDevPath;
  30 } FV_DEVICE_PATH;
  31
  32
  33 typedef struct {
  34   UINTN                                 Signature;
  35   EFI_HANDLE                            Handle;
  36   FV_DEVICE_PATH                        DevicePath;
  37   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    FwVolBlockInstance;
  38   UINTN                                 NumBlocks;
  39   LBA_CACHE                             *LbaCache;
  40   UINT32                                FvbAttributes;
  41   EFI_PHYSICAL_ADDRESS                  BaseAddress;
  42 } EFI_FW_VOL_BLOCK_DEVICE;
  43
  44 #define FVB_DEVICE_FROM_THIS(a) \
  45   CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)
  46
  47
  48
  49 /**
  50   This routine is the driver initialization entry point.  It initializes the
  51   libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
  52   produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
  53
  54   @param  ImageHandle            The image handle.
  55   @param  SystemTable            The system table.
  56
  57   @retval EFI_SUCCESS            Successfully initialized firmware volume block
  58                                  driver.
  59
  60 **/
  61 EFI_STATUS
  62 EFIAPI
  63 FwVolBlockDriverInit (
  64   IN EFI_HANDLE                 ImageHandle,
  65   IN EFI_SYSTEM_TABLE           *SystemTable
  66   );
  67
  68
  69
  70 /**
  71   Retrieves Volume attributes.  No polarity translations are done.
  72
  73   @param  This                   Calling context
  74   @param  Attributes             output buffer which contains attributes
  75
  76   @retval EFI_SUCCESS            The firmware volume attributes were returned.
  77
  78 **/
  79 EFI_STATUS
  80 EFIAPI
  81 FwVolBlockGetAttributes (
  82   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  83   OUT       EFI_FVB_ATTRIBUTES                  *Attributes
  84   );
  85
  86
  87
  88 /**
  89   Modifies the current settings of the firmware volume according to the input parameter.
  90
  91   @param  This                   Calling context
  92   @param  Attributes             input buffer which contains attributes
  93
  94   @retval EFI_SUCCESS            The firmware volume attributes were returned.
  95   @retval EFI_INVALID_PARAMETER  The attributes requested are in conflict with
  96                                  the capabilities as declared in the firmware
  97                                  volume header.
  98   @retval EFI_UNSUPPORTED        Not supported.
  99
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 FwVolBlockSetAttributes (
 104   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 105   IN CONST  EFI_FVB_ATTRIBUTES                  *Attributes
 106   );
 107
 108
 109
 110 /**
 111   The EraseBlock() function erases one or more blocks as denoted by the
 112   variable argument list. The entire parameter list of blocks must be verified
 113   prior to erasing any blocks.  If a block is requested that does not exist
 114   within the associated firmware volume (it has a larger index than the last
 115   block of the firmware volume), the EraseBlock() function must return
 116   EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
 117
 118   @param  This                   Calling context
 119   @param  ...                    Starting LBA followed by Number of Lba to erase.
 120                                  a -1 to terminate the list.
 121
 122   @retval EFI_SUCCESS            The erase request was successfully completed.
 123   @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
 124                                  state.
 125   @retval EFI_DEVICE_ERROR       The block device is not functioning correctly
 126                                  and could not be written. The firmware device
 127                                  may have been partially erased.
 128   @retval EFI_INVALID_PARAMETER  One or more of the LBAs listed in the variable
 129                                  argument list do
 130   @retval EFI_UNSUPPORTED        Not supported.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 FwVolBlockEraseBlock (
 136   IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *This,
 137   ...
 138   );
 139
 140
 141
 142 /**
 143   Read the specified number of bytes from the block to the input buffer.
 144
 145   @param  This                   Indicates the calling context.
 146   @param  Lba                    The starting logical block index to read.
 147   @param  Offset                 Offset into the block at which to begin reading.
 148   @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
 149                                  contains the total size of the buffer. At exit,
 150                                  *NumBytes contains the total number of bytes
 151                                  actually read.
 152   @param  Buffer                 Pinter to a caller-allocated buffer that
 153                                  contains the destine for the read.
 154
 155   @retval EFI_SUCCESS            The firmware volume was read successfully.
 156   @retval EFI_BAD_BUFFER_SIZE    The read was attempted across an LBA boundary.
 157   @retval EFI_ACCESS_DENIED      Access denied.
 158   @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
 159                                  be read.
 160
 161 **/
 162 EFI_STATUS
 163 EFIAPI
 164 FwVolBlockReadBlock (
 165   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
 166   IN CONST  EFI_LBA                              Lba,
 167   IN CONST  UINTN                                Offset,
 168   IN OUT    UINTN                                *NumBytes,
 169   IN OUT    UINT8                                *Buffer
 170   );
 171
 172
 173
 174 /**
 175   Writes the specified number of bytes from the input buffer to the block.
 176
 177   @param  This                   Indicates the calling context.
 178   @param  Lba                    The starting logical block index to write to.
 179   @param  Offset                 Offset into the block at which to begin writing.
 180   @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
 181                                  contains the total size of the buffer. At exit,
 182                                  *NumBytes contains the total number of bytes
 183                                  actually written.
 184   @param  Buffer                 Pinter to a caller-allocated buffer that
 185                                  contains the source for the write.
 186
 187   @retval EFI_SUCCESS            The firmware volume was written successfully.
 188   @retval EFI_BAD_BUFFER_SIZE    The write was attempted across an LBA boundary.
 189                                  On output, NumBytes contains the total number of
 190                                  bytes actually written.
 191   @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
 192                                  state.
 193   @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
 194                                  be written.
 195   @retval EFI_UNSUPPORTED        Not supported.
 196
 197 **/
 198 EFI_STATUS
 199 EFIAPI
 200 FwVolBlockWriteBlock (
 201   IN     EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
 202   IN     EFI_LBA                              Lba,
 203   IN     UINTN                                Offset,
 204   IN OUT UINTN                                *NumBytes,
 205   IN     UINT8                                *Buffer
 206   );
 207
 208
 209
 210 /**
 211   Get Fvb's base address.
 212
 213   @param  This                   Indicates the calling context.
 214   @param  Address                Fvb device base address.
 215
 216   @retval EFI_SUCCESS            Successfully got Fvb's base address.
 217   @retval EFI_UNSUPPORTED        Not supported.
 218
 219 **/
 220 EFI_STATUS
 221 EFIAPI
 222 FwVolBlockGetPhysicalAddress (
 223   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 224   OUT       EFI_PHYSICAL_ADDRESS                *Address
 225   );
 226
 227
 228
 229 /**
 230   Retrieves the size in bytes of a specific block within a firmware volume.
 231
 232   @param  This                   Indicates the calling context.
 233   @param  Lba                    Indicates the block for which to return the
 234                                  size.
 235   @param  BlockSize              Pointer to a caller-allocated UINTN in which the
 236                                  size of the block is returned.
 237   @param  NumberOfBlocks         Pointer to a caller-allocated UINTN in which the
 238                                  number of consecutive blocks starting with Lba
 239                                  is returned. All blocks in this range have a
 240                                  size of BlockSize.
 241
 242   @retval EFI_SUCCESS            The firmware volume base address is returned.
 243   @retval EFI_INVALID_PARAMETER  The requested LBA is out of range.
 244
 245 **/
 246 EFI_STATUS
 247 EFIAPI
 248 FwVolBlockGetBlockSize (
 249   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 250   IN CONST  EFI_LBA                             Lba,
 251   IN OUT    UINTN                               *BlockSize,
 252   IN OUT    UINTN                               *NumberOfBlocks
 253   );
 254
 255 /**
 256   This routine is the driver initialization entry point.  It initializes the
 257   libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
 258   produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
 259
 260   @param  ImageHandle            The image handle.
 261   @param  SystemTable            The system table.
 262
 263   @retval EFI_SUCCESS            Successfully initialized firmware volume block
 264                                  driver.
 265
 266 **/
 267 EFI_STATUS
 268 EFIAPI
 269 FwVolBlockDriverInit (
 270   IN EFI_HANDLE                 ImageHandle,
 271   IN EFI_SYSTEM_TABLE           *SystemTable
 272   );
 273
 274
 275 /**
 276   This routine produces a firmware volume block protocol on a given
 277   buffer.
 278
 279   @param  BaseAddress            base address of the firmware volume image
 280   @param  Length                 length of the firmware volume image
 281   @param  ParentHandle           handle of parent firmware volume, if this image
 282                                  came from an FV image file in another firmware
 283                                  volume (ala capsules)
 284   @param  FvProtocol             Firmware volume block protocol produced.
 285
 286   @retval EFI_VOLUME_CORRUPTED   Volume corrupted.
 287   @retval EFI_OUT_OF_RESOURCES   No enough buffer to be allocated.
 288   @retval EFI_SUCCESS            Successfully produced a FVB protocol on given
 289                                  buffer.
 290
 291 **/
 292 EFI_STATUS
 293 ProduceFVBProtocolOnBuffer (
 294   IN EFI_PHYSICAL_ADDRESS   BaseAddress,
 295   IN UINT64                 Length,
 296   IN EFI_HANDLE             ParentHandle,
 297   OUT EFI_HANDLE            *FvProtocol  OPTIONAL
 298   );
 299
 300 #endif