MdeModulePkg/Include/Library/PlatDriOverLib.h

   1 /** @file
   2
   3   This library provides basic platform driver override functions.
   4
   5 Copyright (c) 2007 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _PLAT_DRI_OVER_LIB_H_
  17 #define _PLAT_DRI_OVER_LIB_H_
  18
  19 #include <PiDxe.h>
  20 #include <Protocol/PlatformDriverOverride.h>
  21 #include <Protocol/DevicePath.h>
  22 #include <Protocol/DriverBinding.h>
  23 #include <Library/BaseLib.h>
  24
  25 #include <VariableFormat.h>
  26
  27 /**
  28   Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol
  29   in the system.
  30
  31   @param  gPlatformDriverOverride  PlatformDriverOverride protocol interface which
  32                                    needs to be installed
  33
  34   @retval EFI_ALREADY_STARTED      There has been a Platform Driver Override
  35                                    Protocol in the system, cannot install it again.
  36   @retval EFI_SUCCESS              The protocol is installed successfully.
  37
  38 **/
  39 EFI_STATUS
  40 EFIAPI
  41 InstallPlatformDriverOverrideProtocol (
  42   EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride
  43   );
  44
  45 /**
  46   Free all the mapping database memory resource and initialize the mapping list entry.
  47
  48   @param  MappingDataBase          Mapping database list entry pointer
  49
  50   @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL
  51   @retval EFI_SUCCESS              Free success
  52
  53 **/
  54 EFI_STATUS
  55 EFIAPI
  56 FreeMappingDatabase (
  57   IN  OUT  LIST_ENTRY            *MappingDataBase
  58   );
  59
  60 /**
  61   Read the environment variable(s) that contain the override mappings from Controller Device Path to
  62   a set of Driver Device Paths, and create the mapping database in memory with those variable info.
  63
  64   @param  MappingDataBase          Mapping database list entry pointer
  65
  66   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  67   @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable
  68   @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted
  69   @retval EFI_SUCCESS              Create the mapping database in memory successfully
  70
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 InitOverridesMapping (
  75   OUT  LIST_ENTRY            *MappingDataBase
  76   );
  77
  78 /**
  79   Save the memory mapping database into NV environment variable(s).
  80
  81   @param  MappingDataBase          Mapping database list entry pointer
  82
  83   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  84   @retval EFI_SUCCESS              Save memory mapping database successfully
  85
  86 **/
  87 EFI_STATUS
  88 EFIAPI
  89 SaveOverridesMapping (
  90   IN  LIST_ENTRY              *MappingDataBase
  91   );
  92
  93 /**
  94   Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
  95
  96   @param  This                     A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
  97   @param  ControllerHandle         The device handle of the controller to check if
  98                                    a driver override exists.
  99   @param  DriverImageHandle        On output, a pointer to the next driver handle.
 100                                    Passing in a pointer to NULL, will return the
 101                                    first driver handle for ControllerHandle.
 102   @param  MappingDataBase          MappingDataBase - Mapping database list entry
 103                                    pointer
 104   @param  CallerImageHandle        The caller driver's image handle, for
 105                                    UpdateFvFileDevicePath use.
 106
 107   @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not
 108                                    a valid handle.  Or DriverImagePath is not a
 109                                    device path that was returned on a previous call
 110                                    to GetDriverPath().
 111   @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not
 112                                    found.
 113   @retval EFI_UNSUPPORTED          The operation is not supported.
 114   @retval EFI_SUCCESS              The driver override for ControllerHandle was
 115                                    returned in DriverImagePath.
 116
 117 **/
 118 EFI_STATUS
 119 EFIAPI
 120 GetDriverFromMapping (
 121   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              * This,
 122   IN     EFI_HANDLE                                     ControllerHandle,
 123   IN OUT EFI_HANDLE                                     * DriverImageHandle,
 124   IN     LIST_ENTRY                                     * MappingDataBase,
 125   IN     EFI_HANDLE                                     CallerImageHandle
 126   );
 127
 128 /**
 129   Deletes all environment variable(s) that contain the override mappings from Controller Device Path to
 130   a set of Driver Device Paths.
 131
 132   @retval EFI_SUCCESS  Delete all variable(s) successfully.
 133 **/
 134 EFI_STATUS
 135 EFIAPI
 136 DeleteOverridesVariables (
 137   VOID
 138   );
 139
 140 /**
 141   Check mapping database whether already has the  mapping info which
 142   records the input Controller to input DriverImage.
 143
 144   @param  ControllerDevicePath     The controller device path is to be check.
 145   @param  DriverImageDevicePath    The driver image device path is to be check.
 146   @param  MappingDataBase          Mapping database list entry pointer
 147   @param  DriverInfoNum            the controller's total override driver number
 148   @param  DriverImageNO            The driver order number for the input DriverImage.
 149                                    If the DriverImageDevicePath is NULL, DriverImageNO is not set.
 150
 151   @retval EFI_INVALID_PARAMETER    ControllerDevicePath or MappingDataBase is NULL.
 152   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 153                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 154   @retval EFI_SUCCESS              The controller's total override driver number and
 155                                    input DriverImage's order number is correctly return.
 156 **/
 157 EFI_STATUS
 158 EFIAPI
 159 CheckMapping (
 160   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 161   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 162   IN     LIST_ENTRY                                     * MappingDataBase,
 163   OUT    UINT32                                         *DriverInfoNum,
 164   OUT    UINT32                                         *DriverImageNO
 165   );
 166
 167 /**
 168   Insert a driver image as a controller's override driver into the mapping database.
 169   The driver image's order number is indicated by DriverImageNO.
 170
 171   @param  ControllerDevicePath     The controller device path need to add a
 172                                    override driver image item
 173   @param  DriverImageDevicePath    The driver image device path need to be insert
 174   @param  MappingDataBase          Mapping database list entry pointer
 175   @param  DriverImageNO            The inserted order number. If this number is taken,
 176                                    the larger available number will be used.
 177
 178   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or DriverImageDevicePath is NULL
 179                                    or MappingDataBase is NULL
 180   @retval EFI_ALREADY_STARTED      The input Controller to input DriverImage has been
 181                                    recorded into the mapping database.
 182   @retval EFI_SUCCESS              The Controller and DriverImage are inserted into
 183                                    the mapping database successfully.
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 InsertDriverImage (
 189   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 190   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 191   IN     LIST_ENTRY                                     *MappingDataBase,
 192   IN     UINT32                                         DriverImageNO
 193   );
 194
 195 /**
 196   Delete a controller's override driver from the mapping database.
 197
 198   @param  ControllerDevicePath     The controller device path will be deleted
 199                                    when all drivers images on it are removed.
 200   @param  DriverImageDevicePath    The driver image device path will be delete.
 201                                    If NULL, all driver image will be delete.
 202   @param  MappingDataBase          Mapping database list entry pointer
 203
 204   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or MappingDataBase is NULL
 205   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 206                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 207   @retval EFI_SUCCESS              Delete the specified driver successfully.
 208
 209 **/
 210 EFI_STATUS
 211 EFIAPI
 212 DeleteDriverImage (
 213   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 214   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 215   IN     LIST_ENTRY                                     *MappingDataBase
 216   );
 217
 218 /**
 219   Get the first Binding protocol which has the specific image handle
 220
 221   @param  ImageHandle          The Image handle
 222   @param  BindingHandle        The BindingHandle of the found Driver Binding protocol.
 223                                If Binding protocol is not found, it is set to NULL.
 224
 225   @return                      Pointer into the Binding Protocol interface
 226   @retval NULL                 The paramter is not valid or the binding protocol is not found.
 227
 228 **/
 229 EFI_DRIVER_BINDING_PROTOCOL *
 230 EFIAPI
 231 GetBindingProtocolFromImageHandle (
 232   IN  EFI_HANDLE   ImageHandle,
 233   OUT EFI_HANDLE   *BindingHandle
 234   );
 235
 236 #endif