MdeModulePkg/Core/Dxe/FwVolBlock.h

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