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