IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.h

   1 /** @file
   2   Section Extraction Protocol implementation.
   3
   4   Stream database is implemented as a linked list of section streams,
   5   where each stream contains a linked list of children, which may be leaves or
   6   encapsulations.
   7
   8   Children that are encapsulations generate new stream entries
   9   when they are created.  Streams can also be created by calls to
  10   SEP->OpenSectionStream().
  11
  12   The database is only created far enough to return the requested data from
  13   any given stream, or to determine that the requested data is not found.
  14
  15   If a GUIDed encapsulation is encountered, there are three possiblilites.
  16
  17   1) A support protocol is found, in which the stream is simply processed with
  18      the support protocol.
  19
  20   2) A support protocol is not found, but the data is available to be read
  21      without processing.  In this case, the database is built up through the
  22      recursions to return the data, and a RPN event is set that will enable
  23      the stream in question to be refreshed if and when the required section
  24      extraction protocol is published.This insures the AuthenticationStatus
  25      does not become stale in the cache.
  26
  27   3) A support protocol is not found, and the data is not available to be read
  28      without it.  This results in EFI_PROTOCOL_ERROR.
  29
  30 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
  31 All rights reserved. This program and the accompanying materials
  32 are licensed and made available under the terms and conditions of the BSD License
  33 which accompanies this distribution.  The full text of the license may be found at
  34 http://opensource.org/licenses/bsd-license.php
  35
  36 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  37 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  38
  39 **/
  40
  41 #ifndef _SECION_EXTRACTION_H_
  42 #define _SECION_EXTRACTION_H_
  43
  44 #include <FrameworkDxe.h>
  45
  46 #include <Protocol/SectionExtraction.h>
  47
  48 #include <Library/BaseLib.h>
  49 #include <Library/DebugLib.h>
  50 #include <Library/UefiLib.h>
  51 #include <Library/UefiBootServicesTableLib.h>
  52 #include <Library/MemoryAllocationLib.h>
  53 #include <Library/BaseMemoryLib.h>
  54 #include <Protocol/Decompress.h>
  55 #include <Protocol/GuidedSectionExtraction.h>
  56
  57 //
  58 // Local defines and typedefs
  59 //
  60 #define CORE_SECTION_CHILD_SIGNATURE  SIGNATURE_32('S','X','C','S')
  61 #define CHILD_SECTION_NODE_FROM_LINK(Node) \
  62   CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)
  63
  64 typedef struct {
  65   UINT32                      Signature;
  66   LIST_ENTRY                  Link;
  67   UINT32                      Type;
  68   UINT32                      Size;
  69   //
  70   // StreamBase + OffsetInStream == pointer to section header in stream.  The
  71   // stream base is always known when walking the sections within.
  72   //
  73   UINT32                      OffsetInStream;
  74   //
  75   // Then EncapsulatedStreamHandle below is always 0 if the section is NOT an
  76   // encapsulating section.  Otherwise, it contains the stream handle
  77   // of the encapsulated stream.  This handle is ALWAYS produced any time an
  78   // encapsulating child is encountered, irrespective of whether the
  79   // encapsulated stream is processed further.
  80   //
  81   UINTN                       EncapsulatedStreamHandle;
  82   EFI_GUID                    *EncapsulationGuid;
  83 } CORE_SECTION_CHILD_NODE;
  84
  85 #define CORE_SECTION_STREAM_SIGNATURE SIGNATURE_32('S','X','S','S')
  86 #define STREAM_NODE_FROM_LINK(Node) \
  87   CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)
  88
  89 typedef struct {
  90   UINT32                      Signature;
  91   LIST_ENTRY                  Link;
  92   UINTN                       StreamHandle;
  93   UINT8                       *StreamBuffer;
  94   UINTN                       StreamLength;
  95   LIST_ENTRY                  Children;
  96   //
  97   // Authentication status is from GUIDed encapsulations.
  98   //
  99   UINT32                      AuthenticationStatus;
 100 } CORE_SECTION_STREAM_NODE;
 101
 102 #define NULL_STREAM_HANDLE    0
 103
 104 typedef struct {
 105   CORE_SECTION_CHILD_NODE     *ChildNode;
 106   CORE_SECTION_STREAM_NODE    *ParentStream;
 107   VOID                        *Registration;
 108   EFI_EVENT                   Event;
 109 } RPN_EVENT_CONTEXT;
 110
 111
 112 /**
 113   Create a protocol notification event and return it.
 114
 115   @param ProtocolGuid    Protocol to register notification event on.
 116   @param NotifyTpl       Maximum TPL to signal the NotifyFunction.
 117   @param NotifyFunction  EFI notification routine.
 118   @param NotifyContext   Context passed into Event when it is created.
 119   @param Registration    Registration key returned from RegisterProtocolNotify().
 120   @param SignalFlag      Boolean value to decide whether kick the event after register or not.
 121
 122   @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
 123            is added to the system.
 124
 125 **/
 126 EFI_EVENT
 127 CoreCreateProtocolNotifyEvent (
 128   IN EFI_GUID             *ProtocolGuid,
 129   IN EFI_TPL              NotifyTpl,
 130   IN EFI_EVENT_NOTIFY     NotifyFunction,
 131   IN VOID                 *NotifyContext,
 132   OUT VOID                **Registration,
 133   IN  BOOLEAN             SignalFlag
 134   );
 135
 136 //
 137 // Local prototypes
 138 //
 139
 140 /**
 141   Worker function.  Determine if the input stream:child matches the input type.
 142
 143   @param Stream                 Indicates the section stream associated with the child
 144   @param Child                  Indicates the child to check
 145   @param SearchType             Indicates the type of section to check against for
 146   @param SectionDefinitionGuid  Indicates the GUID to check against if the type is
 147                                 EFI_SECTION_GUID_DEFINED
 148
 149   @retval TRUE                  The child matches
 150   @retval FALSE                 The child doesn't match
 151
 152 **/
 153 BOOLEAN
 154 ChildIsType (
 155   IN CORE_SECTION_STREAM_NODE *Stream,
 156   IN CORE_SECTION_CHILD_NODE  *Child,
 157   IN EFI_SECTION_TYPE         SearchType,
 158   IN EFI_GUID                 *SectionDefinitionGuid
 159   );
 160
 161 /**
 162   RPN callback function.  Removes a stale section stream and re-initializes it
 163   with an updated AuthenticationStatus.
 164
 165   @param Event               The event that fired
 166   @param RpnContext          A pointer to the context that allows us to identify
 167                              the relevent encapsulation.
 168
 169 **/
 170 VOID
 171 EFIAPI
 172 NotifyGuidedExtraction (
 173   IN   EFI_EVENT   Event,
 174   IN   VOID        *RpnContext
 175   );
 176
 177 /**
 178   Worker function.  Constructor for RPN event if needed to keep AuthenticationStatus
 179   cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...
 180
 181   @param ParentStream        Indicates the parent of the ecnapsulation section (child)
 182   @param ChildNode           Indicates the child node that is the encapsulation section.
 183
 184 **/
 185 VOID
 186 CreateGuidedExtractionRpnEvent (
 187   IN CORE_SECTION_STREAM_NODE       *ParentStream,
 188   IN CORE_SECTION_CHILD_NODE        *ChildNode
 189   );
 190
 191 /**
 192   SEP member function.  This function creates and returns a new section stream
 193   handle to represent the new section stream.
 194
 195   @param This                 Indicates the calling context.
 196   @param SectionStreamLength  Size in bytes of the section stream.
 197   @param SectionStream        Buffer containing the new section stream.
 198   @param SectionStreamHandle  A pointer to a caller allocated UINTN that on output
 199                               contains the new section stream handle.
 200
 201   @retval EFI_SUCCESS           Section wase opened successfully.
 202   @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.
 203   @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
 204                                 last section.
 205
 206 **/
 207 EFI_STATUS
 208 EFIAPI
 209 OpenSectionStream (
 210   IN     EFI_SECTION_EXTRACTION_PROTOCOL           *This,
 211   IN     UINTN                                     SectionStreamLength,
 212   IN     VOID                                      *SectionStream,
 213      OUT UINTN                                     *SectionStreamHandle
 214   );
 215
 216 /**
 217   SEP member function.  Retrieves requested section from section stream.
 218
 219   @param This                  Pointer to SEP instance.
 220   @param SectionStreamHandle   The section stream from which to extract the requested
 221                                section.
 222   @param SectionType           A pointer to the type of section to search for.
 223   @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED, then
 224                                SectionDefinitionGuid indicates which of these types
 225                                of sections to search for.
 226   @param SectionInstance       Indicates which instance of the requested section to
 227                                return.
 228   @param Buffer                Double indirection to buffer.  If *Buffer is non-null on
 229                                input, then the buffer is caller allocated.  If
 230                                *Buffer is NULL, then the buffer is callee allocated.
 231                                In either case, the requried buffer size is returned
 232                                in *BufferSize.
 233   @param BufferSize            On input, indicates the size of *Buffer if *Buffer is
 234                                non-null on input.  On output, indicates the required
 235                                size (allocated size if callee allocated) of *Buffer.
 236   @param AuthenticationStatus  Indicates the authentication status of the retrieved
 237                                section.
 238
 239
 240   @retval EFI_SUCCESS           Section was retrieved successfully
 241   @retval EFI_PROTOCOL_ERROR    A GUID defined section was encountered in the section
 242                                 stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
 243                                 bit set, but there was no corresponding GUIDed Section
 244                                 Extraction Protocol in the handle database.  *Buffer is
 245                                 unmodified.
 246   @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream.
 247                                 This indicates the SectionStream  is not correctly
 248                                 formatted.
 249   @retval EFI_NOT_FOUND         The requested section does not exist.
 250   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the
 251                                 request.
 252   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 253   @retval EFI_WARN_TOO_SMALL    The size of the caller allocated input buffer is
 254                                 insufficient to contain the requested section.  The
 255                                 input buffer is filled and contents are section contents
 256                                 are truncated.
 257
 258 **/
 259 EFI_STATUS
 260 EFIAPI
 261 GetSection (
 262   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 263   IN UINTN                                              SectionStreamHandle,
 264   IN EFI_SECTION_TYPE                                   *SectionType,
 265   IN EFI_GUID                                           *SectionDefinitionGuid,
 266   IN UINTN                                              SectionInstance,
 267   IN VOID                                               **Buffer,
 268   IN OUT UINTN                                          *BufferSize,
 269   OUT UINT32                                            *AuthenticationStatus
 270   );
 271
 272 /**
 273   SEP member function.  Deletes an existing section stream
 274
 275   @param This                   Indicates the calling context.
 276   @param StreamHandleToClose    Indicates the stream to close
 277
 278   @retval EFI_SUCCESS           Section stream was closed successfully.
 279   @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.
 280   @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
 281                                 last section.
 282
 283 **/
 284 EFI_STATUS
 285 EFIAPI
 286 CloseSectionStream (
 287   IN  EFI_SECTION_EXTRACTION_PROTOCOL           *This,
 288   IN  UINTN                                     StreamHandleToClose
 289   );
 290
 291 /**
 292   Worker function.  Search stream database for requested stream handle.
 293
 294   @param SearchHandle        Indicates which stream to look for.
 295   @param FoundStream         Output pointer to the found stream.
 296
 297   @retval EFI_SUCCESS        StreamHandle was found and *FoundStream contains
 298                              the stream node.
 299   @retval EFI_NOT_FOUND      SearchHandle was not found in the stream database.
 300
 301 **/
 302 EFI_STATUS
 303 FindStreamNode (
 304   IN  UINTN                                     SearchHandle,
 305   OUT CORE_SECTION_STREAM_NODE                  **FoundStream
 306   );
 307
 308 /**
 309   Worker function  Recursively searches / builds section stream database
 310   looking for requested section.
 311
 312
 313   @param SourceStream          Indicates the section stream in which to do the search.
 314   @param SearchType            Indicates the type of section to search for.
 315   @param SectionInstance       Indicates which instance of section to find.  This is
 316                                an in/out parameter to deal with recursions.
 317   @param SectionDefinitionGuid Guid of section definition
 318   @param FoundChild            Output indicating the child node that is found.
 319   @param FoundStream           Output indicating which section stream the child was
 320                                found in.  If this stream was generated as a result of
 321                                an encapsulation section, the streamhandle is visible
 322                                within the SEP driver only.
 323   @param AuthenticationStatus  Indicates the authentication status of the found section.
 324
 325   @retval EFI_SUCCESS          Child node was found and returned.
 326   @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
 327   @retval EFI_NOT_FOUND        Requested child node does not exist.
 328   @retval EFI_PROTOCOL_ERROR   A required GUIDED section extraction protocol does not
 329                                exist
 330
 331 **/
 332 EFI_STATUS
 333 FindChildNode (
 334   IN     CORE_SECTION_STREAM_NODE                   *SourceStream,
 335   IN     EFI_SECTION_TYPE                           SearchType,
 336   IN OUT UINTN                                      *SectionInstance,
 337   IN     EFI_GUID                                   *SectionDefinitionGuid,
 338   OUT    CORE_SECTION_CHILD_NODE                    **FoundChild,
 339   OUT    CORE_SECTION_STREAM_NODE                   **FoundStream,
 340   OUT    UINT32                                     *AuthenticationStatus
 341   );
 342
 343 /**
 344   Worker function.  Constructor for new child nodes.
 345
 346   @param Stream                Indicates the section stream in which to add the child.
 347   @param ChildOffset           Indicates the offset in Stream that is the beginning
 348                                of the child section.
 349   @param ChildNode             Indicates the Callee allocated and initialized child.
 350
 351   @retval EFI_SUCCESS          Child node was found and returned.
 352   @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
 353   @retval EFI_PROTOCOL_ERROR   Encapsulation sections produce new stream handles when
 354                                the child node is created.  If the section type is GUID
 355                                defined, and the extraction GUID does not exist, and
 356                                producing the stream requires the GUID, then a protocol
 357                                error is generated and no child is produced.
 358                                Values returned by OpenSectionStreamEx.
 359
 360 **/
 361 EFI_STATUS
 362 CreateChildNode (
 363   IN     CORE_SECTION_STREAM_NODE              *Stream,
 364   IN     UINT32                                ChildOffset,
 365      OUT CORE_SECTION_CHILD_NODE               **ChildNode
 366   );
 367
 368 /**
 369   Worker function.  Destructor for child nodes.
 370
 371   @param ChildNode           Indicates the node to destroy
 372
 373 **/
 374 VOID
 375 FreeChildNode (
 376   IN  CORE_SECTION_CHILD_NODE                   *ChildNode
 377   );
 378
 379 /**
 380   Worker function.  Constructor for section streams.
 381
 382   @param SectionStreamLength   Size in bytes of the section stream.
 383   @param SectionStream         Buffer containing the new section stream.
 384   @param AllocateBuffer        Indicates whether the stream buffer is to be copied
 385                                or the input buffer is to be used in place.
 386   @param AuthenticationStatus  Indicates the default authentication status for the
 387                                new stream.
 388   @param SectionStreamHandle   A pointer to a caller allocated section stream handle.
 389
 390   @retval EFI_SUCCESS           Stream was added to stream database.
 391   @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.
 392
 393 **/
 394 EFI_STATUS
 395 OpenSectionStreamEx (
 396   IN     UINTN                                     SectionStreamLength,
 397   IN     VOID                                      *SectionStream,
 398   IN     BOOLEAN                                   AllocateBuffer,
 399   IN     UINT32                                    AuthenticationStatus,
 400      OUT UINTN                                     *SectionStreamHandle
 401   );
 402
 403 /**
 404
 405   Check if a stream is valid.
 406
 407   @param SectionStream         The section stream to be checked
 408   @param SectionStreamLength   The length of section stream
 409
 410   @return The validness of a stream.
 411
 412 **/
 413 BOOLEAN
 414 IsValidSectionStream (
 415   IN  VOID              *SectionStream,
 416   IN  UINTN             SectionStreamLength
 417   );
 418
 419 #endif  // _SECTION_EXTRACTION_H_