OvmfPkg/Library/SecExtractGuidedSectionLib/SecExtractGuidedSectionLib.c

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