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