2 This file provides control over block-oriented firmware devices.
4 Copyright (c) 2006 - 2008, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 @par Revision Reference:
14 This protocol is defined in framework spec: Firmware Volume Block specification
18 #ifndef __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
19 #define __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
23 typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
;
25 /// type of EFI FVB attribute per Frameowrk spec
27 typedef UINT32 EFI_FVB_ATTRIBUTES
;
30 The GetAttributes() function retrieves the attributes and
31 current settings of the block. Status Codes Returned
33 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
35 @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
36 attributes and current settings are
39 @retval EFI_SUCCESS The firmware volume attributes were
45 (EFIAPI
* FRAMEWORK_EFI_FVB_GET_ATTRIBUTES
)(
46 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
47 OUT EFI_FVB_ATTRIBUTES
*Attributes
52 The SetAttributes() function sets configurable firmware volume
53 attributes and returns the new settings of the firmware volume.
55 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
57 @param Attributes On input, Attributes is a pointer to
58 EFI_FVB_ATTRIBUTES that contains the
59 desired firmware volume settings. On
60 successful return, it contains the new
61 settings of the firmware volume.
63 @retval EFI_SUCCESS The firmware volume attributes were returned.
65 @retval EFI_INVALID_PARAMETER The attributes requested are in
66 conflict with the capabilities
67 as declared in the firmware
73 (EFIAPI
* FRAMEWORK_EFI_FVB_SET_ATTRIBUTES
)(
74 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
75 IN OUT EFI_FVB_ATTRIBUTES
*Attributes
80 The GetPhysicalAddress() function retrieves the base address of
81 a memory-mapped firmware volume. This function should be called
82 only for memory-mapped firmware volumes.
84 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
86 @param Address Pointer to a caller-allocated
87 EFI_PHYSICAL_ADDRESS that, on successful
88 return from GetPhysicalAddress(), contains the
89 base address of the firmware volume.
91 @retval EFI_SUCCESS The firmware volume base address is returned.
93 @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
98 (EFIAPI
* FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS
)(
99 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
100 OUT EFI_PHYSICAL_ADDRESS
*Address
104 The GetBlockSize() function retrieves the size of the requested
105 block. It also returns the number of additional blocks with
106 the identical size. The GetBlockSize() function is used to
107 retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
110 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
112 @param Lba Indicates the block for which to return the size.
114 @param BlockSize Pointer to a caller-allocated UINTN in which
115 the size of the block is returned.
117 @param NumberOfBlocks Pointer to a caller-allocated UINTN in
118 which the number of consecutive blocks,
119 starting with Lba, is returned. All
120 blocks in this range have a size of
124 @retval EFI_SUCCESS The firmware volume base address is returned.
126 @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
131 (EFIAPI
* FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE
)(
132 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
134 OUT UINTN
*BlockSize
,
135 OUT UINTN
*NumberOfBlocks
140 Reads the specified number of bytes into a buffer from the specified block.
142 The Read() function reads the requested number of bytes from the
143 requested block and stores them in the provided buffer.
144 Implementations should be mindful that the firmware volume
145 might be in the ReadDisabled state. If it is in this state,
146 the Read() function must return the status code
147 EFI_ACCESS_DENIED without modifying the contents of the
148 buffer. The Read() function must also prevent spanning block
149 boundaries. If a read is requested that would span a block
150 boundary, the read must read up to the boundary but not
151 beyond. The output parameter NumBytes must be set to correctly
152 indicate the number of bytes actually read. The caller must be
153 aware that a read may be partially completed.
155 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
157 @param Lba The starting logical block index
160 @param Offset Offset into the block at which to begin reading.
162 @param NumBytes Pointer to a UINTN. At entry, *NumBytes
163 contains the total size of the buffer. At
164 exit, *NumBytes contains the total number of
167 @param Buffer Pointer to a caller-allocated buffer that will
168 be used to hold the data that is read.
170 @retval EFI_SUCCESS The firmware volume was read successfully
171 and contents are in Buffer.
173 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
174 boundary. On output, NumBytes
175 contains the total number of bytes
178 @retval EFI_ACCESS_DENIED The firmware volume is in the
181 @retval EFI_DEVICE_ERROR The block device is not
182 functioning correctly and could
188 (EFIAPI
*FRAMEWORK_EFI_FVB_READ
)(
189 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
192 IN OUT UINTN
*NumBytes
,
197 Writes the specified number of bytes from the input buffer to the block.
199 The Write() function writes the specified number of bytes from
200 the provided buffer to the specified block and offset. If the
201 firmware volume is sticky write, the caller must ensure that
202 all the bits of the specified range to write are in the
203 EFI_FVB_ERASE_POLARITY state before calling the Write()
204 function, or else the result will be unpredictable. This
205 unpredictability arises because, for a sticky-write firmware
206 volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
207 state but cannot flip it back again. In general, before
208 calling the Write() function, the caller should call the
209 EraseBlocks() function first to erase the specified block to
210 write. A block erase cycle will transition bits from the
211 (NOT)EFI_FVB_ERASE_POLARITY state back to the
212 EFI_FVB_ERASE_POLARITY state. Implementations should be
213 mindful that the firmware volume might be in the WriteDisabled
214 state. If it is in this state, the Write() function must
215 return the status code EFI_ACCESS_DENIED without modifying the
216 contents of the firmware volume. The Write() function must
217 also prevent spanning block boundaries. If a write is
218 requested that spans a block boundary, the write must store up
219 to the boundary but not beyond. The output parameter NumBytes
220 must be set to correctly indicate the number of bytes actually
221 written. The caller must be aware that a write may be
222 partially completed. All writes, partial or otherwise, must be
223 fully flushed to the hardware before the Write() service
226 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
228 @param Lba The starting logical block index to write to.
230 @param Offset Offset into the block at which to begin writing.
232 @param NumBytes Pointer to a UINTN. At entry, *NumBytes
233 contains the total size of the buffer. At
234 exit, *NumBytes contains the total number of
235 bytes actually written.
237 @param Buffer Pointer to a caller-allocated buffer that
238 contains the source for the write.
240 @retval EFI_SUCCESS The firmware volume was written successfully.
242 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
243 LBA boundary. On output, NumBytes
244 contains the total number of bytes
247 @retval EFI_ACCESS_DENIED The firmware volume is in the
250 @retval EFI_DEVICE_ERROR The block device is malfunctioning
251 and could not be written.
257 (EFIAPI
* FRAMEWORK_EFI_FVB_WRITE
)(
258 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
261 IN OUT UINTN
*NumBytes
,
269 /// EFI_LBA_LIST_TERMINATOR
271 #define FRAMEWORK_EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL
275 Erases and initializes a firmware volume block.
277 The EraseBlocks() function erases one or more blocks as denoted
278 by the variable argument list. The entire parameter list of
279 blocks must be verified before erasing any blocks. If a block is
280 requested that does not exist within the associated firmware
281 volume (it has a larger index than the last block of the
282 firmware volume), the EraseBlocks() function must return the
283 status code EFI_INVALID_PARAMETER without modifying the contents
284 of the firmware volume. Implementations should be mindful that
285 the firmware volume might be in the WriteDisabled state. If it
286 is in this state, the EraseBlocks() function must return the
287 status code EFI_ACCESS_DENIED without modifying the contents of
288 the firmware volume. All calls to EraseBlocks() must be fully
289 flushed to the hardware before the EraseBlocks() service
292 @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
295 @param ... The variable argument list is a list of tuples.
296 Each tuple describes a range of LBAs to erase
297 and consists of the following:
298 - An EFI_LBA that indicates the starting LBA
299 - A UINTN that indicates the number of blocks to
302 The list is terminated with an
303 EFI_LBA_LIST_TERMINATOR. For example, the
304 following indicates that two ranges of blocks
305 (5-7 and 10-11) are to be erased: EraseBlocks
306 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
308 @retval EFI_SUCCESS The erase request was successfully
311 @retval EFI_ACCESS_DENIED The firmware volume is in the
313 @retval EFI_DEVICE_ERROR The block device is not functioning
314 correctly and could not be written.
315 The firmware device may have been
317 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
318 in the variable argument list do
319 not exist in the firmware volume.
324 (EFIAPI
* FRAMEWORK_EFI_FVB_ERASE_BLOCKS
)(
325 IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
330 /// The Firmware Volume Block Protocol is the low-level interface
331 /// to a firmware volume. File-level access to a firmware volume
332 /// should not be done using the Firmware Volume Block Protocol.
333 /// Normal access to a firmware volume must use the Firmware
334 /// Volume Protocol. Typically, only the file system driver that
335 /// produces the Firmware Volume Protocol will bind to the
336 /// Firmware Volume Block Protocol.
338 struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
{
339 FRAMEWORK_EFI_FVB_GET_ATTRIBUTES GetAttributes
;
340 FRAMEWORK_EFI_FVB_SET_ATTRIBUTES SetAttributes
;
341 FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress
;
342 FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE GetBlockSize
;
343 FRAMEWORK_EFI_FVB_READ Read
;
344 FRAMEWORK_EFI_FVB_WRITE Write
;
345 FRAMEWORK_EFI_FVB_ERASE_BLOCKS EraseBlocks
;
347 /// Handle of the parent firmware volume.
349 EFI_HANDLE ParentHandle
;