MdePkg/Library/PeiExtractGuidedSectionLib/PeiExtractGuidedSectionLib.c

   1 /** @file
   2   Provide generic extract guided section functions for PEI phase.
   3
   4   Copyright (c) 2007 - 2008, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include <PiPei.h>
  16
  17 #include <Library/DebugLib.h>
  18 #include <Library/PcdLib.h>
  19 #include <Library/BaseMemoryLib.h>
  20 #include <Library/HobLib.h>
  21 #include <Library/ExtractGuidedSectionLib.h>
  22
  23 #define PEI_EXTRACT_HANDLER_INFO_SIGNATURE EFI_SIGNATURE_32 ('P', 'E', 'H', 'I')
  24
  25 typedef struct {
  26   UINT32                                  Signature;
  27   UINT32                                  NumberOfExtractHandler;
  28   GUID                                    *ExtractHandlerGuidTable;
  29   EXTRACT_GUIDED_SECTION_DECODE_HANDLER   *ExtractDecodeHandlerTable;
  30   EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *ExtractGetInfoHandlerTable;
  31 } PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO;
  32
  33 /**
  34   Build guid hob for the global memory to store the registered guid and Handler list.
  35   If GuidHob exists, HandlerInfo will be directly got from Guid hob data.
  36
  37   @param[in, out]  InfoPointer   Pointer to pei handler info structure.
  38
  39   @retval  RETURN_SUCCESS            Build Guid hob for the global memory space to store guid and function tables.
  40   @retval  RETURN_OUT_OF_RESOURCES   No enough memory to allocated.
  41 **/
  42 RETURN_STATUS
  43 PeiGetExtractGuidedSectionHandlerInfo (
  44   IN OUT PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO **InfoPointer
  45   )
  46 {
  47   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
  48   EFI_PEI_HOB_POINTERS                    Hob;
  49
  50   //
  51   // First try to get handler info from guid hob specified by CallerId.
  52   //
  53   Hob.Raw = GetNextHob (EFI_HOB_TYPE_GUID_EXTENSION, GetHobList ());
  54   while (Hob.Raw != NULL) {
  55     if (CompareGuid (&(Hob.Guid->Name), &gEfiCallerIdGuid)) {
  56       HandlerInfo = (PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *) GET_GUID_HOB_DATA (Hob.Guid);
  57       if (HandlerInfo->Signature == PEI_EXTRACT_HANDLER_INFO_SIGNATURE) {
  58         //
  59         // Update Table Pointer when hob start address is changed.
  60         //
  61         if (HandlerInfo->ExtractHandlerGuidTable != (GUID *) (HandlerInfo + 1)) {
  62           HandlerInfo->ExtractHandlerGuidTable    = (GUID *) (HandlerInfo + 1);
  63           HandlerInfo->ExtractDecodeHandlerTable  = (EXTRACT_GUIDED_SECTION_DECODE_HANDLER *) (
  64                                                       (UINT8 *)HandlerInfo->ExtractHandlerGuidTable +
  65                                                       PcdGet32 (PcdMaximumGuidedExtractHandler) * sizeof (GUID)
  66                                                      );
  67           HandlerInfo->ExtractGetInfoHandlerTable = (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *) (
  68                                                       (UINT8 *)HandlerInfo->ExtractDecodeHandlerTable +
  69                                                       PcdGet32 (PcdMaximumGuidedExtractHandler) *
  70                                                       sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER)
  71                                                      );
  72         }
  73         //
  74         // Return HandlerInfo pointer.
  75         //
  76         *InfoPointer = HandlerInfo;
  77         return EFI_SUCCESS;
  78       }
  79     }
  80     Hob.Raw = GET_NEXT_HOB (Hob);
  81     Hob.Raw = GetNextHob (EFI_HOB_TYPE_GUID_EXTENSION, Hob.Raw);
  82   }
  83
  84   //
  85   // If Guid Hob is not found, Build CallerId Guid hob to store Handler Info
  86   //
  87   HandlerInfo = BuildGuidHob (
  88                  &gEfiCallerIdGuid,
  89                  sizeof (PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO) +
  90                  PcdGet32 (PcdMaximumGuidedExtractHandler) *
  91                  (sizeof (GUID) + sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER) + sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER))
  92                 );
  93   if (HandlerInfo == NULL) {
  94     //
  95     // No enough resource to build guid hob.
  96     //
  97     return EFI_OUT_OF_RESOURCES;
  98   }
  99   //
 100   // Init HandlerInfo structure
 101   //
 102   HandlerInfo->Signature = PEI_EXTRACT_HANDLER_INFO_SIGNATURE;
 103   HandlerInfo->NumberOfExtractHandler     = 0;
 104   HandlerInfo->ExtractHandlerGuidTable    = (GUID *) (HandlerInfo + 1);
 105   HandlerInfo->ExtractDecodeHandlerTable  = (EXTRACT_GUIDED_SECTION_DECODE_HANDLER *) (
 106                                               (UINT8 *)HandlerInfo->ExtractHandlerGuidTable +
 107                                               PcdGet32 (PcdMaximumGuidedExtractHandler) * sizeof (GUID)
 108                                              );
 109   HandlerInfo->ExtractGetInfoHandlerTable = (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *) (
 110                                               (UINT8 *)HandlerInfo->ExtractDecodeHandlerTable +
 111                                               PcdGet32 (PcdMaximumGuidedExtractHandler) *
 112                                               sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER)
 113                                              );
 114   //
 115   // return the created HandlerInfo.
 116   //
 117   *InfoPointer = HandlerInfo;
 118   return EFI_SUCCESS;
 119 }
 120
 121 /**
 122   Retrieve the list GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers().
 123
 124   Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs.
 125   The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated
 126   and caller must treat this array of GUIDs as read-only data.
 127
 128   If ExtractHandlerGuidTable is NULL, then ASSERT().
 129
 130   @param[out]  ExtractHandlerGuidTable  A pointer to the array of GUIDs that have been registered through
 131                                         ExtractGuidedSectionRegisterHandlers().
 132
 133   @return the number of the supported extract guided Handler.
 134
 135 **/
 136 UINTN
 137 EFIAPI
 138 ExtractGuidedSectionGetGuidList (
 139   OUT  GUID  **ExtractHandlerGuidTable
 140   )
 141 {
 142   EFI_STATUS Status;
 143   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 144
 145   ASSERT (ExtractHandlerGuidTable != NULL);
 146
 147   //
 148   // Get all registered handler information
 149   //
 150   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 151   if (EFI_ERROR (Status)) {
 152     return Status;
 153   }
 154
 155   //
 156   // Get GuidTable and Table Number
 157   //
 158   *ExtractHandlerGuidTable = HandlerInfo->ExtractHandlerGuidTable;
 159   return HandlerInfo->NumberOfExtractHandler;
 160 }
 161
 162 /**
 163   Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
 164   for a specific GUID section type.
 165
 166   Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
 167   If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
 168   If there are not enough resources available to register the handlers  then RETURN_OUT_OF_RESOURCES is returned.
 169
 170   If SectionGuid is NULL, then ASSERT().
 171   If GetInfoHandler is NULL, then ASSERT().
 172   If DecodeHandler is NULL, then ASSERT().
 173
 174   @param[in]  SectionGuid    A pointer to the GUID associated with the the handlers
 175                              of the GUIDed section type being registered.
 176   @param[in]  GetInfoHandler Pointer to a function that examines a GUIDed section and returns the
 177                              size of the decoded buffer and the size of an optional scratch buffer
 178                              required to actually decode the data in a GUIDed section.
 179   @param[in]  DecodeHandler  Pointer to a function that decodes a GUIDed section into a caller
 180                              allocated output buffer.
 181
 182   @retval  RETURN_SUCCESS           The handlers were registered.
 183   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to register the handlers.
 184
 185 **/
 186 RETURN_STATUS
 187 EFIAPI
 188 ExtractGuidedSectionRegisterHandlers (
 189   IN CONST  GUID                                     *SectionGuid,
 190   IN        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  GetInfoHandler,
 191   IN        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    DecodeHandler
 192   )
 193 {
 194   EFI_STATUS Status;
 195   UINT32     Index;
 196   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 197
 198   //
 199   // Check input paramter
 200   //
 201   ASSERT (SectionGuid != NULL);
 202   ASSERT (GetInfoHandler != NULL);
 203   ASSERT (DecodeHandler != NULL);
 204
 205
 206
 207   //
 208   // Get the registered handler information
 209   //
 210   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 211   if (EFI_ERROR (Status)) {
 212     return Status;
 213   }
 214
 215   //
 216   // Search the match registered GetInfo handler for the input guided section.
 217   //
 218   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 219     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, SectionGuid)) {
 220       //
 221       // If the guided handler has been registered before, only update its handler.
 222       //
 223       HandlerInfo->ExtractDecodeHandlerTable [Index] = DecodeHandler;
 224       HandlerInfo->ExtractGetInfoHandlerTable [Index] = GetInfoHandler;
 225       return RETURN_SUCCESS;
 226     }
 227   }
 228
 229   //
 230   // Check the global table is enough to contain new Handler.
 231   //
 232   if (HandlerInfo->NumberOfExtractHandler >= PcdGet32 (PcdMaximumGuidedExtractHandler)) {
 233     return RETURN_OUT_OF_RESOURCES;
 234   }
 235
 236   //
 237   // Register new Handler and guid value.
 238   //
 239   CopyGuid (HandlerInfo->ExtractHandlerGuidTable + HandlerInfo->NumberOfExtractHandler, SectionGuid);
 240   HandlerInfo->ExtractDecodeHandlerTable [HandlerInfo->NumberOfExtractHandler] = DecodeHandler;
 241   HandlerInfo->ExtractGetInfoHandlerTable [HandlerInfo->NumberOfExtractHandler++] = GetInfoHandler;
 242
 243   return RETURN_SUCCESS;
 244 }
 245
 246 /**
 247   Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type
 248   EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 249   The selected handler is used to retrieve and return the size of the decoded buffer and the size of an
 250   optional scratch buffer required to actually decode the data in a GUIDed section.
 251
 252   Examines a GUIDed section specified by InputSection.
 253   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 254   then RETURN_UNSUPPORTED is returned.
 255   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 256   of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 257   is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of
 258   type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned.
 259
 260   If InputSection is NULL, then ASSERT().
 261   If OutputBufferSize is NULL, then ASSERT().
 262   If ScratchBufferSize is NULL, then ASSERT().
 263   If SectionAttribute is NULL, then ASSERT().
 264
 265   @param[in]  InputSection       A pointer to a GUIDed section of an FFS formatted file.
 266   @param[out] OutputBufferSize   A pointer to the size, in bytes, of an output buffer required if the buffer
 267                                  specified by InputSection were decoded.
 268   @param[out] ScratchBufferSize  A pointer to the size, in bytes, required as scratch space if the buffer specified by
 269                                  InputSection were decoded.
 270   @param[out] SectionAttribute   A pointer to the attributes of the GUIDed section.  See the Attributes field of
 271                                  EFI_GUID_DEFINED_SECTION in the PI Specification.
 272
 273   @retval  RETURN_SUCCESS      Get the required information successfully.
 274   @retval  RETURN_UNSUPPORTED  The GUID from the section specified by InputSection does not match any of
 275                                the GUIDs registered with ExtractGuidedSectionRegisterHandlers().
 276   @retval  Others              The return status from the handler associated with the GUID retrieved from
 277                                the section specified by InputSection.
 278
 279 **/
 280 RETURN_STATUS
 281 EFIAPI
 282 ExtractGuidedSectionGetInfo (
 283   IN  CONST VOID    *InputSection,
 284   OUT       UINT32  *OutputBufferSize,
 285   OUT       UINT32  *ScratchBufferSize,
 286   OUT       UINT16  *SectionAttribute
 287   )
 288 {
 289   UINT32 Index;
 290   EFI_STATUS Status;
 291   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 292
 293   //
 294   // Check input paramter
 295   //
 296   ASSERT (InputSection != NULL);
 297   ASSERT (OutputBufferSize != NULL);
 298   ASSERT (ScratchBufferSize != NULL);
 299   ASSERT (SectionAttribute != NULL);
 300
 301   //
 302   // Get all registered handler information.
 303   //
 304   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 305   if (EFI_ERROR (Status)) {
 306     return Status;
 307   }
 308
 309   //
 310   // Search the match registered GetInfo handler for the input guided section.
 311   //
 312   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 313     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 314       //
 315       // Call the match handler to get info for the input section data.
 316       //
 317       return HandlerInfo->ExtractGetInfoHandlerTable [Index] (
 318                 InputSection,
 319                 OutputBufferSize,
 320                 ScratchBufferSize,
 321                 SectionAttribute
 322               );
 323     }
 324   }
 325
 326   //
 327   // Not found, the input guided section is not supported.
 328   //
 329   return RETURN_UNSUPPORTED;
 330 }
 331
 332 /**
 333   Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
 334   EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 335   The selected handler is used to decode the data in a GUIDed section and return the result in a caller
 336   allocated output buffer.
 337
 338   Decodes the GUIDed section specified by InputSection.
 339   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 340   then RETURN_UNSUPPORTED is returned.
 341   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 342   of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 343   is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
 344   decode operation is returned in AuthenticationStatus.  If the decoded buffer is identical to the data in InputSection,
 345   then OutputBuffer is set to point at the data in InputSection.  Otherwise, the decoded data will be placed in caller
 346   allocated buffer specified by OutputBuffer.    This function is responsible for computing the  EFI_AUTH_STATUS_PLATFORM_OVERRIDE
 347   bit of in AuthenticationStatus.  The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
 348
 349   If InputSection is NULL, then ASSERT().
 350   If OutputBuffer is NULL, then ASSERT().
 351   If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
 352   If AuthenticationStatus is NULL, then ASSERT().
 353
 354   @param[in]  InputSection   A pointer to a GUIDed section of an FFS formatted file.
 355   @param[out] OutputBuffer   A pointer to a buffer that contains the result of a decode operation.
 356   @param[in]  ScratchBuffer  A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
 357   @param[out] AuthenticationStatus
 358                              A pointer to the authentication status of the decoded output buffer. See the definition
 359                              of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
 360                              Specification.
 361
 362   @retval  RETURN_SUCCESS           The buffer specified by InputSection was decoded.
 363   @retval  RETURN_UNSUPPORTED       The section specified by InputSection does not match the GUID this handler supports.
 364   @retval  RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
 365
 366 **/
 367 RETURN_STATUS
 368 EFIAPI
 369 ExtractGuidedSectionDecode (
 370   IN  CONST VOID    *InputSection,
 371   OUT       VOID    **OutputBuffer,
 372   IN        VOID    *ScratchBuffer,        OPTIONAL
 373   OUT       UINT32  *AuthenticationStatus
 374   )
 375 {
 376   UINT32     Index;
 377   EFI_STATUS Status;
 378   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 379
 380   //
 381   // Check input parameter
 382   //
 383   ASSERT (InputSection != NULL);
 384   ASSERT (OutputBuffer != NULL);
 385   ASSERT (AuthenticationStatus != NULL);
 386
 387   //
 388   // Get all registered handler information.
 389   //
 390   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 391   if (EFI_ERROR (Status)) {
 392     return Status;
 393   }
 394
 395   //
 396   // Search the match registered Extract handler for the input guided section.
 397   //
 398   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 399     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 400       //
 401       // Call the match handler to extract raw data for the input guided section.
 402       //
 403       return HandlerInfo->ExtractDecodeHandlerTable [Index] (
 404                 InputSection,
 405                 OutputBuffer,
 406                 ScratchBuffer,
 407                 AuthenticationStatus
 408               );
 409     }
 410   }
 411
 412   //
 413   // Not found, the input guided section is not supported.
 414   //
 415   return RETURN_UNSUPPORTED;
 416 }