MdePkg/Library/DxeExtractGuidedSectionLib/DxeExtractGuidedSectionLib.c

   1 /** @file
   2   Provide generic extract guided section functions for Dxe phase.
   3
   4   Copyright (c) 2007 - 2018, 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 <PiDxe.h>
  16
  17 #include <Library/DebugLib.h>
  18 #include <Library/BaseMemoryLib.h>
  19 #include <Library/MemoryAllocationLib.h>
  20 #include <Library/ExtractGuidedSectionLib.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22
  23 #define EXTRACT_HANDLER_TABLE_SIZE   0x10
  24
  25 UINT32               mNumberOfExtractHandler = 0;
  26 UINT32               mMaxNumberOfExtractHandler = 0;
  27
  28 GUID                 *mExtractHandlerGuidTable = NULL;
  29 EXTRACT_GUIDED_SECTION_DECODE_HANDLER   *mExtractDecodeHandlerTable = NULL;
  30 EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *mExtractGetInfoHandlerTable = NULL;
  31
  32 /**
  33   Reallocates more global memory to store the registered guid and Handler list.
  34
  35   @retval  RETURN_SUCCESS            Reallocated more global memory space to store guid and function tables.
  36   @retval  RETURN_OUT_OF_RESOURCES   Not enough memory to allocate.
  37 **/
  38 RETURN_STATUS
  39 EFIAPI
  40 ReallocateExtractHandlerTable (
  41   VOID
  42   )
  43 {
  44   //
  45   // Reallocate memory for GuidTable
  46   //
  47   mExtractHandlerGuidTable = ReallocatePool (
  48                                mMaxNumberOfExtractHandler * sizeof (GUID),
  49                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (GUID),
  50                                mExtractHandlerGuidTable
  51                              );
  52
  53   if (mExtractHandlerGuidTable == NULL) {
  54     goto Done;
  55   }
  56
  57   //
  58   // Reallocate memory for Decode handler Table
  59   //
  60   mExtractDecodeHandlerTable = ReallocatePool (
  61                                mMaxNumberOfExtractHandler * sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER),
  62                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER),
  63                                mExtractDecodeHandlerTable
  64                              );
  65
  66   if (mExtractDecodeHandlerTable == NULL) {
  67     goto Done;
  68   }
  69
  70   //
  71   // Reallocate memory for GetInfo handler Table
  72   //
  73   mExtractGetInfoHandlerTable = ReallocatePool (
  74                                mMaxNumberOfExtractHandler * sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER),
  75                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER),
  76                                mExtractGetInfoHandlerTable
  77                              );
  78
  79   if (mExtractGetInfoHandlerTable == NULL) {
  80     goto Done;
  81   }
  82
  83   //
  84   // Increase max handler number
  85   //
  86   mMaxNumberOfExtractHandler = mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE;
  87   return RETURN_SUCCESS;
  88
  89 Done:
  90   if (mExtractHandlerGuidTable != NULL) {
  91     FreePool (mExtractHandlerGuidTable);
  92   }
  93   if (mExtractDecodeHandlerTable != NULL) {
  94     FreePool (mExtractDecodeHandlerTable);
  95   }
  96   if (mExtractGetInfoHandlerTable != NULL) {
  97     FreePool (mExtractGetInfoHandlerTable);
  98   }
  99
 100   return RETURN_OUT_OF_RESOURCES;
 101 }
 102 /**
 103   Constructor allocates the global memory to store the registered guid and Handler list.
 104
 105   @param  ImageHandle   The firmware allocated handle for the EFI image.
 106   @param  SystemTable   A pointer to the EFI System Table.
 107
 108   @retval  RETURN_SUCCESS            Allocated the global memory space to store guid and function tables.
 109   @retval  RETURN_OUT_OF_RESOURCES   Not enough memory to allocate.
 110 **/
 111 RETURN_STATUS
 112 EFIAPI
 113 DxeExtractGuidedSectionLibConstructor (
 114   IN EFI_HANDLE        ImageHandle,
 115   IN EFI_SYSTEM_TABLE  *SystemTable
 116   )
 117 {
 118   return ReallocateExtractHandlerTable ();
 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   ASSERT (ExtractHandlerGuidTable != NULL);
 142
 143   *ExtractHandlerGuidTable = mExtractHandlerGuidTable;
 144   return mNumberOfExtractHandler;
 145 }
 146
 147 /**
 148   Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
 149   for a specific GUID section type.
 150
 151   Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
 152   If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
 153   If there are not enough resources available to register the handlers  then RETURN_OUT_OF_RESOURCES is returned.
 154
 155   If SectionGuid is NULL, then ASSERT().
 156   If GetInfoHandler is NULL, then ASSERT().
 157   If DecodeHandler is NULL, then ASSERT().
 158
 159   @param[in]  SectionGuid    A pointer to the GUID associated with the the handlers
 160                              of the GUIDed section type being registered.
 161   @param[in]  GetInfoHandler The pointer to a function that examines a GUIDed section and returns the
 162                              size of the decoded buffer and the size of an optional scratch buffer
 163                              required to actually decode the data in a GUIDed section.
 164   @param[in]  DecodeHandler  The pointer to a function that decodes a GUIDed section into a caller
 165                              allocated output buffer.
 166
 167   @retval  RETURN_SUCCESS           The handlers were registered.
 168   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to register the handlers.
 169
 170 **/
 171 RETURN_STATUS
 172 EFIAPI
 173 ExtractGuidedSectionRegisterHandlers (
 174   IN CONST  GUID                                     *SectionGuid,
 175   IN        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  GetInfoHandler,
 176   IN        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    DecodeHandler
 177   )
 178 {
 179   UINT32 Index;
 180   VOID   *GuidData;
 181
 182   //
 183   // Check input parameter.
 184   //
 185   ASSERT (SectionGuid != NULL);
 186   ASSERT (GetInfoHandler != NULL);
 187   ASSERT (DecodeHandler != NULL);
 188
 189   //
 190   // Search the match registered GetInfo handler for the input guided section.
 191   //
 192   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 193     if (CompareGuid (&mExtractHandlerGuidTable[Index], SectionGuid)) {
 194       //
 195       // If the guided handler has been registered before, only update its handler.
 196       //
 197       mExtractDecodeHandlerTable [Index] = DecodeHandler;
 198       mExtractGetInfoHandlerTable [Index] = GetInfoHandler;
 199       return RETURN_SUCCESS;
 200     }
 201   }
 202
 203   //
 204   // Check the global table is enough to contain new Handler.
 205   //
 206   if (mNumberOfExtractHandler >= mMaxNumberOfExtractHandler) {
 207     if (ReallocateExtractHandlerTable () != RETURN_SUCCESS) {
 208       return RETURN_OUT_OF_RESOURCES;
 209     }
 210   }
 211
 212   //
 213   // Register new Handler and guid value.
 214   //
 215   CopyGuid (&mExtractHandlerGuidTable [mNumberOfExtractHandler], SectionGuid);
 216   mExtractDecodeHandlerTable [mNumberOfExtractHandler] = DecodeHandler;
 217   mExtractGetInfoHandlerTable [mNumberOfExtractHandler++] = GetInfoHandler;
 218
 219   //
 220   // Install the Guided Section GUID configuration table to record the GUID itself.
 221   // Then the content of the configuration table buffer will be the same as the GUID value itself.
 222   //
 223   GuidData = AllocateCopyPool (sizeof (GUID), (VOID *) SectionGuid);
 224   if (GuidData != NULL) {
 225     gBS->InstallConfigurationTable ((EFI_GUID *) SectionGuid, GuidData);
 226   }
 227
 228   return RETURN_SUCCESS;
 229 }
 230
 231 /**
 232   Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type
 233   EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 234   The selected handler is used to retrieve and return the size of the decoded buffer and the size of an
 235   optional scratch buffer required to actually decode the data in a GUIDed section.
 236
 237   Examines a GUIDed section specified by InputSection.
 238   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 239   then RETURN_UNSUPPORTED is returned.
 240   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 241   of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 242   is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of
 243   type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned.
 244
 245   If InputSection is NULL, then ASSERT().
 246   If OutputBufferSize is NULL, then ASSERT().
 247   If ScratchBufferSize is NULL, then ASSERT().
 248   If SectionAttribute is NULL, then ASSERT().
 249
 250   @param[in]  InputSection       A pointer to a GUIDed section of an FFS formatted file.
 251   @param[out] OutputBufferSize   A pointer to the size, in bytes, of an output buffer required if the buffer
 252                                  specified by InputSection were decoded.
 253   @param[out] ScratchBufferSize  A pointer to the size, in bytes, required as scratch space if the buffer specified by
 254                                  InputSection were decoded.
 255   @param[out] SectionAttribute   A pointer to the attributes of the GUIDed section.  See the Attributes field of
 256                                  EFI_GUID_DEFINED_SECTION in the PI Specification.
 257
 258   @retval  RETURN_SUCCESS      Successfully obtained the required information.
 259   @retval  RETURN_UNSUPPORTED  The GUID from the section specified by InputSection does not match any of
 260                                the GUIDs registered with ExtractGuidedSectionRegisterHandlers().
 261   @retval  Others              The return status from the handler associated with the GUID retrieved from
 262                                the section specified by InputSection.
 263
 264 **/
 265 RETURN_STATUS
 266 EFIAPI
 267 ExtractGuidedSectionGetInfo (
 268   IN  CONST VOID    *InputSection,
 269   OUT       UINT32  *OutputBufferSize,
 270   OUT       UINT32  *ScratchBufferSize,
 271   OUT       UINT16  *SectionAttribute
 272   )
 273 {
 274   UINT32 Index;
 275   EFI_GUID *SectionDefinitionGuid;
 276
 277   ASSERT (InputSection != NULL);
 278   ASSERT (OutputBufferSize != NULL);
 279   ASSERT (ScratchBufferSize != NULL);
 280   ASSERT (SectionAttribute != NULL);
 281
 282   if (IS_SECTION2 (InputSection)) {
 283     SectionDefinitionGuid = &(((EFI_GUID_DEFINED_SECTION2 *) InputSection)->SectionDefinitionGuid);
 284   } else {
 285     SectionDefinitionGuid = &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid);
 286   }
 287
 288   //
 289   // Search the match registered GetInfo handler for the input guided section.
 290   //
 291   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 292     if (CompareGuid (&mExtractHandlerGuidTable[Index], SectionDefinitionGuid)) {
 293       //
 294       // Call the match handler to getinfo for the input section data.
 295       //
 296       return mExtractGetInfoHandlerTable [Index] (
 297                 InputSection,
 298                 OutputBufferSize,
 299                 ScratchBufferSize,
 300                 SectionAttribute
 301               );
 302     }
 303   }
 304
 305   //
 306   // Not found, the input guided section is not supported.
 307   //
 308   return RETURN_UNSUPPORTED;
 309 }
 310
 311 /**
 312   Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
 313   EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 314   The selected handler is used to decode the data in a GUIDed section and return the result in a caller
 315   allocated output buffer.
 316
 317   Decodes the GUIDed section specified by InputSection.
 318   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 319   then RETURN_UNSUPPORTED is returned.
 320   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 321   of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 322   is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
 323   decode operation is returned in AuthenticationStatus.  If the decoded buffer is identical to the data in InputSection,
 324   then OutputBuffer is set to point at the data in InputSection.  Otherwise, the decoded data will be placed in caller
 325   allocated buffer specified by OutputBuffer.    This function is responsible for computing the  EFI_AUTH_STATUS_PLATFORM_OVERRIDE
 326   bit of in AuthenticationStatus.  The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
 327
 328   If InputSection is NULL, then ASSERT().
 329   If OutputBuffer is NULL, then ASSERT().
 330   If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
 331   If AuthenticationStatus is NULL, then ASSERT().
 332
 333   @param[in]  InputSection   A pointer to a GUIDed section of an FFS formatted file.
 334   @param[out] OutputBuffer   A pointer to a buffer that contains the result of a decode operation.
 335   @param[in]  ScratchBuffer  A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
 336   @param[out] AuthenticationStatus
 337                              A pointer to the authentication status of the decoded output buffer. See the definition
 338                              of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
 339                              Specification.
 340
 341   @retval  RETURN_SUCCESS           The buffer specified by InputSection was decoded.
 342   @retval  RETURN_UNSUPPORTED       The section specified by InputSection does not match the GUID this handler supports.
 343   @retval  RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
 344
 345 **/
 346 RETURN_STATUS
 347 EFIAPI
 348 ExtractGuidedSectionDecode (
 349   IN  CONST VOID    *InputSection,
 350   OUT       VOID    **OutputBuffer,
 351   IN        VOID    *ScratchBuffer,        OPTIONAL
 352   OUT       UINT32  *AuthenticationStatus
 353   )
 354 {
 355   UINT32 Index;
 356   EFI_GUID *SectionDefinitionGuid;
 357
 358   //
 359   // Check the input parameters
 360   //
 361   ASSERT (InputSection != NULL);
 362   ASSERT (OutputBuffer != NULL);
 363   ASSERT (AuthenticationStatus != NULL);
 364
 365   if (IS_SECTION2 (InputSection)) {
 366     SectionDefinitionGuid = &(((EFI_GUID_DEFINED_SECTION2 *) InputSection)->SectionDefinitionGuid);
 367   } else {
 368     SectionDefinitionGuid = &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid);
 369   }
 370
 371   //
 372   // Search the match registered extract handler for the input guided section.
 373   //
 374   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 375     if (CompareGuid (&mExtractHandlerGuidTable[Index], SectionDefinitionGuid)) {
 376       //
 377       // Call the match handler to extract raw data for the input section data.
 378       //
 379       return mExtractDecodeHandlerTable [Index] (
 380                 InputSection,
 381                 OutputBuffer,
 382                 ScratchBuffer,
 383                 AuthenticationStatus
 384               );
 385     }
 386   }
 387
 388   //
 389   // Not found, the input guided section is not supported.
 390   //
 391   return RETURN_UNSUPPORTED;
 392 }
 393
 394 /**
 395   Retrieves handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and
 396   EXTRACT_GUIDED_SECTION_DECODE_HANDLER for a specific GUID section type.
 397
 398   Retrieves the handlers associated with SectionGuid and returns them in
 399   GetInfoHandler and DecodeHandler.
 400
 401   If the GUID value specified by SectionGuid has not been registered, then
 402   return RETURN_NOT_FOUND.
 403
 404   If SectionGuid is NULL, then ASSERT().
 405
 406   @param[in]  SectionGuid    A pointer to the GUID associated with the handlersof the GUIDed
 407                              section type being retrieved.
 408   @param[out] GetInfoHandler Pointer to a function that examines a GUIDed section and returns
 409                              the size of the decoded buffer and the size of an optional scratch
 410                              buffer required to actually decode the data in a GUIDed section.
 411                              This is an optional parameter that may be NULL. If it is NULL, then
 412                              the previously registered handler is not returned.
 413   @param[out] DecodeHandler  Pointer to a function that decodes a GUIDed section into a caller
 414                              allocated output buffer. This is an optional parameter that may be NULL.
 415                              If it is NULL, then the previously registered handler is not returned.
 416
 417   @retval  RETURN_SUCCESS     The handlers were retrieved.
 418   @retval  RETURN_NOT_FOUND   No handlers have been registered with the specified GUID.
 419
 420 **/
 421 RETURN_STATUS
 422 EFIAPI
 423 ExtractGuidedSectionGetHandlers (
 424   IN CONST   GUID                                     *SectionGuid,
 425   OUT        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  *GetInfoHandler,  OPTIONAL
 426   OUT        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    *DecodeHandler    OPTIONAL
 427   )
 428 {
 429   UINT32 Index;
 430
 431   //
 432   // Check input parameter.
 433   //
 434   ASSERT (SectionGuid != NULL);
 435
 436   //
 437   // Search the match registered GetInfo handler for the input guided section.
 438   //
 439   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 440     if (CompareGuid (&mExtractHandlerGuidTable[Index], SectionGuid)) {
 441
 442       //
 443       // If the guided handler has been registered before, then return the registered handlers.
 444       //
 445       if (GetInfoHandler != NULL) {
 446         *GetInfoHandler = mExtractGetInfoHandlerTable[Index];
 447       }
 448       if (DecodeHandler != NULL) {
 449         *DecodeHandler = mExtractDecodeHandlerTable[Index];
 450       }
 451       return RETURN_SUCCESS;
 452     }
 453   }
 454   return RETURN_NOT_FOUND;
 455 }