]> git.proxmox.com Git - mirror_edk2.git/blob - MdeModulePkg/Core/Dxe/FwVol/FwVolRead.c
projects / mirror_edk2.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Add doxygen style comments for functions in DxeMain.
[mirror_edk2.git] / MdeModulePkg / Core / Dxe / FwVol / FwVolRead.c
1 /** @file
2
3 Implements functions to read firmware file
4
5 Copyright (c) 2006 - 2008, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16 #include <DxeMain.h>
17
18 /*++
19
20 Required Alignment Alignment Value in FFS Alignment Value in
21 (bytes) Attributes Field Firmware Volume Interfaces
22 1 0 0
23 2 0 1
24 4 0 2
25 8 0 3
26 16 1 4
27 128 2 7
28 512 3 9
29 1 KB 4 10
30 4 KB 5 12
31 32 KB 6 15
32 64 KB 7 16
33
34 --*/
35
36 UINT8 mFvAttributes[] = {0, 4, 7, 9, 10, 12, 15, 16};
37
38
39
40 /**
41 Convert the FFS File Attributes to FV File Attributes
42
43 @param FfsAttributes The attributes of UINT8 type.
44
45 @return The attributes of EFI_FV_FILE_ATTRIBUTES
46
47 **/
48 STATIC
49 EFI_FV_FILE_ATTRIBUTES
50 FfsAttributes2FvFileAttributes (
51 IN EFI_FFS_FILE_ATTRIBUTES FfsAttributes
52 )
53 {
54 FfsAttributes = (EFI_FFS_FILE_ATTRIBUTES)((FfsAttributes & FFS_ATTRIB_DATA_ALIGNMENT) >> 3);
55 ASSERT (FfsAttributes < 8);
56
57 return (EFI_FV_FILE_ATTRIBUTES) mFvAttributes[FfsAttributes];
58 }
59
60
61
62 /**
63 Given the input key, search for the next matching file in the volume.
64
65 @param This Indicates the calling context.
66 @param Key Key is a pointer to a caller allocated
67 buffer that contains implementation specific
68 data that is used to track where to begin
69 the search for the next file. The size of
70 the buffer must be at least This->KeySize
71 bytes long. To reinitialize the search and
72 begin from the beginning of the firmware
73 volume, the entire buffer must be cleared to
74 zero. Other than clearing the buffer to
75 initiate a new search, the caller must not
76 modify the data in the buffer between calls
77 to GetNextFile().
78 @param FileType FileType is a pointer to a caller allocated
79 EFI_FV_FILETYPE. The GetNextFile() API can
80 filter it's search for files based on the
81 value of *FileType input. A *FileType input
82 of 0 causes GetNextFile() to search for
83 files of all types. If a file is found, the
84 file's type is returned in *FileType.
85 *FileType is not modified if no file is
86 found.
87 @param NameGuid NameGuid is a pointer to a caller allocated
88 EFI_GUID. If a file is found, the file's
89 name is returned in *NameGuid. *NameGuid is
90 not modified if no file is found.
91 @param Attributes Attributes is a pointer to a caller
92 allocated EFI_FV_FILE_ATTRIBUTES. If a file
93 is found, the file's attributes are returned
94 in *Attributes. *Attributes is not modified
95 if no file is found.
96 @param Size Size is a pointer to a caller allocated
97 UINTN. If a file is found, the file's size
98 is returned in *Size. *Size is not modified
99 if no file is found.
100
101 @retval EFI_SUCCESS Successfully find the file.
102 @retval EFI_DEVICE_ERROR Device error.
103 @retval EFI_ACCESS_DENIED Fv could not read.
104 @retval EFI_NOT_FOUND No matching file found.
105 @retval EFI_INVALID_PARAMETER Invalid parameter
106
107 **/
108 EFI_STATUS
109 EFIAPI
110 FvGetNextFile (
111 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
112 IN OUT VOID *Key,
113 IN OUT EFI_FV_FILETYPE *FileType,
114 OUT EFI_GUID *NameGuid,
115 OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
116 OUT UINTN *Size
117 )
118 {
119 EFI_STATUS Status;
120 FV_DEVICE *FvDevice;
121 EFI_FV_ATTRIBUTES FvAttributes;
122 EFI_FFS_FILE_HEADER *FfsFileHeader;
123 UINTN *KeyValue;
124 LIST_ENTRY *Link;
125 FFS_FILE_LIST_ENTRY *FfsFileEntry;
126 UINTN FileLength;
127
128 FvDevice = FV_DEVICE_FROM_THIS (This);
129
130 Status = FvGetVolumeAttributes (This, &FvAttributes);
131 if (EFI_ERROR (Status)){
132 return Status;
133 }
134
135 //
136 // Check if read operation is enabled
137 //
138 if ((FvAttributes & EFI_FV2_READ_STATUS) == 0) {
139 return EFI_ACCESS_DENIED;
140 }
141
142 if (*FileType > EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE) {
143 //
144 // File type needs to be in 0 - 0x0B
145 //
146 return EFI_NOT_FOUND;
147 }
148
149 KeyValue = (UINTN *)Key;
150 for (;;) {
151 if (*KeyValue == 0) {
152 //
153 // Search for 1st matching file
154 //
155 Link = &FvDevice->FfsFileListHeader;
156 } else {
157 //
158 // Key is pointer to FFsFileEntry, so get next one
159 //
160 Link = (LIST_ENTRY *)(*KeyValue);
161 }
162
163 if (Link->ForwardLink == &FvDevice->FfsFileListHeader) {
164 //
165 // Next is end of list so we did not find data
166 //
167 return EFI_NOT_FOUND;
168 }
169
170 FfsFileEntry = (FFS_FILE_LIST_ENTRY *)Link->ForwardLink;
171 FfsFileHeader = (EFI_FFS_FILE_HEADER *)FfsFileEntry->FfsHeader;
172
173 //
174 // remember the key
175 //
176 *KeyValue = (UINTN)FfsFileEntry;
177
178 if (FfsFileHeader->Type == EFI_FV_FILETYPE_FFS_PAD) {
179 //
180 // we ignore pad files
181 //
182 continue;
183 }
184
185 if (*FileType == EFI_FV_FILETYPE_ALL) {
186 //
187 // Process all file types so we have a match
188 //
189 break;
190 }
191
192 if (*FileType == FfsFileHeader->Type) {
193 //
194 // Found a matching file type
195 //
196 break;
197 }
198
199 }
200
201 //
202 // Return FileType, NameGuid, and Attributes
203 //
204 *FileType = FfsFileHeader->Type;
205 CopyMem (NameGuid, &FfsFileHeader->Name, sizeof (EFI_GUID));
206 *Attributes = FfsAttributes2FvFileAttributes (FfsFileHeader->Attributes);
207
208 //
209 // Read four bytes out of the 3 byte array and throw out extra data
210 //
211 FileLength = *(UINT32 *)&FfsFileHeader->Size[0] & 0x00FFFFFF;
212
213 //
214 // we need to substract the header size
215 //
216 *Size = FileLength - sizeof(EFI_FFS_FILE_HEADER);
217
218 return EFI_SUCCESS;
219 }
220
221
222
223 /**
224 Locates a file in the firmware volume and
225 copies it to the supplied buffer.
226
227 @param This Indicates the calling context.
228 @param NameGuid Pointer to an EFI_GUID, which is the
229 filename.
230 @param Buffer Buffer is a pointer to pointer to a buffer
231 in which the file or section contents or are
232 returned.
233 @param BufferSize BufferSize is a pointer to caller allocated
234 UINTN. On input *BufferSize indicates the
235 size in bytes of the memory region pointed
236 to by Buffer. On output, *BufferSize
237 contains the number of bytes required to
238 read the file.
239 @param FoundType FoundType is a pointer to a caller allocated
240 EFI_FV_FILETYPE that on successful return
241 from Read() contains the type of file read.
242 This output reflects the file type
243 irrespective of the value of the SectionType
244 input.
245 @param FileAttributes FileAttributes is a pointer to a caller
246 allocated EFI_FV_FILE_ATTRIBUTES. On
247 successful return from Read(),
248 *FileAttributes contains the attributes of
249 the file read.
250 @param AuthenticationStatus AuthenticationStatus is a pointer to a
251 caller allocated UINTN in which the
252 authentication status is returned.
253
254 @retval EFI_SUCCESS Successfully read to memory buffer.
255 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
256 @retval EFI_NOT_FOUND Not found.
257 @retval EFI_DEVICE_ERROR Device error.
258 @retval EFI_ACCESS_DENIED Could not read.
259 @retval EFI_INVALID_PARAMETER Invalid parameter.
260 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
261
262 **/
263 EFI_STATUS
264 EFIAPI
265 FvReadFile (
266 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
267 IN CONST EFI_GUID *NameGuid,
268 IN OUT VOID **Buffer,
269 IN OUT UINTN *BufferSize,
270 OUT EFI_FV_FILETYPE *FoundType,
271 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,
272 OUT UINT32 *AuthenticationStatus
273 )
274 {
275 EFI_STATUS Status;
276 FV_DEVICE *FvDevice;
277 EFI_GUID SearchNameGuid;
278 EFI_FV_FILETYPE LocalFoundType;
279 EFI_FV_FILE_ATTRIBUTES LocalAttributes;
280 UINTN FileSize;
281 UINT8 *SrcPtr;
282 EFI_FFS_FILE_HEADER *FfsHeader;
283 UINTN InputBufferSize;
284
285 if (NULL == NameGuid) {
286 return EFI_INVALID_PARAMETER;
287 }
288
289 FvDevice = FV_DEVICE_FROM_THIS (This);
290
291
292 //
293 // Keep looking until we find the matching NameGuid.
294 // The Key is really an FfsFileEntry
295 //
296 FvDevice->LastKey = 0;
297 do {
298 LocalFoundType = 0;
299 Status = FvGetNextFile (
300 This,
301 &FvDevice->LastKey,
302 &LocalFoundType,
303 &SearchNameGuid,
304 &LocalAttributes,
305 &FileSize
306 );
307 if (EFI_ERROR (Status)) {
308 return EFI_NOT_FOUND;
309 }
310 } while (!CompareGuid (&SearchNameGuid, NameGuid));
311
312 //
313 // Get a pointer to the header
314 //
315 FfsHeader = FvDevice->LastKey->FfsHeader;
316
317 //
318 // Remember callers buffer size
319 //
320 InputBufferSize = *BufferSize;
321
322 //
323 // Calculate return values
324 //
325 *FoundType = FfsHeader->Type;
326 *FileAttributes = FfsAttributes2FvFileAttributes (FfsHeader->Attributes);
327 *AuthenticationStatus = 0;
328 *BufferSize = FileSize;
329
330 if (Buffer == NULL) {
331 //
332 // If Buffer is NULL, we only want to get the information colected so far
333 //
334 return EFI_SUCCESS;
335 }
336
337 //
338 // Skip over file header
339 //
340 SrcPtr = ((UINT8 *)FfsHeader) + sizeof (EFI_FFS_FILE_HEADER);
341
342 Status = EFI_SUCCESS;
343 if (*Buffer == NULL) {
344 //
345 // Caller passed in a pointer so allocate buffer for them
346 //
347 *Buffer = CoreAllocateBootServicesPool (FileSize);
348 if (*Buffer == NULL) {
349 return EFI_OUT_OF_RESOURCES;
350 }
351 } else if (FileSize > InputBufferSize) {
352 //
353 // Callers buffer was not big enough
354 //
355 Status = EFI_WARN_BUFFER_TOO_SMALL;
356 FileSize = InputBufferSize;
357 }
358
359 //
360 // Copy data into callers buffer
361 //
362 CopyMem (*Buffer, SrcPtr, FileSize);
363
364 return Status;
365 }
366
367
368
369 /**
370 Locates a section in a given FFS File and
371 copies it to the supplied buffer (not including section header).
372
373 @param This Indicates the calling context.
374 @param NameGuid Pointer to an EFI_GUID, which is the
375 filename.
376 @param SectionType Indicates the section type to return.
377 @param SectionInstance Indicates which instance of sections with a
378 type of SectionType to return.
379 @param Buffer Buffer is a pointer to pointer to a buffer
380 in which the file or section contents or are
381 returned.
382 @param BufferSize BufferSize is a pointer to caller allocated
383 UINTN.
384 @param AuthenticationStatus AuthenticationStatus is a pointer to a
385 caller allocated UINT32 in which the
386 authentication status is returned.
387
388 @retval EFI_SUCCESS Successfully read the file section into
389 buffer.
390 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
391 @retval EFI_NOT_FOUND Section not found.
392 @retval EFI_DEVICE_ERROR Device error.
393 @retval EFI_ACCESS_DENIED Could not read.
394 @retval EFI_INVALID_PARAMETER Invalid parameter.
395
396 **/
397 EFI_STATUS
398 EFIAPI
399 FvReadFileSection (
400 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
401 IN CONST EFI_GUID *NameGuid,
402 IN EFI_SECTION_TYPE SectionType,
403 IN UINTN SectionInstance,
404 IN OUT VOID **Buffer,
405 IN OUT UINTN *BufferSize,
406 OUT UINT32 *AuthenticationStatus
407 )
408 {
409 EFI_STATUS Status;
410 FV_DEVICE *FvDevice;
411 EFI_FV_FILETYPE FileType;
412 EFI_FV_FILE_ATTRIBUTES FileAttributes;
413 UINTN FileSize;
414 UINT8 *FileBuffer;
415 FFS_FILE_LIST_ENTRY *FfsEntry;
416
417 if (NULL == NameGuid || Buffer == NULL) {
418 return EFI_INVALID_PARAMETER;
419 }
420
421 FvDevice = FV_DEVICE_FROM_THIS (This);
422
423 //
424 // Read the whole file into buffer
425 //
426 FileBuffer = NULL;
427 Status = FvReadFile (
428 This,
429 NameGuid,
430 (VOID **)&FileBuffer,
431 &FileSize,
432 &FileType,
433 &FileAttributes,
434 AuthenticationStatus
435 );
436 //
437 // Get the last key used by our call to FvReadFile as it is the FfsEntry for this file.
438 //
439 FfsEntry = (FFS_FILE_LIST_ENTRY *)FvDevice->LastKey;
440
441 if (EFI_ERROR (Status)) {
442 return Status;
443 }
444
445 //
446 // Check to see that the file actually HAS sections before we go any further.
447 //
448 if (FileType == EFI_FV_FILETYPE_RAW) {
449 Status = EFI_NOT_FOUND;
450 goto Done;
451 }
452
453 //
454 // Use FfsEntry to cache Section Extraction Protocol Inforomation
455 //
456 if (FfsEntry->StreamHandle == 0) {
457 Status = OpenSectionStream (
458 FileSize,
459 FileBuffer,
460 &FfsEntry->StreamHandle
461 );
462 if (EFI_ERROR (Status)) {
463 goto Done;
464 }
465 }
466
467 //
468 // If SectionType == 0 We need the whole section stream
469 //
470 Status = GetSection (
471 FfsEntry->StreamHandle,
472 (SectionType == 0) ? NULL : &SectionType,
473 NULL,
474 (SectionType == 0) ? 0 : SectionInstance,
475 Buffer,
476 BufferSize,
477 AuthenticationStatus
478 );
479
480 //
481 // Close of stream defered to close of FfsHeader list to allow SEP to cache data
482 //
483
484 Done:
485 CoreFreePool (FileBuffer);
486
487 return Status;
488 }
489
490
EFI Development Kit II mirror for PVE