From 220c61c1ee7be1da282238fb62ad4e2d75ad887f Mon Sep 17 00:00:00 2001 From: jchen20 Date: Thu, 9 Jul 2009 07:43:00 +0000 Subject: [PATCH] Add the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL definition to comply with Framework spec git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8831 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Protocol/FrameworkFirmwareVolumeBlock.h | 354 ++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h new file mode 100644 index 0000000000..0d75e4b8f3 --- /dev/null +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h @@ -0,0 +1,354 @@ +/** @file + This file provides control over block-oriented firmware devices. + + Copyright (c) 2006 - 2008, 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. + + @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__ + +#include + +typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL; +/// +/// type of EFI FVB attribute per Frameowrk spec +/// +typedef UINT32 EFI_FVB_ATTRIBUTES; + +/** + The GetAttributes() function retrieves the attributes and + current settings of the block. Status Codes Returned + + @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 Pointer to a caller-allocated UINTN in which + the size of the block is returned. + + @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. + + + @retval EFI_SUCCESS The firmware volume base address is 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 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 *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. 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 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 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 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. 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 FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_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 was 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; + /// + /// Handle of the parent firmware volume. + /// + EFI_HANDLE ParentHandle; +}; + + + +#endif -- 2.39.2