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