[mirror_edk2.git] / FatPkg / FatPei / FatLiteApi.c

/** @file\r
  FAT recovery PEIM entry point, Ppi Functions and FAT Api functions.\r
\r
Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>\r
\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include "FatLitePeim.h"\r
\r
PEI_FAT_PRIVATE_DATA  *mPrivateData = NULL;\r
\r
/**\r
  BlockIo installation notification function. Find out all the current BlockIO\r
  PPIs in the system and add them into private data. Assume there is\r
\r
  @param  PeiServices             General purpose services available to every\r
                                  PEIM.\r
  @param  NotifyDescriptor        The typedef structure of the notification\r
                                  descriptor. Not used in this function.\r
  @param  Ppi                     The typedef structure of the PPI descriptor.\r
                                  Not used in this function.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
BlockIoNotifyEntry (\r
  IN EFI_PEI_SERVICES           **PeiServices,\r
  IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyDescriptor,\r
  IN VOID                       *Ppi\r
  );\r
\r
/**\r
  Discover all the block I/O devices to find the FAT volume.\r
\r
  @param  PrivateData             Global memory map for accessing global\r
                                  variables.\r
  @param  BlockIo2                Boolean to show whether using BlockIo2 or BlockIo\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
\r
**/\r
EFI_STATUS\r
UpdateBlocksAndVolumes (\r
  IN OUT PEI_FAT_PRIVATE_DATA  *PrivateData,\r
  IN     BOOLEAN               BlockIo2\r
  )\r
{\r
  EFI_STATUS                      Status;\r
  EFI_PEI_PPI_DESCRIPTOR          *TempPpiDescriptor;\r
  UINTN                           BlockIoPpiInstance;\r
  EFI_PEI_RECOVERY_BLOCK_IO_PPI   *BlockIoPpi;\r
  EFI_PEI_RECOVERY_BLOCK_IO2_PPI  *BlockIo2Ppi;\r
  UINTN                           NumberBlockDevices;\r
  UINTN                           Index;\r
  EFI_PEI_BLOCK_IO_MEDIA          Media;\r
  EFI_PEI_BLOCK_IO2_MEDIA         Media2;\r
  PEI_FAT_VOLUME                  Volume;\r
  EFI_PEI_SERVICES                **PeiServices;\r
\r
  PeiServices = (EFI_PEI_SERVICES **)GetPeiServicesTablePointer ();\r
  BlockIo2Ppi = NULL;\r
  BlockIoPpi  = NULL;\r
  //\r
  // Clean up caches\r
  //\r
  for (Index = 0; Index < PEI_FAT_CACHE_SIZE; Index++) {\r
    PrivateData->CacheBuffer[Index].Valid = FALSE;\r
  }\r
\r
  PrivateData->BlockDeviceCount = 0;\r
\r
  //\r
  // Find out all Block Io Ppi instances within the system\r
  // Assuming all device Block Io Peims are dispatched already\r
  //\r
  for (BlockIoPpiInstance = 0; BlockIoPpiInstance < PEI_FAT_MAX_BLOCK_IO_PPI; BlockIoPpiInstance++) {\r
    if (BlockIo2) {\r
      Status = PeiServicesLocatePpi (\r
                 &gEfiPeiVirtualBlockIo2PpiGuid,\r
                 BlockIoPpiInstance,\r
                 &TempPpiDescriptor,\r
                 (VOID **)&BlockIo2Ppi\r
                 );\r
    } else {\r
      Status = PeiServicesLocatePpi (\r
                 &gEfiPeiVirtualBlockIoPpiGuid,\r
                 BlockIoPpiInstance,\r
                 &TempPpiDescriptor,\r
                 (VOID **)&BlockIoPpi\r
                 );\r
    }\r
\r
    if (EFI_ERROR (Status)) {\r
      //\r
      // Done with all Block Io Ppis\r
      //\r
      break;\r
    }\r
\r
    if (BlockIo2) {\r
      Status = BlockIo2Ppi->GetNumberOfBlockDevices (\r
                              PeiServices,\r
                              BlockIo2Ppi,\r
                              &NumberBlockDevices\r
                              );\r
    } else {\r
      Status = BlockIoPpi->GetNumberOfBlockDevices (\r
                             PeiServices,\r
                             BlockIoPpi,\r
                             &NumberBlockDevices\r
                             );\r
    }\r
\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    for (Index = 1; Index <= NumberBlockDevices && PrivateData->BlockDeviceCount < PEI_FAT_MAX_BLOCK_DEVICE; Index++) {\r
      if (BlockIo2) {\r
        Status = BlockIo2Ppi->GetBlockDeviceMediaInfo (\r
                                PeiServices,\r
                                BlockIo2Ppi,\r
                                Index,\r
                                &Media2\r
                                );\r
        if (EFI_ERROR (Status) || !Media2.MediaPresent) {\r
          continue;\r
        }\r
\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].BlockIo2      = BlockIo2Ppi;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].InterfaceType = Media2.InterfaceType;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].LastBlock     = Media2.LastBlock;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].BlockSize     = Media2.BlockSize;\r
      } else {\r
        Status = BlockIoPpi->GetBlockDeviceMediaInfo (\r
                               PeiServices,\r
                               BlockIoPpi,\r
                               Index,\r
                               &Media\r
                               );\r
        if (EFI_ERROR (Status) || !Media.MediaPresent) {\r
          continue;\r
        }\r
\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].BlockIo   = BlockIoPpi;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].DevType   = Media.DeviceType;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].LastBlock = Media.LastBlock;\r
        PrivateData->BlockDevice[PrivateData->BlockDeviceCount].BlockSize = (UINT32)Media.BlockSize;\r
      }\r
\r
      PrivateData->BlockDevice[PrivateData->BlockDeviceCount].IoAlign = 0;\r
      //\r
      // Not used here\r
      //\r
      PrivateData->BlockDevice[PrivateData->BlockDeviceCount].Logical          = FALSE;\r
      PrivateData->BlockDevice[PrivateData->BlockDeviceCount].PartitionChecked = FALSE;\r
\r
      PrivateData->BlockDevice[PrivateData->BlockDeviceCount].PhysicalDevNo = (UINT8)Index;\r
      PrivateData->BlockDeviceCount++;\r
    }\r
  }\r
\r
  //\r
  // Find out all logical devices\r
  //\r
  FatFindPartitions (PrivateData);\r
\r
  //\r
  // Build up file system volume array\r
  //\r
  PrivateData->VolumeCount = 0;\r
  for (Index = 0; Index < PrivateData->BlockDeviceCount; Index++) {\r
    Volume.BlockDeviceNo = Index;\r
    Status               = FatGetBpbInfo (PrivateData, &Volume);\r
    if (Status == EFI_SUCCESS) {\r
      //\r
      // Add the detected volume to the volume array\r
      //\r
      CopyMem (\r
        (UINT8 *)&(PrivateData->Volume[PrivateData->VolumeCount]),\r
        (UINT8 *)&Volume,\r
        sizeof (PEI_FAT_VOLUME)\r
        );\r
      PrivateData->VolumeCount += 1;\r
      if (PrivateData->VolumeCount >= PEI_FAT_MAX_VOLUME) {\r
        break;\r
      }\r
    }\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  BlockIo installation notification function. Find out all the current BlockIO\r
  PPIs in the system and add them into private data. Assume there is\r
\r
  @param  PeiServices             General purpose services available to every\r
                                  PEIM.\r
  @param  NotifyDescriptor        The typedef structure of the notification\r
                                  descriptor. Not used in this function.\r
  @param  Ppi                     The typedef structure of the PPI descriptor.\r
                                  Not used in this function.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
BlockIoNotifyEntry (\r
  IN EFI_PEI_SERVICES           **PeiServices,\r
  IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyDescriptor,\r
  IN VOID                       *Ppi\r
  )\r
{\r
  if (CompareGuid (NotifyDescriptor->Guid, &gEfiPeiVirtualBlockIo2PpiGuid)) {\r
    UpdateBlocksAndVolumes (mPrivateData, TRUE);\r
  } else {\r
    UpdateBlocksAndVolumes (mPrivateData, FALSE);\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Installs the Device Recovery Module PPI, Initialize BlockIo Ppi\r
  installation notification\r
\r
  @param  FileHandle              Handle of the file being invoked. Type\r
                                  EFI_PEI_FILE_HANDLE is defined in\r
                                  FfsFindNextFile().\r
  @param  PeiServices             Describes the list of possible PEI Services.\r
\r
  @retval EFI_SUCCESS             The entry point was executed successfully.\r
  @retval EFI_OUT_OF_RESOURCES    There is no enough memory to complete the\r
                                  operations.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FatPeimEntry (\r
  IN EFI_PEI_FILE_HANDLE     FileHandle,\r
  IN CONST EFI_PEI_SERVICES  **PeiServices\r
  )\r
{\r
  EFI_STATUS            Status;\r
  EFI_PHYSICAL_ADDRESS  Address;\r
  PEI_FAT_PRIVATE_DATA  *PrivateData;\r
\r
  Status = PeiServicesRegisterForShadow (FileHandle);\r
  if (!EFI_ERROR (Status)) {\r
    return Status;\r
  }\r
\r
  Status = PeiServicesAllocatePages (\r
             EfiBootServicesCode,\r
             (sizeof (PEI_FAT_PRIVATE_DATA) - 1) / PEI_FAT_MEMORY_PAGE_SIZE + 1,\r
             &Address\r
             );\r
  if (EFI_ERROR (Status)) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  PrivateData = (PEI_FAT_PRIVATE_DATA *)(UINTN)Address;\r
\r
  //\r
  // Initialize Private Data (to zero, as is required by subsequent operations)\r
  //\r
  ZeroMem ((UINT8 *)PrivateData, sizeof (PEI_FAT_PRIVATE_DATA));\r
\r
  PrivateData->Signature = PEI_FAT_PRIVATE_DATA_SIGNATURE;\r
\r
  //\r
  // Installs Ppi\r
  //\r
  PrivateData->DeviceRecoveryPpi.GetNumberRecoveryCapsules = GetNumberRecoveryCapsules;\r
  PrivateData->DeviceRecoveryPpi.GetRecoveryCapsuleInfo    = GetRecoveryCapsuleInfo;\r
  PrivateData->DeviceRecoveryPpi.LoadRecoveryCapsule       = LoadRecoveryCapsule;\r
\r
  PrivateData->PpiDescriptor.Flags = (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST);\r
  PrivateData->PpiDescriptor.Guid  = &gEfiPeiDeviceRecoveryModulePpiGuid;\r
  PrivateData->PpiDescriptor.Ppi   = &PrivateData->DeviceRecoveryPpi;\r
\r
  Status = PeiServicesInstallPpi (&PrivateData->PpiDescriptor);\r
  if (EFI_ERROR (Status)) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // Other initializations\r
  //\r
  PrivateData->BlockDeviceCount = 0;\r
\r
  UpdateBlocksAndVolumes (PrivateData, TRUE);\r
  UpdateBlocksAndVolumes (PrivateData, FALSE);\r
\r
  //\r
  // PrivateData is allocated now, set it to the module variable\r
  //\r
  mPrivateData = PrivateData;\r
\r
  //\r
  // Installs Block Io Ppi notification function\r
  //\r
  PrivateData->NotifyDescriptor[0].Flags =\r
    (\r
     EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK\r
    );\r
  PrivateData->NotifyDescriptor[0].Guid   = &gEfiPeiVirtualBlockIoPpiGuid;\r
  PrivateData->NotifyDescriptor[0].Notify = BlockIoNotifyEntry;\r
  PrivateData->NotifyDescriptor[1].Flags  =\r
    (\r
     EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK |\r
     EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST\r
    );\r
  PrivateData->NotifyDescriptor[1].Guid   = &gEfiPeiVirtualBlockIo2PpiGuid;\r
  PrivateData->NotifyDescriptor[1].Notify = BlockIoNotifyEntry;\r
  return PeiServicesNotifyPpi (&PrivateData->NotifyDescriptor[0]);\r
}\r
\r
/**\r
  Returns the number of DXE capsules residing on the device.\r
\r
  This function searches for DXE capsules from the associated device and returns\r
  the number and maximum size in bytes of the capsules discovered. Entry 1 is\r
  assumed to be the highest load priority and entry N is assumed to be the lowest\r
  priority.\r
\r
  @param[in]  PeiServices              General-purpose services that are available\r
                                       to every PEIM\r
  @param[in]  This                     Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI\r
                                       instance.\r
  @param[out] NumberRecoveryCapsules   Pointer to a caller-allocated UINTN. On\r
                                       output, *NumberRecoveryCapsules contains\r
                                       the number of recovery capsule images\r
                                       available for retrieval from this PEIM\r
                                       instance.\r
\r
  @retval EFI_SUCCESS        One or more capsules were discovered.\r
  @retval EFI_DEVICE_ERROR   A device error occurred.\r
  @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GetNumberRecoveryCapsules (\r
  IN EFI_PEI_SERVICES                    **PeiServices,\r
  IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,\r
  OUT UINTN                              *NumberRecoveryCapsules\r
  )\r
{\r
  EFI_STATUS            Status;\r
  PEI_FAT_PRIVATE_DATA  *PrivateData;\r
  UINTN                 Index;\r
  UINTN                 RecoveryCapsuleCount;\r
  PEI_FILE_HANDLE       Handle;\r
\r
  PrivateData = PEI_FAT_PRIVATE_DATA_FROM_THIS (This);\r
\r
  //\r
  // Search each volume in the root directory for the Recovery capsule\r
  //\r
  RecoveryCapsuleCount = 0;\r
  for (Index = 0; Index < PrivateData->VolumeCount; Index++) {\r
    Status = FindRecoveryFile (PrivateData, Index, (CHAR16 *)PcdGetPtr (PcdRecoveryFileName), &Handle);\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    RecoveryCapsuleCount++;\r
  }\r
\r
  *NumberRecoveryCapsules = RecoveryCapsuleCount;\r
\r
  if (*NumberRecoveryCapsules == 0) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Returns the size and type of the requested recovery capsule.\r
\r
  This function gets the size and type of the capsule specified by CapsuleInstance.\r
\r
  @param[in]  PeiServices       General-purpose services that are available to every PEIM\r
  @param[in]  This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI\r
                                instance.\r
  @param[in]  CapsuleInstance   Specifies for which capsule instance to retrieve\r
                                the information.  This parameter must be between\r
                                one and the value returned by GetNumberRecoveryCapsules()\r
                                in NumberRecoveryCapsules.\r
  @param[out] Size              A pointer to a caller-allocated UINTN in which\r
                                the size of the requested recovery module is\r
                                returned.\r
  @param[out] CapsuleType       A pointer to a caller-allocated EFI_GUID in which\r
                                the type of the requested recovery capsule is\r
                                returned.  The semantic meaning of the value\r
                                returned is defined by the implementation.\r
\r
  @retval EFI_SUCCESS        One or more capsules were discovered.\r
  @retval EFI_DEVICE_ERROR   A device error occurred.\r
  @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GetRecoveryCapsuleInfo (\r
  IN  EFI_PEI_SERVICES                    **PeiServices,\r
  IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,\r
  IN  UINTN                               CapsuleInstance,\r
  OUT UINTN                               *Size,\r
  OUT EFI_GUID                            *CapsuleType\r
  )\r
{\r
  EFI_STATUS            Status;\r
  PEI_FAT_PRIVATE_DATA  *PrivateData;\r
  UINTN                 Index;\r
  UINTN                 BlockDeviceNo;\r
  UINTN                 RecoveryCapsuleCount;\r
  PEI_FILE_HANDLE       Handle;\r
  UINTN                 NumberRecoveryCapsules;\r
\r
  Status = GetNumberRecoveryCapsules (PeiServices, This, &NumberRecoveryCapsules);\r
\r
  if (EFI_ERROR (Status)) {\r
    return Status;\r
  }\r
\r
  if ((CapsuleInstance == 0) || (CapsuleInstance > NumberRecoveryCapsules)) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  PrivateData = PEI_FAT_PRIVATE_DATA_FROM_THIS (This);\r
\r
  //\r
  // Search each volume in the root directory for the Recovery capsule\r
  //\r
  RecoveryCapsuleCount = 0;\r
  for (Index = 0; Index < PrivateData->VolumeCount; Index++) {\r
    Status = FindRecoveryFile (PrivateData, Index, (CHAR16 *)PcdGetPtr (PcdRecoveryFileName), &Handle);\r
\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    if (CapsuleInstance - 1 == RecoveryCapsuleCount) {\r
      //\r
      // Get file size\r
      //\r
      *Size = (UINTN)(((PEI_FAT_FILE *)Handle)->FileSize);\r
\r
      //\r
      // Find corresponding physical block device\r
      //\r
      BlockDeviceNo = PrivateData->Volume[Index].BlockDeviceNo;\r
      while (PrivateData->BlockDevice[BlockDeviceNo].Logical && BlockDeviceNo < PrivateData->BlockDeviceCount) {\r
        BlockDeviceNo = PrivateData->BlockDevice[BlockDeviceNo].ParentDevNo;\r
      }\r
\r
      //\r
      // Fill in the Capsule Type GUID according to the block device type\r
      //\r
      if (BlockDeviceNo < PrivateData->BlockDeviceCount) {\r
        if (PrivateData->BlockDevice[BlockDeviceNo].BlockIo2 != NULL) {\r
          switch (PrivateData->BlockDevice[BlockDeviceNo].InterfaceType) {\r
            case MSG_ATAPI_DP:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatIdeDiskGuid);\r
              break;\r
\r
            case MSG_USB_DP:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatUsbDiskGuid);\r
              break;\r
\r
            case MSG_NVME_NAMESPACE_DP:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatNvmeDiskGuid);\r
              break;\r
\r
            default:\r
              break;\r
          }\r
        }\r
\r
        if (PrivateData->BlockDevice[BlockDeviceNo].BlockIo != NULL) {\r
          switch (PrivateData->BlockDevice[BlockDeviceNo].DevType) {\r
            case LegacyFloppy:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatFloppyDiskGuid);\r
              break;\r
\r
            case IdeCDROM:\r
            case IdeLS120:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatIdeDiskGuid);\r
              break;\r
\r
            case UsbMassStorage:\r
              CopyGuid (CapsuleType, &gRecoveryOnFatUsbDiskGuid);\r
              break;\r
\r
            default:\r
              break;\r
          }\r
        }\r
      }\r
\r
      return EFI_SUCCESS;\r
    }\r
\r
    RecoveryCapsuleCount++;\r
  }\r
\r
  return EFI_NOT_FOUND;\r
}\r
\r
/**\r
  Loads a DXE capsule from some media into memory.\r
\r
  This function, by whatever mechanism, retrieves a DXE capsule from some device\r
  and loads it into memory. Note that the published interface is device neutral.\r
\r
  @param[in]     PeiServices       General-purpose services that are available\r
                                   to every PEIM\r
  @param[in]     This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI\r
                                   instance.\r
  @param[in]     CapsuleInstance   Specifies which capsule instance to retrieve.\r
  @param[out]    Buffer            Specifies a caller-allocated buffer in which\r
                                   the requested recovery capsule will be returned.\r
\r
  @retval EFI_SUCCESS        The capsule was loaded correctly.\r
  @retval EFI_DEVICE_ERROR   A device error occurred.\r
  @retval EFI_NOT_FOUND      A requested recovery DXE capsule cannot be found.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
LoadRecoveryCapsule (\r
  IN EFI_PEI_SERVICES                    **PeiServices,\r
  IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,\r
  IN UINTN                               CapsuleInstance,\r
  OUT VOID                               *Buffer\r
  )\r
{\r
  EFI_STATUS            Status;\r
  PEI_FAT_PRIVATE_DATA  *PrivateData;\r
  UINTN                 Index;\r
  UINTN                 RecoveryCapsuleCount;\r
  PEI_FILE_HANDLE       Handle;\r
  UINTN                 NumberRecoveryCapsules;\r
\r
  Status = GetNumberRecoveryCapsules (PeiServices, This, &NumberRecoveryCapsules);\r
\r
  if (EFI_ERROR (Status)) {\r
    return Status;\r
  }\r
\r
  if ((CapsuleInstance == 0) || (CapsuleInstance > NumberRecoveryCapsules)) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  PrivateData = PEI_FAT_PRIVATE_DATA_FROM_THIS (This);\r
\r
  //\r
  // Search each volume in the root directory for the Recovery capsule\r
  //\r
  RecoveryCapsuleCount = 0;\r
  for (Index = 0; Index < PrivateData->VolumeCount; Index++) {\r
    Status = FindRecoveryFile (PrivateData, Index, (CHAR16 *)PcdGetPtr (PcdRecoveryFileName), &Handle);\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    if (CapsuleInstance - 1 == RecoveryCapsuleCount) {\r
      Status = FatReadFile (\r
                 PrivateData,\r
                 Handle,\r
                 (UINTN)(((PEI_FAT_FILE *)Handle)->FileSize),\r
                 Buffer\r
                 );\r
      return Status;\r
    }\r
\r
    RecoveryCapsuleCount++;\r
  }\r
\r
  return EFI_NOT_FOUND;\r
}\r
\r
/**\r
  Finds the recovery file on a FAT volume.\r
  This function finds the recovery file named FileName on a specified FAT volume and returns\r
  its FileHandle pointer.\r
\r
  @param  PrivateData             Global memory map for accessing global\r
                                  variables.\r
  @param  VolumeIndex             The index of the volume.\r
  @param  FileName                The recovery file name to find.\r
  @param  Handle                  The output file handle.\r
\r
  @retval EFI_DEVICE_ERROR        Some error occurred when operating the FAT\r
                                  volume.\r
  @retval EFI_NOT_FOUND           The recovery file was not found.\r
  @retval EFI_SUCCESS             The recovery file was successfully found on the\r
                                  FAT volume.\r
\r
**/\r
EFI_STATUS\r
FindRecoveryFile (\r
  IN  PEI_FAT_PRIVATE_DATA  *PrivateData,\r
  IN  UINTN                 VolumeIndex,\r
  IN  CHAR16                *FileName,\r
  OUT PEI_FILE_HANDLE       *Handle\r
  )\r
{\r
  EFI_STATUS    Status;\r
  PEI_FAT_FILE  Parent;\r
  PEI_FAT_FILE  *File;\r
\r
  File = &PrivateData->File;\r
\r
  //\r
  // VolumeIndex must be less than PEI_FAT_MAX_VOLUME because PrivateData->VolumeCount\r
  // cannot be larger than PEI_FAT_MAX_VOLUME when detecting recovery volume.\r
  //\r
  ASSERT (VolumeIndex < PEI_FAT_MAX_VOLUME);\r
\r
  //\r
  // Construct root directory file\r
  //\r
  ZeroMem (&Parent, sizeof (PEI_FAT_FILE));\r
  Parent.IsFixedRootDir  = (BOOLEAN)((PrivateData->Volume[VolumeIndex].FatType == Fat32) ? FALSE : TRUE);\r
  Parent.Attributes      = FAT_ATTR_DIRECTORY;\r
  Parent.CurrentPos      = 0;\r
  Parent.CurrentCluster  = Parent.IsFixedRootDir ? 0 : PrivateData->Volume[VolumeIndex].RootDirCluster;\r
  Parent.StartingCluster = Parent.CurrentCluster;\r
  Parent.Volume          = &PrivateData->Volume[VolumeIndex];\r
\r
  Status = FatSetFilePos (PrivateData, &Parent, 0);\r
  if (EFI_ERROR (Status)) {\r
    return EFI_DEVICE_ERROR;\r
  }\r
\r
  //\r
  // Search for recovery capsule in root directory\r
  //\r
  Status = FatReadNextDirectoryEntry (PrivateData, &Parent, File);\r
  while (Status == EFI_SUCCESS) {\r
    //\r
    // Compare whether the file name is recovery file name.\r
    //\r
    if (EngStriColl (PrivateData, FileName, File->FileName)) {\r
      break;\r
    }\r
\r
    Status = FatReadNextDirectoryEntry (PrivateData, &Parent, File);\r
  }\r
\r
  if (EFI_ERROR (Status)) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  //\r
  // Get the recovery file, set its file position to 0.\r
  //\r
  if (File->StartingCluster != 0) {\r
    Status = FatSetFilePos (PrivateData, File, 0);\r
  }\r
\r
  *Handle = File;\r
\r
  return EFI_SUCCESS;\r
}\r