MdeModulePkg/Include/Library/PlatDriOverLib.h

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