MdeModulePkg/Library/DxePlatDriOverLib/PlatDriOverLib.c

   1 /** @file
   2
   3 Copyright (c) 2007, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14     PlatDriOverLib.c
  15
  16 Abstract:
  17
  18
  19 **/
  20
  21 #include "PlatDriOver.h"
  22
  23 LIST_ENTRY   mDevicePathStack = INITIALIZE_LIST_HEAD_VARIABLE (mDevicePathStack);
  24
  25
  26 /**
  27   Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol
  28   in the system.
  29
  30   @param  gPlatformDriverOverride  PlatformDriverOverride protocol interface which
  31                                    needs to be installed
  32
  33   @retval EFI_ALREADY_STARTED      There has been a Platform Driver Override
  34                                    Protocol in the system, cannot install it again.
  35   @retval Other                    Returned by InstallProtocolInterface
  36
  37 **/
  38 EFI_STATUS
  39 EFIAPI
  40 InstallPlatformDriverOverrideProtocol (
  41   EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride
  42   )
  43 {
  44   EFI_HANDLE          Handle;
  45   EFI_STATUS          Status;
  46   UINTN               HandleCount;
  47   EFI_HANDLE          *HandleBuffer;
  48
  49   //
  50   // There will be only one platform driver override protocol in the system
  51   // If there is another out there, someone is trying to install us again,
  52   // Fail that scenario.
  53   //
  54   Status = gBS->LocateHandleBuffer (
  55                   ByProtocol,
  56                   &gEfiPlatformDriverOverrideProtocolGuid,
  57                   NULL,
  58                   &HandleCount,
  59                   &HandleBuffer
  60                   );
  61   //
  62   // If there was no error, assume there is an installation and return error
  63   //
  64   if (!EFI_ERROR (Status)) {
  65     if (HandleBuffer != NULL) {
  66       FreePool (HandleBuffer);
  67     }
  68     return EFI_ALREADY_STARTED;
  69   }
  70
  71   //
  72   // Install platform driver override protocol
  73   //
  74   Handle = NULL;
  75   Status = gBS->InstallProtocolInterface (
  76                   &Handle,
  77                   &gEfiPlatformDriverOverrideProtocolGuid,
  78                   EFI_NATIVE_INTERFACE,
  79                   gPlatformDriverOverride
  80                   );
  81   return Status;
  82 }
  83
  84
  85 /**
  86   Free all the mapping database memory resource and initialize the mapping list entry
  87
  88   @param  MappingDataBase          Mapping database list entry pointer
  89
  90   @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL
  91   @retval EFI_SUCCESS              Free success
  92
  93 **/
  94 EFI_STATUS
  95 EFIAPI
  96 FreeMappingDatabase (
  97   IN  OUT  LIST_ENTRY            *MappingDataBase
  98   )
  99 {
 100   LIST_ENTRY                  *OverrideItemListIndex;
 101   LIST_ENTRY                  *ImageInfoListIndex;
 102   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 103   DRIVER_IMAGE_INFO           *DriverImageInfo;
 104
 105   if (MappingDataBase == NULL) {
 106     return EFI_INVALID_PARAMETER;
 107   }
 108
 109   OverrideItemListIndex = MappingDataBase->ForwardLink;
 110   while (OverrideItemListIndex != MappingDataBase){
 111     OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
 112     //
 113     // Free PLATFORM_OVERRIDE_ITEM.ControllerDevicePath[]
 114     //
 115     if (OverrideItem->ControllerDevicePath != NULL){
 116       FreePool(OverrideItem->ControllerDevicePath);
 117     }
 118
 119     ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
 120     while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
 121       //
 122       // Free all DRIVER_IMAGE_INFO.DriverImagePath[]
 123       //
 124       DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
 125       if (DriverImageInfo->DriverImagePath != NULL) {
 126         FreePool(DriverImageInfo->DriverImagePath);
 127       }
 128       //
 129       // Free DRIVER_IMAGE_INFO itself
 130       //
 131       ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
 132       RemoveEntryList (&DriverImageInfo->Link);
 133       FreePool (DriverImageInfo);
 134     }
 135     //
 136     // Free PLATFORM_OVERRIDE_ITEM itself
 137     //
 138     OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
 139     RemoveEntryList (&OverrideItem->Link);
 140     FreePool (OverrideItem);
 141   }
 142
 143   InitializeListHead (MappingDataBase);
 144   return EFI_SUCCESS;
 145 }
 146
 147
 148 /**
 149   Read the environment variable(s) that contain the override mappings from Controller Device Path to
 150   a set of Driver Device Paths, and create the mapping database in memory with those variable info.
 151   VariableLayout{
 152   //
 153   // NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load.
 154   // Each variable has MaximumVariableSize limitation, so  we maybe need multi variables to store
 155   // large mapping infos.
 156   // The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, ....
 157   //
 158   UINT32                         NotEnd;
 159   //
 160   // The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths
 161   // There are often multi mapping entries in a variable.
 162   //
 163   UINT32                         SIGNATURE;            //EFI_SIGNATURE_32('p','d','o','i')
 164   UINT32                         DriverNum;
 165   EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];
 166   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 167   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 168   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 169   ......
 170   UINT32                         SIGNATURE;
 171   UINT32                         DriverNum;
 172   EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];
 173   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 174   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 175   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
 176   ......
 177   }
 178   typedef struct _PLATFORM_OVERRIDE_ITEM{
 179   UINTN                          Signature;                  //EFI_SIGNATURE_32('p','d','o','i')
 180   LIST_ENTRY                     Link;
 181   UINT32                         DriverInfoNum;
 182   EFI_DEVICE_PATH_PROTOCOL       *ControllerDevicePath;
 183   LIST_ENTRY                     DriverInfoList;         //DRIVER_IMAGE_INFO List
 184   } PLATFORM_OVERRIDE_ITEM;
 185   typedef struct _DRIVER_IMAGE_INFO{
 186   UINTN                          Signature;                  //EFI_SIGNATURE_32('p','d','i','i')
 187   LIST_ENTRY                     Link;
 188   EFI_HANDLE                     ImageHandle;
 189   EFI_DEVICE_PATH_PROTOCOL       *DriverImagePath;
 190   BOOLEAN                        UnLoadable;
 191   BOOLEAN                        UnStartable;
 192   } DRIVER_IMAGE_INFO;
 193
 194   @param  MappingDataBase          Mapping database list entry pointer
 195
 196   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
 197   @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable
 198   @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted
 199   @retval EFI_SUCCESS              Create the mapping database in memory
 200                                    successfully
 201
 202 **/
 203 EFI_STATUS
 204 EFIAPI
 205 InitOverridesMapping (
 206   OUT  LIST_ENTRY            *MappingDataBase
 207   )
 208 {
 209   UINTN                       BufferSize;
 210   VOID                        *VariableBuffer;
 211   UINT8                       *VariableIndex;
 212   UINTN                       VariableNum;
 213   CHAR16                      OverrideVariableName[40];
 214   UINT32                      NotEnd;
 215   UINT32                      DriverNumber;
 216   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 217   DRIVER_IMAGE_INFO           *DriverImageInfo;
 218   BOOLEAN                     Corrupted;
 219   UINT32                      Signature;
 220   EFI_DEVICE_PATH_PROTOCOL    *ControllerDevicePath;
 221   EFI_DEVICE_PATH_PROTOCOL    *DriverDevicePath;
 222   UINTN                       Index;
 223
 224   if (MappingDataBase == NULL) {
 225     return EFI_INVALID_PARAMETER;
 226   }
 227
 228   VariableNum = 0;
 229   Corrupted = FALSE;
 230   //
 231   // Check the environment variable(s) that contain the override mappings .
 232   //
 233   VariableBuffer = GetVariableAndSize (L"PlatDriOver", &gEfiOverrideVariableGuid, &BufferSize);
 234   ASSERT ((UINTN) VariableBuffer % sizeof(UINTN) == 0);
 235   VariableNum ++;
 236   if (VariableBuffer == NULL) {
 237     return EFI_NOT_FOUND;
 238   }
 239
 240   do {
 241     VariableIndex = VariableBuffer;
 242     NotEnd = *(UINT32*) VariableIndex;
 243     VariableIndex = VariableIndex + sizeof (UINT32);
 244     while (VariableIndex < ((UINT8 *)VariableBuffer + BufferSize)) {
 245       OverrideItem = AllocateZeroPool (sizeof (PLATFORM_OVERRIDE_ITEM));
 246       ASSERT (OverrideItem != NULL);
 247       OverrideItem->Signature = PLATFORM_OVERRIDE_ITEM_SIGNATURE;
 248       InitializeListHead (&OverrideItem->DriverInfoList);
 249       //
 250       // Check SIGNATURE
 251       //
 252       Signature = *(UINT32 *) VariableIndex;
 253       VariableIndex = VariableIndex + sizeof (UINT32);
 254       if (Signature != PLATFORM_OVERRIDE_ITEM_SIGNATURE) {
 255         FreePool (OverrideItem);
 256         Corrupted = TRUE;
 257         break;
 258       }
 259       //
 260       // Get DriverNum
 261       //
 262       DriverNumber = *(UINT32*) VariableIndex;
 263       OverrideItem->DriverInfoNum = DriverNumber;
 264       VariableIndex = VariableIndex + sizeof (UINT32);
 265       //
 266       // Get ControllerDevicePath[]
 267       //
 268       ControllerDevicePath = (EFI_DEVICE_PATH_PROTOCOL *) VariableIndex;
 269       OverrideItem->ControllerDevicePath = DuplicateDevicePath (ControllerDevicePath);
 270       VariableIndex = VariableIndex + GetDevicePathSize (ControllerDevicePath);
 271       //
 272       // Align the VariableIndex since the controller device path may not be aligned, refer to the SaveOverridesMapping()
 273       //
 274       VariableIndex += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 275
 276       //
 277       // Get all DriverDevicePath[]
 278       //
 279       for (Index = 0; Index < DriverNumber; Index++) {
 280         DriverImageInfo = AllocateZeroPool (sizeof (DRIVER_IMAGE_INFO));
 281         ASSERT (DriverImageInfo != NULL);
 282         DriverImageInfo->Signature = DRIVER_IMAGE_INFO_SIGNATURE;
 283
 284         DriverDevicePath = (EFI_DEVICE_PATH_PROTOCOL *) VariableIndex;
 285         DriverImageInfo->DriverImagePath = DuplicateDevicePath (DriverDevicePath);
 286         VariableIndex = VariableIndex + GetDevicePathSize (DriverDevicePath);
 287         //
 288         // Align the VariableIndex since the driver image device path may not be aligned, refer to the SaveOverridesMapping()
 289         //
 290         VariableIndex += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 291
 292         InsertTailList (&OverrideItem->DriverInfoList, &DriverImageInfo->Link);
 293       }
 294       InsertTailList (MappingDataBase, &OverrideItem->Link);
 295     }
 296
 297     FreePool (VariableBuffer);
 298     if (Corrupted) {
 299       FreeMappingDatabase (MappingDataBase);
 300       return EFI_VOLUME_CORRUPTED;
 301     }
 302
 303     //
 304     // If has other variable(PlatDriOver1, PlatDriOver2, PlatDriOver3.....), get them.
 305     // NotEnd indicate whether current variable is the end variable.
 306     //
 307     if (NotEnd != 0) {
 308       UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", VariableNum);
 309       VariableBuffer = GetVariableAndSize (OverrideVariableName, &gEfiOverrideVariableGuid, &BufferSize);
 310       ASSERT ((UINTN) VariableBuffer % sizeof(UINTN) == 0);
 311       VariableNum ++;
 312       if (VariableBuffer == NULL) {
 313         FreeMappingDatabase (MappingDataBase);
 314         return EFI_VOLUME_CORRUPTED;
 315       }
 316     }
 317
 318   } while (NotEnd != 0);
 319
 320   return EFI_SUCCESS;
 321 }
 322
 323
 324 /**
 325   Calculate the needed size in NV variable for recording a specific PLATFORM_OVERRIDE_ITEM info
 326
 327   @param  OverrideItemListIndex    a list entry point to a specific
 328                                    PLATFORM_OVERRIDE_ITEM
 329
 330   @return The needed size number
 331
 332 **/
 333 UINTN
 334 EFIAPI
 335 GetOneItemNeededSize (
 336   IN  LIST_ENTRY            *OverrideItemListIndex
 337   )
 338 {
 339   UINTN                       NeededSize;
 340   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 341   LIST_ENTRY                  *ImageInfoListIndex;
 342   DRIVER_IMAGE_INFO           *DriverImageInfo;
 343
 344
 345   NeededSize = 0;
 346   OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
 347   NeededSize += sizeof (UINT32); //UINT32  SIGNATURE;
 348   NeededSize += sizeof (UINT32); //UINT32  DriverNum;
 349   NeededSize += GetDevicePathSize (OverrideItem->ControllerDevicePath); // ControllerDevicePath
 350   //
 351   // Align the controller device path
 352   //
 353   NeededSize += ((sizeof(UINT32) - ((UINTN) GetDevicePathSize (OverrideItem->ControllerDevicePath))) \
 354                   & (sizeof(UINT32) - 1));
 355   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
 356   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
 357     DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
 358     NeededSize += GetDevicePathSize (DriverImageInfo->DriverImagePath); //DriverDevicePath
 359     //
 360     // Align the driver image device path
 361     //
 362     NeededSize += ((sizeof(UINT32) - ((UINTN) GetDevicePathSize (DriverImageInfo->DriverImagePath))) \
 363                     & (sizeof(UINT32) - 1));
 364     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
 365   }
 366
 367   return NeededSize;
 368 }
 369
 370
 371
 372 /**
 373   Save the memory mapping database into NV environment variable(s)
 374
 375   @param  MappingDataBase          Mapping database list entry pointer
 376
 377   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
 378   @retval EFI_SUCCESS              Save memory mapping database successfully
 379
 380 **/
 381 EFI_STATUS
 382 EFIAPI
 383 SaveOverridesMapping (
 384   IN  LIST_ENTRY              *MappingDataBase
 385   )
 386 {
 387   EFI_STATUS                  Status;
 388   VOID                        *VariableBuffer;
 389   UINT8                       *VariableIndex;
 390   UINTN                       NumIndex;
 391   CHAR16                      OverrideVariableName[40];
 392   UINT32                      NotEnd;
 393   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 394   DRIVER_IMAGE_INFO           *DriverImageInfo;
 395   LIST_ENTRY                  *OverrideItemListIndex;
 396   LIST_ENTRY                  *ItemIndex;
 397   LIST_ENTRY                  *ImageInfoListIndex;
 398   UINTN                       VariableNeededSize;
 399   UINTN                       SavedSize;
 400   UINT64                      MaximumVariableStorageSize;
 401   UINT64                      RemainingVariableStorageSize;
 402   UINT64                      MaximumVariableSize;
 403   UINTN                       OneItemNeededSize;
 404
 405   if (MappingDataBase == NULL) {
 406     return EFI_INVALID_PARAMETER;
 407   }
 408
 409   if (MappingDataBase->ForwardLink == MappingDataBase) {
 410     Status = DeleteOverridesVariables ();
 411     return EFI_SUCCESS;
 412   }
 413
 414   //
 415   // Get the the maximum size of an individual EFI variable in current system
 416   //
 417   gRT->QueryVariableInfo (
 418           EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE,
 419           &MaximumVariableStorageSize,
 420           &RemainingVariableStorageSize,
 421           &MaximumVariableSize
 422           );
 423
 424   NumIndex = 0;
 425   OverrideItemListIndex = MappingDataBase->ForwardLink;
 426   while (OverrideItemListIndex != MappingDataBase) {
 427     //
 428     // Try to find the most proper variable size which <= MaximumVariableSize, but can contain mapping info as much as possible
 429     //
 430     VariableNeededSize = 0;
 431     VariableNeededSize += sizeof (UINT32); //BOOLEAN  NotEnd;
 432     ItemIndex = OverrideItemListIndex;
 433     NotEnd = FALSE;
 434
 435     while (ItemIndex != MappingDataBase){
 436       OneItemNeededSize = GetOneItemNeededSize (ItemIndex);
 437       if ((VariableNeededSize +
 438            OneItemNeededSize +
 439            sizeof (VARIABLE_HEADER) +
 440            StrSize (L"PlatDriOver ")
 441            ) >= MaximumVariableSize
 442           ) {
 443         NotEnd = TRUE;
 444         break;
 445       }
 446
 447       VariableNeededSize += GetOneItemNeededSize (ItemIndex);
 448       ItemIndex =  ItemIndex->ForwardLink;
 449     }
 450
 451     if (NotEnd) {
 452       if (VariableNeededSize == sizeof (UINT32)) {
 453         //
 454         // If an individual EFI variable cannot contain a single Item, return error
 455         //
 456         return EFI_OUT_OF_RESOURCES;
 457       }
 458     }
 459
 460     //
 461     // VariableNeededSize is the most proper variable size, allocate variable buffer
 462     // ItemIndex now points to the next PLATFORM_OVERRIDE_ITEM which is not covered by VariableNeededSize
 463     //
 464     VariableBuffer = AllocateZeroPool (VariableNeededSize);
 465     ASSERT ((UINTN) VariableBuffer % sizeof(UINTN) == 0);
 466
 467     //
 468     // Fill the variable buffer according to MappingDataBase
 469     //
 470     SavedSize = 0;
 471     VariableIndex = VariableBuffer;
 472     *(UINT32 *) VariableIndex = NotEnd;
 473     VariableIndex += sizeof (UINT32); // pass NoEnd
 474     SavedSize += sizeof (UINT32);
 475     //
 476     // ItemIndex points to the next PLATFORM_OVERRIDE_ITEM which is not covered by VariableNeededSize
 477     //
 478     while (OverrideItemListIndex != ItemIndex){
 479       *(UINT32 *) VariableIndex = PLATFORM_OVERRIDE_ITEM_SIGNATURE;
 480       VariableIndex += sizeof (UINT32); // pass SIGNATURE
 481       SavedSize += sizeof (UINT32);
 482
 483       OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
 484       *(UINT32 *) VariableIndex = OverrideItem->DriverInfoNum;
 485       VariableIndex += sizeof (UINT32); // pass DriverNum
 486       SavedSize += sizeof (UINT32);
 487
 488       CopyMem (VariableIndex, OverrideItem->ControllerDevicePath, GetDevicePathSize (OverrideItem->ControllerDevicePath));
 489       VariableIndex += GetDevicePathSize (OverrideItem->ControllerDevicePath); // pass ControllerDevicePath
 490       SavedSize += GetDevicePathSize (OverrideItem->ControllerDevicePath);
 491
 492       //
 493       // Align the VariableIndex since the controller device path may not be aligned
 494       //
 495       SavedSize += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 496       VariableIndex += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 497
 498       ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
 499       while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
 500         DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
 501         CopyMem (VariableIndex, DriverImageInfo->DriverImagePath, GetDevicePathSize (DriverImageInfo->DriverImagePath));
 502         VariableIndex += GetDevicePathSize (DriverImageInfo->DriverImagePath); // pass DriverImageDevicePath
 503         SavedSize += GetDevicePathSize (DriverImageInfo->DriverImagePath);
 504         //
 505         // Align the VariableIndex since the driver image device path may not be aligned
 506         //
 507         SavedSize += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 508         VariableIndex += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));
 509         ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
 510       }
 511
 512       OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
 513     }
 514
 515     ASSERT (SavedSize == VariableNeededSize);
 516
 517     if (NumIndex == 0) {
 518       UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver");
 519     } else {
 520       UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", NumIndex );
 521     }
 522
 523     Status = gRT->SetVariable (
 524                     OverrideVariableName,
 525                     &gEfiOverrideVariableGuid,
 526                     EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE,
 527                     VariableNeededSize,
 528                     VariableBuffer
 529                     );
 530     ASSERT (!EFI_ERROR(Status));
 531
 532     NumIndex ++;
 533     FreePool (VariableBuffer);
 534   }
 535
 536   return EFI_SUCCESS;
 537 }
 538
 539 /**
 540   Get the first Binding protocol which has the specific image handle
 541
 542   @param  Image          Image handle
 543
 544   @return Pointer into the Binding Protocol interface
 545
 546 **/
 547 EFI_DRIVER_BINDING_PROTOCOL *
 548 EFIAPI
 549 GetBindingProtocolFromImageHandle (
 550   IN  EFI_HANDLE   ImageHandle,
 551   OUT EFI_HANDLE   *BindingHandle
 552   )
 553 {
 554   EFI_STATUS                        Status;
 555   UINTN                             Index;
 556   UINTN                             DriverBindingHandleCount;
 557   EFI_HANDLE                        *DriverBindingHandleBuffer;
 558   EFI_DRIVER_BINDING_PROTOCOL       *DriverBindingInterface;
 559
 560   if (BindingHandle == NULL || ImageHandle == NULL) {
 561     return NULL;
 562   }
 563   //
 564   // Get all driver which support binding protocol in second page
 565   //
 566   DriverBindingHandleCount  = 0;
 567   Status = gBS->LocateHandleBuffer (
 568                   ByProtocol,
 569                   &gEfiDriverBindingProtocolGuid,
 570                   NULL,
 571                   &DriverBindingHandleCount,
 572                   &DriverBindingHandleBuffer
 573                   );
 574   if (EFI_ERROR (Status) || (DriverBindingHandleCount == 0)) {
 575     return NULL;
 576   }
 577
 578   for (Index = 0; Index < DriverBindingHandleCount; Index++) {
 579     DriverBindingInterface =NULL;
 580     Status = gBS->OpenProtocol (
 581                     DriverBindingHandleBuffer[Index],
 582                     &gEfiDriverBindingProtocolGuid,
 583                     (VOID **) &DriverBindingInterface,
 584                     NULL,
 585                     NULL,
 586                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
 587                     );
 588     if (EFI_ERROR (Status)) {
 589       continue;
 590     }
 591
 592     if (DriverBindingInterface->ImageHandle == ImageHandle) {
 593       *BindingHandle = DriverBindingHandleBuffer[Index];
 594       FreePool (DriverBindingHandleBuffer);
 595       return DriverBindingInterface;
 596     }
 597   }
 598
 599   FreePool (DriverBindingHandleBuffer);
 600   *BindingHandle = NULL;
 601   return NULL;
 602 }
 603
 604 /**
 605   return the current TPL, copied from the EDKII glue lib
 606
 607   @param  VOID
 608
 609   @return Current TPL
 610
 611 **/
 612 EFI_TPL
 613 GetCurrentTpl (
 614   VOID
 615   )
 616 {
 617   EFI_TPL                 Tpl;
 618
 619   Tpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
 620   gBS->RestoreTPL (Tpl);
 621
 622   return Tpl;
 623 }
 624
 625
 626 /**
 627   Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
 628
 629   @param  This                     A pointer to the
 630                                    EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
 631   @param  ControllerHandle         The device handle of the controller to check if
 632                                    a driver override exists.
 633   @param  DriverImageHandle        On output, a pointer to the next driver handle.
 634                                    Passing in a pointer to NULL, will return the
 635                                    first driver handle for ControllerHandle.
 636   @param  MappingDataBase          MappingDataBase - Mapping database list entry
 637                                    pointer
 638   @param  CallerImageHandle        The caller driver's image handle, for
 639                                    UpdateFvFileDevicePath use.
 640
 641   @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not
 642                                    a valid handle.  Or DriverImagePath is not a
 643                                    device path that was returned on a previous call
 644                                    to GetDriverPath().
 645   @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not
 646                                    found.
 647   @retval EFI_UNSUPPORTED          The operation is not supported.
 648   @retval EFI_SUCCESS              The driver override for ControllerHandle was
 649                                    returned in DriverImagePath.
 650
 651 **/
 652 EFI_STATUS
 653 EFIAPI
 654 GetDriverFromMapping (
 655   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              * This,
 656   IN     EFI_HANDLE                                     ControllerHandle,
 657   IN OUT EFI_HANDLE                                     * DriverImageHandle,
 658   IN     LIST_ENTRY                                     * MappingDataBase,
 659   IN     EFI_HANDLE                                     CallerImageHandle
 660   )
 661 {
 662   EFI_STATUS                  Status;
 663   EFI_DEVICE_PATH_PROTOCOL    *ControllerDevicePath;
 664   BOOLEAN                     ControllerFound;
 665   BOOLEAN                     ImageFound;
 666   EFI_HANDLE                  *ImageHandleBuffer;
 667   UINTN                       ImageHandleCount;
 668   UINTN                       Index;
 669   EFI_DRIVER_BINDING_PROTOCOL *DriverBinding;
 670   EFI_HANDLE                  DriverBindingHandle;
 671   BOOLEAN                     FoundLastReturned;
 672   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 673   DRIVER_IMAGE_INFO           *DriverImageInfo;
 674   LIST_ENTRY                  *OverrideItemListIndex;
 675   LIST_ENTRY                  *ImageInfoListIndex;
 676   EFI_DEVICE_PATH_PROTOCOL    *TempDriverImagePath;
 677   EFI_HANDLE                  ImageHandle;
 678   EFI_HANDLE                  Handle;
 679   EFI_DEVICE_PATH_PROTOCOL    *LoadedImageDevicePath;
 680   EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL  *BusSpecificDriverOverride;
 681   UINTN                       DevicePathSize;
 682
 683   //
 684   // Check that ControllerHandle is a valid handle
 685   //
 686   if (ControllerHandle == NULL) {
 687     return EFI_INVALID_PARAMETER;
 688   }
 689
 690   Status = gBS->HandleProtocol (
 691               ControllerHandle,
 692               &gEfiDevicePathProtocolGuid,
 693               (VOID **) &ControllerDevicePath
 694               );
 695   if (EFI_ERROR (Status) || ControllerDevicePath == NULL) {
 696     return EFI_INVALID_PARAMETER;
 697   }
 698
 699   //
 700   // Search ControllerDevicePath in MappingDataBase
 701   //
 702   OverrideItem = NULL;
 703   ControllerFound = FALSE;
 704   OverrideItemListIndex = MappingDataBase->ForwardLink;
 705   while (OverrideItemListIndex != MappingDataBase){
 706     OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
 707     DevicePathSize = GetDevicePathSize (ControllerDevicePath);
 708     if (DevicePathSize == GetDevicePathSize (OverrideItem->ControllerDevicePath)) {
 709       if (CompareMem (
 710             ControllerDevicePath,
 711             OverrideItem->ControllerDevicePath,
 712             GetDevicePathSize (OverrideItem->ControllerDevicePath)
 713             ) == 0
 714           ) {
 715         ControllerFound = TRUE;
 716         break;
 717       }
 718
 719     }
 720     OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
 721   }
 722
 723   if (!ControllerFound) {
 724     return EFI_NOT_FOUND;
 725   }
 726   //
 727   // Passing in a pointer to NULL, will return the first driver device path for ControllerHandle.
 728   // Check whether the driverImagePath is not a device path that was returned on a previous call to GetDriverPath().
 729   //
 730   if (*DriverImageHandle != NULL) {
 731     if (*DriverImageHandle != OverrideItem->LastReturnedImageHandle) {
 732       return EFI_INVALID_PARAMETER;
 733     }
 734   }
 735   //
 736   // The GetDriverPath() maybe called recursively, because it use ConnectDevicePath() internally,
 737   //  so should check whether there is a dead loop.
 738   //  Here use a controller device path stack to record all processed controller device path during a GetDriverPath() call,
 739   //  and check the  controller device path whether appear again during the  GetDriverPath() call.
 740   //
 741   if (CheckExistInStack(OverrideItem->ControllerDevicePath)) {
 742     //
 743     // There is a dependecy dead loop if the ControllerDevicePath appear in stack twice
 744     //
 745     return EFI_UNSUPPORTED;
 746   }
 747   PushDevPathStack (OverrideItem->ControllerDevicePath);
 748
 749   //
 750   // Check every override driver, try to load and start them
 751   //
 752   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
 753   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
 754     DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
 755     if (DriverImageInfo->ImageHandle == NULL) {
 756       //
 757       // Skip if the image is unloadable or unstartable
 758       //
 759       if ((!DriverImageInfo->UnLoadable) && ((!DriverImageInfo->UnStartable))) {
 760         TempDriverImagePath = DriverImageInfo->DriverImagePath;
 761         //
 762         // If the image device path contain a FV node, check the Fv file device path is valid. If it is invalid, try to return the valid device path.
 763         // FV address maybe changes for memory layout adjust from time to time, use this funciton could promise the Fv file device path is right.
 764         //
 765         Status = UpdateFvFileDevicePath (&TempDriverImagePath, NULL, CallerImageHandle);
 766         if (!EFI_ERROR (Status)) {
 767           FreePool(DriverImageInfo->DriverImagePath);
 768           DriverImageInfo->DriverImagePath = TempDriverImagePath;
 769         }
 770         //
 771         // Get all Loaded Image protocol to check whether the driver image has been loaded and started
 772         //
 773         ImageFound = FALSE;
 774         ImageHandleCount  = 0;
 775         Status = gBS->LocateHandleBuffer (
 776                         ByProtocol,
 777                         &gEfiLoadedImageProtocolGuid,
 778                         NULL,
 779                         &ImageHandleCount,
 780                         &ImageHandleBuffer
 781                         );
 782         if (EFI_ERROR (Status) || (ImageHandleCount == 0)) {
 783           return EFI_NOT_FOUND;
 784         }
 785
 786         for(Index = 0; Index < ImageHandleCount; Index ++) {
 787           //
 788           // Get the EFI Loaded Image Device Path Protocol
 789           //
 790           LoadedImageDevicePath = NULL;
 791           Status = gBS->HandleProtocol (
 792                               ImageHandleBuffer[Index],
 793                               &gEfiLoadedImageDevicePathProtocolGuid,
 794                               (VOID **) &LoadedImageDevicePath
 795                               );
 796           if (EFI_ERROR (Status)) {
 797             //
 798             // Maybe Not all EFI Loaded Image Device Path Protocol existed.
 799             //
 800             continue;
 801           }
 802
 803           DevicePathSize = GetDevicePathSize (DriverImageInfo->DriverImagePath);
 804           if (DevicePathSize == GetDevicePathSize (LoadedImageDevicePath)) {
 805             if (CompareMem (
 806                   DriverImageInfo->DriverImagePath,
 807                   LoadedImageDevicePath,
 808                   GetDevicePathSize (LoadedImageDevicePath)
 809                   ) == 0
 810                 ) {
 811               ImageFound = TRUE;
 812               break;
 813             }
 814           }
 815         }
 816
 817         if (ImageFound) {
 818           //
 819           // Find its related driver binding protocol
 820           // Driver binding handle may be different with its driver's Image handle,
 821           //
 822           DriverBindingHandle = NULL;
 823           DriverBinding = GetBindingProtocolFromImageHandle (
 824                                       ImageHandleBuffer[Index],
 825                                       &DriverBindingHandle
 826                                       );
 827           ASSERT (DriverBinding != NULL);
 828           DriverImageInfo->ImageHandle = ImageHandleBuffer[Index];
 829         } else if (GetCurrentTpl() <= TPL_CALLBACK){
 830           //
 831           // The driver image has not been loaded and started, need try to load and start it now
 832           // Try to connect all device in the driver image path
 833           //
 834           // Note: LoadImage() and  StartImage() should be called under CALLBACK TPL in theory, but
 835           // since many device need to be connected in  CALLBACK level environment( e.g. Usb devices )
 836           // and the Fat and Patition driver can endure executing in CALLBACK level in fact, so here permit
 837           // to use LoadImage() and  StartImage() in CALLBACK TPL.
 838           //
 839           Status = ConnectDevicePath (DriverImageInfo->DriverImagePath);
 840           //
 841           // check whether it points to a PCI Option Rom image, and try to use bus override protocol to get its first option rom image driver
 842           //
 843           TempDriverImagePath = DriverImageInfo->DriverImagePath;
 844           gBS->LocateDevicePath (&gEfiDevicePathProtocolGuid, &TempDriverImagePath, &Handle);
 845           //
 846           // Get the Bus Specific Driver Override Protocol instance on the Controller Handle
 847           //
 848           Status = gBS->HandleProtocol(
 849                            Handle,
 850                            &gEfiBusSpecificDriverOverrideProtocolGuid,
 851                            (VOID **) &BusSpecificDriverOverride
 852                            );
 853           if (!EFI_ERROR (Status) && (BusSpecificDriverOverride != NULL)) {
 854             ImageHandle = NULL;
 855             Status = BusSpecificDriverOverride->GetDriver (
 856                                                   BusSpecificDriverOverride,
 857                                                   &ImageHandle
 858                                                   );
 859             if (!EFI_ERROR (Status)) {
 860               //
 861               // Find its related driver binding protocol
 862               // Driver binding handle may be different with its driver's Image handle
 863               //
 864               DriverBindingHandle = NULL;
 865               DriverBinding = GetBindingProtocolFromImageHandle (
 866                                           ImageHandle,
 867                                           &DriverBindingHandle
 868                                           );
 869               ASSERT (DriverBinding != NULL);
 870               DriverImageInfo->ImageHandle = ImageHandle;
 871             }
 872           }
 873           //
 874           // Skip if any device cannot be connected now, future passes through GetDriver() may be able to load that driver.
 875           // Only file path media or FwVol Device Path Node remain if all device is connected
 876           //
 877           TempDriverImagePath = DriverImageInfo->DriverImagePath;
 878           gBS->LocateDevicePath (&gEfiDevicePathProtocolGuid, &TempDriverImagePath, &Handle);
 879           if (((DevicePathType (TempDriverImagePath) == MEDIA_DEVICE_PATH) &&
 880                (DevicePathSubType (TempDriverImagePath) == MEDIA_FILEPATH_DP)) ||
 881               (EfiGetNameGuidFromFwVolDevicePathNode ((MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *) TempDriverImagePath) != NULL)
 882              ) {
 883             //
 884             // Try to load the driver
 885             //
 886             TempDriverImagePath = DriverImageInfo->DriverImagePath;
 887             Status = gBS->LoadImage (
 888                             FALSE,
 889                             CallerImageHandle,
 890                             TempDriverImagePath,
 891                             NULL,
 892                             0,
 893                             &ImageHandle
 894                             );
 895             if (!EFI_ERROR (Status)) {
 896               //
 897               // Try to start the driver
 898               //
 899               Status = gBS->StartImage (ImageHandle, NULL, NULL);
 900               if (EFI_ERROR (Status)){
 901                 DriverImageInfo->UnStartable = TRUE;
 902                 DriverImageInfo->ImageHandle = NULL;
 903               } else {
 904                 //
 905                 // Find its related driver binding protocol
 906                 // Driver binding handle may be different with its driver's Image handle
 907                 //
 908                 DriverBindingHandle = NULL;
 909                 DriverBinding = GetBindingProtocolFromImageHandle (
 910                                             ImageHandle,
 911                                             &DriverBindingHandle
 912                                             );
 913                 ASSERT (DriverBinding != NULL);
 914                 DriverImageInfo->ImageHandle = ImageHandle;
 915               }
 916             } else {
 917               DriverImageInfo->UnLoadable = TRUE;
 918               DriverImageInfo->ImageHandle = NULL;
 919             }
 920           }
 921         }
 922         FreePool (ImageHandleBuffer);
 923       }
 924     }
 925     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
 926   }
 927   //
 928   // Finish try to load and start the override driver of a controller, popup the controller's device path
 929   //
 930   PopDevPathStack (NULL);
 931
 932   //
 933   // return the DriverImageHandle for ControllerHandle
 934   //
 935   FoundLastReturned = FALSE;
 936   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
 937   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
 938     DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
 939     if (DriverImageInfo->ImageHandle != NULL) {
 940       if ((*DriverImageHandle == NULL) || FoundLastReturned) {
 941         OverrideItem->LastReturnedImageHandle = DriverImageInfo->ImageHandle;
 942         *DriverImageHandle = DriverImageInfo->ImageHandle;
 943         return EFI_SUCCESS;
 944       } else if (*DriverImageHandle == DriverImageInfo->ImageHandle){
 945         FoundLastReturned = TRUE;
 946       }
 947     }
 948     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
 949   }
 950
 951   return EFI_NOT_FOUND;
 952 }
 953
 954
 955 /**
 956   Check mapping database whether already has the  mapping info which
 957   records the input Controller to input DriverImage.
 958   If has, the controller's total override driver number and input DriverImage's order number is return.
 959
 960   @param  ControllerDevicePath     The controller device path need to add a
 961                                    override driver image item
 962   @param  DriverImageDevicePath    The driver image device path need to be insert
 963   @param  MappingDataBase          Mapping database list entry pointer
 964   @param  DriverInfoNum            the controller's total override driver number
 965   @param  DriverImageNO            The inserted order number
 966
 967   @return EFI_INVALID_PARAMETER
 968   @return EFI_NOT_FOUND
 969   @return EFI_SUCCESS
 970
 971 **/
 972 EFI_STATUS
 973 EFIAPI
 974 CheckMapping (
 975   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 976   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 977   IN     LIST_ENTRY                                     * MappingDataBase,
 978   OUT    UINT32                                         *DriverInfoNum,
 979   OUT    UINT32                                         *DriverImageNO
 980   )
 981 {
 982   LIST_ENTRY                  *OverrideItemListIndex;
 983   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
 984   LIST_ENTRY                  *ImageInfoListIndex;
 985   DRIVER_IMAGE_INFO           *DriverImageInfo;
 986   BOOLEAN                     Found;
 987   UINT32                      ImageNO;
 988   UINTN                       DevicePathSize;
 989
 990   //
 991   // Check that ControllerHandle is a valid handle
 992   //
 993   if (ControllerDevicePath == NULL) {
 994     return EFI_INVALID_PARAMETER;
 995   }
 996   if (MappingDataBase == NULL) {
 997     return EFI_INVALID_PARAMETER;
 998   }
 999   //
1000   // Search ControllerDevicePath in MappingDataBase
1001   //
1002   Found = FALSE;
1003   OverrideItem = NULL;
1004   OverrideItemListIndex = MappingDataBase->ForwardLink;
1005   while (OverrideItemListIndex != MappingDataBase){
1006     OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
1007     DevicePathSize = GetDevicePathSize (ControllerDevicePath);
1008     if (DevicePathSize == GetDevicePathSize (OverrideItem->ControllerDevicePath)) {
1009       if (CompareMem (
1010             ControllerDevicePath,
1011             OverrideItem->ControllerDevicePath,
1012             GetDevicePathSize (OverrideItem->ControllerDevicePath)
1013             ) == 0
1014           ) {
1015         Found = TRUE;
1016         break;
1017       }
1018     }
1019     OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
1020   }
1021
1022   if (!Found) {
1023     return EFI_NOT_FOUND;
1024   }
1025
1026   ASSERT (OverrideItem->DriverInfoNum != 0);
1027   if (DriverInfoNum != NULL) {
1028     *DriverInfoNum = OverrideItem->DriverInfoNum;
1029   }
1030
1031
1032   if (DriverImageDevicePath == NULL) {
1033     return EFI_SUCCESS;
1034   }
1035   //
1036   // return the DriverImageHandle for ControllerHandle
1037   //
1038   ImageNO = 0;
1039   Found = FALSE;
1040   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
1041   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
1042     DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
1043     ImageNO++;
1044     DevicePathSize = GetDevicePathSize (DriverImageDevicePath);
1045     if (DevicePathSize == GetDevicePathSize (DriverImageInfo->DriverImagePath)) {
1046       if (CompareMem (
1047             DriverImageDevicePath,
1048             DriverImageInfo->DriverImagePath,
1049             GetDevicePathSize (DriverImageInfo->DriverImagePath)
1050             ) == 0
1051           ) {
1052         Found = TRUE;
1053         break;
1054       }
1055     }
1056     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
1057   }
1058
1059   if (!Found) {
1060     return EFI_NOT_FOUND;
1061   } else {
1062     if (DriverImageNO != NULL) {
1063       *DriverImageNO = ImageNO;
1064     }
1065     return EFI_SUCCESS;
1066   }
1067
1068 }
1069
1070
1071 /**
1072   Insert a driver image as a controller's override driver into the mapping database.
1073   The driver image's order number is indicated by DriverImageNO.
1074
1075   @param  ControllerDevicePath     The controller device path need to add a
1076                                    override driver image item
1077   @param  DriverImageDevicePath    The driver image device path need to be insert
1078   @param  MappingDataBase          Mapping database list entry pointer
1079   @param  DriverImageNO            The inserted order number
1080
1081   @return EFI_INVALID_PARAMETER
1082   @return EFI_ALREADY_STARTED
1083   @return EFI_SUCCESS
1084
1085 **/
1086 EFI_STATUS
1087 EFIAPI
1088 InsertDriverImage (
1089   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
1090   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
1091   IN     LIST_ENTRY                                     *MappingDataBase,
1092   IN     UINT32                                         DriverImageNO
1093   )
1094 {
1095   EFI_STATUS                  Status;
1096   LIST_ENTRY                  *OverrideItemListIndex;
1097   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
1098   LIST_ENTRY                  *ImageInfoListIndex;
1099   DRIVER_IMAGE_INFO           *DriverImageInfo;
1100   BOOLEAN                     Found;
1101   UINT32                      ImageNO;
1102   UINTN                       DevicePathSize;
1103
1104   //
1105   // Check that ControllerHandle is a valid handle
1106   //
1107   if (ControllerDevicePath == NULL) {
1108     return EFI_INVALID_PARAMETER;
1109   }
1110   if (DriverImageDevicePath == NULL) {
1111     return EFI_INVALID_PARAMETER;
1112   }
1113   if (MappingDataBase == NULL) {
1114     return EFI_INVALID_PARAMETER;
1115   }
1116
1117   Status = CheckMapping (
1118             ControllerDevicePath,
1119             DriverImageDevicePath,
1120             MappingDataBase,
1121             NULL,
1122             NULL
1123             );
1124   if (Status == EFI_SUCCESS) {
1125     return EFI_ALREADY_STARTED;
1126   }
1127
1128   //
1129   // Search the input ControllerDevicePath in MappingDataBase
1130   //
1131   Found = FALSE;
1132   OverrideItem = NULL;
1133   OverrideItemListIndex = MappingDataBase->ForwardLink;
1134   while (OverrideItemListIndex != MappingDataBase){
1135     OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
1136     DevicePathSize = GetDevicePathSize (ControllerDevicePath);
1137     if (DevicePathSize == GetDevicePathSize (OverrideItem->ControllerDevicePath)) {
1138       if (CompareMem (
1139             ControllerDevicePath,
1140             OverrideItem->ControllerDevicePath,
1141             GetDevicePathSize (OverrideItem->ControllerDevicePath)
1142             ) == 0
1143           ) {
1144         Found = TRUE;
1145         break;
1146       }
1147     }
1148     OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
1149   }
1150   //
1151   // If cannot find, this is a new controller item
1152   // Add the Controller related PLATFORM_OVERRIDE_ITEM structrue in mapping data base
1153   //
1154   if (!Found) {
1155     OverrideItem = AllocateZeroPool (sizeof (PLATFORM_OVERRIDE_ITEM));
1156     ASSERT (OverrideItem != NULL);
1157     OverrideItem->Signature = PLATFORM_OVERRIDE_ITEM_SIGNATURE;
1158     OverrideItem->ControllerDevicePath = DuplicateDevicePath (ControllerDevicePath);
1159     InitializeListHead (&OverrideItem->DriverInfoList);
1160     InsertTailList (MappingDataBase, &OverrideItem->Link);
1161   }
1162
1163   //
1164   // Prepare the driver image related DRIVER_IMAGE_INFO structure.
1165   //
1166   DriverImageInfo = AllocateZeroPool (sizeof (DRIVER_IMAGE_INFO));
1167   ASSERT (DriverImageInfo != NULL);
1168   DriverImageInfo->Signature = DRIVER_IMAGE_INFO_SIGNATURE;
1169   DriverImageInfo->DriverImagePath = DuplicateDevicePath (DriverImageDevicePath);
1170   //
1171   // Find the driver image wantted order location
1172   //
1173   ImageNO = 0;
1174   Found = FALSE;
1175   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
1176   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
1177     if (ImageNO == (DriverImageNO - 1)) {
1178       //
1179       // find the wantted order location, insert it
1180       //
1181       InsertTailList (ImageInfoListIndex, &DriverImageInfo->Link);
1182       OverrideItem->DriverInfoNum ++;
1183       Found = TRUE;
1184       break;
1185     }
1186     //DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
1187     ImageNO++;
1188     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
1189   }
1190
1191   if (!Found) {
1192     //
1193     // if not find the wantted order location, add it as last item of the controller mapping item
1194     //
1195     InsertTailList (&OverrideItem->DriverInfoList, &DriverImageInfo->Link);
1196     OverrideItem->DriverInfoNum ++;
1197   }
1198
1199   return EFI_SUCCESS;
1200 }
1201
1202
1203 /**
1204   Delete a controller's override driver from the mapping database.
1205
1206   @param  ControllerDevicePath     The controller device path need to add a
1207                                    override driver image item
1208   @param  DriverImageDevicePath    The driver image device path need to be insert
1209   @param  MappingDataBase          Mapping database list entry pointer
1210   @param  DriverImageNO            The inserted order number
1211
1212   @return EFI_INVALID_PARAMETER
1213   @return EFI_NOT_FOUND
1214   @return EFI_SUCCESS
1215
1216 **/
1217 EFI_STATUS
1218 EFIAPI
1219 DeleteDriverImage (
1220   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
1221   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
1222   IN     LIST_ENTRY                                     *MappingDataBase
1223   )
1224 {
1225   EFI_STATUS                  Status;
1226   LIST_ENTRY                  *OverrideItemListIndex;
1227   PLATFORM_OVERRIDE_ITEM      *OverrideItem;
1228   LIST_ENTRY                  *ImageInfoListIndex;
1229   DRIVER_IMAGE_INFO           *DriverImageInfo;
1230   BOOLEAN                     Found;
1231   UINTN                       DevicePathSize;
1232
1233   //
1234   // Check that ControllerHandle is a valid handle
1235   //
1236   if (ControllerDevicePath == NULL) {
1237     return EFI_INVALID_PARAMETER;
1238   }
1239
1240   if (MappingDataBase == NULL) {
1241     return EFI_INVALID_PARAMETER;
1242   }
1243
1244    Status = CheckMapping (
1245               ControllerDevicePath,
1246               DriverImageDevicePath,
1247               MappingDataBase,
1248               NULL,
1249               NULL
1250               );
1251   if (Status == EFI_NOT_FOUND) {
1252     return EFI_NOT_FOUND;
1253   }
1254
1255   //
1256   // Search ControllerDevicePath in MappingDataBase
1257   //
1258   Found = FALSE;
1259   OverrideItem = NULL;
1260   OverrideItemListIndex = MappingDataBase->ForwardLink;
1261   while (OverrideItemListIndex != MappingDataBase){
1262     OverrideItem = CR(OverrideItemListIndex, PLATFORM_OVERRIDE_ITEM, Link, PLATFORM_OVERRIDE_ITEM_SIGNATURE);
1263     DevicePathSize = GetDevicePathSize (ControllerDevicePath);
1264     if (DevicePathSize == GetDevicePathSize (OverrideItem->ControllerDevicePath)) {
1265       if (CompareMem (
1266             ControllerDevicePath,
1267             OverrideItem->ControllerDevicePath,
1268             GetDevicePathSize (OverrideItem->ControllerDevicePath)
1269             ) == 0
1270           ) {
1271         Found = TRUE;
1272         break;
1273       }
1274     }
1275     OverrideItemListIndex =  OverrideItemListIndex->ForwardLink;
1276   }
1277
1278   ASSERT (Found);
1279   ASSERT (OverrideItem->DriverInfoNum != 0);
1280   //
1281   //
1282   //
1283   Found = FALSE;
1284   ImageInfoListIndex =  OverrideItem->DriverInfoList.ForwardLink;
1285   while (ImageInfoListIndex != &OverrideItem->DriverInfoList){
1286     DriverImageInfo = CR(ImageInfoListIndex, DRIVER_IMAGE_INFO, Link, DRIVER_IMAGE_INFO_SIGNATURE);
1287     ImageInfoListIndex = ImageInfoListIndex->ForwardLink;
1288     if (DriverImageDevicePath != NULL) {
1289       DevicePathSize = GetDevicePathSize (DriverImageDevicePath);
1290       if (DevicePathSize == GetDevicePathSize (DriverImageInfo->DriverImagePath)) {
1291         if (CompareMem (
1292               DriverImageDevicePath,
1293               DriverImageInfo->DriverImagePath,
1294               GetDevicePathSize (DriverImageInfo->DriverImagePath)
1295               ) == 0
1296             ) {
1297           Found = TRUE;
1298           FreePool(DriverImageInfo->DriverImagePath);
1299           RemoveEntryList (&DriverImageInfo->Link);
1300           OverrideItem->DriverInfoNum --;
1301           break;
1302         }
1303       }
1304     } else {
1305       Found = TRUE;
1306       FreePool(DriverImageInfo->DriverImagePath);
1307       RemoveEntryList (&DriverImageInfo->Link);
1308       OverrideItem->DriverInfoNum --;
1309     }
1310   }
1311
1312   if (DriverImageDevicePath == NULL) {
1313     ASSERT (OverrideItem->DriverInfoNum == 0);
1314   }
1315
1316   if (OverrideItem->DriverInfoNum == 0) {
1317     FreePool(OverrideItem->ControllerDevicePath);
1318     RemoveEntryList (&OverrideItem->Link);
1319     FreePool (OverrideItem);
1320   }
1321
1322   if (!Found) {
1323     return EFI_NOT_FOUND;
1324   }
1325
1326   return EFI_SUCCESS;
1327 }
1328
1329
1330 /**
1331   Deletes all environment variable(s) that contain the override mappings from Controller Device Path to
1332   a set of Driver Device Paths.
1333
1334   None
1335
1336   @return EFI_SUCCESS
1337
1338 **/
1339 EFI_STATUS
1340 EFIAPI
1341 DeleteOverridesVariables (
1342   VOID
1343   )
1344 {
1345   EFI_STATUS                  Status;
1346   VOID                        *VariableBuffer;
1347   UINTN                       VariableNum;
1348   UINTN                       BufferSize;
1349   UINTN                       Index;
1350   CHAR16                      OverrideVariableName[40];
1351
1352   //
1353   // Get environment variable(s)  number
1354   //
1355   VariableNum =0;
1356   VariableBuffer = GetVariableAndSize (L"PlatDriOver", &gEfiOverrideVariableGuid, &BufferSize);
1357   VariableNum ++;
1358   if (VariableBuffer == NULL) {
1359     return EFI_NOT_FOUND;
1360   }
1361   //
1362   // Check NotEnd to get all PlatDriOverX variable(s)
1363   //
1364   while (*(UINT32*)VariableBuffer) {
1365     UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", VariableNum);
1366     VariableBuffer = GetVariableAndSize (OverrideVariableName, &gEfiOverrideVariableGuid, &BufferSize);
1367     VariableNum ++;
1368     ASSERT (VariableBuffer != NULL);
1369   }
1370
1371   Status = gRT->SetVariable (
1372                   L"PlatDriOver",
1373                   &gEfiOverrideVariableGuid,
1374                   EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE,
1375                   0,
1376                   NULL
1377                   );
1378   ASSERT (!EFI_ERROR (Status));
1379   for (Index = 1; Index < VariableNum; Index++) {
1380     UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", Index);
1381     Status = gRT->SetVariable (
1382                     OverrideVariableName,
1383                     &gEfiOverrideVariableGuid,
1384                     EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE,
1385                     0,
1386                     NULL
1387                     );
1388     ASSERT (!EFI_ERROR (Status));
1389   }
1390   return EFI_SUCCESS;
1391 }
1392
1393
1394 /**
1395   Push a controller device path into a globle device path list
1396
1397   @param  ControllerDevicePath     The controller device path need to push into
1398                                    stack
1399
1400   @return EFI_SUCCESS
1401
1402 **/
1403 EFI_STATUS
1404 EFIAPI
1405 PushDevPathStack (
1406   IN  EFI_DEVICE_PATH_PROTOCOL    *DevicePath
1407   )
1408 {
1409   DEVICE_PATH_STACK_ITEM  *DevicePathStackItem;
1410
1411   DevicePathStackItem = AllocateZeroPool (sizeof (DEVICE_PATH_STACK_ITEM));
1412   ASSERT (DevicePathStackItem != NULL);
1413   DevicePathStackItem->Signature = DEVICE_PATH_STACK_ITEM_SIGNATURE;
1414   DevicePathStackItem->DevicePath = DuplicateDevicePath (DevicePath);
1415   InsertTailList (&mDevicePathStack, &DevicePathStackItem->Link);
1416   return EFI_SUCCESS;
1417 }
1418
1419
1420 /**
1421   Pop a controller device path from a globle device path list
1422
1423   @param  ControllerDevicePath     The controller device path retrieved from stack
1424
1425   @return EFI_SUCCESS
1426   @return EFI_NOT_FOUND
1427
1428 **/
1429 EFI_STATUS
1430 EFIAPI
1431 PopDevPathStack (
1432   OUT  EFI_DEVICE_PATH_PROTOCOL    **DevicePath
1433   )
1434 {
1435   DEVICE_PATH_STACK_ITEM  *DevicePathStackItem;
1436   LIST_ENTRY              *ItemListIndex;
1437
1438   ItemListIndex = mDevicePathStack.BackLink;
1439   if (ItemListIndex != &mDevicePathStack){
1440     DevicePathStackItem = CR(ItemListIndex, DEVICE_PATH_STACK_ITEM, Link, DEVICE_PATH_STACK_ITEM_SIGNATURE);
1441     if (DevicePath != NULL) {
1442       *DevicePath = DuplicateDevicePath (DevicePathStackItem->DevicePath);
1443     }
1444     FreePool (DevicePathStackItem->DevicePath);
1445     RemoveEntryList (&DevicePathStackItem->Link);
1446     FreePool (DevicePathStackItem);
1447     return EFI_SUCCESS;
1448   }
1449   return EFI_NOT_FOUND;
1450 }
1451
1452
1453 /**
1454   Check whether a controller device path is in a globle device path list
1455
1456   @param  ControllerDevicePath     The controller device path need to check
1457
1458   @return True
1459   @return False
1460
1461 **/
1462 BOOLEAN
1463 EFIAPI
1464 CheckExistInStack (
1465   IN  EFI_DEVICE_PATH_PROTOCOL    *DevicePath
1466   )
1467 {
1468   DEVICE_PATH_STACK_ITEM  *DevicePathStackItem;
1469   LIST_ENTRY              *ItemListIndex;
1470   BOOLEAN                 Found;
1471   UINTN                   DevicePathSize;
1472
1473   Found = FALSE;
1474   ItemListIndex = mDevicePathStack.BackLink;
1475   while (ItemListIndex != &mDevicePathStack){
1476     DevicePathStackItem = CR(ItemListIndex, DEVICE_PATH_STACK_ITEM, Link, DEVICE_PATH_STACK_ITEM_SIGNATURE);
1477     DevicePathSize = GetDevicePathSize (DevicePath);
1478     if (DevicePathSize == GetDevicePathSize (DevicePathStackItem->DevicePath)) {
1479       if (CompareMem (
1480             DevicePath,
1481             DevicePathStackItem->DevicePath,
1482             GetDevicePathSize (DevicePathStackItem->DevicePath)
1483             ) == 0
1484           ) {
1485         Found = TRUE;
1486         break;
1487       }
1488     }
1489     ItemListIndex = ItemListIndex->BackLink;
1490   }
1491
1492   return Found;
1493 }
1494
1495
1496 /**
1497   According to a file guild, check a Fv file device path is valid. If it is invalid,
1498   try to return the valid device path.
1499   FV address maybe changes for memory layout adjust from time to time, use this funciton
1500   could promise the Fv file device path is right.
1501
1502   @param  DevicePath               on input, the Fv file device path need to check
1503                                    on output, the updated valid Fv file device path
1504   @param  FileGuid                 the Fv file guild
1505   @param  CallerImageHandle
1506
1507   @retval EFI_INVALID_PARAMETER    the input DevicePath or FileGuid is invalid
1508                                    parameter
1509   @retval EFI_UNSUPPORTED          the input DevicePath does not contain Fv file
1510                                    guild at all
1511   @retval EFI_ALREADY_STARTED      the input DevicePath has pointed to Fv file, it
1512                                    is valid
1513   @retval EFI_SUCCESS              has successfully updated the invalid DevicePath,
1514                                    and return the updated device path in DevicePath
1515
1516 **/
1517 EFI_STATUS
1518 EFIAPI
1519 UpdateFvFileDevicePath (
1520   IN  OUT EFI_DEVICE_PATH_PROTOCOL      ** DevicePath,
1521   IN  EFI_GUID                          *FileGuid,
1522   IN  EFI_HANDLE                        CallerImageHandle
1523   )
1524 {
1525   EFI_DEVICE_PATH_PROTOCOL      *TempDevicePath;
1526   EFI_DEVICE_PATH_PROTOCOL      *LastDeviceNode;
1527   EFI_STATUS                    Status;
1528   EFI_GUID                      *GuidPoint;
1529   UINTN                         Index;
1530   UINTN                         FvHandleCount;
1531   EFI_HANDLE                    *FvHandleBuffer;
1532   EFI_FV_FILETYPE               Type;
1533   UINTN                         Size;
1534   EFI_FV_FILE_ATTRIBUTES        Attributes;
1535   UINT32                        AuthenticationStatus;
1536   BOOLEAN                       FindFvFile;
1537   EFI_LOADED_IMAGE_PROTOCOL     *LoadedImage;
1538   EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv;
1539   MEDIA_FW_VOL_FILEPATH_DEVICE_PATH FvFileNode;
1540   EFI_HANDLE                    FoundFvHandle;
1541   EFI_DEVICE_PATH_PROTOCOL      *NewDevicePath;
1542   BOOLEAN                       HasFVNode;
1543
1544   if ((DevicePath == NULL) || (*DevicePath == NULL)) {
1545     return EFI_INVALID_PARAMETER;
1546   }
1547
1548   //
1549   // Check whether the device path point to the default the input Fv file
1550   //
1551   TempDevicePath = *DevicePath;
1552   LastDeviceNode = TempDevicePath;
1553   while (!EfiIsDevicePathEnd (TempDevicePath)) {
1554      LastDeviceNode = TempDevicePath;
1555      TempDevicePath = EfiNextDevicePathNode (TempDevicePath);
1556   }
1557   GuidPoint = EfiGetNameGuidFromFwVolDevicePathNode (
1558                 (MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *) LastDeviceNode
1559                 );
1560   if (GuidPoint == NULL) {
1561     //
1562     // if this option does not points to a Fv file, just return EFI_UNSUPPORTED
1563     //
1564     return EFI_UNSUPPORTED;
1565   }
1566
1567   if (FileGuid != NULL) {
1568     if (!CompareGuid (GuidPoint, FileGuid)) {
1569       //
1570       // If the Fv file is not the input file guid, just return EFI_UNSUPPORTED
1571       //
1572       return EFI_UNSUPPORTED;
1573     }
1574   } else {
1575     FileGuid = GuidPoint;
1576   }
1577
1578   //
1579   // Check to see if the device path contain memory map node
1580   //
1581   TempDevicePath = *DevicePath;
1582   HasFVNode = FALSE;
1583   while (!EfiIsDevicePathEnd (TempDevicePath)) {
1584     //
1585     // Use old Device Path
1586     //
1587     if (DevicePathType (TempDevicePath) == HARDWARE_DEVICE_PATH &&
1588         DevicePathSubType (TempDevicePath) == HW_MEMMAP_DP) {
1589       HasFVNode = TRUE;
1590       break;
1591     }
1592     TempDevicePath = EfiNextDevicePathNode (TempDevicePath);
1593   }
1594
1595   if (!HasFVNode) {
1596     return EFI_UNSUPPORTED;
1597   }
1598
1599   //
1600   // Check whether the input Fv file device path is valid
1601   //
1602   TempDevicePath = *DevicePath;
1603   FoundFvHandle = NULL;
1604   Status = gBS->LocateDevicePath (
1605                   &gEfiFirmwareVolume2ProtocolGuid,
1606                   &TempDevicePath,
1607                   &FoundFvHandle
1608                   );
1609   if (!EFI_ERROR (Status)) {
1610     Status = gBS->HandleProtocol (
1611                     FoundFvHandle,
1612                     &gEfiFirmwareVolume2ProtocolGuid,
1613                     (VOID **) &Fv
1614                     );
1615     if (!EFI_ERROR (Status)) {
1616       //
1617       // Set FV ReadFile Buffer as NULL, only need to check whether input Fv file exist there
1618       //
1619       Status = Fv->ReadFile (
1620                     Fv,
1621                     FileGuid,
1622                     NULL,
1623                     &Size,
1624                     &Type,
1625                     &Attributes,
1626                     &AuthenticationStatus
1627                     );
1628       if (!EFI_ERROR (Status)) {
1629         return EFI_ALREADY_STARTED;
1630       }
1631     }
1632   }
1633
1634   //
1635   // Look for the input wanted FV file in current FV
1636   // First, try to look for in Caller own FV. Caller and input wanted FV file usually are in the same FV
1637   //
1638   FindFvFile = FALSE;
1639   FoundFvHandle = NULL;
1640   Status = gBS->HandleProtocol (
1641              CallerImageHandle,
1642              &gEfiLoadedImageProtocolGuid,
1643              (VOID **) &LoadedImage
1644              );
1645   if (!EFI_ERROR (Status)) {
1646     Status = gBS->HandleProtocol (
1647                     LoadedImage->DeviceHandle,
1648                     &gEfiFirmwareVolume2ProtocolGuid,
1649                     (VOID **) &Fv
1650                     );
1651     if (!EFI_ERROR (Status)) {
1652       Status = Fv->ReadFile (
1653                     Fv,
1654                     FileGuid,
1655                     NULL,
1656                     &Size,
1657                     &Type,
1658                     &Attributes,
1659                     &AuthenticationStatus
1660                     );
1661       if (!EFI_ERROR (Status)) {
1662         FindFvFile = TRUE;
1663         FoundFvHandle = LoadedImage->DeviceHandle;
1664       }
1665     }
1666   }
1667   //
1668   // Second, if fail to find, try to enumerate all FV
1669   //
1670   if (!FindFvFile) {
1671     gBS->LocateHandleBuffer (
1672           ByProtocol,
1673           &gEfiFirmwareVolume2ProtocolGuid,
1674           NULL,
1675           &FvHandleCount,
1676           &FvHandleBuffer
1677           );
1678     for (Index = 0; Index < FvHandleCount; Index++) {
1679       gBS->HandleProtocol (
1680             FvHandleBuffer[Index],
1681             &gEfiFirmwareVolume2ProtocolGuid,
1682             (VOID **) &Fv
1683             );
1684
1685       Status = Fv->ReadFile (
1686                     Fv,
1687                     FileGuid,
1688                     NULL,
1689                     &Size,
1690                     &Type,
1691                     &Attributes,
1692                     &AuthenticationStatus
1693                     );
1694       if (EFI_ERROR (Status)) {
1695         //
1696         // Skip if input Fv file not in the FV
1697         //
1698         continue;
1699       }
1700       FindFvFile = TRUE;
1701       FoundFvHandle = FvHandleBuffer[Index];
1702       break;
1703     }
1704   }
1705
1706   if (FindFvFile) {
1707     //
1708     // Build the shell device path
1709     //
1710     NewDevicePath = DevicePathFromHandle (FoundFvHandle);
1711     EfiInitializeFwVolDevicepathNode (&FvFileNode, FileGuid);
1712     NewDevicePath = AppendDevicePathNode (NewDevicePath, (EFI_DEVICE_PATH_PROTOCOL *) &FvFileNode);
1713     *DevicePath = NewDevicePath;
1714     return EFI_SUCCESS;
1715   }
1716   return EFI_NOT_FOUND;
1717 }
1718
1719
1720 /**
1721   Read the EFI variable (VendorGuid/Name) and return a dynamically allocated
1722   buffer, and the size of the buffer. If failure return NULL.
1723
1724   @param  Name                     String part of EFI variable name
1725   @param  VendorGuid               GUID part of EFI variable name
1726   @param  VariableSize             Returns the size of the EFI variable that was
1727                                    read
1728
1729   @return Dynamically allocated memory that contains a copy of the EFI variable.
1730   @return Caller is responsible freeing the buffer.
1731   @retval NULL                     Variable was not read
1732
1733 **/
1734 VOID *
1735 EFIAPI
1736 GetVariableAndSize (
1737   IN  CHAR16              *Name,
1738   IN  EFI_GUID            *VendorGuid,
1739   OUT UINTN               *VariableSize
1740   )
1741 {
1742   EFI_STATUS  Status;
1743   UINTN       BufferSize;
1744   VOID        *Buffer;
1745
1746   Buffer = NULL;
1747
1748   //
1749   // Pass in a zero size buffer to find the required buffer size.
1750   //
1751   BufferSize  = 0;
1752   Status      = gRT->GetVariable (Name, VendorGuid, NULL, &BufferSize, Buffer);
1753   if (Status == EFI_BUFFER_TOO_SMALL) {
1754     //
1755     // Allocate the buffer to return
1756     //
1757     Buffer = AllocateZeroPool (BufferSize);
1758     if (Buffer == NULL) {
1759       return NULL;
1760     }
1761     //
1762     // Read variable into the allocated buffer.
1763     //
1764     Status = gRT->GetVariable (Name, VendorGuid, NULL, &BufferSize, Buffer);
1765     if (EFI_ERROR (Status)) {
1766       BufferSize = 0;
1767     }
1768   }
1769
1770   *VariableSize = BufferSize;
1771   return Buffer;
1772 }
1773
1774
1775 /**
1776   This function will create all handles associate with every device
1777   path node. If the handle associate with one device path node can not
1778   be created success, then still give one chance to do the dispatch,
1779   which load the missing drivers if possible.
1780
1781   @param  DevicePathToConnect      The device path which will be connected, it can
1782                                    be a multi-instance device path
1783
1784   @retval EFI_SUCCESS              All handles associate with every device path
1785                                    node have been created
1786   @retval EFI_OUT_OF_RESOURCES     There is no resource to create new handles
1787   @retval EFI_NOT_FOUND            Create the handle associate with one device
1788                                    path node failed
1789
1790 **/
1791 EFI_STATUS
1792 EFIAPI
1793 ConnectDevicePath (
1794   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePathToConnect
1795   )
1796 {
1797   EFI_STATUS                Status;
1798   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
1799   EFI_DEVICE_PATH_PROTOCOL  *CopyOfDevicePath;
1800   EFI_DEVICE_PATH_PROTOCOL  *Instance;
1801   EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath;
1802   EFI_DEVICE_PATH_PROTOCOL  *Next;
1803   EFI_HANDLE                Handle;
1804   EFI_HANDLE                PreviousHandle;
1805   UINTN                     Size;
1806
1807   if (DevicePathToConnect == NULL) {
1808     return EFI_SUCCESS;
1809   }
1810
1811   DevicePath        = DuplicateDevicePath (DevicePathToConnect);
1812   CopyOfDevicePath  = DevicePath;
1813   if (DevicePath == NULL) {
1814     return EFI_OUT_OF_RESOURCES;
1815   }
1816
1817   do {
1818     //
1819     // The outer loop handles multi instance device paths.
1820     // Only console variables contain multiple instance device paths.
1821     //
1822     // After this call DevicePath points to the next Instance
1823     //
1824     Instance  = GetNextDevicePathInstance (&DevicePath, &Size);
1825     Next      = Instance;
1826     while (!IsDevicePathEndType (Next)) {
1827       Next = NextDevicePathNode (Next);
1828     }
1829
1830     SetDevicePathEndNode (Next);
1831
1832     //
1833     // Start the real work of connect with RemainingDevicePath
1834     //
1835     PreviousHandle = NULL;
1836     do {
1837       //
1838       // Find the handle that best matches the Device Path. If it is only a
1839       // partial match the remaining part of the device path is returned in
1840       // RemainingDevicePath.
1841       //
1842       RemainingDevicePath = Instance;
1843       Status              = gBS->LocateDevicePath (&gEfiDevicePathProtocolGuid, &RemainingDevicePath, &Handle);
1844
1845       if (!EFI_ERROR (Status)) {
1846         if (Handle == PreviousHandle) {
1847           //
1848           // If no forward progress is made try invoking the Dispatcher.
1849           // A new FV may have been added to the system an new drivers
1850           // may now be found.
1851           // Status == EFI_SUCCESS means a driver was dispatched
1852           // Status == EFI_NOT_FOUND means no new drivers were dispatched
1853           //
1854           Status = gDS->Dispatch ();
1855         }
1856
1857         if (!EFI_ERROR (Status)) {
1858           PreviousHandle = Handle;
1859           //
1860           // Connect all drivers that apply to Handle and RemainingDevicePath,
1861           // the Recursive flag is FALSE so only one level will be expanded.
1862           //
1863           // Do not check the connect status here, if the connect controller fail,
1864           // then still give the chance to do dispatch, because partial
1865           // RemainingDevicepath may be in the new FV
1866           //
1867           // 1. If the connect fail, RemainingDevicepath and handle will not
1868           //    change, so next time will do the dispatch, then dispatch's status
1869           //    will take effect
1870           // 2. If the connect success, the RemainingDevicepath and handle will
1871           //    change, then avoid the dispatch, we have chance to continue the
1872           //    next connection
1873           //
1874           gBS->ConnectController (Handle, NULL, RemainingDevicePath, FALSE);
1875         }
1876       }
1877       //
1878       // Loop until RemainingDevicePath is an empty device path
1879       //
1880     } while (!EFI_ERROR (Status) && !IsDevicePathEnd (RemainingDevicePath));
1881
1882   } while (DevicePath != NULL);
1883
1884   if (CopyOfDevicePath != NULL) {
1885     FreePool (CopyOfDevicePath);
1886   }
1887   //
1888   // All handle with DevicePath exists in the handle database
1889   //
1890   return Status;
1891 }