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 <Library/BaseLib.h>
  28
  29 #include <VariableFormat.h>
  30
  31 /**
  32   Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol
  33   in the system.
  34
  35   @param  gPlatformDriverOverride  PlatformDriverOverride protocol interface which
  36                                    needs to be installed
  37
  38   @retval EFI_ALREADY_STARTED      There has been a Platform Driver Override
  39                                    Protocol in the system, cannot install it again.
  40   @retval Other                    Returned by InstallProtocolInterface
  41
  42 **/
  43 EFI_STATUS
  44 EFIAPI
  45 InstallPlatformDriverOverrideProtocol (
  46   EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride
  47   );
  48
  49 /**
  50   Free all the mapping database memory resource and initialize the mapping list entry
  51
  52   @param  MappingDataBase          Mapping database list entry pointer
  53
  54   @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL
  55   @retval EFI_SUCCESS              Free success
  56
  57 **/
  58 EFI_STATUS
  59 EFIAPI
  60 FreeMappingDatabase (
  61   IN  OUT  LIST_ENTRY            *MappingDataBase
  62   );
  63
  64 /**
  65   Read the environment variable(s) that contain the override mappings from Controller Device Path to
  66   a set of Driver Device Paths, and create the mapping database in memory with those variable info.
  67   VariableLayout{
  68   //
  69   // NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load.
  70   // Each variable has MaximumVariableSize limitation, so  we maybe need multi variables to store
  71   // large mapping infos.
  72   // The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, ....
  73   //
  74   UINT32                         NotEnd;
  75   //
  76   // The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths
  77   // There are often multi mapping entries in a variable.
  78   //
  79   UINT32                         SIGNATURE;            //EFI_SIGNATURE_32('p','d','o','i')
  80   UINT32                         DriverNum;
  81   EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];
  82   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  83   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  84   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  85   ......
  86   UINT32                         SIGNATURE;
  87   UINT32                         DriverNum;
  88   EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];
  89   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  90   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  91   EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];
  92   ......
  93   }
  94   typedef struct _PLATFORM_OVERRIDE_ITEM{
  95   UINTN                          Signature;                  //EFI_SIGNATURE_32('p','d','o','i')
  96   LIST_ENTRY                     Link;
  97   UINT32                         DriverInfoNum;
  98   EFI_DEVICE_PATH_PROTOCOL       *ControllerDevicePath;
  99   LIST_ENTRY                     DriverInfoList;         //DRIVER_IMAGE_INFO List
 100   } PLATFORM_OVERRIDE_ITEM;
 101   typedef struct _DRIVER_IMAGE_INFO{
 102   UINTN                          Signature;                  //EFI_SIGNATURE_32('p','d','i','i')
 103   LIST_ENTRY                     Link;
 104   EFI_HANDLE                     ImageHandle;
 105   EFI_DEVICE_PATH_PROTOCOL       *DriverImagePath;
 106   BOOLEAN                        UnLoadable;
 107   BOOLEAN                        UnStartable;
 108   } DRIVER_IMAGE_INFO;
 109
 110   @param  MappingDataBase          Mapping database list entry pointer
 111
 112   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
 113   @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable
 114   @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted
 115   @retval EFI_SUCCESS              Create the mapping database in memory
 116                                    successfully
 117
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 InitOverridesMapping (
 122   OUT  LIST_ENTRY            *MappingDataBase
 123   );
 124
 125 /**
 126   Save the memory mapping database into NV environment variable(s)
 127
 128   @param  MappingDataBase          Mapping database list entry pointer
 129
 130   @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null
 131   @retval EFI_SUCCESS              Save memory mapping database successfully
 132
 133 **/
 134 EFI_STATUS
 135 EFIAPI
 136 SaveOverridesMapping (
 137   IN  LIST_ENTRY              *MappingDataBase
 138   );
 139
 140 /**
 141   Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
 142
 143   @param  This                     A pointer to the
 144                                    EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
 145   @param  ControllerHandle         The device handle of the controller to check if
 146                                    a driver override exists.
 147   @param  DriverImageHandle        On output, a pointer to the next driver handle.
 148                                    Passing in a pointer to NULL, will return the
 149                                    first driver handle for ControllerHandle.
 150   @param  MappingDataBase          MappingDataBase - Mapping database list entry
 151                                    pointer
 152   @param  CallerImageHandle        The caller driver's image handle, for
 153                                    UpdateFvFileDevicePath use.
 154
 155   @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not
 156                                    a valid handle.  Or DriverImagePath is not a
 157                                    device path that was returned on a previous call
 158                                    to GetDriverPath().
 159   @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not
 160                                    found.
 161   @retval EFI_UNSUPPORTED          The operation is not supported.
 162   @retval EFI_SUCCESS              The driver override for ControllerHandle was
 163                                    returned in DriverImagePath.
 164
 165 **/
 166 EFI_STATUS
 167 EFIAPI
 168 GetDriverFromMapping (
 169   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              * This,
 170   IN     EFI_HANDLE                                     ControllerHandle,
 171   IN OUT EFI_HANDLE                                     * DriverImageHandle,
 172   IN     LIST_ENTRY                                     * MappingDataBase,
 173   IN     EFI_HANDLE                                     CallerImageHandle
 174   );
 175
 176 EFI_STATUS
 177 EFIAPI
 178 DeleteOverridesVariables (
 179   VOID
 180   );
 181
 182 /**
 183   Check mapping database whether already has the  mapping info which
 184   records the input Controller to input DriverImage.
 185   If has, the controller's total override driver number and input DriverImage's order number is return.
 186
 187   @param  ControllerDevicePath     The controller device path need to add a
 188                                    override driver image item
 189   @param  DriverImageDevicePath    The driver image device path need to be insert
 190   @param  MappingDataBase          Mapping database list entry pointer
 191   @param  DriverInfoNum            the controller's total override driver number
 192   @param  DriverImageNO            The inserted order number
 193
 194   @return EFI_INVALID_PARAMETER
 195   @return EFI_NOT_FOUND
 196   @return EFI_SUCCESS
 197
 198 **/
 199 EFI_STATUS
 200 EFIAPI
 201 CheckMapping (
 202   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 203   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 204   IN     LIST_ENTRY                                     * MappingDataBase,
 205   OUT    UINT32                                         *DriverInfoNum,
 206   OUT    UINT32                                         *DriverImageNO
 207   );
 208
 209 /**
 210   Insert a driver image as a controller's override driver into the mapping database.
 211   The driver image's order number is indicated by DriverImageNO.
 212
 213   @param  ControllerDevicePath     The controller device path need to add a
 214                                    override driver image item
 215   @param  DriverImageDevicePath    The driver image device path need to be insert
 216   @param  MappingDataBase          Mapping database list entry pointer
 217   @param  DriverImageNO            The inserted order number
 218
 219   @return EFI_INVALID_PARAMETER
 220   @return EFI_ALREADY_STARTED
 221   @return EFI_SUCCESS
 222
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 InsertDriverImage (
 227   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 228   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 229   IN     LIST_ENTRY                                     *MappingDataBase,
 230   IN     UINT32                                         DriverImageNO
 231   );
 232
 233 /**
 234   Delete a controller's override driver from the mapping database.
 235
 236   @param  ControllerDevicePath     The controller device path need to add a
 237                                    override driver image item
 238   @param  DriverImageDevicePath    The driver image device path need to be insert
 239   @param  MappingDataBase          Mapping database list entry pointer
 240   @param  DriverImageNO            The inserted order number
 241
 242   @return EFI_INVALID_PARAMETER
 243   @return EFI_NOT_FOUND
 244   @return EFI_SUCCESS
 245
 246 **/
 247 EFI_STATUS
 248 EFIAPI
 249 DeleteDriverImage (
 250   IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,
 251   IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,
 252   IN     LIST_ENTRY                                     *MappingDataBase
 253   );
 254
 255 #endif