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