MdePkg/Include/Protocol/FirmwareVolumeBlock.h

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