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/DevicePath.h>
  20
  21 /**
  22   Free all the mapping database memory resource and initialize the mapping list entry.
  23
  24   @param  MappingDataBase          Mapping database list entry pointer
  25
  26   @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL
  27   @retval EFI_SUCCESS              Free success
  28
  29 **/
  30 EFI_STATUS
  31 EFIAPI
  32 FreeMappingDatabase (
  33   IN  OUT  LIST_ENTRY            *MappingDataBase
  34   )
  35 ;
  36
  37 /**
  38   Read the NV environment variable(s) that contain the override mappings from Controller Device Path to
  39   a set of Driver Device Paths, and create the mapping database in memory to contain these variable info.
  40
  41   @param  MappingDataBase          Mapping database list entry pointer
  42
  43   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  44   @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable
  45   @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted
  46   @retval EFI_SUCCESS              Create the mapping database in memory successfully
  47
  48 **/
  49 EFI_STATUS
  50 EFIAPI
  51 InitOverridesMapping (
  52   OUT  LIST_ENTRY            *MappingDataBase
  53   )
  54 ;
  55
  56 /**
  57   Save the memory mapping database into NV environment variable(s).
  58   If MappingDataBase list is empty, then delete all platform override NV variables.
  59
  60   @param  MappingDataBase          Mapping database list entry pointer
  61
  62   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
  63   @retval EFI_SUCCESS              Save memory mapping database successfully
  64
  65 **/
  66 EFI_STATUS
  67 EFIAPI
  68 SaveOverridesMapping (
  69   IN  LIST_ENTRY              *MappingDataBase
  70   )
  71 ;
  72
  73 /**
  74   Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
  75
  76   @param  ControllerHandle         The device handle of the controller to check if
  77                                    a driver override exists.
  78   @param  DriverImageHandle        On output, a pointer to the next driver handle.
  79                                    Passing in a pointer to NULL, will return the
  80                                    first driver handle for ControllerHandle.
  81   @param  MappingDataBase          MappingDataBase - Mapping database list entry
  82                                    pointer
  83   @param  CallerImageHandle        The caller driver's image handle, for
  84                                    UpdateFvFileDevicePath use.
  85
  86   @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not
  87                                    a valid handle.  Or DriverImagePath is not a
  88                                    device path that was returned on a previous call
  89                                    to GetDriverPath().
  90   @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not
  91                                    found.
  92   @retval EFI_UNSUPPORTED          The operation is not supported.
  93   @retval EFI_SUCCESS              The driver override for ControllerHandle was
  94                                    returned in DriverImagePath.
  95
  96 **/
  97 EFI_STATUS
  98 EFIAPI
  99 GetDriverFromMapping (
 100   IN     EFI_HANDLE                                     ControllerHandle,
 101   IN OUT EFI_HANDLE                                     *DriverImageHandle,
 102   IN     LIST_ENTRY                                     *MappingDataBase,
 103   IN     EFI_HANDLE                                     CallerImageHandle
 104   )
 105 ;
 106
 107 /**
 108   Check mapping database whether already has the mapping info which
 109   records the input Controller to input DriverImage.
 110
 111   @param  ControllerDevicePath     The controller device path is to be check.
 112   @param  DriverImageDevicePath    The driver image device path is to be check.
 113   @param  MappingDataBase          Mapping database list entry pointer
 114   @param  DriverInfoNum            the controller's total override driver number
 115   @param  DriverImageNO            The driver order number for the input DriverImage.
 116                                    If the DriverImageDevicePath is NULL, DriverImageNO is not set.
 117
 118   @retval EFI_INVALID_PARAMETER    ControllerDevicePath or MappingDataBase is NULL.
 119   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 120                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 121   @retval EFI_SUCCESS              The controller's total override driver number and
 122                                    input DriverImage's order number is correctly return.
 123 **/
 124 EFI_STATUS
 125 EFIAPI
 126 CheckMapping (
 127   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 128   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath  OPTIONAL,
 129   IN     LIST_ENTRY                                     *MappingDataBase,
 130   OUT    UINT32                                         *DriverInfoNum  OPTIONAL,
 131   OUT    UINT32                                         *DriverImageNO  OPTIONAL
 132   )
 133 ;
 134
 135 /**
 136   Insert a driver image as a controller's override driver into the mapping database.
 137   The driver image's order number is indicated by DriverImageNO.
 138
 139   @param  ControllerDevicePath     The controller device path need to add a
 140                                    override driver image item
 141   @param  DriverImageDevicePath    The driver image device path need to be insert
 142   @param  MappingDataBase          Mapping database list entry pointer
 143   @param  DriverImageNO            The inserted order number. If this number is taken,
 144                                    the larger available number will be used.
 145
 146   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or DriverImageDevicePath is NULL
 147                                    or MappingDataBase is NULL
 148   @retval EFI_ALREADY_STARTED      The input Controller to input DriverImage has been
 149                                    recorded into the mapping database.
 150   @retval EFI_SUCCESS              The Controller and DriverImage are inserted into
 151                                    the mapping database successfully.
 152
 153 **/
 154 EFI_STATUS
 155 EFIAPI
 156 InsertDriverImage (
 157   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 158   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 159   IN     LIST_ENTRY                                     *MappingDataBase,
 160   IN     UINT32                                         DriverImageNO
 161   )
 162 ;
 163
 164 /**
 165   Delete a controller's override driver from the mapping database.
 166
 167   @param  ControllerDevicePath     The controller device path will be deleted
 168                                    when all drivers images on it are removed.
 169   @param  DriverImageDevicePath    The driver image device path will be delete.
 170                                    If NULL, all driver image will be delete.
 171   @param  MappingDataBase          Mapping database list entry pointer
 172
 173   @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or MappingDataBase is NULL
 174   @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or
 175                                    DriverImageDevicePath is not found in the found DriverImage Info list.
 176   @retval EFI_SUCCESS              Delete the specified driver successfully.
 177
 178 **/
 179 EFI_STATUS
 180 EFIAPI
 181 DeleteDriverImage (
 182   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 183   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 184   IN     LIST_ENTRY                                     *MappingDataBase
 185   )
 186 ;
 187
 188 #endif