MdePkg/Library/BaseExtractGuidedSectionLib/BaseExtractGuidedSectionLib.c

   1 /** @file
   2   Provide generic extract guided section functions.
   3
   4   Copyright (c) 2007 - 2010, 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 /**
  33   HandlerInfo table address is set by PcdGuidedExtractHandlerTableAddress, which is used to store
  34   the registered guid and Handler list. When it is initialized, it will be directly returned.
  35   Or, HandlerInfo table will be initialized in this function.
  36
  37   @param[in, out]  InfoPointer   The pointer to the handler info structure.
  38
  39   @retval  RETURN_SUCCESS            HandlerInfo table can be used to store guid and function tables.
  40   @retval  RETURN_OUT_OF_RESOURCES   HandlerInfo table address is not writable.
  41 **/
  42 RETURN_STATUS
  43 GetExtractGuidedSectionHandlerInfo (
  44   IN OUT EXTRACT_GUIDED_SECTION_HANDLER_INFO **InfoPointer
  45   )
  46 {
  47   EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
  48
  49   //
  50   // Set the available memory address to handler info.
  51   //
  52   HandlerInfo = (EXTRACT_GUIDED_SECTION_HANDLER_INFO*)(VOID*)(UINTN) PcdGet64 (PcdGuidedExtractHandlerTableAddress);
  53
  54   //
  55   // First check whether the handler info structure is initialized.
  56   //
  57   if (HandlerInfo->Signature == EXTRACT_HANDLER_INFO_SIGNATURE) {
  58     //
  59     // The handler info has been initialized and is returned.
  60     //
  61     *InfoPointer = HandlerInfo;
  62     return RETURN_SUCCESS;
  63   }
  64
  65   //
  66   // Try to initialize the handler info structure
  67   //
  68   HandlerInfo->Signature = EXTRACT_HANDLER_INFO_SIGNATURE;
  69   if (HandlerInfo->Signature != EXTRACT_HANDLER_INFO_SIGNATURE) {
  70     //
  71     // The handler info structure was not writeable because the memory is not ready.
  72     //
  73     *InfoPointer = NULL;
  74     return RETURN_OUT_OF_RESOURCES;
  75   }
  76
  77   //
  78   // Init HandlerInfo structure
  79   //
  80   HandlerInfo->NumberOfExtractHandler     = 0;
  81   HandlerInfo->ExtractHandlerGuidTable    = (GUID *) (HandlerInfo + 1);
  82   HandlerInfo->ExtractDecodeHandlerTable  = (EXTRACT_GUIDED_SECTION_DECODE_HANDLER *) (
  83                                               (UINT8 *)HandlerInfo->ExtractHandlerGuidTable +
  84                                               PcdGet32 (PcdMaximumGuidedExtractHandler) * sizeof (GUID)
  85                                              );
  86   HandlerInfo->ExtractGetInfoHandlerTable = (EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER *) (
  87                                               (UINT8 *)HandlerInfo->ExtractDecodeHandlerTable +
  88                                               PcdGet32 (PcdMaximumGuidedExtractHandler) *
  89                                               sizeof (EXTRACT_GUIDED_SECTION_DECODE_HANDLER)
  90                                              );
  91   *InfoPointer = HandlerInfo;
  92   return RETURN_SUCCESS;
  93 }
  94
  95 /**
  96   Retrieve the list GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers().
  97
  98   Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs.
  99   The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated
 100   and caller must treat this array of GUIDs as read-only data.
 101   If ExtractHandlerGuidTable is NULL, then ASSERT().
 102
 103   @param[out]  ExtractHandlerGuidTable  A pointer to the array of GUIDs that have been registered through
 104                                         ExtractGuidedSectionRegisterHandlers().
 105
 106   @return The number of the supported extract guided Handler.
 107
 108 **/
 109 UINTN
 110 EFIAPI
 111 ExtractGuidedSectionGetGuidList (
 112   OUT  GUID  **ExtractHandlerGuidTable
 113   )
 114 {
 115   RETURN_STATUS                       Status;
 116   EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 117
 118   ASSERT (ExtractHandlerGuidTable != NULL);
 119
 120   //
 121   // Get all registered handler information
 122   //
 123   Status = GetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 124   if (RETURN_ERROR (Status)) {
 125     *ExtractHandlerGuidTable = NULL;
 126     return 0;
 127   }
 128
 129   //
 130   // Get GuidTable and Table Number
 131   //
 132   *ExtractHandlerGuidTable = HandlerInfo->ExtractHandlerGuidTable;
 133   return HandlerInfo->NumberOfExtractHandler;
 134 }
 135
 136 /**
 137   Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER
 138   for a specific GUID section type.
 139
 140   Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid.
 141   If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED.
 142   If there are not enough resources available to register the handlers  then RETURN_OUT_OF_RESOURCES is returned.
 143
 144   If SectionGuid is NULL, then ASSERT().
 145   If GetInfoHandler is NULL, then ASSERT().
 146   If DecodeHandler is NULL, then ASSERT().
 147
 148   @param[in]  SectionGuid    A pointer to the GUID associated with the the handlers
 149                              of the GUIDed section type being registered.
 150   @param[in]  GetInfoHandler The pointer to a function that examines a GUIDed section and returns the
 151                              size of the decoded buffer and the size of an optional scratch buffer
 152                              required to actually decode the data in a GUIDed section.
 153   @param[in]  DecodeHandler  The pointer to a function that decodes a GUIDed section into a caller
 154                              allocated output buffer.
 155
 156   @retval  RETURN_SUCCESS           The handlers were registered.
 157   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to register the handlers.
 158
 159 **/
 160 RETURN_STATUS
 161 EFIAPI
 162 ExtractGuidedSectionRegisterHandlers (
 163   IN CONST  GUID                                     *SectionGuid,
 164   IN        EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER  GetInfoHandler,
 165   IN        EXTRACT_GUIDED_SECTION_DECODE_HANDLER    DecodeHandler
 166   )
 167 {
 168   UINT32                              Index;
 169   RETURN_STATUS                       Status;
 170   EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 171
 172   //
 173   // Check input paramter
 174   //
 175   ASSERT (SectionGuid != NULL);
 176   ASSERT (GetInfoHandler != NULL);
 177   ASSERT (DecodeHandler != NULL);
 178
 179   //
 180   // Get the registered handler information
 181   //
 182   Status = GetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 183   if (RETURN_ERROR (Status)) {
 184     return Status;
 185   }
 186
 187   //
 188   // Search the match registered GetInfo handler for the input guided section.
 189   //
 190   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 191     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, SectionGuid)) {
 192       //
 193       // If the guided handler has been registered before, only update its handler.
 194       //
 195       HandlerInfo->ExtractDecodeHandlerTable [Index] = DecodeHandler;
 196       HandlerInfo->ExtractGetInfoHandlerTable [Index] = GetInfoHandler;
 197       return RETURN_SUCCESS;
 198     }
 199   }
 200
 201   //
 202   // Check the global table is enough to contain new Handler.
 203   //
 204   if (HandlerInfo->NumberOfExtractHandler >= PcdGet32 (PcdMaximumGuidedExtractHandler)) {
 205     return RETURN_OUT_OF_RESOURCES;
 206   }
 207
 208   //
 209   // Register new Handler and guid value.
 210   //
 211   CopyGuid (HandlerInfo->ExtractHandlerGuidTable + HandlerInfo->NumberOfExtractHandler, SectionGuid);
 212   HandlerInfo->ExtractDecodeHandlerTable [HandlerInfo->NumberOfExtractHandler] = DecodeHandler;
 213   HandlerInfo->ExtractGetInfoHandlerTable [HandlerInfo->NumberOfExtractHandler++] = 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      Successfully retrieved the required information.
 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   RETURN_STATUS                       Status;
 263   EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 264
 265   //
 266   // Check input paramter
 267   //
 268   ASSERT (InputSection != NULL);
 269   ASSERT (OutputBufferSize != NULL);
 270   ASSERT (ScratchBufferSize != NULL);
 271   ASSERT (SectionAttribute != NULL);
 272
 273   //
 274   // Get all registered handler information.
 275   //
 276   Status = GetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 277   if (RETURN_ERROR (Status)) {
 278     return Status;
 279   }
 280
 281   //
 282   // Search the match registered GetInfo handler for the input guided section.
 283   //
 284   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 285     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 286       //
 287       // Call the match handler to get info for the input section data.
 288       //
 289       return HandlerInfo->ExtractGetInfoHandlerTable [Index] (
 290                 InputSection,
 291                 OutputBufferSize,
 292                 ScratchBufferSize,
 293                 SectionAttribute
 294               );
 295     }
 296   }
 297
 298   //
 299   // Not found, the input guided section is not supported.
 300   //
 301   return RETURN_UNSUPPORTED;
 302 }
 303
 304 /**
 305   Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type
 306   EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers().
 307   The selected handler is used to decode the data in a GUIDed section and return the result in a caller
 308   allocated output buffer.
 309
 310   Decodes the GUIDed section specified by InputSection.
 311   If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(),
 312   then RETURN_UNSUPPORTED is returned.
 313   If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler
 314   of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers()
 315   is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this
 316   decode operation is returned in AuthenticationStatus.  If the decoded buffer is identical to the data in InputSection,
 317   then OutputBuffer is set to point at the data in InputSection.  Otherwise, the decoded data will be placed in a caller
 318   allocated buffer specified by OutputBuffer.    This function is responsible for computing the  EFI_AUTH_STATUS_PLATFORM_OVERRIDE
 319   bit of in AuthenticationStatus.  The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned.
 320
 321   If InputSection is NULL, then ASSERT().
 322   If OutputBuffer is NULL, then ASSERT().
 323   If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT().
 324   If AuthenticationStatus is NULL, then ASSERT().
 325
 326   @param[in]  InputSection   A pointer to a GUIDed section of an FFS formatted file.
 327   @param[out] OutputBuffer   A pointer to a buffer that contains the result of a decode operation.
 328   @param[in]  ScratchBuffer  A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation.
 329   @param[out] AuthenticationStatus
 330                              A pointer to the authentication status of the decoded output buffer. See the definition
 331                              of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI
 332                              Specification.
 333
 334   @retval  RETURN_SUCCESS           The buffer specified by InputSection was decoded.
 335   @retval  RETURN_UNSUPPORTED       The section specified by InputSection does not match the GUID this handler supports.
 336   @retval  RETURN_INVALID_PARAMETER The section specified by InputSection can not be decoded.
 337
 338 **/
 339 RETURN_STATUS
 340 EFIAPI
 341 ExtractGuidedSectionDecode (
 342   IN  CONST VOID    *InputSection,
 343   OUT       VOID    **OutputBuffer,
 344   IN        VOID    *ScratchBuffer,        OPTIONAL
 345   OUT       UINT32  *AuthenticationStatus
 346   )
 347 {
 348   UINT32                              Index;
 349   RETURN_STATUS                       Status;
 350   EXTRACT_GUIDED_SECTION_HANDLER_INFO *HandlerInfo;
 351
 352   //
 353   // Check input parameter
 354   //
 355   ASSERT (InputSection != NULL);
 356   ASSERT (OutputBuffer != NULL);
 357   ASSERT (AuthenticationStatus != NULL);
 358
 359   //
 360   // Get all registered handler information.
 361   //
 362   Status = GetExtractGuidedSectionHandlerInfo (&HandlerInfo);
 363   if (RETURN_ERROR (Status)) {
 364     return Status;
 365   }
 366
 367   //
 368   // Search the match registered Extract handler for the input guided section.
 369   //
 370   for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) {
 371     if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {
 372       //
 373       // Call the match handler to extract raw data for the input guided section.
 374       //
 375       return HandlerInfo->ExtractDecodeHandlerTable [Index] (
 376                 InputSection,
 377                 OutputBuffer,
 378                 ScratchBuffer,
 379                 AuthenticationStatus
 380               );
 381     }
 382   }
 383
 384   //
 385   // Not found, the input guided section is not supported.
 386   //
 387   return RETURN_UNSUPPORTED;
 388 }