/** @file\r
- This file declares GUIDed section extraction protocol.\r
+ If a GUID-defined section is encountered when doing section\r
+ extraction, the section extraction driver calls the appropriate\r
+ instance of the GUIDed Section Extraction Protocol to extract\r
+ the section stream contained therein.\r
\r
- This interface provides a means of decoding a GUID defined encapsulation \r
- section. There may be multiple different GUIDs associated with the GUIDed\r
- section extraction protocol. That is, all instances of the GUIDed section\r
- extraction protocol must have the same interface structure.\r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: GuidedSectionExtraction.h\r
-\r
- @par Revision Reference:\r
- This protocol is defined in Firmware Volume Specification.\r
- Version 0.9\r
+ @par Revision Reference: PI\r
+ Version 1.00.\r
\r
**/\r
\r
-#ifndef __GUIDED_SECTION_EXTRACTION_PROTOCOL_H__\r
-#define __GUIDED_SECTION_EXTRACTION_PROTOCOL_H__\r
-\r
+#ifndef __GUID_SECTION_EXTRACTION_PROTOCOL_H__\r
+#define __GUID_SECTION_EXTRACTION_PROTOCOL_H__\r
\r
//\r
-// Protocol GUID definition. Each GUIDed section extraction protocol has the\r
-// same interface but with different GUID. All the GUIDs is defined here.\r
-// May add multiple GUIDs here.\r
+// The protocol interface structures are identified by associating\r
+// them with a GUID. Each instance of a protocol with a given\r
+// GUID must have the same interface structure. While all instances\r
+// of the GUIDed Section Extraction Protocol must have the same\r
+// interface structure, they do not all have the same GUID. The\r
+// GUID that is associated with an instance of the GUIDed Section\r
+// Extraction Protocol is used to correlate it with the GUIDed\r
+// section type that it is intended to process.\r
//\r
-#define EFI_CRC32_GUIDED_SECTION_EXTRACTION_PROTOCOL_GUID \\r
- { \\r
- 0xFC1BCDB0, 0x7D31, 0x49aa, {0x93, 0x6A, 0xA4, 0x60, 0x0D, 0x9D, 0xD0, 0x83 } \\r
- }\r
\r
-//\r
-// Forward reference for pure ANSI compatability\r
-//\r
-typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL;\r
+typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL;\r
+\r
\r
-//\r
-// Protocol member functions\r
-//\r
/**\r
- Processes the input section and returns the data contained therein along \r
- with the authentication status.\r
-\r
- @param This Indicates the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance. \r
- @param InputSection Buffer containing the input GUIDed section to be processed. \r
- @param OutputBuffer *OutputBuffer is allocated from boot services pool memory \r
- and contains the new section stream. \r
- @param OutputSize A pointer to a caller-allocated UINTN in which the size \r
- of *OutputBuffer allocation is stored. \r
- @param AuthenticationStatus A pointer to a caller-allocated UINT32 that \r
- indicates the authentication status of the output buffer.\r
- \r
- @retval EFI_SUCCESS The InputSection was successfully processed and the \r
- section contents were returned.\r
- @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to \r
- process the request.\r
- @retval EFI_INVALID_PARAMETER The GUID in InputSection does not match \r
- this instance of the GUIDed Section Extraction Protocol.\r
+ The ExtractSection() function processes the input section and\r
+ allocates a buffer from the pool in which it returns the section\r
+ contents. If the section being extracted contains\r
+ authentication information (the section's\r
+ GuidedSectionHeader.Attributes field has the\r
+ EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values\r
+ returned in AuthenticationStatus must reflect the results of\r
+ the authentication operation. Depending on the algorithm and\r
+ size of the encapsulated data, the time that is required to do\r
+ a full authentication may be prohibitively long for some\r
+ classes of systems. To indicate this, use\r
+ EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by\r
+ the security policy driver (see the Platform Initialization\r
+ Driver Execution Environment Core Interface Specification for\r
+ more details and the GUID definition). If the\r
+ EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle\r
+ database, then, if possible, full authentication should be\r
+ skipped and the section contents simply returned in the\r
+ OutputBuffer. In this case, the\r
+ EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus\r
+ must be set on return. ExtractSection() is callable only from\r
+ TPL_NOTIFY and below. Behavior of ExtractSection() at any\r
+ EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is\r
+ defined in RaiseTPL() in the UEFI 2.0 specification.\r
+\r
+\r
+ @param This Indicates the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.\r
+\r
+ @param InputSection Buffer containing the input GUIDed section\r
+ to be processed. OutputBuffer OutputBuffer\r
+ is allocated from boot services pool\r
+ memory and contains the new section\r
+ stream. The caller is responsible for\r
+ freeing this buffer.\r
+\r
+ @param OutputSize A pointer to a caller-allocated UINTN in\r
+ which the size of OutputBuffer allocation\r
+ is stored. If the function returns\r
+ anything other than EFI_SUCCESS, the value\r
+ of OutputSize is undefined.\r
+\r
+ @param AuthenticationStatus A pointer to a caller-allocated\r
+ UINT32 that indicates the\r
+ authentication status of the\r
+ output buffer. If the input\r
+ section's\r
+ GuidedSectionHeader.Attributes\r
+ field has the\r
+ EFI_GUIDED_SECTION_AUTH_STATUS_VAL\r
+ bit as clear, AuthenticationStatus\r
+ must return zero. Both local bits\r
+ (19:16) and aggregate bits (3:0)\r
+ in AuthenticationStatus are\r
+ returned by ExtractSection().\r
+ These bits reflect the status of\r
+ the extraction operation. The bit\r
+ pattern in both regions must be\r
+ the same, as the local and\r
+ aggregate authentication statuses\r
+ have equivalent meaning at this\r
+ level. If the function returns\r
+ anything other than EFI_SUCCESS,\r
+ the value of AuthenticationStatus\r
+ is undefined.\r
+\r
+ @retval EFI_SUCCESS The InputSection was successfully\r
+ processed and the section contents were\r
+ returned.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient\r
+ resources to process the\r
+ request.\r
+\r
+ @retval EFI_INVALID_PARAMETER The GUID in InputSection does\r
+ not match this instance of the\r
+ GUIDed Section Extraction\r
+ Protocol.\r
\r
**/\r
-\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_EXTRACT_GUIDED_SECTION) (\r
- IN EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL *This,\r
- IN VOID *InputSection,\r
- OUT VOID **OutputBuffer,\r
- OUT UINTN *OutputSize,\r
- OUT UINT32 *AuthenticationStatus\r
- );\r
-\r
-//\r
-// Protocol definition\r
-//\r
-/**\r
- @par Protocol Description:\r
- If a GUID-defined section is encountered when doing section extraction, \r
- the section extraction driver calls the appropriate instance of the GUIDed \r
- Section Extraction Protocol to extract the section stream contained therein.\r
-\r
- @param ExtractSection\r
- Takes the GUIDed section as input and produces the section stream data. \r
-\r
-**/\r
+(EFIAPI *EFI_EXTRACT_GUIDED_SECTION)(\r
+ IN CONST EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL *This,\r
+ IN CONST VOID *InputSection,\r
+ OUT VOID **OutputBuffer,\r
+ OUT UINTN *OutputSize,\r
+ OUT UINT32 *AuthenticationStatus\r
+);\r
+\r
+\r
+///\r
+/// Typically, protocol interface structures are identified by associating them with a GUID. Each\r
+/// instance of a protocol with a given GUID must have the same interface structure. While all instances\r
+/// of the GUIDed Section Extraction Protocol must have the same interface structure, they do not all\r
+/// have the same GUID. The GUID that is associated with an instance of the GUIDed Section\r
+/// Extraction Protocol is used to correlate it with the GUIDed section type that it is intended to process.\r
+///\r
struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL {\r
EFI_EXTRACT_GUIDED_SECTION ExtractSection;\r
};\r
\r
-//\r
-// may add other GUID here\r
-//\r
-extern EFI_GUID gEfiCrc32GuidedSectionExtractionProtocolGuid;\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff