IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h

   1 /** @file
   2   This file provides control over block-oriented firmware devices.
   3
   4   Copyright (c) 2006 - 2008, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Revision Reference:
  14   This protocol is defined in framework spec: Firmware Volume Block specification
  15
  16 **/
  17
  18 #ifndef __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
  19 #define __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
  20
  21
  22 typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  23 ///
  24 /// type of EFI FVB attribute per Frameowrk spec
  25 ///
  26 typedef UINT32  EFI_FVB_ATTRIBUTES;
  27
  28 /**
  29   The GetAttributes() function retrieves the attributes and
  30   current settings of the block. Status Codes Returned
  31
  32   @param This       Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  33
  34   @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
  35                     attributes and current settings are
  36                     returned.
  37
  38   @retval EFI_SUCCESS The firmware volume attributes were
  39                       returned.
  40
  41 **/
  42 typedef
  43 EFI_STATUS
  44 (EFIAPI * FRAMEWORK_EFI_FVB_GET_ATTRIBUTES)(
  45   IN   FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  46   OUT  EFI_FVB_ATTRIBUTES                *Attributes
  47 );
  48
  49
  50 /**
  51   The SetAttributes() function sets configurable firmware volume
  52   attributes and returns the new settings of the firmware volume.
  53
  54   @param This         Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  55
  56   @param Attributes   On input, Attributes is a pointer to
  57                       EFI_FVB_ATTRIBUTES that contains the
  58                       desired firmware volume settings. On
  59                       successful return, it contains the new
  60                       settings of the firmware volume.
  61
  62   @retval EFI_SUCCESS           The firmware volume attributes were returned.
  63
  64   @retval EFI_INVALID_PARAMETER The attributes requested are in
  65                                 conflict with the capabilities
  66                                 as declared in the firmware
  67                                 volume header.
  68
  69 **/
  70 typedef
  71 EFI_STATUS
  72 (EFIAPI * FRAMEWORK_EFI_FVB_SET_ATTRIBUTES)(
  73   IN      FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  74   IN OUT  EFI_FVB_ATTRIBUTES                *Attributes
  75 );
  76
  77
  78 /**
  79   The GetPhysicalAddress() function retrieves the base address of
  80   a memory-mapped firmware volume. This function should be called
  81   only for memory-mapped firmware volumes.
  82
  83   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  84
  85   @param Address  Pointer to a caller-allocated
  86                   EFI_PHYSICAL_ADDRESS that, on successful
  87                   return from GetPhysicalAddress(), contains the
  88                   base address of the firmware volume.
  89
  90   @retval EFI_SUCCESS       The firmware volume base address is returned.
  91
  92   @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
  93
  94 **/
  95 typedef
  96 EFI_STATUS
  97 (EFIAPI * FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS)(
  98   IN    FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  99   OUT   EFI_PHYSICAL_ADDRESS                *Address
 100 );
 101
 102 /**
 103   The GetBlockSize() function retrieves the size of the requested
 104   block. It also returns the number of additional blocks with
 105   the identical size. The GetBlockSize() function is used to
 106   retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
 107
 108
 109   @param This           Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 110
 111   @param Lba            Indicates the block for which to return the size.
 112
 113   @param BlockSize      Pointer to a caller-allocated UINTN in which
 114                         the size of the block is returned.
 115
 116   @param NumberOfBlocks Pointer to a caller-allocated UINTN in
 117                         which the number of consecutive blocks,
 118                         starting with Lba, is returned. All
 119                         blocks in this range have a size of
 120                         BlockSize.
 121
 122
 123   @retval EFI_SUCCESS             The firmware volume base address is returned.
 124
 125   @retval EFI_INVALID_PARAMETER   The requested LBA is out of range.
 126
 127 **/
 128 typedef
 129 EFI_STATUS
 130 (EFIAPI * FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE)(
 131   IN  FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 132   IN  EFI_LBA                             Lba,
 133   OUT UINTN                               *BlockSize,
 134   OUT UINTN                               *NumberOfBlocks
 135 );
 136
 137
 138 /**
 139   Reads the specified number of bytes into a buffer from the specified block.
 140
 141   The Read() function reads the requested number of bytes from the
 142   requested block and stores them in the provided buffer.
 143   Implementations should be mindful that the firmware volume
 144   might be in the ReadDisabled state. If it is in this state,
 145   the Read() function must return the status code
 146   EFI_ACCESS_DENIED without modifying the contents of the
 147   buffer. The Read() function must also prevent spanning block
 148   boundaries. If a read is requested that would span a block
 149   boundary, the read must read up to the boundary but not
 150   beyond. The output parameter NumBytes must be set to correctly
 151   indicate the number of bytes actually read. The caller must be
 152   aware that a read may be partially completed.
 153
 154   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 155
 156   @param Lba      The starting logical block index
 157                   from which to read.
 158
 159   @param Offset   Offset into the block at which to begin reading.
 160
 161   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 162                   contains the total size of the buffer. At
 163                   exit, *NumBytes contains the total number of
 164                   bytes read.
 165
 166   @param Buffer   Pointer to a caller-allocated buffer that will
 167                   be used to hold the data that is read.
 168
 169   @retval EFI_SUCCESS         The firmware volume was read successfully
 170                               and contents are in Buffer.
 171
 172   @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
 173                               boundary. On output, NumBytes
 174                               contains the total number of bytes
 175                               returned in Buffer.
 176
 177   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 178                               ReadDisabled state.
 179
 180   @retval EFI_DEVICE_ERROR    The block device is not
 181                               functioning correctly and could
 182                               not be read.
 183
 184 **/
 185 typedef
 186 EFI_STATUS
 187 (EFIAPI *FRAMEWORK_EFI_FVB_READ)(
 188   IN       FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 189   IN       EFI_LBA                             Lba,
 190   IN       UINTN                               Offset,
 191   IN OUT   UINTN                               *NumBytes,
 192   IN OUT   UINT8                               *Buffer
 193 );
 194
 195 /**
 196   Writes the specified number of bytes from the input buffer to the block.
 197
 198   The Write() function writes the specified number of bytes from
 199   the provided buffer to the specified block and offset. If the
 200   firmware volume is sticky write, the caller must ensure that
 201   all the bits of the specified range to write are in the
 202   EFI_FVB_ERASE_POLARITY state before calling the Write()
 203   function, or else the result will be unpredictable. This
 204   unpredictability arises because, for a sticky-write firmware
 205   volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
 206   state but cannot flip it back again. In general, before
 207   calling the Write() function, the caller should call the
 208   EraseBlocks() function first to erase the specified block to
 209   write. A block erase cycle will transition bits from the
 210   (NOT)EFI_FVB_ERASE_POLARITY state back to the
 211   EFI_FVB_ERASE_POLARITY state. Implementations should be
 212   mindful that the firmware volume might be in the WriteDisabled
 213   state. If it is in this state, the Write() function must
 214   return the status code EFI_ACCESS_DENIED without modifying the
 215   contents of the firmware volume. The Write() function must
 216   also prevent spanning block boundaries. If a write is
 217   requested that spans a block boundary, the write must store up
 218   to the boundary but not beyond. The output parameter NumBytes
 219   must be set to correctly indicate the number of bytes actually
 220   written. The caller must be aware that a write may be
 221   partially completed. All writes, partial or otherwise, must be
 222   fully flushed to the hardware before the Write() service
 223   returns.
 224
 225   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 226
 227   @param Lba      The starting logical block index to write to.
 228
 229   @param Offset   Offset into the block at which to begin writing.
 230
 231   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 232                   contains the total size of the buffer. At
 233                   exit, *NumBytes contains the total number of
 234                   bytes actually written.
 235
 236   @param Buffer   Pointer to a caller-allocated buffer that
 237                   contains the source for the write.
 238
 239   @retval EFI_SUCCESS         The firmware volume was written successfully.
 240
 241   @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
 242                               LBA boundary. On output, NumBytes
 243                               contains the total number of bytes
 244                               actually written.
 245
 246   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 247                               WriteDisabled state.
 248
 249   @retval EFI_DEVICE_ERROR    The block device is malfunctioning
 250                               and could not be written.
 251
 252
 253 **/
 254 typedef
 255 EFI_STATUS
 256 (EFIAPI * FRAMEWORK_EFI_FVB_WRITE)(
 257   IN       FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 258   IN       EFI_LBA                             Lba,
 259   IN       UINTN                               Offset,
 260   IN OUT   UINTN                               *NumBytes,
 261   IN       UINT8                               *Buffer
 262 );
 263
 264
 265
 266
 267 ///
 268 /// EFI_LBA_LIST_TERMINATOR
 269 ///
 270 #define FRAMEWORK_EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
 271
 272
 273 /**
 274   Erases and initializes a firmware volume block.
 275
 276   The EraseBlocks() function erases one or more blocks as denoted
 277   by the variable argument list. The entire parameter list of
 278   blocks must be verified before erasing any blocks. If a block is
 279   requested that does not exist within the associated firmware
 280   volume (it has a larger index than the last block of the
 281   firmware volume), the EraseBlocks() function must return the
 282   status code EFI_INVALID_PARAMETER without modifying the contents
 283   of the firmware volume. Implementations should be mindful that
 284   the firmware volume might be in the WriteDisabled state. If it
 285   is in this state, the EraseBlocks() function must return the
 286   status code EFI_ACCESS_DENIED without modifying the contents of
 287   the firmware volume. All calls to EraseBlocks() must be fully
 288   flushed to the hardware before the EraseBlocks() service
 289   returns.
 290
 291   @param This   Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 292                 instance.
 293
 294   @param ...    The variable argument list is a list of tuples.
 295                 Each tuple describes a range of LBAs to erase
 296                 and consists of the following:
 297                 - An EFI_LBA that indicates the starting LBA
 298                 - A UINTN that indicates the number of blocks to
 299                   erase
 300
 301                 The list is terminated with an
 302                 EFI_LBA_LIST_TERMINATOR. For example, the
 303                 following indicates that two ranges of blocks
 304                 (5-7 and 10-11) are to be erased: EraseBlocks
 305                 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
 306
 307   @retval EFI_SUCCESS The erase request was successfully
 308                       completed.
 309
 310   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 311                               WriteDisabled state.
 312   @retval EFI_DEVICE_ERROR  The block device is not functioning
 313                             correctly and could not be written.
 314                             The firmware device may have been
 315                             partially erased.
 316   @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
 317                                 in the variable argument list do
 318                                 not exist in the firmware volume.
 319
 320 **/
 321 typedef
 322 EFI_STATUS
 323 (EFIAPI * FRAMEWORK_EFI_FVB_ERASE_BLOCKS)(
 324   IN   FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 325   ...
 326 );
 327
 328 ///
 329 /// The Firmware Volume Block Protocol is the low-level interface
 330 /// to a firmware volume. File-level access to a firmware volume
 331 /// should not be done using the Firmware Volume Block Protocol.
 332 /// Normal access to a firmware volume must use the Firmware
 333 /// Volume Protocol. Typically, only the file system driver that
 334 /// produces the Firmware Volume Protocol will bind to the
 335 /// Firmware Volume Block Protocol.
 336 ///
 337 struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 338   FRAMEWORK_EFI_FVB_GET_ATTRIBUTES        GetAttributes;
 339   FRAMEWORK_EFI_FVB_SET_ATTRIBUTES        SetAttributes;
 340   FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 341   FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 342   FRAMEWORK_EFI_FVB_READ                  Read;
 343   FRAMEWORK_EFI_FVB_WRITE                 Write;
 344   FRAMEWORK_EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 345   ///
 346   /// Handle of the parent firmware volume.
 347   ///
 348   EFI_HANDLE                    ParentHandle;
 349 };
 350
 351
 352
 353 #endif