X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FFirmwareVolumeBlock.h;h=9d4f6ebac0323835c5c8bc0e133dbc4f03cefb1b;hp=0c3d03276b290028f780e116e7b97ed8ffd6befe;hb=9344f0921518309295da89c221d10cbead8531aa;hpb=0647c9adf92c6a8712091607a73b2768327a865d diff --git a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h index 0c3d03276b..9d4f6ebac0 100644 --- a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h +++ b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h @@ -1,251 +1,360 @@ /** @file - This file declares Firmware Volume Block protocol. + This file provides control over block-oriented firmware devices. - Low level firmware device access routines to abstract firmware device - hardware. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
+SPDX-License-Identifier: BSD-2-Clause-Patent - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - Module Name: FirmwareVolumeBlock.h - - @par Revision Reference: - This protocol is defined in Framework of EFI Firmware Volume Block specification. - Version 0.9 + @par Revision Reference: PI + Version 1.0 and 1.2. **/ #ifndef __FIRMWARE_VOLUME_BLOCK_H__ #define __FIRMWARE_VOLUME_BLOCK_H__ - +// +// EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL is defined in PI 1.0 spec and its GUID value +// is later updated to be the same as that of EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL +// defined in PI 1.2 spec. +// #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \ - { \ - 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD, 0xB5, 0x8D, 0xA1 } \ - } + { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } } + +#define EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL_GUID \ + { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } } + +typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL; -typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL; +typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL; /** - Retrieves Volume attributes. No polarity translations are done. + The GetAttributes() function retrieves the attributes and + current settings of the block. - @param This Calling context - @param Attributes output buffer which contains attributes + @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - @retval EFI_INVALID_PARAMETER - @retval EFI_SUCCESS + @param Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the + attributes and current settings are + returned. Type EFI_FVB_ATTRIBUTES_2 is defined + in EFI_FIRMWARE_VOLUME_HEADER. + + @retval EFI_SUCCESS The firmware volume attributes were + returned. **/ typedef EFI_STATUS -(EFIAPI *EFI_FVB_GET_ATTRIBUTES) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - OUT EFI_FVB_ATTRIBUTES *Attributes - ) -; +(EFIAPI * EFI_FVB_GET_ATTRIBUTES)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + OUT EFI_FVB_ATTRIBUTES_2 *Attributes +); + /** - Sets Volume attributes. No polarity translations are done. + The SetAttributes() function sets configurable firmware volume + attributes and returns the new settings of the firmware volume. + + @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - @param This Calling context - @param Attributes On input: contains new attributes - On output: contains current attributes of FV + @param Attributes On input, Attributes is a pointer to + EFI_FVB_ATTRIBUTES_2 that contains the + desired firmware volume settings. On + successful return, it contains the new + settings of the firmware volume. Type + EFI_FVB_ATTRIBUTES_2 is defined in + EFI_FIRMWARE_VOLUME_HEADER. - @retval EFI_INVALID_PARAMETER - @retval EFI_SUCCESS + @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 *EFI_FVB_SET_ATTRIBUTES) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - IN OUT EFI_FVB_ATTRIBUTES *Attributes - ) -; +(EFIAPI * EFI_FVB_SET_ATTRIBUTES)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + IN OUT EFI_FVB_ATTRIBUTES_2 *Attributes +); + /** - Retrieves the physical address of a memory mapped FV. + 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 Calling context - @param Attributes Address is a pointer to a caller allocated EFI_PHYSICAL_ADDRESS - that on successful return from GetPhysicalAddress() contains the - base address of the firmware volume. + @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - @retval EFI_UNSUPPORTED - @retval EFI_SUCCESS + @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 was returned. + + @retval EFI_UNSUPPORTED The firmware volume is not memory mapped. **/ typedef EFI_STATUS -(EFIAPI *EFI_FVB_GET_PHYSICAL_ADDRESS) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - OUT EFI_PHYSICAL_ADDRESS *Address - ) -; +(EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + OUT EFI_PHYSICAL_ADDRESS *Address +); /** - Retrieves the size in bytes of a specific block within an FV. + 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 Calling context. - @param Lba Indicates which block to return the size for. - @param BlockSize BlockSize is a pointer to a caller allocated - UINTN in which the size of the block is returned. - @param NumberOfBlocks NumberOfBlocks is a 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_INVALID_PARAMETER - @retval EFI_SUCCESS + @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_FVB_GET_BLOCK_SIZE) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - IN EFI_LBA Lba, - OUT UINTN *BlockSize, - OUT UINTN *NumberOfBlocks - ) -; + @param Lba Indicates the block for which to return the size. -/** - Reads data beginning at Lba:Offset from FV and places the data in Buffer. - The read terminates either when *NumBytes of data have been read, or when - a block boundary is reached. *NumBytes is updated to reflect the actual - number of bytes read. - - @param This Calling context - @param Lba Block in which to begin read - @param Offset Offset in the block at which to begin read - @param NumBytes At input, indicates the requested read size. At output, indicates - the actual number of bytes read. - @param Buffer Data buffer in which to place data read. - - @retval EFI_INVALID_PARAMETER - @retval EFI_NOT_FOUND - @retval EFI_DEVICE_ERROR - @retval EFI_SUCCESS + @param BlockSize Pointer to a caller-allocated UINTN in which + the size of the block is returned. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_FVB_READ) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - IN EFI_LBA Lba, - IN UINTN Offset, - IN OUT UINTN *NumBytes, - OUT UINT8 *Buffer - ) -; + @param NumberOfBlocks 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. -/** - Writes data beginning at Lba:Offset from FV. The write terminates either - when *NumBytes of data have been written, or when a block boundary is - reached. *NumBytes is updated to reflect the actual number of bytes - written. - - @param This Calling context - @param Lba Block in which to begin write - @param Offset Offset in the block at which to begin write - @param NumBytes At input, indicates the requested write size. At output, indicates - the actual number of bytes written. - @param Buffer Buffer containing source data for the write. - - @retval EFI_INVALID_PARAMETER - @retval EFI_NOT_FOUND - @retval EFI_DEVICE_ERROR - @retval EFI_SUCCESS + + @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 *EFI_FVB_WRITE) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - IN EFI_LBA Lba, - IN UINTN Offset, - IN OUT UINTN *NumBytes, - IN UINT8 *Buffer - ) -; +(EFIAPI * EFI_FVB_GET_BLOCK_SIZE)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + IN EFI_LBA Lba, + OUT UINTN *BlockSize, + OUT UINTN *NumberOfBlocks +); -#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL /** - The EraseBlock() function erases one or more blocks as denoted by the - variable argument list. The entire parameter list of blocks must be verified - prior to 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 EraseBlock() function must return - EFI_INVALID_PARAMETER without modifying the contents of the firmware volume. - - @param This Calling context - @param ... Starting LBA followed by Number of Lba to erase. a -1 to terminate - the list. - - @retval EFI_INVALID_PARAMETER - @retval EFI_DEVICE_ERROR - @retval EFI_SUCCESS - @retval EFI_ACCESS_DENIED + 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 EFI_FIRMWARE_VOLUME_BLOCK2_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 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 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 Read 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 *EFI_FVB_ERASE_BLOCKS) ( - IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This, - ... - ) -; +(EFIAPI *EFI_FVB_READ)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + IN EFI_LBA Lba, + IN UINTN Offset, + IN OUT UINTN *NumBytes, + IN OUT UINT8 *Buffer +); /** - @par Protocol Description: - This protocol provides control over block-oriented firmware devices. - Typically, the FFS (or an alternate file system) driver consumes the - Firmware Volume Block Protocol and produces the Firmware Volume Protocol. + 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. Before calling the + Write() function, it is recommended for the caller to first call + the EraseBlocks() function 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. Implementations should be + mindful 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 EFI_FIRMWARE_VOLUME_BLOCK2_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. At entry, *NumBytes + contains the total size of the buffer. At + exit, *NumBytes contains 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. - @param GetAttributes - Retrieves the current volume attributes. - @param SetAttributes - Sets the current volume attributes. +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_FVB_WRITE)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, + IN EFI_LBA Lba, + IN UINTN Offset, + IN OUT UINTN *NumBytes, + IN UINT8 *Buffer +); - @param GetPhysicalAddress - Retrieves the memory-mapped address of the firmware volume. - @param GetBlockSize - Retrieves the size for a specific block. - @param Read - Reads n bytes into a buffer from the firmware volume hardware. - @param Write - Writes n bytes from a buffer into the firmware volume hardware. +/// +/// EFI_LBA_LIST_TERMINATOR +/// +#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL - @param EraseBlocks - Erases specified block(s) and sets all values as indicated by - the EFI_FVB_ERASE_POLARITY bit. - @param ParentHandle - Handle of the parent firmware volume. +/** + 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. Implementations should be mindful 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 EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL + instance. + + @param ... The variable argument list is 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. **/ -struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL { - EFI_FVB_GET_ATTRIBUTES GetVolumeAttributes; - EFI_FVB_SET_ATTRIBUTES SetVolumeAttributes; +typedef +EFI_STATUS +(EFIAPI * EFI_FVB_ERASE_BLOCKS)( + IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_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 _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL{ + EFI_FVB_GET_ATTRIBUTES GetAttributes; + EFI_FVB_SET_ATTRIBUTES SetAttributes; EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress; EFI_FVB_GET_BLOCK_SIZE GetBlockSize; EFI_FVB_READ Read; EFI_FVB_WRITE Write; EFI_FVB_ERASE_BLOCKS EraseBlocks; + /// + /// The handle of the parent firmware volume. + /// EFI_HANDLE ParentHandle; }; + extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid; +extern EFI_GUID gEfiFirmwareVolumeBlock2ProtocolGuid; #endif