EdkModulePkg/Core/Dxe/FwVolBlock.h

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