MdePkg/Include/Protocol/FirmwareVolumeBlock.h

   1 /** @file
   2   This file provides control over block-oriented firmware devices.
   3
   4   Copyright (c) 2006 - 2007, 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   Module Name:  FirmwareVolumeBlock.h
  14
  15   @par Revision Reference: PI
  16   Version 1.00.
  17
  18 **/
  19
  20 #ifndef __FIRMWARE_VOLUME_BLOCK_H__
  21 #define __FIRMWARE_VOLUME_BLOCK_H__
  22
  23
  24 #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
  25   { 0xDE28BC59, 0x6228, 0x41BD, 0xBD, {0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }
  26
  27
  28 typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  29
  30 /**
  31   The GetAttributes() function retrieves the attributes and
  32   current settings of the block. Status Codes Returned
  33
  34   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
  35                 instance.
  36
  37   @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
  38                     attributes and current settings are
  39                     returned. Type EFI_FVB_ATTRIBUTES is defined
  40                     in EFI_FIRMWARE_VOLUME_HEADER.
  41
  42   @retval EFI_SUCCESS The firmware volume attributes were
  43                       returned.
  44
  45 **/
  46 typedef
  47 EFI_STATUS
  48 (EFIAPI * EFI_FVB_GET_ATTRIBUTES) (
  49   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  50   OUT       EFI_FVB_ATTRIBUTES                  *Attributes
  51 );
  52
  53
  54 /**
  55   The SetAttributes() function sets configurable firmware volume
  56   attributes and returns the new settings of the firmware volume.
  57
  58   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
  59                 instance.
  60
  61   @param Attributes   On input, Attributes is a pointer to
  62                       EFI_FVB_ATTRIBUTES that contains the
  63                       desired firmware volume settings. On
  64                       successful return, it contains the new
  65                       settings of the firmware volume. Type
  66                       EFI_FVB_ATTRIBUTES is defined in
  67                       EFI_FIRMWARE_VOLUME_HEADER.
  68
  69
  70   @retval EFI_SUCCESS The firmware volume attributes were
  71                       returned.
  72
  73   @retval EFI_INVALID_PARAMETER The attributes requested are in
  74                                 conflict with the capabilities
  75                                 as declared in the firmware
  76                                 volume header.
  77
  78 **/
  79 typedef
  80 EFI_STATUS
  81 (EFIAPI * EFI_FVB_SET_ATTRIBUTES) (
  82   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
  83   IN OUT    EFI_FVB_ATTRIBUTES                  *Attributes
  84 );
  85
  86
  87 /**
  88   The GetPhysicalAddress() function retrieves the base address of
  89   a memory-mapped firmware volume. This function should be called
  90   only for memory-mapped firmware volumes.
  91
  92   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
  93                 nstance.
  94
  95   @param Address  Pointer to a caller-allocated
  96                   EFI_PHYSICAL_ADDRESS that, on successful
  97                   return from GetPhysicalAddress(), contains the
  98                   base address of the firmware volume. Type
  99                   EFI_PHYSICAL_ADDRESS is defined in
 100                   AllocatePages() in the UEFI 2.0 specification.
 101
 102   @retval EFI_SUCCESS The firmware volume base address is
 103                       returned.
 104
 105   @retval EFI_NOT_SUPPORTED The firmware volume is not memory
 106                             mapped.
 107
 108
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS) (
 113   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 114   OUT       EFI_PHYSICAL_ADDRESS                *Address
 115 );
 116
 117 /**
 118   The GetBlockSize() function retrieves the size of the requested
 119   block. It also returns the number of additional blocks with
 120   the identical size. The GetBlockSize() function is used to
 121   retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
 122
 123
 124   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 125                 instance.
 126
 127   @param Lba  Indicates the block for which to return the size.
 128               Type EFI_LBA is defined in the BLOCK_IO Protocol
 129               (section 11.6) in the UEFI 2.0 specification.
 130
 131   @param BlockSize  Pointer to a caller-allocated UINTN in which
 132                     the size of the block is returned.
 133
 134   @param NumberOfBlocks Pointer to a caller-allocated UINTN in
 135                         which the number of consecutive blocks,
 136                         starting with Lba, is returned. All
 137                         blocks in this range have a size of
 138                         BlockSize.
 139
 140
 141   @retval EFI_SUCCESS The firmware volume base address is
 142                       returned.
 143
 144   @retval EFI_INVALID_PARAMETER   The requested LBA is out of
 145                                   range.
 146
 147 **/
 148 typedef
 149 EFI_STATUS
 150 (EFIAPI * EFI_FVB_GET_BLOCK_SIZE) (
 151   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 152   IN CONST  EFI_LBA                             Lba,
 153   OUT       UINTN                               *BlockSize,
 154   OUT       UINTN                               *NumberOfBlocks
 155 );
 156
 157
 158 /**
 159   The Read() function reads the requested number of bytes from the
 160   requested block and stores them in the provided buffer.
 161   Implementations should be mindful that the firmware volume
 162   might be in the ReadDisabled state. If it is in this state,
 163   the Read() function must return the status code
 164   EFI_ACCESS_DENIED without modifying the contents of the
 165   buffer. The Read() function must also prevent spanning block
 166   boundaries. If a read is requested that would span a block
 167   boundary, the read must read up to the boundary but not
 168   beyond. The output parameter NumBytes must be set to correctly
 169   indicate the number of bytes actually read. The caller must be
 170   aware that a read may be partially completed.
 171
 172   @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 173               instance. Lba The starting logical block index
 174               from which to read. Type EFI_LBA is defined in the
 175               BLOCK_IO Protocol (section 11.6) in the UEFI 2.0
 176               specification.
 177
 178   @param Offset Offset into the block at which to begin reading.
 179
 180   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 181                   contains the total size of the buffer. At
 182                   exit, *NumBytes contains the total number of
 183                   bytes read.
 184
 185   @param Buffer   Pointer to a caller-allocated buffer that will
 186                   be used to hold the data that is read.
 187
 188   @retval EFI_SUCCESS The firmware volume was read successfully
 189                       and contents are in Buffer.
 190
 191   @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
 192                               boundary. On output, NumBytes
 193                               contains the total number of bytes
 194                               returned in Buffer.
 195
 196   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 197                               ReadDisabled state.
 198
 199   @retval EFI_DEVICE_ERROR    The block device is not
 200                               functioning correctly and could
 201                               not be read.
 202
 203 **/
 204 typedef
 205 EFI_STATUS
 206 (EFIAPI *EFI_FVB_READ) (
 207   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 208   IN CONST  EFI_LBA                             Lba,
 209   IN CONST  UINTN                               Offset,
 210   IN OUT    UINTN                               *NumBytes,
 211   OUT       UINT8                               *Buffer
 212 );
 213
 214
 215
 216 /**
 217   The Write() function writes the specified number of bytes from
 218   the provided buffer to the specified block and offset. If the
 219   firmware volume is sticky write, the caller must ensure that
 220   all the bits of the specified range to write are in the
 221   EFI_FVB_ERASE_POLARITY state before calling the Write()
 222   function, or else the result will be unpredictable. This
 223   unpredictability arises because, for a sticky-write firmware
 224   volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
 225   state but it cannot flip it back again. In general, before
 226   calling the Write() function, the caller should call the
 227   EraseBlocks() function first to erase the specified block to
 228   write. A block erase cycle will transition bits from the
 229   (NOT)EFI_FVB_ERASE_POLARITY state back to the
 230   EFI_FVB_ERASE_POLARITY state. Implementations should be
 231   mindful that the firmware volume might be in the WriteDisabled
 232   state. If it is in this state, the Write() function must
 233   return the status code EFI_ACCESS_DENIED without modifying the
 234   contents of the firmware volume. The Write() function must
 235   also prevent spanning block boundaries. If a write is
 236   requested that spans a block boundary, the write must store up
 237   to the boundary but not beyond. The output parameter NumBytes
 238   must be set to correctly indicate the number of bytes actually
 239   written. The caller must be aware that a write may be
 240   partially completed. All writes, partial or otherwise, must be
 241   fully flushed to the hardware before the Write() service
 242   returns.
 243
 244   @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 245               instance.
 246
 247   @param Lba  The starting logical block index to write to. Type
 248               EFI_LBA is defined in the BLOCK_IO Protocol
 249               (section 11.6) in the UEFI 2.0 specification.
 250               Offset Offset into the block at which to begin
 251               writing.
 252
 253   @param NumBytes Pointer to a UINTN. At entry, *NumBytes
 254                   contains the total size of the buffer. At
 255                   exit, *NumBytes contains the total number of
 256                   bytes actually written.
 257
 258   @param Buffer Pointer to a caller-allocated buffer that
 259                 contains the source for the write.
 260
 261   @retval EFI_SUCCESS The firmware volume was written
 262                       successfully.
 263
 264   @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
 265                               LBA boundary. On output, NumBytes
 266                               contains the total number of bytes
 267                               actually written.
 268
 269   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 270                               WriteDisabled state.
 271
 272   @retval EFI_DEVICE_ERROR    The block device is malfunctioning
 273                               and could not be written.
 274
 275
 276 **/
 277 typedef
 278 EFI_STATUS
 279 (EFIAPI * EFI_FVB_WRITE) (
 280   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 281   IN CONST  EFI_LBA                             Lba,
 282   IN CONST  UINTN                               Offset,
 283   IN OUT    UINTN                               *NumBytes,
 284   IN CONST  UINT8                               *Buffer
 285 );
 286
 287
 288
 289
 290 //
 291 // EFI_LBA_LIST_TERMINATOR
 292 //
 293 #define EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
 294
 295
 296 /**
 297   The EraseBlocks() function erases one or more blocks as denoted
 298   by the variable argument list. The entire parameter list of
 299   blocks must be verified before erasing any blocks. If a block is
 300   requested that does not exist within the associated firmware
 301   volume (it has a larger index than the last block of the
 302   firmware volume), the EraseBlocks() function must return the
 303   status code EFI_INVALID_PARAMETER without modifying the contents
 304   of the firmware volume. Implementations should be mindful that
 305   the firmware volume might be in the WriteDisabled state. If it
 306   is in this state, the EraseBlocks() function must return the
 307   status code EFI_ACCESS_DENIED without modifying the contents of
 308   the firmware volume. All calls to EraseBlocks() must be fully
 309   flushed to the hardware before the EraseBlocks() service
 310   returns.
 311
 312   @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
 313                 instance.
 314
 315   @param ...    The variable argument list is a list of tuples.
 316                 Each tuple describes a range of LBAs to erase
 317                 and consists of the following:
 318                 - An EFI_LBA that indicates the starting LBA
 319                 - A UINTN that indicates the number of blocks to
 320                   erase
 321
 322                 The list is terminated with an
 323                 EFI_LBA_LIST_TERMINATOR. For example, the
 324                 following indicates that two ranges of blocks
 325                 (5-7 and 10-11) are to be erased: EraseBlocks
 326                 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
 327
 328   @retval EFI_SUCCESS The erase request was successfully
 329                       completed.
 330
 331   @retval EFI_ACCESS_DENIED   The firmware volume is in the
 332                               WriteDisabled state.
 333   @retval EFI_DEVICE_ERROR  The block device is not functioning
 334                             correctly and could not be written.
 335                             The firmware device may have been
 336                             partially erased.
 337   @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
 338                                 in the variable argument list do
 339                                 not exist in the firmware volume.
 340
 341 **/
 342 typedef
 343 EFI_STATUS
 344 (EFIAPI * EFI_FVB_ERASE_BLOCKS) (
 345   IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
 346   ...
 347 );
 348
 349
 350
 351 /**
 352   The Firmware Volume Block Protocol is the low-level interface
 353   to a firmware volume. File-level access to a firmware volume
 354   should not be done using the Firmware Volume Block Protocol.
 355   Normal access to a firmware volume must use the Firmware
 356   Volume Protocol. Typically, only the file system driver that
 357   produces the Firmware Volume Protocol will bind to the
 358   Firmware Volume Block Protocol. The Firmware Volume Block
 359   Protocol provides the following:
 360   - Byte-level read/write functionality.
 361   - Block-level erase functionality.
 362   - It further exposes device-hardening features, such as may be
 363     equired to protect the firmware from unwanted overwriting
 364     and/or erasure.
 365   - It is useful to layer a file system driver on top of the
 366     Firmware Volume Block Protocol.
 367
 368   This file system driver produces the Firmware Volume Protocol,
 369   which provides file-level access to a firmware volume. The
 370   Firmware Volume Protocol abstracts the file system that is
 371   used to format the firmware volume and the hardware
 372   device-hardening features that may be present.
 373
 374
 375   @param GetPhysicalAddress   Retrieves the memory-mapped
 376                               address of the firmware volume.
 377                               See the GetPhysicalAddress()
 378                               function description.
 379
 380   @param GetBlockSize   Retrieves the size for a specific block.
 381                         Also returns the number of consecutive
 382                         similarly sized blocks. See the
 383                         GetBlockSize() function description.
 384
 385   @param Read   Reads n bytes into a buffer from the firmware
 386                 volume hardware. See the Read() function
 387                 description.
 388
 389   @param Write  Writes n bytes from a buffer into the firmware
 390                 volume hardware. See the Write() function
 391                 description.
 392
 393   @param EraseBlocks  Erases specified block(s) and sets all
 394                       values as indicated by the
 395                       EFI_FVB_ERASE_POLARITY bit. See the
 396                       EraseBlocks() function description. Type
 397                       EFI_FVB_ERASE_POLARITY is defined in
 398                       EFI_FIRMWARE_VOLUME_HEADER. ParentHandle
 399                       Handle of the parent firmware volume. Type
 400                       EFI_HANDLE is defined in
 401                       InstallProtocolInterface() in the UEFI 2.0
 402                       specification.
 403
 404   @param GetAttributes Retrieves the current volume attributes.
 405                        See the GetAttributes() function
 406                        description.
 407
 408   @param SetAttributes Sets the current volume attributes. See
 409                        the SetAttributes() function description.
 410
 411
 412 **/
 413 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
 414   EFI_FVB_GET_ATTRIBUTES        GetAttributes;
 415   EFI_FVB_SET_ATTRIBUTES        SetAttributes;
 416   EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
 417   EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
 418   EFI_FVB_READ                  Read;
 419   EFI_FVB_WRITE                 Write;
 420   EFI_FVB_ERASE_BLOCKS          EraseBlocks;
 421   EFI_HANDLE                    ParentHandle;
 422 };
 423
 424
 425 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;
 426
 427
 428 #endif