Update the release notes:
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / FirmwareVolumeBlock.h
CommitLineData
79964ac8 1/** @file\r
2 This file declares Firmware Volume Block protocol.\r
3\r
4 Low level firmware device access routines to abstract firmware device\r
5 hardware.\r
6\r
7 Copyright (c) 2007, Intel Corporation\r
8 All rights reserved. This program and the accompanying materials\r
9 are licensed and made available under the terms and conditions of the BSD License\r
10 which accompanies this distribution. The full text of the license may be found at\r
11 http://opensource.org/licenses/bsd-license.php\r
12\r
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
15\r
16 Module Name: FirmwareVolumeBlock.h\r
17\r
18 @par Revision Reference:\r
19 This protocol is defined in Framework of EFI Firmware Volume Block specification.\r
20 Version 0.9\r
21\r
22**/\r
23\r
24#ifndef _FIRMWARE_VOLUME_BLOCK_H_\r
25#define _FIRMWARE_VOLUME_BLOCK_H_\r
26\r
b80fbe85 27#include <PiDxe.h>\r
79964ac8 28\r
29#define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \\r
30 { \\r
31 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD, 0xB5, 0x8D, 0xA1 } \\r
32 }\r
33\r
34typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;\r
35\r
36/**\r
37 Retrieves Volume attributes. No polarity translations are done.\r
38\r
39 @param This Calling context\r
40 @param Attributes output buffer which contains attributes\r
41\r
42 @retval EFI_INVALID_PARAMETER\r
43 @retval EFI_SUCCESS\r
44\r
45**/\r
46typedef\r
47EFI_STATUS\r
48(EFIAPI *EFI_FVB_GET_ATTRIBUTES) (\r
49 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
50 OUT EFI_FVB_ATTRIBUTES *Attributes\r
51 )\r
52;\r
53\r
54/**\r
55 Sets Volume attributes. No polarity translations are done.\r
56\r
57 @param This Calling context\r
58 @param Attributes On input: contains new attributes\r
59 On output: contains current attributes of FV\r
60\r
61 @retval EFI_INVALID_PARAMETER\r
62 @retval EFI_SUCCESS\r
63\r
64**/\r
65typedef\r
66EFI_STATUS\r
67(EFIAPI *EFI_FVB_SET_ATTRIBUTES) (\r
68 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
69 IN OUT EFI_FVB_ATTRIBUTES *Attributes\r
70 )\r
71;\r
72\r
73/**\r
74 Retrieves the physical address of a memory mapped FV.\r
75\r
76 @param This Calling context\r
77 @param Attributes Address is a pointer to a caller allocated EFI_PHYSICAL_ADDRESS\r
78 that on successful return from GetPhysicalAddress() contains the\r
79 base address of the firmware volume.\r
80\r
81 @retval EFI_UNSUPPORTED\r
82 @retval EFI_SUCCESS\r
83\r
84**/\r
85typedef\r
86EFI_STATUS\r
87(EFIAPI *EFI_FVB_GET_PHYSICAL_ADDRESS) (\r
88 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
89 OUT EFI_PHYSICAL_ADDRESS *Address\r
90 )\r
91;\r
92\r
93/**\r
94 Retrieves the size in bytes of a specific block within an FV.\r
95\r
96 @param This Calling context.\r
97 @param Lba Indicates which block to return the size for.\r
98 @param BlockSize BlockSize is a pointer to a caller allocated\r
99 UINTN in which the size of the block is returned.\r
100 @param NumberOfBlocks NumberOfBlocks is a pointer to a caller allocated\r
101 UINTN in which the number of consecutive blocks\r
102 starting with Lba is returned. All blocks in this\r
103 range have a size of BlockSize.\r
104\r
105 @retval EFI_INVALID_PARAMETER\r
106 @retval EFI_SUCCESS\r
107\r
108**/\r
109typedef\r
110EFI_STATUS\r
111(EFIAPI *EFI_FVB_GET_BLOCK_SIZE) (\r
112 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
113 IN EFI_LBA Lba,\r
114 OUT UINTN *BlockSize,\r
115 OUT UINTN *NumberOfBlocks\r
116 )\r
117;\r
118\r
119/**\r
120 Reads data beginning at Lba:Offset from FV and places the data in Buffer.\r
121 The read terminates either when *NumBytes of data have been read, or when\r
122 a block boundary is reached. *NumBytes is updated to reflect the actual\r
123 number of bytes read.\r
124\r
125 @param This Calling context\r
126 @param Lba Block in which to begin read\r
127 @param Offset Offset in the block at which to begin read\r
128 @param NumBytes At input, indicates the requested read size. At output, indicates\r
129 the actual number of bytes read.\r
130 @param Buffer Data buffer in which to place data read.\r
131\r
132 @retval EFI_INVALID_PARAMETER\r
133 @retval EFI_NOT_FOUND\r
134 @retval EFI_DEVICE_ERROR\r
135 @retval EFI_SUCCESS\r
136\r
137**/\r
138typedef\r
139EFI_STATUS\r
140(EFIAPI *EFI_FVB_READ) (\r
141 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
142 IN EFI_LBA Lba,\r
143 IN UINTN Offset,\r
144 IN OUT UINTN *NumBytes,\r
145 OUT UINT8 *Buffer\r
146 )\r
147;\r
148\r
149/**\r
150 Writes data beginning at Lba:Offset from FV. The write terminates either\r
151 when *NumBytes of data have been written, or when a block boundary is\r
152 reached. *NumBytes is updated to reflect the actual number of bytes\r
153 written.\r
154\r
155 @param This Calling context\r
156 @param Lba Block in which to begin write\r
157 @param Offset Offset in the block at which to begin write\r
158 @param NumBytes At input, indicates the requested write size. At output, indicates\r
159 the actual number of bytes written.\r
160 @param Buffer Buffer containing source data for the write.\r
161\r
162 @retval EFI_INVALID_PARAMETER\r
163 @retval EFI_NOT_FOUND\r
164 @retval EFI_DEVICE_ERROR\r
165 @retval EFI_SUCCESS\r
166\r
167**/\r
168typedef\r
169EFI_STATUS\r
170(EFIAPI *EFI_FVB_WRITE) (\r
171 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
172 IN EFI_LBA Lba,\r
173 IN UINTN Offset,\r
174 IN OUT UINTN *NumBytes,\r
175 IN UINT8 *Buffer\r
176 )\r
177;\r
178\r
179#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL\r
180\r
181/**\r
182 The EraseBlock() function erases one or more blocks as denoted by the\r
183 variable argument list. The entire parameter list of blocks must be verified\r
184 prior to erasing any blocks. If a block is requested that does not exist\r
185 within the associated firmware volume (it has a larger index than the last\r
186 block of the firmware volume), the EraseBlock() function must return\r
187 EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.\r
188\r
189 @param This Calling context\r
190 @param ... Starting LBA followed by Number of Lba to erase. a -1 to terminate\r
191 the list.\r
192\r
193 @retval EFI_INVALID_PARAMETER\r
194 @retval EFI_DEVICE_ERROR\r
195 @retval EFI_SUCCESS\r
196 @retval EFI_ACCESS_DENIED\r
197\r
198**/\r
199typedef\r
200EFI_STATUS\r
201(EFIAPI *EFI_FVB_ERASE_BLOCKS) (\r
202 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
203 ...\r
204 )\r
205;\r
206\r
207/**\r
208 @par Protocol Description:\r
209 This protocol provides control over block-oriented firmware devices.\r
210 Typically, the FFS (or an alternate file system) driver consumes the\r
211 Firmware Volume Block Protocol and produces the Firmware Volume Protocol.\r
212\r
213 @param GetAttributes\r
214 Retrieves the current volume attributes.\r
215\r
216 @param SetAttributes\r
217 Sets the current volume attributes.\r
218\r
219 @param GetPhysicalAddress\r
220 Retrieves the memory-mapped address of the firmware volume.\r
221\r
222 @param GetBlockSize\r
223 Retrieves the size for a specific block.\r
224\r
225 @param Read\r
226 Reads n bytes into a buffer from the firmware volume hardware.\r
227\r
228 @param Write\r
229 Writes n bytes from a buffer into the firmware volume hardware.\r
230\r
231 @param EraseBlocks\r
232 Erases specified block(s) and sets all values as indicated by\r
233 the EFI_FVB_ERASE_POLARITY bit.\r
234\r
235 @param ParentHandle\r
236 Handle of the parent firmware volume.\r
237\r
238**/\r
239struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {\r
240 EFI_FVB_GET_ATTRIBUTES GetVolumeAttributes;\r
241 EFI_FVB_SET_ATTRIBUTES SetVolumeAttributes;\r
242 EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress;\r
243 EFI_FVB_GET_BLOCK_SIZE GetBlockSize;\r
244 EFI_FVB_READ Read;\r
245 EFI_FVB_WRITE Write;\r
246 EFI_FVB_ERASE_BLOCKS EraseBlocks;\r
247 EFI_HANDLE ParentHandle;\r
248};\r
249\r
250extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;\r
251\r
252#endif\r