SectionExtraction.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155
  1. /** @file
  2. This file declares Section Extraction Protocol.
  3. This interface provides a means of decoding a set of sections into a linked list of
  4. leaf sections. This provides for an extensible and flexible file format.
  5. Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  6. SPDX-License-Identifier: BSD-2-Clause-Patent
  7. @par Revision Reference:
  8. This protocol is defined in Firmware Volume Specification.
  9. Version 0.9.
  10. **/
  11. #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
  12. #define _SECTION_EXTRACTION_PROTOCOL_H_
  13. //
  14. // Protocol GUID definition
  15. //
  16. #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
  17. { \
  18. 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
  19. }
  20. typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
  21. //
  22. // Protocol member functions
  23. //
  24. /**
  25. Creates and returns a new section stream handle to represent the new section stream.
  26. @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  27. @param SectionStreamLength The size in bytes of the section stream.
  28. @param SectionStream A buffer containing the new section stream.
  29. @param SectionStreamHandle A pointer to a caller-allocated UINTN that,
  30. on output, contains the new section stream handle.
  31. @retval EFI_SUCCESS The SectionStream was successfully processed, and
  32. the section stream handle was returned.
  33. @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to
  34. process the request.
  35. @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
  36. of SectionStreamLength may be incorrect.
  37. **/
  38. typedef
  39. EFI_STATUS
  40. (EFIAPI *EFI_OPEN_SECTION_STREAM)(
  41. IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
  42. IN UINTN SectionStreamLength,
  43. IN VOID *SectionStream,
  44. OUT UINTN *SectionStreamHandle
  45. );
  46. /**
  47. Reads and returns a single section from a section stream.
  48. @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  49. @param SectionStreamHandle Indicates from which section stream to read.
  50. @param SectionType The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
  51. the contents of the entire section stream are returned
  52. in Buffer. If SectionType is not NULL, only the
  53. requested section is returned. EFI_SECTION_ALL
  54. matches all section types and can be used as a
  55. wild card to extract all sections in order.
  56. @param SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==
  57. EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  58. indicates what section GUID to search for. If
  59. SectionType !=EFI_SECTION_GUID_DEFINED, then
  60. SectionDefinitionGuid is unused and is ignored.
  61. @param SectionInstance Indicates which instance of the requested section
  62. type to return when SectionType is not NULL.
  63. @param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output,
  64. contains the new section stream handle.
  65. @param Buffer Pointer to a pointer to a buffer in which the section
  66. contents are returned.
  67. @param BufferSize A pointer to a caller-allocated UINTN.
  68. @param AuthenticationStatus A pointer to a caller-allocated UINT32 in
  69. which any meta-data from encapsulation GUID-defined
  70. sections is returned.
  71. @retval EFI_SUCCESS The SectionStream was successfully processed and
  72. the section contents were returned in Buffer.
  73. @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered inthe section
  74. stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
  75. bit set, but there was no corresponding GUIDed
  76. Section Extraction Protocol in the handle database.
  77. @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream,
  78. which indicates that the SectionStream is not
  79. correctly formatted. Or, the requested section does not exist.
  80. @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
  81. the request.
  82. @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  83. @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient
  84. to contain the requested section. The input
  85. buffer is filled and section contents are truncated.
  86. **/
  87. typedef
  88. EFI_STATUS
  89. (EFIAPI *EFI_GET_SECTION)(
  90. IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
  91. IN UINTN SectionStreamHandle,
  92. IN EFI_SECTION_TYPE *SectionType,
  93. IN EFI_GUID *SectionDefinitionGuid,
  94. IN UINTN SectionInstance,
  95. IN VOID **Buffer,
  96. IN OUT UINTN *BufferSize,
  97. OUT UINT32 *AuthenticationStatus
  98. );
  99. /**
  100. Deletes a section stream handle and returns all associated resources to the system.
  101. @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  102. @param SectionStreamHandle Indicates the section stream to close.
  103. @retval EFI_SUCCESS The SectionStream was successfully processed and
  104. the section stream handle was returned.
  105. @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  106. **/
  107. typedef
  108. EFI_STATUS
  109. (EFIAPI *EFI_CLOSE_SECTION_STREAM)(
  110. IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
  111. IN UINTN SectionStreamHandle
  112. );
  113. //
  114. // Protocol definition
  115. //
  116. struct _EFI_SECTION_EXTRACTION_PROTOCOL {
  117. ///
  118. /// Takes a bounded stream of sections and returns a section stream handle.
  119. ///
  120. EFI_OPEN_SECTION_STREAM OpenSectionStream;
  121. ///
  122. /// Given a section stream handle, retrieves the requested section and
  123. /// meta-data from the section stream.
  124. ///
  125. EFI_GET_SECTION GetSection;
  126. ///
  127. /// Given a section stream handle, closes the section stream.
  128. ///
  129. EFI_CLOSE_SECTION_STREAM CloseSectionStream;
  130. };
  131. extern EFI_GUID gEfiSectionExtractionProtocolGuid;
  132. #endif