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