1/** @file
2  This file provides control over block-oriented firmware devices.
3
4Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials are licensed and made available under
6the terms and conditions of the BSD License that accompanies this distribution.
7The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php.
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13  @par Revision Reference: PI
14  Version 1.0 and 1.2.
15
16**/
17
18#ifndef __FIRMWARE_VOLUME_BLOCK_H__
19#define __FIRMWARE_VOLUME_BLOCK_H__
20
21//
22// EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL is defined in PI 1.0 spec and its GUID value
23// is later updated to be the same as that of EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
24// defined in PI 1.2 spec.
25//
26#define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
27  { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } }
28
29#define EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL_GUID \
30  { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } }
31
32typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
33
34typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL;
35
36/**
37  The GetAttributes() function retrieves the attributes and
38  current settings of the block.
39
40  @param This       Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
41
42  @param Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
43                    attributes and current settings are
44                    returned. Type EFI_FVB_ATTRIBUTES_2 is defined
45                    in EFI_FIRMWARE_VOLUME_HEADER.
46
47  @retval EFI_SUCCESS The firmware volume attributes were
48                      returned.
49
50**/
51typedef
52EFI_STATUS
53(EFIAPI * EFI_FVB_GET_ATTRIBUTES)(
54  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
55  OUT       EFI_FVB_ATTRIBUTES_2                *Attributes
56);
57
58
59/**
60  The SetAttributes() function sets configurable firmware volume
61  attributes and returns the new settings of the firmware volume.
62
63  @param This         Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
64
65  @param Attributes   On input, Attributes is a pointer to
66                      EFI_FVB_ATTRIBUTES_2 that contains the
67                      desired firmware volume settings. On
68                      successful return, it contains the new
69                      settings of the firmware volume. Type
70                      EFI_FVB_ATTRIBUTES_2 is defined in
71                      EFI_FIRMWARE_VOLUME_HEADER.
72
73  @retval EFI_SUCCESS           The firmware volume attributes were returned.
74
75  @retval EFI_INVALID_PARAMETER The attributes requested are in
76                                conflict with the capabilities
77                                as declared in the firmware
78                                volume header.
79
80**/
81typedef
82EFI_STATUS
83(EFIAPI * EFI_FVB_SET_ATTRIBUTES)(
84  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
85  IN OUT    EFI_FVB_ATTRIBUTES_2                *Attributes
86);
87
88
89/**
90  The GetPhysicalAddress() function retrieves the base address of
91  a memory-mapped firmware volume. This function should be called
92  only for memory-mapped firmware volumes.
93
94  @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
95
96  @param Address  Pointer to a caller-allocated
97                  EFI_PHYSICAL_ADDRESS that, on successful
98                  return from GetPhysicalAddress(), contains the
99                  base address of the firmware volume.
100
101  @retval EFI_SUCCESS       The firmware volume base address was returned.
102
103  @retval EFI_UNSUPPORTED   The firmware volume is not memory mapped.
104
105**/
106typedef
107EFI_STATUS
108(EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS)(
109  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
110  OUT       EFI_PHYSICAL_ADDRESS                *Address
111);
112
113/**
114  The GetBlockSize() function retrieves the size of the requested
115  block. It also returns the number of additional blocks with
116  the identical size. The GetBlockSize() function is used to
117  retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
118
119
120  @param This           Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
121
122  @param Lba            Indicates the block for which to return the size.
123
124  @param BlockSize      Pointer to a caller-allocated UINTN in which
125                        the size of the block is returned.
126
127  @param NumberOfBlocks Pointer to a caller-allocated UINTN in
128                        which the number of consecutive blocks,
129                        starting with Lba, is returned. All
130                        blocks in this range have a size of
131                        BlockSize.
132
133
134  @retval EFI_SUCCESS             The firmware volume base address was returned.
135
136  @retval EFI_INVALID_PARAMETER   The requested LBA is out of range.
137
138**/
139typedef
140EFI_STATUS
141(EFIAPI * EFI_FVB_GET_BLOCK_SIZE)(
142  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
143  IN        EFI_LBA                             Lba,
144  OUT       UINTN                               *BlockSize,
145  OUT       UINTN                               *NumberOfBlocks
146);
147
148
149/**
150  Reads the specified number of bytes into a buffer from the specified block.
151
152  The Read() function reads the requested number of bytes from the
153  requested block and stores them in the provided buffer.
154  Implementations should be mindful that the firmware volume
155  might be in the ReadDisabled state. If it is in this state,
156  the Read() function must return the status code
157  EFI_ACCESS_DENIED without modifying the contents of the
158  buffer. The Read() function must also prevent spanning block
159  boundaries. If a read is requested that would span a block
160  boundary, the read must read up to the boundary but not
161  beyond. The output parameter NumBytes must be set to correctly
162  indicate the number of bytes actually read. The caller must be
163  aware that a read may be partially completed.
164
165  @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
166
167  @param Lba      The starting logical block index
168                  from which to read.
169
170  @param Offset   Offset into the block at which to begin reading.
171
172  @param NumBytes Pointer to a UINTN. At entry, *NumBytes
173                  contains the total size of the buffer. At
174                  exit, *NumBytes contains the total number of
175                  bytes read.
176
177  @param Buffer   Pointer to a caller-allocated buffer that will
178                  be used to hold the data that is read.
179
180  @retval EFI_SUCCESS         The firmware volume was read successfully,
181                              and contents are in Buffer.
182
183  @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA
184                              boundary. On output, NumBytes
185                              contains the total number of bytes
186                              returned in Buffer.
187
188  @retval EFI_ACCESS_DENIED   The firmware volume is in the
189                              ReadDisabled state.
190
191  @retval EFI_DEVICE_ERROR    The block device is not
192                              functioning correctly and could
193                              not be read.
194
195**/
196typedef
197EFI_STATUS
198(EFIAPI *EFI_FVB_READ)(
199  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
200  IN        EFI_LBA                             Lba,
201  IN        UINTN                               Offset,
202  IN OUT    UINTN                               *NumBytes,
203  IN OUT    UINT8                               *Buffer
204);
205
206/**
207  Writes the specified number of bytes from the input buffer to the block.
208
209  The Write() function writes the specified number of bytes from
210  the provided buffer to the specified block and offset. If the
211  firmware volume is sticky write, the caller must ensure that
212  all the bits of the specified range to write are in the
213  EFI_FVB_ERASE_POLARITY state before calling the Write()
214  function, or else the result will be unpredictable. This
215  unpredictability arises because, for a sticky-write firmware
216  volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
217  state but cannot flip it back again.  Before calling the
218  Write() function,  it is recommended for the caller to first call
219  the EraseBlocks() function to erase the specified block to
220  write. A block erase cycle will transition bits from the
221  (NOT)EFI_FVB_ERASE_POLARITY state back to the
222  EFI_FVB_ERASE_POLARITY state. Implementations should be
223  mindful that the firmware volume might be in the WriteDisabled
224  state. If it is in this state, the Write() function must
225  return the status code EFI_ACCESS_DENIED without modifying the
226  contents of the firmware volume. The Write() function must
227  also prevent spanning block boundaries. If a write is
228  requested that spans a block boundary, the write must store up
229  to the boundary but not beyond. The output parameter NumBytes
230  must be set to correctly indicate the number of bytes actually
231  written. The caller must be aware that a write may be
232  partially completed. All writes, partial or otherwise, must be
233  fully flushed to the hardware before the Write() service
234  returns.
235
236  @param This     Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
237
238  @param Lba      The starting logical block index to write to.
239
240  @param Offset   Offset into the block at which to begin writing.
241
242  @param NumBytes The pointer to a UINTN. At entry, *NumBytes
243                  contains the total size of the buffer. At
244                  exit, *NumBytes contains the total number of
245                  bytes actually written.
246
247  @param Buffer   The pointer to a caller-allocated buffer that
248                  contains the source for the write.
249
250  @retval EFI_SUCCESS         The firmware volume was written successfully.
251
252  @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
253                              LBA boundary. On output, NumBytes
254                              contains the total number of bytes
255                              actually written.
256
257  @retval EFI_ACCESS_DENIED   The firmware volume is in the
258                              WriteDisabled state.
259
260  @retval EFI_DEVICE_ERROR    The block device is malfunctioning
261                              and could not be written.
262
263
264**/
265typedef
266EFI_STATUS
267(EFIAPI * EFI_FVB_WRITE)(
268  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
269  IN        EFI_LBA                             Lba,
270  IN        UINTN                               Offset,
271  IN OUT    UINTN                               *NumBytes,
272  IN        UINT8                               *Buffer
273);
274
275
276
277
278///
279/// EFI_LBA_LIST_TERMINATOR
280///
281#define EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL
282
283
284/**
285  Erases and initializes a firmware volume block.
286
287  The EraseBlocks() function erases one or more blocks as denoted
288  by the variable argument list. The entire parameter list of
289  blocks must be verified before erasing any blocks. If a block is
290  requested that does not exist within the associated firmware
291  volume (it has a larger index than the last block of the
292  firmware volume), the EraseBlocks() function must return the
293  status code EFI_INVALID_PARAMETER without modifying the contents
294  of the firmware volume. Implementations should be mindful that
295  the firmware volume might be in the WriteDisabled state. If it
296  is in this state, the EraseBlocks() function must return the
297  status code EFI_ACCESS_DENIED without modifying the contents of
298  the firmware volume. All calls to EraseBlocks() must be fully
299  flushed to the hardware before the EraseBlocks() service
300  returns.
301
302  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL
303                instance.
304
305  @param ...    The variable argument list is a list of tuples.
306                Each tuple describes a range of LBAs to erase
307                and consists of the following:
308                - An EFI_LBA that indicates the starting LBA
309                - A UINTN that indicates the number of blocks to
310                  erase.
311
312                The list is terminated with an
313                EFI_LBA_LIST_TERMINATOR. For example, the
314                following indicates that two ranges of blocks
315                (5-7 and 10-11) are to be erased: EraseBlocks
316                (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
317
318  @retval EFI_SUCCESS The erase request successfully
319                      completed.
320
321  @retval EFI_ACCESS_DENIED   The firmware volume is in the
322                              WriteDisabled state.
323  @retval EFI_DEVICE_ERROR  The block device is not functioning
324                            correctly and could not be written.
325                            The firmware device may have been
326                            partially erased.
327  @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
328                                in the variable argument list do
329                                not exist in the firmware volume.
330
331**/
332typedef
333EFI_STATUS
334(EFIAPI * EFI_FVB_ERASE_BLOCKS)(
335  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
336  ...
337);
338
339///
340/// The Firmware Volume Block Protocol is the low-level interface
341/// to a firmware volume. File-level access to a firmware volume
342/// should not be done using the Firmware Volume Block Protocol.
343/// Normal access to a firmware volume must use the Firmware
344/// Volume Protocol. Typically, only the file system driver that
345/// produces the Firmware Volume Protocol will bind to the
346/// Firmware Volume Block Protocol.
347///
348struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL{
349  EFI_FVB_GET_ATTRIBUTES        GetAttributes;
350  EFI_FVB_SET_ATTRIBUTES        SetAttributes;
351  EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;
352  EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;
353  EFI_FVB_READ                  Read;
354  EFI_FVB_WRITE                 Write;
355  EFI_FVB_ERASE_BLOCKS          EraseBlocks;
356  ///
357  /// The handle of the parent firmware volume.
358  ///
359  EFI_HANDLE                    ParentHandle;
360};
361
362
363extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;
364extern EFI_GUID gEfiFirmwareVolumeBlock2ProtocolGuid;
365
366#endif
367