123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347 |
- /** @file
- This file provides control over block-oriented firmware devices.
- Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
- @par Revision Reference:
- This protocol is defined in framework spec: Firmware Volume Block Specification.
- **/
- #ifndef __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
- #define __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
- #define FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
- { 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }
- typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
- ///
- /// The type of EFI FVB attribute per the Framework specification.
- ///
- typedef UINT32 EFI_FVB_ATTRIBUTES;
- /**
- The GetAttributes() function retrieves the attributes and
- current settings of the block.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
- attributes and current settings are
- returned.
- @retval EFI_SUCCESS The firmware volume attributes were
- returned.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_GET_ATTRIBUTES)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- OUT EFI_FVB_ATTRIBUTES *Attributes
- );
- /**
- The SetAttributes() function sets configurable firmware volume
- attributes and returns the new settings of the firmware volume.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Attributes On input, Attributes is a pointer to
- EFI_FVB_ATTRIBUTES that contains the
- desired firmware volume settings. On
- successful return, it contains the new
- settings of the firmware volume.
- @retval EFI_SUCCESS The firmware volume attributes were returned.
- @retval EFI_INVALID_PARAMETER The attributes requested are in
- conflict with the capabilities
- as declared in the firmware
- volume header.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_SET_ATTRIBUTES)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- IN OUT EFI_FVB_ATTRIBUTES *Attributes
- );
- /**
- The GetPhysicalAddress() function retrieves the base address of
- a memory-mapped firmware volume. This function should be called
- only for memory-mapped firmware volumes.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Address Pointer to a caller-allocated
- EFI_PHYSICAL_ADDRESS that, on successful
- return from GetPhysicalAddress(), contains the
- base address of the firmware volume.
- @retval EFI_SUCCESS The firmware volume base address is returned.
- @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- OUT EFI_PHYSICAL_ADDRESS *Address
- );
- /**
- The GetBlockSize() function retrieves the size of the requested
- block. It also returns the number of additional blocks with
- the identical size. The GetBlockSize() function is used to
- retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Lba Indicates the block for which to return the size.
- @param BlockSize The pointer to a caller-allocated UINTN in which
- the size of the block is returned.
- @param NumberOfBlocks The pointer to a caller-allocated UINTN in
- which the number of consecutive blocks,
- starting with Lba, is returned. All
- blocks in this range have a size of
- BlockSize.
- @retval EFI_SUCCESS The firmware volume base address was returned.
- @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- IN EFI_LBA Lba,
- OUT UINTN *BlockSize,
- OUT UINTN *NumberOfBlocks
- );
- /**
- Reads the specified number of bytes into a buffer from the specified block.
- The Read() function reads the requested number of bytes from the
- requested block and stores them in the provided buffer.
- Implementations should be mindful that the firmware volume
- might be in the ReadDisabled state. If it is in this state,
- the Read() function must return the status code
- EFI_ACCESS_DENIED without modifying the contents of the
- buffer. The Read() function must also prevent spanning block
- boundaries. If a read is requested that would span a block
- boundary, the read must read up to the boundary but not
- beyond. The output parameter NumBytes must be set to correctly
- indicate the number of bytes actually read. The caller must be
- aware that a read may be partially completed.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Lba The starting logical block index
- from which to read.
- @param Offset Offset into the block at which to begin reading.
- @param NumBytes The pointer to a UINTN. At entry, *NumBytes
- contains the total size of the buffer. At
- exit, *NumBytes contains the total number of
- bytes read.
- @param Buffer The pointer to a caller-allocated buffer that will
- be used to hold the data that is read.
- @retval EFI_SUCCESS The firmware volume was read successfully
- and contents are in Buffer.
- @retval EFI_BAD_BUFFER_SIZE A read was attempted across an LBA
- boundary. On output, NumBytes
- contains the total number of bytes
- returned in Buffer.
- @retval EFI_ACCESS_DENIED The firmware volume is in the
- ReadDisabled state.
- @retval EFI_DEVICE_ERROR The block device is not
- functioning correctly and could
- not be read.
- **/
- typedef
- EFI_STATUS
- (EFIAPI *FRAMEWORK_EFI_FVB_READ)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- IN EFI_LBA Lba,
- IN UINTN Offset,
- IN OUT UINTN *NumBytes,
- IN OUT UINT8 *Buffer
- );
- /**
- Writes the specified number of bytes from the input buffer to the block.
- The Write() function writes the specified number of bytes from
- the provided buffer to the specified block and offset. If the
- firmware volume is sticky write, the caller must ensure that
- all the bits of the specified range to write are in the
- EFI_FVB_ERASE_POLARITY state before calling the Write()
- function, or else the result will be unpredictable. This
- unpredictability arises because, for a sticky-write firmware
- volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
- state but cannot flip it back again. In general, before
- calling the Write() function, the caller should call the
- EraseBlocks() function first to erase the specified block to
- write. A block erase cycle will transition bits from the
- (NOT)EFI_FVB_ERASE_POLARITY state back to the
- EFI_FVB_ERASE_POLARITY state. Implementors should note
- that the firmware volume might be in the WriteDisabled
- state. If it is in this state, the Write() function must
- return the status code EFI_ACCESS_DENIED without modifying the
- contents of the firmware volume. The Write() function must
- also prevent spanning block boundaries. If a write is
- requested that spans a block boundary, the write must store up
- to the boundary but not beyond. The output parameter NumBytes
- must be set to correctly indicate the number of bytes actually
- written. The caller must be aware that a write may be
- partially completed. All writes, partial or otherwise, must be
- fully flushed to the hardware before the Write() service
- returns.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
- @param Lba The starting logical block index to write to.
- @param Offset Offset into the block at which to begin writing.
- @param NumBytes The pointer to a UINTN. Input: the total size of the buffer.
- Output: the total number of bytes actually written.
- @param Buffer The pointer to a caller-allocated buffer that
- contains the source for the write.
- @retval EFI_SUCCESS The firmware volume was written successfully.
- @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
- LBA boundary. On output, NumBytes
- contains the total number of bytes
- actually written.
- @retval EFI_ACCESS_DENIED The firmware volume is in the
- WriteDisabled state.
- @retval EFI_DEVICE_ERROR The block device is malfunctioning
- and could not be written.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_WRITE)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- IN EFI_LBA Lba,
- IN UINTN Offset,
- IN OUT UINTN *NumBytes,
- IN UINT8 *Buffer
- );
- ///
- /// EFI_LBA_LIST_TERMINATOR.
- ///
- #define FRAMEWORK_EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL
- /**
- Erases and initializes a firmware volume block.
- The EraseBlocks() function erases one or more blocks as denoted
- by the variable argument list. The entire parameter list of
- blocks must be verified before erasing any blocks. If a block is
- requested that does not exist within the associated firmware
- volume (it has a larger index than the last block of the
- firmware volume), the EraseBlocks() function must return the
- status code EFI_INVALID_PARAMETER without modifying the contents
- of the firmware volume. Implementors should note that
- the firmware volume might be in the WriteDisabled state. If it
- is in this state, the EraseBlocks() function must return the
- status code EFI_ACCESS_DENIED without modifying the contents of
- the firmware volume. All calls to EraseBlocks() must be fully
- flushed to the hardware before the EraseBlocks() service
- returns.
- @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
- instance.
- @param ... A list of tuples.
- Each tuple describes a range of LBAs to erase
- and consists of the following:
- - An EFI_LBA that indicates the starting LBA
- - A UINTN that indicates the number of blocks to
- erase
- The list is terminated with an
- EFI_LBA_LIST_TERMINATOR. For example, the
- following indicates that two ranges of blocks
- (5-7 and 10-11) are to be erased: EraseBlocks
- (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
- @retval EFI_SUCCESS The erase request successfully
- completed.
- @retval EFI_ACCESS_DENIED The firmware volume is in the
- WriteDisabled state.
- @retval EFI_DEVICE_ERROR The block device is not functioning
- correctly and could not be written.
- The firmware device may have been
- partially erased.
- @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
- in the variable argument list do
- not exist in the firmware volume.
- **/
- typedef
- EFI_STATUS
- (EFIAPI * FRAMEWORK_EFI_FVB_ERASE_BLOCKS)(
- IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
- ...
- );
- ///
- /// The Firmware Volume Block Protocol is the low-level interface
- /// to a firmware volume. File-level access to a firmware volume
- /// should not be done using the Firmware Volume Block Protocol.
- /// Normal access to a firmware volume must use the Firmware
- /// Volume Protocol. Typically, only the file system driver that
- /// produces the Firmware Volume Protocol will bind to the
- /// Firmware Volume Block Protocol.
- ///
- struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
- FRAMEWORK_EFI_FVB_GET_ATTRIBUTES GetAttributes;
- FRAMEWORK_EFI_FVB_SET_ATTRIBUTES SetAttributes;
- FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress;
- FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE GetBlockSize;
- FRAMEWORK_EFI_FVB_READ Read;
- FRAMEWORK_EFI_FVB_WRITE Write;
- FRAMEWORK_EFI_FVB_ERASE_BLOCKS EraseBlocks;
- ///
- /// The handle of the parent firmware volume.
- ///
- EFI_HANDLE ParentHandle;
- };
- extern EFI_GUID gFramerworkEfiFirmwareVolumeBlockProtocolGuid;
- #endif
|