IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h

   1 /** @file
   2   This file provides control over block-oriented firmware devices.
   3
   4 Copyright (c) 2006 - 2010, 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:
  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 #define FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
  22 { 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }
  23
  24 typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  25 ///
  26 /// The type of EFI FVB attribute per the Framework specification.
  27 ///
  28 typedef UINT32  EFI_FVB_ATTRIBUTES;
  29
  30 /**
  31   The GetAttributes() function retrieves the attributes and
  32   current settings of the block.
  33
  34   @param This       Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  35
  36   @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
  37                     attributes and current settings are
  38                     returned.
  39
  40   @retval EFI_SUCCESS The firmware volume attributes were
  41                       returned.
  42
  43 **/
  44 typedef
  45 EFI_STATUS
  46 (EFIAPI * FRAMEWORK_EFI_FVB_GET_ATTRIBUTES)(
  47   IN   FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  48   OUT  EFI_FVB_ATTRIBUTES                *Attributes
  49 );
  50
  51
  52 /**
  53   The SetAttributes() function sets configurable firmware volume
  54   attributes and returns the new settings of the firmware volume.
  55
  56   @param This         Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  57
  58   @param Attributes   On input, Attributes is a pointer to
  59                       EFI_FVB_ATTRIBUTES that contains the
  60                       desired firmware volume settings. On
  61                       successful return, it contains the new
  62                       settings of the firmware volume.
  63
  64   @retval EFI_SUCCESS           The firmware volume attributes were returned.
  65
  66   @retval EFI_INVALID_PARAMETER The attributes requested are in
  67                                 conflict with the capabilities
  68                                 as declared in the firmware
  69                                 volume header.
  70
  71 **/
  72 typedef
  73 EFI_STATUS
  74 (EFIAPI * FRAMEWORK_EFI_FVB_SET_ATTRIBUTES)(
  75   IN      FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  76   IN OUT  EFI_FVB_ATTRIBUTES                *Attributes
  77 );
  78
  79
  80 /**
  81   The GetPhysicalAddress() function retrieves the base address of
  82   a memory-mapped firmware volume. This function should be called
  83   only for memory-mapped firmware volumes.
  84
  85   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  86
  87   @param Address  Pointer to a caller-allocated
  88                   EFI_PHYSICAL_ADDRESS that, on successful
  89                   return from GetPhysicalAddress(), contains the
  90                   base address of the firmware volume.
  91
  92   @retval EFI_SUCCESS       The firmware volume base address is returned.
  93
  94   @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
  95
  96 **/
  97 typedef
  98 EFI_STATUS
  99 (EFIAPI * FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS)(
 100   IN    FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 101   OUT   EFI_PHYSICAL_ADDRESS                *Address
 102 );
 103
 104 /**
 105   The GetBlockSize() function retrieves the size of the requested
 106   block. It also returns the number of additional blocks with
 107   the identical size. The GetBlockSize() function is used to
 108   retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
 109
 110
 111   @param This           Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 112
 113   @param Lba            Indicates the block for which to return the size.
 114
 115   @param BlockSize      The pointer to a caller-allocated UINTN in which
 116                         the size of the block is returned.
 117
 118   @param NumberOfBlocks The pointer to a caller-allocated UINTN in
 119                         which the number of consecutive blocks,
 120                         starting with Lba, is returned. All
 121                         blocks in this range have a size of
 122                         BlockSize.
 123
 124
 125   @retval EFI_SUCCESS             The firmware volume base address was returned.
 126
 127   @retval EFI_INVALID_PARAMETER   The requested LBA is out of range.
 128
 129 **/
 130 typedef
 131 EFI_STATUS
 132 (EFIAPI * FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE)(
 133   IN  FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 134   IN  EFI_LBA                             Lba,
 135   OUT UINTN                               *BlockSize,
 136   OUT UINTN                               *NumberOfBlocks
 137 );
 138
 139
 140 /**
 141   Reads the specified number of bytes into a buffer from the specified block.
 142
 143   The Read() function reads the requested number of bytes from the
 144   requested block and stores them in the provided buffer.
 145   Implementations should be mindful that the firmware volume
 146   might be in the ReadDisabled state. If it is in this state,
 147   the Read() function must return the status code
 148   EFI_ACCESS_DENIED without modifying the contents of the
 149   buffer. The Read() function must also prevent spanning block
 150   boundaries. If a read is requested that would span a block
 151   boundary, the read must read up to the boundary but not
 152   beyond. The output parameter NumBytes must be set to correctly
 153   indicate the number of bytes actually read. The caller must be
 154   aware that a read may be partially completed.
 155
 156   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 157
 158   @param Lba      The starting logical block index
 159                   from which to read.
 160
 161   @param Offset   Offset into the block at which to begin reading.
 162
 163   @param NumBytes The pointer to a UINTN. At entry, *NumBytes
 164                   contains the total size of the buffer. At
 165                   exit, *NumBytes contains the total number of
 166                   bytes read.
 167
 168   @param Buffer   The pointer to a caller-allocated buffer that will
 169                   be used to hold the data that is read.
 170
 171   @retval EFI_SUCCESS         The firmware volume was read successfully
 172                               and contents are in Buffer.
 173
 174   @retval EFI_BAD_BUFFER_SIZE A read was attempted across an LBA
 175                               boundary. On output, NumBytes
 176                               contains the total number of bytes
 177                               returned in Buffer.
 178
 179   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 180                               ReadDisabled state.
 181
 182   @retval EFI_DEVICE_ERROR    The block device is not
 183                               functioning correctly and could
 184                               not be read.
 185
 186 **/
 187 typedef
 188 EFI_STATUS
 189 (EFIAPI *FRAMEWORK_EFI_FVB_READ)(
 190   IN       FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 191   IN       EFI_LBA                             Lba,
 192   IN       UINTN                               Offset,
 193   IN OUT   UINTN                               *NumBytes,
 194   IN OUT   UINT8                               *Buffer
 195 );
 196
 197 /**
 198   Writes the specified number of bytes from the input buffer to the block.
 199
 200   The Write() function writes the specified number of bytes from
 201   the provided buffer to the specified block and offset. If the
 202   firmware volume is sticky write, the caller must ensure that
 203   all the bits of the specified range to write are in the
 204   EFI_FVB_ERASE_POLARITY state before calling the Write()
 205   function, or else the result will be unpredictable. This
 206   unpredictability arises because, for a sticky-write firmware
 207   volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
 208   state but cannot flip it back again. In general, before
 209   calling the Write() function, the caller should call the
 210   EraseBlocks() function first to erase the specified block to
 211   write. A block erase cycle will transition bits from the
 212   (NOT)EFI_FVB_ERASE_POLARITY state back to the
 213   EFI_FVB_ERASE_POLARITY state. Implementors should note
 214   that the firmware volume might be in the WriteDisabled
 215   state. If it is in this state, the Write() function must
 216   return the status code EFI_ACCESS_DENIED without modifying the
 217   contents of the firmware volume. The Write() function must
 218   also prevent spanning block boundaries. If a write is
 219   requested that spans a block boundary, the write must store up
 220   to the boundary but not beyond. The output parameter NumBytes
 221   must be set to correctly indicate the number of bytes actually
 222   written. The caller must be aware that a write may be
 223   partially completed. All writes, partial or otherwise, must be
 224   fully flushed to the hardware before the Write() service
 225   returns.
 226
 227   @param This     Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 228
 229   @param Lba      The starting logical block index to write to.
 230
 231   @param Offset   Offset into the block at which to begin writing.
 232
 233   @param NumBytes The pointer to a UINTN. Input: the total size of the buffer.
 234                   Output: the total number of bytes actually written.
 235
 236   @param Buffer   The 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. Implementors should note 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 ...    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 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   /// The handle of the parent firmware volume.
 347   ///
 348   EFI_HANDLE                    ParentHandle;
 349 };
 350
 351 extern EFI_GUID gFramerworkEfiFirmwareVolumeBlockProtocolGuid;
 352
 353 #endif