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