2 This library provides common functions to process the different guided section data.
4 This library provides functions to process GUIDed sections of FFS files. Handlers may
5 be registered to decode GUIDed sections of FFS files. Services are provided to determine
6 the set of supported section GUIDs, collection information about a specific GUIDed section,
7 and decode a specific GUIDed section.
9 A library instance that produces this library class may be used to produce a
10 EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI or a EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL
11 providing a simple method to extend the number of GUIDed sections types a platform supports.
13 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
14 SPDX-License-Identifier: BSD-2-Clause-Patent
18 #ifndef __EXTRACT_GUIDED_SECTION_H__
19 #define __EXTRACT_GUIDED_SECTION_H__
22 Examines a GUIDed section and returns the size of the decoded buffer and the
23 size of an optional scratch buffer required to actually decode the data in a GUIDed section.
25 Examines a GUIDed section specified by InputSection.
26 If GUID for InputSection does not match the GUID that this handler supports,
27 then RETURN_UNSUPPORTED is returned.
28 If the required information can not be retrieved from InputSection,
29 then RETURN_INVALID_PARAMETER is returned.
30 If the GUID of InputSection does match the GUID that this handler supports,
31 then the size required to hold the decoded buffer is returned in OututBufferSize,
32 the size of an optional scratch buffer is returned in ScratchSize, and the Attributes field
33 from EFI_GUID_DEFINED_SECTION header of InputSection is returned in SectionAttribute.
35 If InputSection is NULL, then ASSERT().
36 If OutputBufferSize is NULL, then ASSERT().
37 If ScratchBufferSize is NULL, then ASSERT().
38 If SectionAttribute is NULL, then ASSERT().
41 @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file.
42 @param[out] OutputBufferSize A pointer to the size, in bytes, of an output buffer required
43 if the buffer specified by InputSection were decoded.
44 @param[out] ScratchBufferSize A pointer to the size, in bytes, required as scratch space
45 if the buffer specified by InputSection were decoded.
46 @param[out] SectionAttribute A pointer to the attributes of the GUIDed section. See the Attributes
47 field of EFI_GUID_DEFINED_SECTION in the PI Specification.
49 @retval RETURN_SUCCESS The information about InputSection was returned.
50 @retval RETURN_UNSUPPORTED The section specified by InputSection does not match the GUID this handler supports.
51 @retval RETURN_INVALID_PARAMETER The information can not be retrieved from the section specified by InputSection.
56 (EFIAPI
*EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER
)(
57 IN CONST VOID
*InputSection
,
58 OUT UINT32
*OutputBufferSize
,
59 OUT UINT32
*ScratchBufferSize
,
60 OUT UINT16
*SectionAttribute
64 Decodes a GUIDed section into a caller allocated output buffer.
66 Decodes the GUIDed section specified by InputSection.
67 If GUID for InputSection does not match the GUID that this handler supports, then RETURN_UNSUPPORTED is returned.
68 If the data in InputSection can not be decoded, then RETURN_INVALID_PARAMETER is returned.
69 If the GUID of InputSection does match the GUID that this handler supports, then InputSection
70 is decoded into the buffer specified by OutputBuffer and the authentication status of this
71 decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the
72 data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise,
73 the decoded data will be placed in caller allocated buffer specified by OutputBuffer.
75 If InputSection is NULL, then ASSERT().
76 If OutputBuffer is NULL, then ASSERT().
77 If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
78 If AuthenticationStatus is NULL, then ASSERT().
81 @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file.
82 @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation.
83 @param[out] ScratchBuffer A caller allocated buffer that may be required by this function
84 as a scratch buffer to perform the decode operation.
85 @param[out] AuthenticationStatus
86 A pointer to the authentication status of the decoded output buffer.
87 See the definition of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI
88 section of the PI Specification. EFI_AUTH_STATUS_PLATFORM_OVERRIDE must
89 never be set by this handler.
91 @retval RETURN_SUCCESS The buffer specified by InputSection was decoded.
92 @retval RETURN_UNSUPPORTED The section specified by InputSection does not match the GUID this handler supports.
93 @retval RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
98 (EFIAPI
*EXTRACT_GUIDED_SECTION_DECODE_HANDLER
)(
99 IN CONST VOID
*InputSection
,
100 OUT VOID
**OutputBuffer
,
101 IN VOID
*ScratchBuffer OPTIONAL
,
102 OUT UINT32
*AuthenticationStatus
106 Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
107 for a specific GUID section type.
109 Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
110 If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
111 If there are not enough resources available to register the handlers then RETURN_OUT_OF_RESOURCES is returned.
113 If SectionGuid is NULL, then ASSERT().
114 If GetInfoHandler is NULL, then ASSERT().
115 If DecodeHandler is NULL, then ASSERT().
117 @param[in] SectionGuid A pointer to the GUID associated with the the handlers
118 of the GUIDed section type being registered.
119 @param[in] GetInfoHandler Pointer to a function that examines a GUIDed section and returns the
120 size of the decoded buffer and the size of an optional scratch buffer
121 required to actually decode the data in a GUIDed section.
122 @param[in] DecodeHandler Pointer to a function that decodes a GUIDed section into a caller
123 allocated output buffer.
125 @retval RETURN_SUCCESS The handlers were registered.
126 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to register the handlers.
131 ExtractGuidedSectionRegisterHandlers (
132 IN CONST GUID
*SectionGuid
,
133 IN EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER GetInfoHandler
,
134 IN EXTRACT_GUIDED_SECTION_DECODE_HANDLER DecodeHandler
138 Retrieve the list GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers().
140 Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs.
141 The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated
142 and caller must treat this array of GUIDs as read-only data.
143 If ExtractHandlerGuidTable is NULL, then ASSERT().
145 @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs that have been registered through
146 ExtractGuidedSectionRegisterHandlers().
148 @return the number of the supported extract guided Handler.
153 ExtractGuidedSectionGetGuidList (
154 OUT GUID
**ExtractHandlerGuidTable
158 Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type
159 EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
160 The selected handler is used to retrieve and return the size of the decoded buffer and the size of an
161 optional scratch buffer required to actually decode the data in a GUIDed section.
163 Examines a GUIDed section specified by InputSection.
164 If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
165 then RETURN_UNSUPPORTED is returned.
166 If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
167 of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
168 is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of
169 type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned.
171 If InputSection is NULL, then ASSERT().
172 If OutputBufferSize is NULL, then ASSERT().
173 If ScratchBufferSize is NULL, then ASSERT().
174 If SectionAttribute is NULL, then ASSERT().
176 @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file.
177 @param[out] OutputBufferSize A pointer to the size, in bytes, of an output buffer required if the buffer
178 specified by InputSection were decoded.
179 @param[out] ScratchBufferSize A pointer to the size, in bytes, required as scratch space if the buffer specified by
180 InputSection were decoded.
181 @param[out] SectionAttribute A pointer to the attributes of the GUIDed section. See the Attributes field of
182 EFI_GUID_DEFINED_SECTION in the PI Specification.
184 @retval RETURN_SUCCESS Get the required information successfully.
185 @retval RETURN_UNSUPPORTED The GUID from the section specified by InputSection does not match any of
186 the GUIDs registered with ExtractGuidedSectionRegisterHandlers().
187 @retval Others The return status from the handler associated with the GUID retrieved from
188 the section specified by InputSection.
193 ExtractGuidedSectionGetInfo (
194 IN CONST VOID
*InputSection
,
195 OUT UINT32
*OutputBufferSize
,
196 OUT UINT32
*ScratchBufferSize
,
197 OUT UINT16
*SectionAttribute
201 Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
202 EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
203 The selected handler is used to decode the data in a GUIDed section and return the result in a caller
204 allocated output buffer.
206 Decodes the GUIDed section specified by InputSection.
207 If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
208 then RETURN_UNSUPPORTED is returned.
209 If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
210 of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
211 is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
212 decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection,
213 then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller
214 allocated buffer specified by OutputBuffer. This function is responsible for computing the EFI_AUTH_STATUS_PLATFORM_OVERRIDE
215 bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
217 If InputSection is NULL, then ASSERT().
218 If OutputBuffer is NULL, then ASSERT().
219 If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
220 If AuthenticationStatus is NULL, then ASSERT().
222 @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file.
223 @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation.
224 @param[in] ScratchBuffer A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
225 @param[out] AuthenticationStatus
226 A pointer to the authentication status of the decoded output buffer. See the definition
227 of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
230 @retval RETURN_SUCCESS The buffer specified by InputSection was decoded.
231 @retval RETURN_UNSUPPORTED The section specified by InputSection does not match the GUID this handler supports.
232 @retval RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
237 ExtractGuidedSectionDecode (
238 IN CONST VOID
*InputSection
,
239 OUT VOID
**OutputBuffer
,
240 IN VOID
*ScratchBuffer OPTIONAL
,
241 OUT UINT32
*AuthenticationStatus
245 Retrieves handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and
246 EXTRACT_GUIDED_SECTION_DECODE_HANDLER for a specific GUID section type.
248 Retrieves the handlers associated with SectionGuid and returns them in
249 GetInfoHandler and DecodeHandler.
251 If the GUID value specified by SectionGuid has not been registered, then
252 return RETURN_NOT_FOUND.
254 If SectionGuid is NULL, then ASSERT().
256 @param[in] SectionGuid A pointer to the GUID associated with the handlersof the GUIDed
257 section type being retrieved.
258 @param[out] GetInfoHandler Pointer to a function that examines a GUIDed section and returns
259 the size of the decoded buffer and the size of an optional scratch
260 buffer required to actually decode the data in a GUIDed section.
261 This is an optional parameter that may be NULL. If it is NULL, then
262 the previously registered handler is not returned.
263 @param[out] DecodeHandler Pointer to a function that decodes a GUIDed section into a caller
264 allocated output buffer. This is an optional parameter that may be NULL.
265 If it is NULL, then the previously registered handler is not returned.
267 @retval RETURN_SUCCESS The handlers were retrieved.
268 @retval RETURN_NOT_FOUND No handlers have been registered with the specified GUID.
273 ExtractGuidedSectionGetHandlers (
274 IN CONST GUID
*SectionGuid
,
275 OUT EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER
*GetInfoHandler OPTIONAL
,
276 OUT EXTRACT_GUIDED_SECTION_DECODE_HANDLER
*DecodeHandler OPTIONAL