1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
/** @file
MDE PI library functions and macros
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef __PI_LIB_H__
#define __PI_LIB_H__
#include <Pi/PiFirmwareFile.h>
/**
Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
PiLibGetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function
will search the first file with the specified name in all firmware volumes in the system. The search order for firmware
volumes in the system is determistic but abitrary if no new firmware volume is added into the system between
each calls of this function.
After the specific file is located, the function searches the specifc firmware section with type SectionType in this file.
The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
found in PI Specification.
If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND
is returned.
The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
by this function. This function can only be called at TPL_NOTIFY and below.
If NameGuid is NULL, then ASSERT();
If Buffer is NULL, then ASSERT();
If Size is NULL, then ASSERT().
@param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
section will be read. Type EFI_GUID is defined in
InstallProtocolInterface() in the UEFI 2.0 specification.
@param SectionType Indicates the section type to return. SectionType in conjunction with
SectionInstance indicates which section to return. Type
EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
@param SectionInstance Indicates which instance of sections with a type of SectionType to return.
SectionType in conjunction with SectionInstance indicates which section to
return. SectionInstance is zero based.
@param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
including the section header. Caller is responsible to free this memory.
@param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
*Buffer.
@retval EFI_SUCCESS The image is found and data and size is returned.
@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromAnyFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
;
/**
Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
PiLibGetSectionFromCurrentFv () is used to read a specific section from a file within the same firmware volume from which
the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType.
The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
found in PI Specification.
If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND
is returned.
The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
by this function. This function can be only called at TPL_NOTIFY and below.
If NameGuid is NULL, then ASSERT();
If Buffer is NULL, then ASSERT();
If Size is NULL, then ASSERT().
@param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
section will be read. Type EFI_GUID is defined in
InstallProtocolInterface() in the UEFI 2.0 specification.
@param SectionType Indicates the section type to return. SectionType in conjunction with
SectionInstance indicates which section to return. Type
EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
@param SectionInstance Indicates which instance of sections with a type of SectionType to return.
SectionType in conjunction with SectionInstance indicates which section to
return. SectionInstance is zero based.
@param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
including the section header. Caller is responsible to free this memory.
@param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
*Buffer.
@retval EFI_SUCCESS The image is found and data and size is returned.
@retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromCurrentFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
;
/**
Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
PiLibGetSectionFromCurrentFfs () searches the specifc firmware section with type SectionType in the same firmware file from
which the running image is loaded. The details of this search order is defined in description of
EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.
If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND
is returned.
The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
by this function. This function can only be called at TPL_NOTIFY and below.
If Buffer is NULL, then ASSERT();
If Size is NULL, then ASSERT().
@param SectionType Indicates the section type to return. SectionType in conjunction with
SectionInstance indicates which section to return. Type
EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
@param SectionInstance Indicates which instance of sections with a type of SectionType to return.
SectionType in conjunction with SectionInstance indicates which section to
return. SectionInstance is zero based.
@param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
including the section header. Caller is responsible to free this memory.
@param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
*Buffer.
@retval EFI_SUCCESS The image is found and data and size is returned.
@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromCurrentFfs (
IN EFI_SECTION_TYPE SectionType,
IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
;
#endif
|
