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 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   If ExtractHandlerGuidTable is NULL, then ASSERT().
 128
 129   @param[out]  ExtractHandlerGuidTable  A pointer to the array of GUIDs that have been registered through
 130                                         ExtractGuidedSectionRegisterHandlers().
 131
 132   @return the number of the supported extract guided Handler.
 133
 134 **/
 135 UINTN
 136 EFIAPI
 137 ExtractGuidedSectionGetGuidList (
 138   OUT  GUID  **ExtractHandlerGuidTable
 139   )
 140 {
 141   EFI_STATUS Status;
 142   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 143
 144   ASSERT (ExtractHandlerGuidTable != NULL);
 145
 146   //
 147   // Get all registered handler information
 148   //
 149   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 150   if (EFI_ERROR (Status)) {
 151     return Status;
 152   }
 153
 154   //
 155   // Get GuidTable and Table Number
 156   //
 157   *ExtractHandlerGuidTable = HandlerInfo->ExtractHandlerGuidTable;
 158   return HandlerInfo->NumberOfExtractHandler;
 159 }
 160
 161 /**
 162   Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
 163   for a specific GUID section type.
 164
 165   Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
 166   If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
 167   If there are not enough resources available to register the handlers  then RETURN_OUT_OF_RESOURCES is returned.
 168
 169   If SectionGuid is NULL, then ASSERT().
 170   If GetInfoHandler is NULL, then ASSERT().
 171   If DecodeHandler is NULL, then ASSERT().
 172
 173   @param[in]  SectionGuid    A pointer to the GUID associated with the the handlers
 174                              of the GUIDed section type being registered.
 175   @param[in]  GetInfoHandler Pointer to a function that examines a GUIDed section and returns the
 176                              size of the decoded buffer and the size of an optional scratch buffer
 177                              required to actually decode the data in a GUIDed section.
 178   @param[in]  DecodeHandler  Pointer to a function that decodes a GUIDed section into a caller
 179                              allocated output buffer.
 180
 181   @retval  RETURN_SUCCESS           The handlers were registered.
 182   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to register the handlers.
 183
 184 **/
 185 RETURN_STATUS
 186 EFIAPI
 187 ExtractGuidedSectionRegisterHandlers (
 188   IN CONST  GUID                                     *SectionGuid,
 189   IN        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  GetInfoHandler,
 190   IN        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    DecodeHandler
 191   )
 192 {
 193   EFI_STATUS Status;
 194   UINT32     Index;
 195   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 196
 197   //
 198   // Check input paramter
 199   //
 200   ASSERT (SectionGuid != NULL);
 201   ASSERT (GetInfoHandler != NULL);
 202   ASSERT (DecodeHandler != NULL);
 203
 204
 205
 206   //
 207   // Get the registered handler information
 208   //
 209   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 210   if (EFI_ERROR (Status)) {
 211     return Status;
 212   }
 213
 214   //
 215   // Search the match registered GetInfo handler for the input guided section.
 216   //
 217   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 218     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, SectionGuid)) {
 219       //
 220       // If the guided handler has been registered before, only update its handler.
 221       //
 222       HandlerInfo->ExtractDecodeHandlerTable [Index] = DecodeHandler;
 223       HandlerInfo->ExtractGetInfoHandlerTable [Index] = GetInfoHandler;
 224       return RETURN_SUCCESS;
 225     }
 226   }
 227
 228   //
 229   // Check the global table is enough to contain new Handler.
 230   //
 231   if (HandlerInfo->NumberOfExtractHandler >= PcdGet32 (PcdMaximumGuidedExtractHandler)) {
 232     return RETURN_OUT_OF_RESOURCES;
 233   }
 234
 235   //
 236   // Register new Handler and guid value.
 237   //
 238   CopyGuid (HandlerInfo->ExtractHandlerGuidTable + HandlerInfo->NumberOfExtractHandler, SectionGuid);
 239   HandlerInfo->ExtractDecodeHandlerTable [HandlerInfo->NumberOfExtractHandler] = DecodeHandler;
 240   HandlerInfo->ExtractGetInfoHandlerTable [HandlerInfo->NumberOfExtractHandler++] = GetInfoHandler;
 241
 242   return RETURN_SUCCESS;
 243 }
 244
 245 /**
 246   Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type
 247   EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 248   The selected handler is used to retrieve and return the size of the decoded buffer and the size of an
 249   optional scratch buffer required to actually decode the data in a GUIDed section.
 250
 251   Examines a GUIDed section specified by InputSection.
 252   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 253   then RETURN_UNSUPPORTED is returned.
 254   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 255   of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 256   is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of
 257   type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned.
 258
 259   If InputSection is NULL, then ASSERT().
 260   If OutputBufferSize is NULL, then ASSERT().
 261   If ScratchBufferSize is NULL, then ASSERT().
 262   If SectionAttribute is NULL, then ASSERT().
 263
 264   @param[in]  InputSection       A pointer to a GUIDed section of an FFS formatted file.
 265   @param[out] OutputBufferSize   A pointer to the size, in bytes, of an output buffer required if the buffer
 266                                  specified by InputSection were decoded.
 267   @param[out] ScratchBufferSize  A pointer to the size, in bytes, required as scratch space if the buffer specified by
 268                                  InputSection were decoded.
 269   @param[out] SectionAttribute   A pointer to the attributes of the GUIDed section.  See the Attributes field of
 270                                  EFI_GUID_DEFINED_SECTION in the PI Specification.
 271
 272   @retval  RETURN_SUCCESS      Get the required information successfully.
 273   @retval  RETURN_UNSUPPORTED  The GUID from the section specified by InputSection does not match any of
 274                                the GUIDs registered with ExtractGuidedSectionRegisterHandlers().
 275   @retval  Others              The return status from the handler associated with the GUID retrieved from
 276                                the section specified by InputSection.
 277
 278 **/
 279 RETURN_STATUS
 280 EFIAPI
 281 ExtractGuidedSectionGetInfo (
 282   IN  CONST VOID    *InputSection,
 283   OUT       UINT32  *OutputBufferSize,
 284   OUT       UINT32  *ScratchBufferSize,
 285   OUT       UINT16  *SectionAttribute
 286   )
 287 {
 288   UINT32 Index;
 289   EFI_STATUS Status;
 290   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 291
 292   //
 293   // Check input paramter
 294   //
 295   ASSERT (InputSection != NULL);
 296   ASSERT (OutputBufferSize != NULL);
 297   ASSERT (ScratchBufferSize != NULL);
 298   ASSERT (SectionAttribute != NULL);
 299
 300   //
 301   // Get all registered handler information.
 302   //
 303   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 304   if (EFI_ERROR (Status)) {
 305     return Status;
 306   }
 307
 308   //
 309   // Search the match registered GetInfo handler for the input guided section.
 310   //
 311   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 312     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 313       //
 314       // Call the match handler to get info for the input section data.
 315       //
 316       return HandlerInfo->ExtractGetInfoHandlerTable [Index] (
 317                 InputSection,
 318                 OutputBufferSize,
 319                 ScratchBufferSize,
 320                 SectionAttribute
 321               );
 322     }
 323   }
 324
 325   //
 326   // Not found, the input guided section is not supported.
 327   //
 328   return RETURN_UNSUPPORTED;
 329 }
 330
 331 /**
 332   Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
 333   EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 334   The selected handler is used to decode the data in a GUIDed section and return the result in a caller
 335   allocated output buffer.
 336
 337   Decodes the GUIDed section specified by InputSection.
 338   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 339   then RETURN_UNSUPPORTED is returned.
 340   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 341   of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 342   is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
 343   decode operation is returned in AuthenticationStatus.  If the decoded buffer is identical to the data in InputSection,
 344   then OutputBuffer is set to point at the data in InputSection.  Otherwise, the decoded data will be placed in caller
 345   allocated buffer specified by OutputBuffer.    This function is responsible for computing the  EFI_AUTH_STATUS_PLATFORM_OVERRIDE
 346   bit of in AuthenticationStatus.  The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
 347
 348   If InputSection is NULL, then ASSERT().
 349   If OutputBuffer is NULL, then ASSERT().
 350   If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
 351   If AuthenticationStatus is NULL, then ASSERT().
 352
 353   @param[in]  InputSection   A pointer to a GUIDed section of an FFS formatted file.
 354   @param[out] OutputBuffer   A pointer to a buffer that contains the result of a decode operation.
 355   @param[in]  ScratchBuffer  A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
 356   @param[out] AuthenticationStatus
 357                              A pointer to the authentication status of the decoded output buffer. See the definition
 358                              of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
 359                              Specification.
 360
 361   @retval  RETURN_SUCCESS           The buffer specified by InputSection was decoded.
 362   @retval  RETURN_UNSUPPORTED       The section specified by InputSection does not match the GUID this handler supports.
 363   @retval  RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
 364
 365 **/
 366 RETURN_STATUS
 367 EFIAPI
 368 ExtractGuidedSectionDecode (
 369   IN  CONST VOID    *InputSection,
 370   OUT       VOID    **OutputBuffer,
 371   IN        VOID    *ScratchBuffer,        OPTIONAL
 372   OUT       UINT32  *AuthenticationStatus
 373   )
 374 {
 375   UINT32     Index;
 376   EFI_STATUS Status;
 377   PEI_EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 378
 379   //
 380   // Check input parameter
 381   //
 382   ASSERT (InputSection != NULL);
 383   ASSERT (OutputBuffer != NULL);
 384   ASSERT (AuthenticationStatus != NULL);
 385
 386   //
 387   // Get all registered handler information.
 388   //
 389   Status = PeiGetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 390   if (EFI_ERROR (Status)) {
 391     return Status;
 392   }
 393
 394   //
 395   // Search the match registered Extract handler for the input guided section.
 396   //
 397   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 398     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 399       //
 400       // Call the match handler to extract raw data for the input guided section.
 401       //
 402       return HandlerInfo->ExtractDecodeHandlerTable [Index] (
 403                 InputSection,
 404                 OutputBuffer,
 405                 ScratchBuffer,
 406                 AuthenticationStatus
 407               );
 408     }
 409   }
 410
 411   //
 412   // Not found, the input guided section is not supported.
 413   //
 414   return RETURN_UNSUPPORTED;
 415 }