1/** @file
2  Firmware Volume Block protocol functions.
3  Consumes FV hobs and creates appropriate block protocols.
4
5Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
6This program and the accompanying materials
7are licensed and made available under the terms and conditions of the BSD License
8which accompanies this distribution.  The full text of the license may be found at
9http://opensource.org/licenses/bsd-license.php
10
11THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14**/
15
16#ifndef _FWVOL_BLOCK_H_
17#define _FWVOL_BLOCK_H_
18
19
20#define FVB_DEVICE_SIGNATURE       SIGNATURE_32('_','F','V','B')
21
22
23typedef struct {
24  UINTN                       Base;
25  UINTN                       Length;
26} LBA_CACHE;
27
28typedef struct {
29  MEMMAP_DEVICE_PATH          MemMapDevPath;
30  EFI_DEVICE_PATH_PROTOCOL    EndDevPath;
31} FV_MEMMAP_DEVICE_PATH;
32
33//
34// UEFI Specification define FV device path format if FV provide name guid in extension header
35//
36typedef struct {
37  MEDIA_FW_VOL_DEVICE_PATH    FvDevPath;
38  EFI_DEVICE_PATH_PROTOCOL    EndDevPath;
39} FV_PIWG_DEVICE_PATH;
40
41typedef struct {
42  UINTN                                 Signature;
43  EFI_HANDLE                            Handle;
44  EFI_DEVICE_PATH_PROTOCOL              *DevicePath;
45  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    FwVolBlockInstance;
46  UINTN                                 NumBlocks;
47  LBA_CACHE                             *LbaCache;
48  UINT32                                FvbAttributes;
49  EFI_PHYSICAL_ADDRESS                  BaseAddress;
50  UINT32                                AuthenticationStatus;
51} EFI_FW_VOL_BLOCK_DEVICE;
52
53
54#define FVB_DEVICE_FROM_THIS(a) \
55  CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)
56
57
58/**
59  Retrieves Volume attributes.  No polarity translations are done.
60
61  @param  This                   Calling context
62  @param  Attributes             output buffer which contains attributes
63
64  @retval EFI_SUCCESS            The firmware volume attributes were returned.
65
66**/
67EFI_STATUS
68EFIAPI
69FwVolBlockGetAttributes (
70  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
71  OUT       EFI_FVB_ATTRIBUTES_2                *Attributes
72  );
73
74
75
76/**
77  Modifies the current settings of the firmware volume according to the input parameter.
78
79  @param  This                   Calling context
80  @param  Attributes             input buffer which contains attributes
81
82  @retval EFI_SUCCESS            The firmware volume attributes were returned.
83  @retval EFI_INVALID_PARAMETER  The attributes requested are in conflict with
84                                 the capabilities as declared in the firmware
85                                 volume header.
86  @retval EFI_UNSUPPORTED        Not supported.
87
88**/
89EFI_STATUS
90EFIAPI
91FwVolBlockSetAttributes (
92  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
93  IN CONST  EFI_FVB_ATTRIBUTES_2                *Attributes
94  );
95
96
97
98/**
99  The EraseBlock() function erases one or more blocks as denoted by the
100  variable argument list. The entire parameter list of blocks must be verified
101  prior to erasing any blocks.  If a block is requested that does not exist
102  within the associated firmware volume (it has a larger index than the last
103  block of the firmware volume), the EraseBlock() function must return
104  EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
105
106  @param  This                   Calling context
107  @param  ...                    Starting LBA followed by Number of Lba to erase.
108                                 a -1 to terminate the list.
109
110  @retval EFI_SUCCESS            The erase request was successfully completed.
111  @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
112                                 state.
113  @retval EFI_DEVICE_ERROR       The block device is not functioning correctly
114                                 and could not be written. The firmware device
115                                 may have been partially erased.
116  @retval EFI_INVALID_PARAMETER  One or more of the LBAs listed in the variable
117                                 argument list do
118  @retval EFI_UNSUPPORTED        Not supported.
119
120**/
121EFI_STATUS
122EFIAPI
123FwVolBlockEraseBlock (
124  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *This,
125  ...
126  );
127
128
129
130/**
131  Read the specified number of bytes from the block to the input buffer.
132
133  @param  This                   Indicates the calling context.
134  @param  Lba                    The starting logical block index to read.
135  @param  Offset                 Offset into the block at which to begin reading.
136  @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
137                                 contains the total size of the buffer. At exit,
138                                 *NumBytes contains the total number of bytes
139                                 actually read.
140  @param  Buffer                 Pinter to a caller-allocated buffer that
141                                 contains the destine for the read.
142
143  @retval EFI_SUCCESS            The firmware volume was read successfully.
144  @retval EFI_BAD_BUFFER_SIZE    The read was attempted across an LBA boundary.
145  @retval EFI_ACCESS_DENIED      Access denied.
146  @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
147                                 be read.
148
149**/
150EFI_STATUS
151EFIAPI
152FwVolBlockReadBlock (
153  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
154  IN CONST  EFI_LBA                              Lba,
155  IN CONST  UINTN                                Offset,
156  IN OUT    UINTN                                *NumBytes,
157  IN OUT    UINT8                                *Buffer
158  );
159
160
161
162/**
163  Writes the specified number of bytes from the input buffer to the block.
164
165  @param  This                   Indicates the calling context.
166  @param  Lba                    The starting logical block index to write to.
167  @param  Offset                 Offset into the block at which to begin writing.
168  @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes
169                                 contains the total size of the buffer. At exit,
170                                 *NumBytes contains the total number of bytes
171                                 actually written.
172  @param  Buffer                 Pinter to a caller-allocated buffer that
173                                 contains the source for the write.
174
175  @retval EFI_SUCCESS            The firmware volume was written successfully.
176  @retval EFI_BAD_BUFFER_SIZE    The write was attempted across an LBA boundary.
177                                 On output, NumBytes contains the total number of
178                                 bytes actually written.
179  @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled
180                                 state.
181  @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not
182                                 be written.
183  @retval EFI_UNSUPPORTED        Not supported.
184
185**/
186EFI_STATUS
187EFIAPI
188FwVolBlockWriteBlock (
189  IN     EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,
190  IN     EFI_LBA                              Lba,
191  IN     UINTN                                Offset,
192  IN OUT UINTN                                *NumBytes,
193  IN     UINT8                                *Buffer
194  );
195
196
197
198/**
199  Get Fvb's base address.
200
201  @param  This                   Indicates the calling context.
202  @param  Address                Fvb device base address.
203
204  @retval EFI_SUCCESS            Successfully got Fvb's base address.
205  @retval EFI_UNSUPPORTED        Not supported.
206
207**/
208EFI_STATUS
209EFIAPI
210FwVolBlockGetPhysicalAddress (
211  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
212  OUT       EFI_PHYSICAL_ADDRESS                *Address
213  );
214
215
216
217/**
218  Retrieves the size in bytes of a specific block within a firmware volume.
219
220  @param  This                   Indicates the calling context.
221  @param  Lba                    Indicates the block for which to return the
222                                 size.
223  @param  BlockSize              Pointer to a caller-allocated UINTN in which the
224                                 size of the block is returned.
225  @param  NumberOfBlocks         Pointer to a caller-allocated UINTN in which the
226                                 number of consecutive blocks starting with Lba
227                                 is returned. All blocks in this range have a
228                                 size of BlockSize.
229
230  @retval EFI_SUCCESS            The firmware volume base address is returned.
231  @retval EFI_INVALID_PARAMETER  The requested LBA is out of range.
232
233**/
234EFI_STATUS
235EFIAPI
236FwVolBlockGetBlockSize (
237  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,
238  IN CONST  EFI_LBA                             Lba,
239  IN OUT    UINTN                               *BlockSize,
240  IN OUT    UINTN                               *NumberOfBlocks
241  );
242
243
244#endif
245