2 This file provides control over block-oriented firmware devices.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
7 @par Revision Reference: PI
12 #ifndef __FIRMWARE_VOLUME_BLOCK_H__
13 #define __FIRMWARE_VOLUME_BLOCK_H__
16 // EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL is defined in PI 1.0 spec and its GUID value
17 // is later updated to be the same as that of EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
18 // defined in PI 1.2 spec.
20 #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
21 { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } }
23 #define EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL_GUID \
24 { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } }
26 typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
;
28 typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
;
31 The GetAttributes() function retrieves the attributes and
32 current settings of the block.
34 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
36 @param Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
37 attributes and current settings are
38 returned. Type EFI_FVB_ATTRIBUTES_2 is defined
39 in EFI_FIRMWARE_VOLUME_HEADER.
41 @retval EFI_SUCCESS The firmware volume attributes were
47 (EFIAPI
* EFI_FVB_GET_ATTRIBUTES
)(
48 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
49 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
54 The SetAttributes() function sets configurable firmware volume
55 attributes and returns the new settings of the firmware volume.
57 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
59 @param Attributes On input, Attributes is a pointer to
60 EFI_FVB_ATTRIBUTES_2 that contains the
61 desired firmware volume settings. On
62 successful return, it contains the new
63 settings of the firmware volume. Type
64 EFI_FVB_ATTRIBUTES_2 is defined in
65 EFI_FIRMWARE_VOLUME_HEADER.
67 @retval EFI_SUCCESS The firmware volume attributes were returned.
69 @retval EFI_INVALID_PARAMETER The attributes requested are in
70 conflict with the capabilities
71 as declared in the firmware
77 (EFIAPI
* EFI_FVB_SET_ATTRIBUTES
)(
78 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
79 IN OUT EFI_FVB_ATTRIBUTES_2
*Attributes
84 The GetPhysicalAddress() function retrieves the base address of
85 a memory-mapped firmware volume. This function should be called
86 only for memory-mapped firmware volumes.
88 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
90 @param Address Pointer to a caller-allocated
91 EFI_PHYSICAL_ADDRESS that, on successful
92 return from GetPhysicalAddress(), contains the
93 base address of the firmware volume.
95 @retval EFI_SUCCESS The firmware volume base address was returned.
97 @retval EFI_UNSUPPORTED The firmware volume is not memory mapped.
102 (EFIAPI
* EFI_FVB_GET_PHYSICAL_ADDRESS
)(
103 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
104 OUT EFI_PHYSICAL_ADDRESS
*Address
108 The GetBlockSize() function retrieves the size of the requested
109 block. It also returns the number of additional blocks with
110 the identical size. The GetBlockSize() function is used to
111 retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
114 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
116 @param Lba Indicates the block for which to return the size.
118 @param BlockSize Pointer to a caller-allocated UINTN in which
119 the size of the block is returned.
121 @param NumberOfBlocks Pointer to a caller-allocated UINTN in
122 which the number of consecutive blocks,
123 starting with Lba, is returned. All
124 blocks in this range have a size of
128 @retval EFI_SUCCESS The firmware volume base address was returned.
130 @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
135 (EFIAPI
* EFI_FVB_GET_BLOCK_SIZE
)(
136 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
138 OUT UINTN
*BlockSize
,
139 OUT UINTN
*NumberOfBlocks
144 Reads the specified number of bytes into a buffer from the specified block.
146 The Read() function reads the requested number of bytes from the
147 requested block and stores them in the provided buffer.
148 Implementations should be mindful that the firmware volume
149 might be in the ReadDisabled state. If it is in this state,
150 the Read() function must return the status code
151 EFI_ACCESS_DENIED without modifying the contents of the
152 buffer. The Read() function must also prevent spanning block
153 boundaries. If a read is requested that would span a block
154 boundary, the read must read up to the boundary but not
155 beyond. The output parameter NumBytes must be set to correctly
156 indicate the number of bytes actually read. The caller must be
157 aware that a read may be partially completed.
159 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
161 @param Lba The starting logical block index
164 @param Offset Offset into the block at which to begin reading.
166 @param NumBytes Pointer to a UINTN. At entry, *NumBytes
167 contains the total size of the buffer. At
168 exit, *NumBytes contains the total number of
171 @param Buffer Pointer to a caller-allocated buffer that will
172 be used to hold the data that is read.
174 @retval EFI_SUCCESS The firmware volume was read successfully,
175 and contents are in Buffer.
177 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
178 boundary. On output, NumBytes
179 contains the total number of bytes
182 @retval EFI_ACCESS_DENIED The firmware volume is in the
185 @retval EFI_DEVICE_ERROR The block device is not
186 functioning correctly and could
192 (EFIAPI
*EFI_FVB_READ
)(
193 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
196 IN OUT UINTN
*NumBytes
,
201 Writes the specified number of bytes from the input buffer to the block.
203 The Write() function writes the specified number of bytes from
204 the provided buffer to the specified block and offset. If the
205 firmware volume is sticky write, the caller must ensure that
206 all the bits of the specified range to write are in the
207 EFI_FVB_ERASE_POLARITY state before calling the Write()
208 function, or else the result will be unpredictable. This
209 unpredictability arises because, for a sticky-write firmware
210 volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
211 state but cannot flip it back again. Before calling the
212 Write() function, it is recommended for the caller to first call
213 the EraseBlocks() function to erase the specified block to
214 write. A block erase cycle will transition bits from the
215 (NOT)EFI_FVB_ERASE_POLARITY state back to the
216 EFI_FVB_ERASE_POLARITY state. Implementations should be
217 mindful that the firmware volume might be in the WriteDisabled
218 state. If it is in this state, the Write() function must
219 return the status code EFI_ACCESS_DENIED without modifying the
220 contents of the firmware volume. The Write() function must
221 also prevent spanning block boundaries. If a write is
222 requested that spans a block boundary, the write must store up
223 to the boundary but not beyond. The output parameter NumBytes
224 must be set to correctly indicate the number of bytes actually
225 written. The caller must be aware that a write may be
226 partially completed. All writes, partial or otherwise, must be
227 fully flushed to the hardware before the Write() service
230 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
232 @param Lba The starting logical block index to write to.
234 @param Offset Offset into the block at which to begin writing.
236 @param NumBytes The pointer to a UINTN. At entry, *NumBytes
237 contains the total size of the buffer. At
238 exit, *NumBytes contains the total number of
239 bytes actually written.
241 @param Buffer The pointer to a caller-allocated buffer that
242 contains the source for the write.
244 @retval EFI_SUCCESS The firmware volume was written successfully.
246 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
247 LBA boundary. On output, NumBytes
248 contains the total number of bytes
251 @retval EFI_ACCESS_DENIED The firmware volume is in the
254 @retval EFI_DEVICE_ERROR The block device is malfunctioning
255 and could not be written.
261 (EFIAPI
* EFI_FVB_WRITE
)(
262 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
265 IN OUT UINTN
*NumBytes
,
273 /// EFI_LBA_LIST_TERMINATOR
275 #define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL
279 Erases and initializes a firmware volume block.
281 The EraseBlocks() function erases one or more blocks as denoted
282 by the variable argument list. The entire parameter list of
283 blocks must be verified before erasing any blocks. If a block is
284 requested that does not exist within the associated firmware
285 volume (it has a larger index than the last block of the
286 firmware volume), the EraseBlocks() function must return the
287 status code EFI_INVALID_PARAMETER without modifying the contents
288 of the firmware volume. Implementations should be mindful that
289 the firmware volume might be in the WriteDisabled state. If it
290 is in this state, the EraseBlocks() function must return the
291 status code EFI_ACCESS_DENIED without modifying the contents of
292 the firmware volume. All calls to EraseBlocks() must be fully
293 flushed to the hardware before the EraseBlocks() service
296 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
299 @param ... The variable argument list is a list of tuples.
300 Each tuple describes a range of LBAs to erase
301 and consists of the following:
302 - An EFI_LBA that indicates the starting LBA
303 - A UINTN that indicates the number of blocks to
306 The list is terminated with an
307 EFI_LBA_LIST_TERMINATOR. For example, the
308 following indicates that two ranges of blocks
309 (5-7 and 10-11) are to be erased: EraseBlocks
310 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
312 @retval EFI_SUCCESS The erase request successfully
315 @retval EFI_ACCESS_DENIED The firmware volume is in the
317 @retval EFI_DEVICE_ERROR The block device is not functioning
318 correctly and could not be written.
319 The firmware device may have been
321 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
322 in the variable argument list do
323 not exist in the firmware volume.
328 (EFIAPI
* EFI_FVB_ERASE_BLOCKS
)(
329 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
*This
,
334 /// The Firmware Volume Block Protocol is the low-level interface
335 /// to a firmware volume. File-level access to a firmware volume
336 /// should not be done using the Firmware Volume Block Protocol.
337 /// Normal access to a firmware volume must use the Firmware
338 /// Volume Protocol. Typically, only the file system driver that
339 /// produces the Firmware Volume Protocol will bind to the
340 /// Firmware Volume Block Protocol.
342 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
{
343 EFI_FVB_GET_ATTRIBUTES GetAttributes
;
344 EFI_FVB_SET_ATTRIBUTES SetAttributes
;
345 EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress
;
346 EFI_FVB_GET_BLOCK_SIZE GetBlockSize
;
349 EFI_FVB_ERASE_BLOCKS EraseBlocks
;
351 /// The handle of the parent firmware volume.
353 EFI_HANDLE ParentHandle
;
357 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid
;
358 extern EFI_GUID gEfiFirmwareVolumeBlock2ProtocolGuid
;