MdePkg/Include/Protocol/FirmwareVolumeBlock.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: PI
  14   Version 1.00.
  15
  16 **/
  17
  18 #ifndef __FIRMWARE_VOLUME_BLOCK_H__
  19 #define __FIRMWARE_VOLUME_BLOCK_H__
  20
  21
  22 #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
  23   { 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }
  24
  25
  26 typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  27
  28 /**
  29   The GetAttributes() function retrieves the attributes and
  30   current settings of the block. Status Codes Returned
  31
  32   @param This       Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  33
  34   @param Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
  35                     attributes and current settings are
  36                     returned. Type EFI_FVB_ATTRIBUTES_2 is defined
  37                     in EFI_FIRMWARE_VOLUME_HEADER.
  38
  39   @retval EFI_SUCCESS The firmware volume attributes were
  40                       returned.
  41
  42 **/
  43 typedef
  44 EFI_STATUS
  45 (EFIAPI * EFI_FVB_GET_ATTRIBUTES)(
  46   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  47   OUT       EFI_FVB_ATTRIBUTES_2                *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 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  56
  57   @param Attributes   On input, Attributes is a pointer to
  58                       EFI_FVB_ATTRIBUTES_2 that contains the
  59                       desired firmware volume settings. On
  60                       successful return, it contains the new
  61                       settings of the firmware volume. Type
  62                       EFI_FVB_ATTRIBUTES_2 is defined in
  63                       EFI_FIRMWARE_VOLUME_HEADER.
  64
  65   @retval EFI_SUCCESS           The firmware volume attributes were returned.
  66
  67   @retval EFI_INVALID_PARAMETER The attributes requested are in
  68                                 conflict with the capabilities
  69                                 as declared in the firmware
  70                                 volume header.
  71
  72 **/
  73 typedef
  74 EFI_STATUS
  75 (EFIAPI * EFI_FVB_SET_ATTRIBUTES)(
  76   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  77   IN OUT    EFI_FVB_ATTRIBUTES_2                *Attributes
  78 );
  79
  80
  81 /**
  82   The GetPhysicalAddress() function retrieves the base address of
  83   a memory-mapped firmware volume. This function should be called
  84   only for memory-mapped firmware volumes.
  85
  86   @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  87
  88   @param Address  Pointer to a caller-allocated
  89                   EFI_PHYSICAL_ADDRESS that, on successful
  90                   return from GetPhysicalAddress(), contains the
  91                   base address of the firmware volume.
  92
  93   @retval EFI_SUCCESS       The firmware volume base address is returned.
  94
  95   @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
  96
  97 **/
  98 typedef
  99 EFI_STATUS
 100 (EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS)(
 101   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 102   OUT       EFI_PHYSICAL_ADDRESS                *Address
 103 );
 104
 105 /**
 106   The GetBlockSize() function retrieves the size of the requested
 107   block. It also returns the number of additional blocks with
 108   the identical size. The GetBlockSize() function is used to
 109   retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
 110
 111
 112   @param This           Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 113
 114   @param Lba            Indicates the block for which to return the size.
 115
 116   @param BlockSize      Pointer to a caller-allocated UINTN in which
 117                         the size of the block is returned.
 118
 119   @param NumberOfBlocks Pointer to a caller-allocated UINTN in
 120                         which the number of consecutive blocks,
 121                         starting with Lba, is returned. All
 122                         blocks in this range have a size of
 123                         BlockSize.
 124
 125
 126   @retval EFI_SUCCESS             The firmware volume base address is returned.
 127
 128   @retval EFI_INVALID_PARAMETER   The requested LBA is out of range.
 129
 130 **/
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI * EFI_FVB_GET_BLOCK_SIZE)(
 134   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 135   IN        EFI_LBA                             Lba,
 136   OUT       UINTN                               *BlockSize,
 137   OUT       UINTN                               *NumberOfBlocks
 138 );
 139
 140
 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 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 *EFI_FVB_READ)(
 189   IN CONST  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   The Write() function writes the specified number of bytes from
 198   the provided buffer to the specified block and offset. If the
 199   firmware volume is sticky write, the caller must ensure that
 200   all the bits of the specified range to write are in the
 201   EFI_FVB_ERASE_POLARITY state before calling the Write()
 202   function, or else the result will be unpredictable. This
 203   unpredictability arises because, for a sticky-write firmware
 204   volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
 205   state but it cannot flip it back again. In general, before
 206   calling the Write() function, the caller should call the
 207   EraseBlocks() function first to erase the specified block to
 208   write. A block erase cycle will transition bits from the
 209   (NOT)EFI_FVB_ERASE_POLARITY state back to the
 210   EFI_FVB_ERASE_POLARITY state. Implementations should be
 211   mindful that the firmware volume might be in the WriteDisabled
 212   state. If it is in this state, the Write() function must
 213   return the status code EFI_ACCESS_DENIED without modifying the
 214   contents of the firmware volume. The Write() function must
 215   also prevent spanning block boundaries. If a write is
 216   requested that spans a block boundary, the write must store up
 217   to the boundary but not beyond. The output parameter NumBytes
 218   must be set to correctly indicate the number of bytes actually
 219   written. The caller must be aware that a write may be
 220   partially completed. All writes, partial or otherwise, must be
 221   fully flushed to the hardware before the Write() service
 222   returns.
 223
 224   @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 225
 226   @param Lba      The starting logical block index to write to.
 227
 228   @param Offset   Offset into the block at which to begin writing.
 229
 230   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 231                   contains the total size of the buffer. At
 232                   exit, *NumBytes contains the total number of
 233                   bytes actually written.
 234
 235   @param Buffer   Pointer to a caller-allocated buffer that
 236                   contains the source for the write.
 237
 238   @retval EFI_SUCCESS         The firmware volume was written successfully.
 239
 240   @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
 241                               LBA boundary. On output, NumBytes
 242                               contains the total number of bytes
 243                               actually written.
 244
 245   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 246                               WriteDisabled state.
 247
 248   @retval EFI_DEVICE_ERROR    The block device is malfunctioning
 249                               and could not be written.
 250
 251
 252 **/
 253 typedef
 254 EFI_STATUS
 255 (EFIAPI * EFI_FVB_WRITE)(
 256   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 257   IN        EFI_LBA                             Lba,
 258   IN        UINTN                               Offset,
 259   IN OUT    UINTN                               *NumBytes,
 260   IN        UINT8                               *Buffer
 261 );
 262
 263
 264
 265
 266 ///
 267 /// EFI_LBA_LIST_TERMINATOR
 268 ///
 269 #define EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
 270
 271
 272 /**
 273   The EraseBlocks() function erases one or more blocks as denoted
 274   by the variable argument list. The entire parameter list of
 275   blocks must be verified before erasing any blocks. If a block is
 276   requested that does not exist within the associated firmware
 277   volume (it has a larger index than the last block of the
 278   firmware volume), the EraseBlocks() function must return the
 279   status code EFI_INVALID_PARAMETER without modifying the contents
 280   of the firmware volume. Implementations should be mindful that
 281   the firmware volume might be in the WriteDisabled state. If it
 282   is in this state, the EraseBlocks() function must return the
 283   status code EFI_ACCESS_DENIED without modifying the contents of
 284   the firmware volume. All calls to EraseBlocks() must be fully
 285   flushed to the hardware before the EraseBlocks() service
 286   returns.
 287
 288   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 289                 instance.
 290
 291   @param ...    The variable argument list is a list of tuples.
 292                 Each tuple describes a range of LBAs to erase
 293                 and consists of the following:
 294                 - An EFI_LBA that indicates the starting LBA
 295                 - A UINTN that indicates the number of blocks to
 296                   erase
 297
 298                 The list is terminated with an
 299                 EFI_LBA_LIST_TERMINATOR. For example, the
 300                 following indicates that two ranges of blocks
 301                 (5-7 and 10-11) are to be erased: EraseBlocks
 302                 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
 303
 304   @retval EFI_SUCCESS The erase request was successfully
 305                       completed.
 306
 307   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 308                               WriteDisabled state.
 309   @retval EFI_DEVICE_ERROR  The block device is not functioning
 310                             correctly and could not be written.
 311                             The firmware device may have been
 312                             partially erased.
 313   @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
 314                                 in the variable argument list do
 315                                 not exist in the firmware volume.
 316
 317 **/
 318 typedef
 319 EFI_STATUS
 320 (EFIAPI * EFI_FVB_ERASE_BLOCKS)(
 321   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 322   ...
 323 );
 324
 325 /**
 326   @par Protocol Description:
 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. The Firmware Volume Block
 334   Protocol provides the following:
 335   - Byte-level read/write functionality.
 336   - Block-level erase functionality.
 337   - It further exposes device-hardening features, such as may be
 338     equired to protect the firmware from unwanted overwriting
 339     and/or erasure.
 340   - It is useful to layer a file system driver on top of the
 341     Firmware Volume Block Protocol.
 342
 343   This file system driver produces the Firmware Volume Protocol,
 344   which provides file-level access to a firmware volume. The
 345   Firmware Volume Protocol abstracts the file system that is
 346   used to format the firmware volume and the hardware
 347   device-hardening features that may be present.
 348 **/
 349 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 350   EFI_FVB_GET_ATTRIBUTES        GetAttributes;
 351   EFI_FVB_SET_ATTRIBUTES        SetAttributes;
 352   EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 353   EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 354   EFI_FVB_READ                  Read;
 355   EFI_FVB_WRITE                 Write;
 356   EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 357   ///
 358   /// Handle of the parent firmware volume.
 359   ///
 360   EFI_HANDLE                    ParentHandle;
 361 };
 362
 363
 364 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;
 365
 366
 367 #endif