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 <Protocol/PlatformDriverOverride.h>
  20 #include <Protocol/DevicePath.h>
  21 #include <Protocol/DriverBinding.h>
  22 #include <Library/BaseLib.h>
  23
  24 #include <VariableFormat.h>
  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 EFI_SUCCESS              The protocol is installed successfully.
  36
  37 **/
  38 EFI_STATUS
  39 EFIAPI
  40 InstallPlatformDriverOverrideProtocol (
  41   EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride
  42   );
  43
  44 /**
  45   Free all the mapping database memory resource and initialize the mapping list entry.
  46
  47   @param  MappingDataBase          Mapping database list entry pointer
  48
  49   @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL
  50   @retval EFI_SUCCESS              Free success
  51
  52 **/
  53 EFI_STATUS
  54 EFIAPI
  55 FreeMappingDatabase (
  56   IN  OUT  LIST_ENTRY            *MappingDataBase
  57   );
  58
  59 /**
  60   Read the environment variable(s) that contain the override mappings from Controller Device Path to
  61   a set of Driver Device Paths, and create the mapping database in memory with those variable info.
  62
  63   @param  MappingDataBase          Mapping database list entry pointer
  64
  65   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  66   @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable
  67   @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted
  68   @retval EFI_SUCCESS              Create the mapping database in memory successfully
  69
  70 **/
  71 EFI_STATUS
  72 EFIAPI
  73 InitOverridesMapping (
  74   OUT  LIST_ENTRY            *MappingDataBase
  75   );
  76
  77 /**
  78   Save the memory mapping database into NV environment variable(s).
  79
  80   @param  MappingDataBase          Mapping database list entry pointer
  81
  82   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  83   @retval EFI_SUCCESS              Save memory mapping database successfully
  84
  85 **/
  86 EFI_STATUS
  87 EFIAPI
  88 SaveOverridesMapping (
  89   IN  LIST_ENTRY              *MappingDataBase
  90   );
  91
  92 /**
  93   Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
  94
  95   @param  This                     A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
  96   @param  ControllerHandle         The device handle of the controller to check if
  97                                    a driver override exists.
  98   @param  DriverImageHandle        On output, a pointer to the next driver handle.
  99                                    Passing in a pointer to NULL, will return the
 100                                    first driver handle for ControllerHandle.
 101   @param  MappingDataBase          MappingDataBase - Mapping database list entry
 102                                    pointer
 103   @param  CallerImageHandle        The caller driver's image handle, for
 104                                    UpdateFvFileDevicePath use.
 105
 106   @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not
 107                                    a valid handle.  Or DriverImagePath is not a
 108                                    device path that was returned on a previous call
 109                                    to GetDriverPath().
 110   @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not
 111                                    found.
 112   @retval EFI_UNSUPPORTED          The operation is not supported.
 113   @retval EFI_SUCCESS              The driver override for ControllerHandle was
 114                                    returned in DriverImagePath.
 115
 116 **/
 117 EFI_STATUS
 118 EFIAPI
 119 GetDriverFromMapping (
 120   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              * This,
 121   IN     EFI_HANDLE                                     ControllerHandle,
 122   IN OUT EFI_HANDLE                                     * DriverImageHandle,
 123   IN     LIST_ENTRY                                     * MappingDataBase,
 124   IN     EFI_HANDLE                                     CallerImageHandle
 125   );
 126
 127 /**
 128   Deletes all environment variable(s) that contain the override mappings from Controller Device Path to
 129   a set of Driver Device Paths.
 130
 131   @retval EFI_SUCCESS  Delete all variable(s) successfully.
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 DeleteOverridesVariables (
 136   VOID
 137   );
 138
 139 /**
 140   Check mapping database whether already has the  mapping info which
 141   records the input Controller to input DriverImage.
 142
 143   @param  ControllerDevicePath     The controller device path is to be check.
 144   @param  DriverImageDevicePath    The driver image device path is to be check.
 145   @param  MappingDataBase          Mapping database list entry pointer
 146   @param  DriverInfoNum            the controller's total override driver number
 147   @param  DriverImageNO            The driver order number for the input DriverImage.
 148                                    If the DriverImageDevicePath is NULL, DriverImageNO is not set.
 149
 150   @retval EFI_INVALID_PARAMETER    ControllerDevicePath or MappingDataBase is NULL.
 151   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 152                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 153   @retval EFI_SUCCESS              The controller's total override driver number and
 154                                    input DriverImage's order number is correctly return.
 155 **/
 156 EFI_STATUS
 157 EFIAPI
 158 CheckMapping (
 159   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 160   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 161   IN     LIST_ENTRY                                     * MappingDataBase,
 162   OUT    UINT32                                         *DriverInfoNum,
 163   OUT    UINT32                                         *DriverImageNO
 164   );
 165
 166 /**
 167   Insert a driver image as a controller's override driver into the mapping database.
 168   The driver image's order number is indicated by DriverImageNO.
 169
 170   @param  ControllerDevicePath     The controller device path need to add a
 171                                    override driver image item
 172   @param  DriverImageDevicePath    The driver image device path need to be insert
 173   @param  MappingDataBase          Mapping database list entry pointer
 174   @param  DriverImageNO            The inserted order number. If this number is taken,
 175                                    the larger available number will be used.
 176
 177   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or DriverImageDevicePath is NULL
 178                                    or MappingDataBase is NULL
 179   @retval EFI_ALREADY_STARTED      The input Controller to input DriverImage has been
 180                                    recorded into the mapping database.
 181   @retval EFI_SUCCESS              The Controller and DriverImage are inserted into
 182                                    the mapping database successfully.
 183
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 InsertDriverImage (
 188   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 189   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 190   IN     LIST_ENTRY                                     *MappingDataBase,
 191   IN     UINT32                                         DriverImageNO
 192   );
 193
 194 /**
 195   Delete a controller's override driver from the mapping database.
 196
 197   @param  ControllerDevicePath     The controller device path will be deleted
 198                                    when all drivers images on it are removed.
 199   @param  DriverImageDevicePath    The driver image device path will be delete.
 200                                    If NULL, all driver image will be delete.
 201   @param  MappingDataBase          Mapping database list entry pointer
 202
 203   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or MappingDataBase is NULL
 204   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 205                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 206   @retval EFI_SUCCESS              Delete the specified driver successfully.
 207
 208 **/
 209 EFI_STATUS
 210 EFIAPI
 211 DeleteDriverImage (
 212   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 213   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 214   IN     LIST_ENTRY                                     *MappingDataBase
 215   );
 216
 217 /**
 218   Get the first Binding protocol which has the specific image handle
 219
 220   @param  ImageHandle          The Image handle
 221   @param  BindingHandle        The BindingHandle of the found Driver Binding protocol.
 222                                If Binding protocol is not found, it is set to NULL.
 223
 224   @return                      Pointer into the Binding Protocol interface
 225   @retval NULL                 The paramter is not valid or the binding protocol is not found.
 226
 227 **/
 228 EFI_DRIVER_BINDING_PROTOCOL *
 229 EFIAPI
 230 GetBindingProtocolFromImageHandle (
 231   IN  EFI_HANDLE   ImageHandle,
 232   OUT EFI_HANDLE   *BindingHandle
 233   );
 234
 235 #endif