MdePkg/Include/Protocol/FirmwareVolumeBlock.h

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