--- /dev/null
+/** @file\r
+ This file provides control over block-oriented firmware devices.\r
+\r
+ Copyright (c) 2006 - 2008, Intel Corporation \r
+ All rights reserved. This program and the accompanying materials \r
+ are licensed and made available under the terms and conditions of the BSD License \r
+ which accompanies this distribution. The full text of the license may be found at \r
+ http://opensource.org/licenses/bsd-license.php \r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \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
+#include <PiDxe.h>\r
+\r
+typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;\r
+///\r
+/// type of EFI FVB attribute per Frameowrk spec\r
+/// \r
+typedef UINT32 EFI_FVB_ATTRIBUTES;\r
+\r
+/**\r
+ The GetAttributes() function retrieves the attributes and\r
+ current settings of the block. Status Codes Returned\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 Pointer to a caller-allocated UINTN in which\r
+ the size of the block is returned.\r
+\r
+ @param NumberOfBlocks 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 is 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 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 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 Read 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. Implementations should be\r
+ mindful 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 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 actually written.\r
+ \r
+ @param Buffer 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. Implementations should be mindful 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 ... The variable argument list is 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 was 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
+ /// Handle of the parent firmware volume.\r
+ /// \r
+ EFI_HANDLE ParentHandle;\r
+};\r
+\r
+\r
+\r
+#endif\r
projects / mirror_edk2.git / commitdiff