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