MdePkg/Library/DxeExtractGuidedSectionLib/DxeExtractGuidedSectionLib.c

   1 /** @file
   2   Provide generic extract guided section functions for Dxe phase.
   3
   4   Copyright (c) 2007 - 2008, 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
  22 #define EXTRACT_HANDLER_TABLE_SIZE   0x10
  23
  24 UINT32               mNumberOfExtractHandler = 0;
  25 UINT32               mMaxNumberOfExtractHandler = 0;
  26
  27 GUID                 *mExtractHandlerGuidTable = NULL;
  28 EXTRACT_GUIDED_SECTION_DECODE_HANDLER   *mExtractDecodeHandlerTable = NULL;
  29 EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *mExtractGetInfoHandlerTable = NULL;
  30
  31 /**
  32   Reallocates more global memory to store the registered guid and Handler list.
  33
  34   @retval  RETURN_SUCCESS            Reallocate more global memory space to store guid and function tables.
  35   @retval  RETURN_OUT_OF_RESOURCES   No enough memory to allocated.
  36 **/
  37 RETURN_STATUS
  38 EFIAPI
  39 ReallocateExtractHandlerTable (
  40   )
  41 {
  42   //
  43   // Reallocate memory for GuidTable
  44   //
  45   mExtractHandlerGuidTable = ReallocatePool (
  46                                mMaxNumberOfExtractHandler * sizeof (GUID),
  47                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (GUID),
  48                                mExtractHandlerGuidTable
  49                              );
  50
  51   if (mExtractHandlerGuidTable == NULL) {
  52     goto Done;
  53   }
  54
  55   //
  56   // Reallocate memory for Decode handler Table
  57   //
  58   mExtractDecodeHandlerTable = ReallocatePool (
  59                                mMaxNumberOfExtractHandler * sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER),
  60                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER),
  61                                mExtractDecodeHandlerTable
  62                              );
  63
  64   if (mExtractDecodeHandlerTable == NULL) {
  65     goto Done;
  66   }
  67
  68   //
  69   // Reallocate memory for GetInfo handler Table
  70   //
  71   mExtractGetInfoHandlerTable = ReallocatePool (
  72                                mMaxNumberOfExtractHandler * sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER),
  73                                (mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE) * sizeof (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER),
  74                                mExtractGetInfoHandlerTable
  75                              );
  76
  77   if (mExtractGetInfoHandlerTable == NULL) {
  78     goto Done;
  79   }
  80
  81   //
  82   // Increase max handler number
  83   //
  84   mMaxNumberOfExtractHandler = mMaxNumberOfExtractHandler + EXTRACT_HANDLER_TABLE_SIZE;
  85   return RETURN_SUCCESS;
  86
  87 Done:
  88   if (mExtractHandlerGuidTable != NULL) {
  89     FreePool (mExtractHandlerGuidTable);
  90   }
  91   if (mExtractDecodeHandlerTable != NULL) {
  92     FreePool (mExtractDecodeHandlerTable);
  93   }
  94   if (mExtractGetInfoHandlerTable != NULL) {
  95     FreePool (mExtractGetInfoHandlerTable);
  96   }
  97
  98   return RETURN_OUT_OF_RESOURCES;
  99 }
 100 /**
 101   Constructor allocates the global memory to store the registered guid and Handler list.
 102
 103   @param  ImageHandle   The firmware allocated handle for the EFI image.
 104   @param  SystemTable   A pointer to the EFI System Table.
 105
 106   @retval  RETURN_SUCCESS            Allocate the global memory space to store guid and function tables.
 107   @retval  RETURN_OUT_OF_RESOURCES   No enough memory to allocated.
 108 **/
 109 RETURN_STATUS
 110 EFIAPI
 111 DxeExtractGuidedSectionLibConstructor (
 112   IN EFI_HANDLE        ImageHandle,
 113   IN EFI_SYSTEM_TABLE  *SystemTable
 114   )
 115 {
 116   return ReallocateExtractHandlerTable ();
 117 }
 118
 119 /**
 120   Retrieve the list GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers().
 121
 122   Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs.
 123   The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated
 124   and caller must treat this array of GUIDs as read-only data.
 125   If ExtractHandlerGuidTable is NULL, then ASSERT().
 126
 127   @param[out]  ExtractHandlerGuidTable  A pointer to the array of GUIDs that have been registered through
 128                                         ExtractGuidedSectionRegisterHandlers().
 129
 130   @return the number of the supported extract guided Handler.
 131
 132 **/
 133 UINTN
 134 EFIAPI
 135 ExtractGuidedSectionGetGuidList (
 136   OUT  GUID  **ExtractHandlerGuidTable
 137   )
 138 {
 139   ASSERT (ExtractHandlerGuidTable != NULL);
 140
 141   *ExtractHandlerGuidTable = mExtractHandlerGuidTable;
 142   return mNumberOfExtractHandler;
 143 }
 144
 145 /**
 146   Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
 147   for a specific GUID section type.
 148
 149   Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
 150   If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
 151   If there are not enough resources available to register the handlers  then RETURN_OUT_OF_RESOURCES is returned.
 152
 153   If SectionGuid is NULL, then ASSERT().
 154   If GetInfoHandler is NULL, then ASSERT().
 155   If DecodeHandler is NULL, then ASSERT().
 156
 157   @param[in]  SectionGuid    A pointer to the GUID associated with the the handlers
 158                              of the GUIDed section type being registered.
 159   @param[in]  GetInfoHandler Pointer to a function that examines a GUIDed section and returns the
 160                              size of the decoded buffer and the size of an optional scratch buffer
 161                              required to actually decode the data in a GUIDed section.
 162   @param[in]  DecodeHandler  Pointer to a function that decodes a GUIDed section into a caller
 163                              allocated output buffer.
 164
 165   @retval  RETURN_SUCCESS           The handlers were registered.
 166   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to register the handlers.
 167
 168 **/
 169 RETURN_STATUS
 170 EFIAPI
 171 ExtractGuidedSectionRegisterHandlers (
 172   IN CONST  GUID                                     *SectionGuid,
 173   IN        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  GetInfoHandler,
 174   IN        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    DecodeHandler
 175   )
 176 {
 177   UINT32 Index;
 178   //
 179   // Check input paramter.
 180   //
 181   ASSERT (SectionGuid != NULL);
 182   ASSERT (GetInfoHandler != NULL);
 183   ASSERT (DecodeHandler != NULL);
 184
 185   //
 186   // Search the match registered GetInfo handler for the input guided section.
 187   //
 188   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 189     if (CompareGuid (&mExtractHandlerGuidTable[Index], SectionGuid)) {
 190       //
 191       // If the guided handler has been registered before, only update its handler.
 192       //
 193       mExtractDecodeHandlerTable [Index] = DecodeHandler;
 194       mExtractGetInfoHandlerTable [Index] = GetInfoHandler;
 195       return RETURN_SUCCESS;
 196     }
 197   }
 198
 199   //
 200   // Check the global table is enough to contain new Handler.
 201   //
 202   if (mNumberOfExtractHandler >= mMaxNumberOfExtractHandler) {
 203     if (ReallocateExtractHandlerTable () != RETURN_SUCCESS) {
 204       return RETURN_OUT_OF_RESOURCES;
 205     }
 206   }
 207
 208   //
 209   // Register new Handler and guid value.
 210   //
 211   CopyGuid (&mExtractHandlerGuidTable [mNumberOfExtractHandler], SectionGuid);
 212   mExtractDecodeHandlerTable [mNumberOfExtractHandler] = DecodeHandler;
 213   mExtractGetInfoHandlerTable [mNumberOfExtractHandler++] = GetInfoHandler;
 214
 215   return RETURN_SUCCESS;
 216 }
 217
 218 /**
 219   Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type
 220   EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 221   The selected handler is used to retrieve and return the size of the decoded buffer and the size of an
 222   optional scratch buffer required to actually decode the data in a GUIDed section.
 223
 224   Examines a GUIDed section specified by InputSection.
 225   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 226   then RETURN_UNSUPPORTED is returned.
 227   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 228   of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 229   is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of
 230   type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned.
 231
 232   If InputSection is NULL, then ASSERT().
 233   If OutputBufferSize is NULL, then ASSERT().
 234   If ScratchBufferSize is NULL, then ASSERT().
 235   If SectionAttribute is NULL, then ASSERT().
 236
 237   @param[in]  InputSection       A pointer to a GUIDed section of an FFS formatted file.
 238   @param[out] OutputBufferSize   A pointer to the size, in bytes, of an output buffer required if the buffer
 239                                  specified by InputSection were decoded.
 240   @param[out] ScratchBufferSize  A pointer to the size, in bytes, required as scratch space if the buffer specified by
 241                                  InputSection were decoded.
 242   @param[out] SectionAttribute   A pointer to the attributes of the GUIDed section.  See the Attributes field of
 243                                  EFI_GUID_DEFINED_SECTION in the PI Specification.
 244
 245   @retval  RETURN_SUCCESS      Get the required information successfully.
 246   @retval  RETURN_UNSUPPORTED  The GUID from the section specified by InputSection does not match any of
 247                                the GUIDs registered with ExtractGuidedSectionRegisterHandlers().
 248   @retval  Others              The return status from the handler associated with the GUID retrieved from
 249                                the section specified by InputSection.
 250
 251 **/
 252 RETURN_STATUS
 253 EFIAPI
 254 ExtractGuidedSectionGetInfo (
 255   IN  CONST VOID    *InputSection,
 256   OUT       UINT32  *OutputBufferSize,
 257   OUT       UINT32  *ScratchBufferSize,
 258   OUT       UINT16  *SectionAttribute
 259   )
 260 {
 261   UINT32 Index;
 262
 263   ASSERT (InputSection != NULL);
 264   ASSERT (OutputBufferSize != NULL);
 265   ASSERT (ScratchBufferSize != NULL);
 266   ASSERT (SectionAttribute != NULL);
 267
 268   //
 269   // Search the match registered GetInfo handler for the input guided section.
 270   //
 271   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 272     if (CompareGuid (&mExtractHandlerGuidTable[Index], &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 273       //
 274       // Call the match handler to getinfo for the input section data.
 275       //
 276       return mExtractGetInfoHandlerTable [Index] (
 277                 InputSection,
 278                 OutputBufferSize,
 279                 ScratchBufferSize,
 280                 SectionAttribute
 281               );
 282     }
 283   }
 284
 285   //
 286   // Not found, the input guided section is not supported.
 287   //
 288   return RETURN_UNSUPPORTED;
 289 }
 290
 291 /**
 292   Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
 293   EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 294   The selected handler is used to decode the data in a GUIDed section and return the result in a caller
 295   allocated output buffer.
 296
 297   Decodes the GUIDed section specified by InputSection.
 298   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 299   then RETURN_UNSUPPORTED is returned.
 300   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 301   of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 302   is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
 303   decode operation is returned in AuthenticationStatus.  If the decoded buffer is identical to the data in InputSection,
 304   then OutputBuffer is set to point at the data in InputSection.  Otherwise, the decoded data will be placed in caller
 305   allocated buffer specified by OutputBuffer.    This function is responsible for computing the  EFI_AUTH_STATUS_PLATFORM_OVERRIDE
 306   bit of in AuthenticationStatus.  The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
 307
 308   If InputSection is NULL, then ASSERT().
 309   If OutputBuffer is NULL, then ASSERT().
 310   If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
 311   If AuthenticationStatus is NULL, then ASSERT().
 312
 313   @param[in]  InputSection   A pointer to a GUIDed section of an FFS formatted file.
 314   @param[out] OutputBuffer   A pointer to a buffer that contains the result of a decode operation.
 315   @param[in]  ScratchBuffer  A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
 316   @param[out] AuthenticationStatus
 317                              A pointer to the authentication status of the decoded output buffer. See the definition
 318                              of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
 319                              Specification.
 320
 321   @retval  RETURN_SUCCESS           The buffer specified by InputSection was decoded.
 322   @retval  RETURN_UNSUPPORTED       The section specified by InputSection does not match the GUID this handler supports.
 323   @retval  RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
 324
 325 **/
 326 RETURN_STATUS
 327 EFIAPI
 328 ExtractGuidedSectionDecode (
 329   IN  CONST VOID    *InputSection,
 330   OUT       VOID    **OutputBuffer,
 331   IN        VOID    *ScratchBuffer,        OPTIONAL
 332   OUT       UINT32  *AuthenticationStatus
 333   )
 334 {
 335   UINT32 Index;
 336
 337   //
 338   // Check the input parameters
 339   //
 340   ASSERT (InputSection != NULL);
 341   ASSERT (OutputBuffer != NULL);
 342   ASSERT (AuthenticationStatus != NULL);
 343
 344   //
 345   // Search the match registered extract handler for the input guided section.
 346   //
 347   for (Index = 0; Index < mNumberOfExtractHandler; Index ++) {
 348     if (CompareGuid (&mExtractHandlerGuidTable[Index], &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 349       //
 350       // Call the match handler to extract raw data for the input section data.
 351       //
 352       return mExtractDecodeHandlerTable [Index] (
 353                 InputSection,
 354                 OutputBuffer,
 355                 ScratchBuffer,
 356                 AuthenticationStatus
 357               );
 358     }
 359   }
 360
 361   //
 362   // Not found, the input guided section is not supported.
 363   //
 364   return RETURN_UNSUPPORTED;
 365 }