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.
  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. Input: the total size of the buffer.
 232                   Output: the total number of bytes actually written.
 233
 234   @param Buffer   Pointer to a caller-allocated buffer that
 235                   contains the source for the write.
 236
 237   @retval EFI_SUCCESS         The firmware volume was written successfully.
 238
 239   @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
 240                               LBA boundary. On output, NumBytes
 241                               contains the total number of bytes
 242                               actually written.
 243
 244   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 245                               WriteDisabled state.
 246
 247   @retval EFI_DEVICE_ERROR    The block device is malfunctioning
 248                               and could not be written.
 249
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI * FRAMEWORK_EFI_FVB_WRITE)(
 255   IN       FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 256   IN       EFI_LBA                             Lba,
 257   IN       UINTN                               Offset,
 258   IN OUT   UINTN                               *NumBytes,
 259   IN       UINT8                               *Buffer
 260 );
 261
 262
 263
 264
 265 ///
 266 /// EFI_LBA_LIST_TERMINATOR
 267 ///
 268 #define FRAMEWORK_EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
 269
 270
 271 /**
 272   Erases and initializes a firmware volume block.
 273
 274   The EraseBlocks() function erases one or more blocks as denoted
 275   by the variable argument list. The entire parameter list of
 276   blocks must be verified before erasing any blocks. If a block is
 277   requested that does not exist within the associated firmware
 278   volume (it has a larger index than the last block of the
 279   firmware volume), the EraseBlocks() function must return the
 280   status code EFI_INVALID_PARAMETER without modifying the contents
 281   of the firmware volume. Implementations should be mindful that
 282   the firmware volume might be in the WriteDisabled state. If it
 283   is in this state, the EraseBlocks() function must return the
 284   status code EFI_ACCESS_DENIED without modifying the contents of
 285   the firmware volume. All calls to EraseBlocks() must be fully
 286   flushed to the hardware before the EraseBlocks() service
 287   returns.
 288
 289   @param This   Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 290                 instance.
 291
 292   @param ...    A list of tuples.
 293                 Each tuple describes a range of LBAs to erase
 294                 and consists of the following:
 295                 - An EFI_LBA that indicates the starting LBA
 296                 - A UINTN that indicates the number of blocks to
 297                   erase
 298
 299                 The list is terminated with an
 300                 EFI_LBA_LIST_TERMINATOR. For example, the
 301                 following indicates that two ranges of blocks
 302                 (5-7 and 10-11) are to be erased: EraseBlocks
 303                 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
 304
 305   @retval EFI_SUCCESS The erase request was successfully
 306                       completed.
 307
 308   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 309                               WriteDisabled state.
 310   @retval EFI_DEVICE_ERROR  The block device is not functioning
 311                             correctly and could not be written.
 312                             The firmware device may have been
 313                             partially erased.
 314   @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
 315                                 in the variable argument list do
 316                                 not exist in the firmware volume.
 317
 318 **/
 319 typedef
 320 EFI_STATUS
 321 (EFIAPI * FRAMEWORK_EFI_FVB_ERASE_BLOCKS)(
 322   IN   FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 323   ...
 324 );
 325
 326 ///
 327 /// The Firmware Volume Block Protocol is the low-level interface
 328 /// to a firmware volume. File-level access to a firmware volume
 329 /// should not be done using the Firmware Volume Block Protocol.
 330 /// Normal access to a firmware volume must use the Firmware
 331 /// Volume Protocol. Typically, only the file system driver that
 332 /// produces the Firmware Volume Protocol will bind to the
 333 /// Firmware Volume Block Protocol.
 334 ///
 335 struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 336   FRAMEWORK_EFI_FVB_GET_ATTRIBUTES        GetAttributes;
 337   FRAMEWORK_EFI_FVB_SET_ATTRIBUTES        SetAttributes;
 338   FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 339   FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 340   FRAMEWORK_EFI_FVB_READ                  Read;
 341   FRAMEWORK_EFI_FVB_WRITE                 Write;
 342   FRAMEWORK_EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 343   ///
 344   /// Handle of the parent firmware volume.
 345   ///
 346   EFI_HANDLE                    ParentHandle;
 347 };
 348
 349
 350
 351 #endif