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   Reads the specified number of bytes into a buffer from the specified block.
 143
 144   The Read() function reads the requested number of bytes from the
 145   requested block and stores them in the provided buffer.
 146   Implementations should be mindful that the firmware volume
 147   might be in the ReadDisabled state. If it is in this state,
 148   the Read() function must return the status code
 149   EFI_ACCESS_DENIED without modifying the contents of the
 150   buffer. The Read() function must also prevent spanning block
 151   boundaries. If a read is requested that would span a block
 152   boundary, the read must read up to the boundary but not
 153   beyond. The output parameter NumBytes must be set to correctly
 154   indicate the number of bytes actually read. The caller must be
 155   aware that a read may be partially completed.
 156
 157   @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 158
 159   @param Lba      The starting logical block index
 160                   from which to read.
 161
 162   @param Offset   Offset into the block at which to begin reading.
 163
 164   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 165                   contains the total size of the buffer. At
 166                   exit, *NumBytes contains the total number of
 167                   bytes read.
 168
 169   @param Buffer   Pointer to a caller-allocated buffer that will
 170                   be used to hold the data that is read.
 171
 172   @retval EFI_SUCCESS         The firmware volume was read successfully
 173                               and contents are in Buffer.
 174
 175   @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
 176                               boundary. On output, NumBytes
 177                               contains the total number of bytes
 178                               returned in Buffer.
 179
 180   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 181                               ReadDisabled state.
 182
 183   @retval EFI_DEVICE_ERROR    The block device is not
 184                               functioning correctly and could
 185                               not be read.
 186
 187 **/
 188 typedef
 189 EFI_STATUS
 190 (EFIAPI *EFI_FVB_READ)(
 191   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 192   IN        EFI_LBA                             Lba,
 193   IN        UINTN                               Offset,
 194   IN OUT    UINTN                               *NumBytes,
 195   IN OUT    UINT8                               *Buffer
 196 );
 197
 198 /**
 199   Writes the specified number of bytes from the input buffer to the block.
 200
 201   The Write() function writes the specified number of bytes from
 202   the provided buffer to the specified block and offset. If the
 203   firmware volume is sticky write, the caller must ensure that
 204   all the bits of the specified range to write are in the
 205   EFI_FVB_ERASE_POLARITY state before calling the Write()
 206   function, or else the result will be unpredictable. This
 207   unpredictability arises because, for a sticky-write firmware
 208   volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
 209   state but it cannot flip it back again. In general, before
 210   calling the Write() function, the caller should call the
 211   EraseBlocks() function first to erase the specified block to
 212   write. A block erase cycle will transition bits from the
 213   (NOT)EFI_FVB_ERASE_POLARITY state back to the
 214   EFI_FVB_ERASE_POLARITY state. Implementations should be
 215   mindful that the firmware volume might be in the WriteDisabled
 216   state. If it is in this state, the Write() function must
 217   return the status code EFI_ACCESS_DENIED without modifying the
 218   contents of the firmware volume. The Write() function must
 219   also prevent spanning block boundaries. If a write is
 220   requested that spans a block boundary, the write must store up
 221   to the boundary but not beyond. The output parameter NumBytes
 222   must be set to correctly indicate the number of bytes actually
 223   written. The caller must be aware that a write may be
 224   partially completed. All writes, partial or otherwise, must be
 225   fully flushed to the hardware before the Write() service
 226   returns.
 227
 228   @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
 229
 230   @param Lba      The starting logical block index to write to.
 231
 232   @param Offset   Offset into the block at which to begin writing.
 233
 234   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 235                   contains the total size of the buffer. At
 236                   exit, *NumBytes contains the total number of
 237                   bytes actually written.
 238
 239   @param Buffer   Pointer to a caller-allocated buffer that
 240                   contains the source for the write.
 241
 242   @retval EFI_SUCCESS         The firmware volume was written successfully.
 243
 244   @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
 245                               LBA boundary. On output, NumBytes
 246                               contains the total number of bytes
 247                               actually written.
 248
 249   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 250                               WriteDisabled state.
 251
 252   @retval EFI_DEVICE_ERROR    The block device is malfunctioning
 253                               and could not be written.
 254
 255
 256 **/
 257 typedef
 258 EFI_STATUS
 259 (EFIAPI * EFI_FVB_WRITE)(
 260   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 261   IN        EFI_LBA                             Lba,
 262   IN        UINTN                               Offset,
 263   IN OUT    UINTN                               *NumBytes,
 264   IN        UINT8                               *Buffer
 265 );
 266
 267
 268
 269
 270 ///
 271 /// EFI_LBA_LIST_TERMINATOR
 272 ///
 273 #define EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
 274
 275
 276 /**
 277   Erases and initializes a firmware volume block.
 278
 279   The EraseBlocks() function erases one or more blocks as denoted
 280   by the variable argument list. The entire parameter list of
 281   blocks must be verified before erasing any blocks. If a block is
 282   requested that does not exist within the associated firmware
 283   volume (it has a larger index than the last block of the
 284   firmware volume), the EraseBlocks() function must return the
 285   status code EFI_INVALID_PARAMETER without modifying the contents
 286   of the firmware volume. Implementations should be mindful that
 287   the firmware volume might be in the WriteDisabled state. If it
 288   is in this state, the EraseBlocks() function must return the
 289   status code EFI_ACCESS_DENIED without modifying the contents of
 290   the firmware volume. All calls to EraseBlocks() must be fully
 291   flushed to the hardware before the EraseBlocks() service
 292   returns.
 293
 294   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 295                 instance.
 296
 297   @param ...    The variable argument list is a list of tuples.
 298                 Each tuple describes a range of LBAs to erase
 299                 and consists of the following:
 300                 - An EFI_LBA that indicates the starting LBA
 301                 - A UINTN that indicates the number of blocks to
 302                   erase
 303
 304                 The list is terminated with an
 305                 EFI_LBA_LIST_TERMINATOR. For example, the
 306                 following indicates that two ranges of blocks
 307                 (5-7 and 10-11) are to be erased: EraseBlocks
 308                 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
 309
 310   @retval EFI_SUCCESS The erase request was successfully
 311                       completed.
 312
 313   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 314                               WriteDisabled state.
 315   @retval EFI_DEVICE_ERROR  The block device is not functioning
 316                             correctly and could not be written.
 317                             The firmware device may have been
 318                             partially erased.
 319   @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
 320                                 in the variable argument list do
 321                                 not exist in the firmware volume.
 322
 323 **/
 324 typedef
 325 EFI_STATUS
 326 (EFIAPI * EFI_FVB_ERASE_BLOCKS)(
 327   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 328   ...
 329 );
 330
 331 ///
 332 /// The Firmware Volume Block Protocol is the low-level interface
 333 /// to a firmware volume. File-level access to a firmware volume
 334 /// should not be done using the Firmware Volume Block Protocol.
 335 /// Normal access to a firmware volume must use the Firmware
 336 /// Volume Protocol. Typically, only the file system driver that
 337 /// produces the Firmware Volume Protocol will bind to the
 338 /// Firmware Volume Block Protocol.
 339 ///
 340 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 341   EFI_FVB_GET_ATTRIBUTES        GetAttributes;
 342   EFI_FVB_SET_ATTRIBUTES        SetAttributes;
 343   EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 344   EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 345   EFI_FVB_READ                  Read;
 346   EFI_FVB_WRITE                 Write;
 347   EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 348   ///
 349   /// Handle of the parent firmware volume.
 350   ///
 351   EFI_HANDLE                    ParentHandle;
 352 };
 353
 354
 355 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;
 356
 357
 358 #endif