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