Sync in bug fix from EDK I:

[mirror_edk2.git] / MdeModulePkg / Include / Library / PlatDriOverLib.h

/** @file\r
\r
  This library provides basic platform driver override functions.\r
\r
Copyright (c) 2007 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _PLAT_DRI_OVER_LIB_H_\r
#define _PLAT_DRI_OVER_LIB_H_\r
\r
#include <Protocol/PlatformDriverOverride.h>\r
#include <Protocol/DevicePath.h>\r
#include <Protocol/DriverBinding.h>\r
#include <Library/BaseLib.h>\r
\r
#include <VariableFormat.h>\r
\r
/**\r
  Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol\r
  in the system.\r
\r
  @param  gPlatformDriverOverride  PlatformDriverOverride protocol interface which\r
                                   needs to be installed\r
\r
  @retval EFI_ALREADY_STARTED      There has been a Platform Driver Override\r
                                   Protocol in the system, cannot install it again.\r
  @retval EFI_SUCCESS              The protocol is installed successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InstallPlatformDriverOverrideProtocol (\r
  EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride\r
  );\r
\r
/**\r
  Free all the mapping database memory resource and initialize the mapping list entry.\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL\r
  @retval EFI_SUCCESS              Free success\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FreeMappingDatabase (\r
  IN  OUT  LIST_ENTRY            *MappingDataBase\r
  );\r
\r
/**\r
  Read the environment variable(s) that contain the override mappings from Controller Device Path to\r
  a set of Driver Device Paths, and create the mapping database in memory with those variable info.\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null\r
  @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable\r
  @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted\r
  @retval EFI_SUCCESS              Create the mapping database in memory successfully\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitOverridesMapping (\r
  OUT  LIST_ENTRY            *MappingDataBase\r
  );\r
\r
/**\r
  Save the memory mapping database into NV environment variable(s).\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null\r
  @retval EFI_SUCCESS              Save memory mapping database successfully\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SaveOverridesMapping (\r
  IN  LIST_ENTRY              *MappingDataBase\r
  );\r
\r
/**\r
  Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.\r
\r
  @param  This                     A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.\r
  @param  ControllerHandle         The device handle of the controller to check if\r
                                   a driver override exists.\r
  @param  DriverImageHandle        On output, a pointer to the next driver handle.\r
                                   Passing in a pointer to NULL, will return the\r
                                   first driver handle for ControllerHandle.\r
  @param  MappingDataBase          MappingDataBase - Mapping database list entry\r
                                   pointer\r
  @param  CallerImageHandle        The caller driver's image handle, for\r
                                   UpdateFvFileDevicePath use.\r
\r
  @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not\r
                                   a valid handle.  Or DriverImagePath is not a\r
                                   device path that was returned on a previous call\r
                                   to GetDriverPath().\r
  @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not\r
                                   found.\r
  @retval EFI_UNSUPPORTED          The operation is not supported.\r
  @retval EFI_SUCCESS              The driver override for ControllerHandle was\r
                                   returned in DriverImagePath.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GetDriverFromMapping (\r
  IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              * This,\r
  IN     EFI_HANDLE                                     ControllerHandle,\r
  IN OUT EFI_HANDLE                                     * DriverImageHandle,\r
  IN     LIST_ENTRY                                     * MappingDataBase,\r
  IN     EFI_HANDLE                                     CallerImageHandle\r
  );\r
\r
/**\r
  Deletes all environment variable(s) that contain the override mappings from Controller Device Path to\r
  a set of Driver Device Paths.\r
\r
  @retval EFI_SUCCESS  Delete all variable(s) successfully.\r
**/\r
EFI_STATUS\r
EFIAPI\r
DeleteOverridesVariables (\r
  VOID\r
  );\r
\r
/**\r
  Check mapping database whether already has the  mapping info which\r
  records the input Controller to input DriverImage.\r
\r
  @param  ControllerDevicePath     The controller device path is to be check.\r
  @param  DriverImageDevicePath    The driver image device path is to be check.\r
  @param  MappingDataBase          Mapping database list entry pointer\r
  @param  DriverInfoNum            the controller's total override driver number\r
  @param  DriverImageNO            The driver order number for the input DriverImage.\r
                                   If the DriverImageDevicePath is NULL, DriverImageNO is not set.\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath or MappingDataBase is NULL.\r
  @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or\r
                                   DriverImageDevicePath is not found in the found DriverImage Info list. \r
  @retval EFI_SUCCESS              The controller's total override driver number and \r
                                   input DriverImage's order number is correctly return.\r
**/\r
EFI_STATUS\r
EFIAPI\r
CheckMapping (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,\r
  IN     LIST_ENTRY                                     * MappingDataBase,\r
  OUT    UINT32                                         *DriverInfoNum,\r
  OUT    UINT32                                         *DriverImageNO\r
  );\r
\r
/**\r
  Insert a driver image as a controller's override driver into the mapping database.\r
  The driver image's order number is indicated by DriverImageNO.\r
\r
  @param  ControllerDevicePath     The controller device path need to add a\r
                                   override driver image item\r
  @param  DriverImageDevicePath    The driver image device path need to be insert\r
  @param  MappingDataBase          Mapping database list entry pointer\r
  @param  DriverImageNO            The inserted order number. If this number is taken, \r
                                   the larger available number will be used.\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or DriverImageDevicePath is NULL\r
                                   or MappingDataBase is NULL\r
  @retval EFI_ALREADY_STARTED      The input Controller to input DriverImage has been \r
                                   recorded into the mapping database.\r
  @retval EFI_SUCCESS              The Controller and DriverImage are inserted into \r
                                   the mapping database successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InsertDriverImage (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,\r
  IN     LIST_ENTRY                                     *MappingDataBase,\r
  IN     UINT32                                         DriverImageNO\r
  );\r
\r
/**\r
  Delete a controller's override driver from the mapping database.\r
\r
  @param  ControllerDevicePath     The controller device path will be deleted \r
                                   when all drivers images on it are removed.\r
  @param  DriverImageDevicePath    The driver image device path will be delete.\r
                                   If NULL, all driver image will be delete.\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or MappingDataBase is NULL\r
  @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or\r
                                   DriverImageDevicePath is not found in the found DriverImage Info list. \r
  @retval EFI_SUCCESS              Delete the specified driver successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
DeleteDriverImage (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,\r
  IN     LIST_ENTRY                                     *MappingDataBase\r
  );\r
\r
/**\r
  Get the first Binding protocol which has the specific image handle\r
\r
  @param  ImageHandle          The Image handle\r
  @param  BindingHandle        The BindingHandle of the found Driver Binding protocol.\r
                               If Binding protocol is not found, it is set to NULL. \r
\r
  @return                      Pointer into the Binding Protocol interface\r
  @retval NULL                 The paramter is not valid or the binding protocol is not found.\r
\r
**/\r
EFI_DRIVER_BINDING_PROTOCOL *\r
EFIAPI\r
GetBindingProtocolFromImageHandle (\r
  IN  EFI_HANDLE   ImageHandle,\r
  OUT EFI_HANDLE   *BindingHandle\r
  );\r
\r
#endif\r