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