MdePkg/Include/Protocol/PlatformDriverOverride.h

   1 /** @file
   2   Platform Driver Override protocol as defined in the UEFI 2.1 specification.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
  10 #define __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
  11
  12 ///
  13 /// Global ID for the Platform Driver Override Protocol
  14 ///
  15 #define EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_GUID \
  16   { \
  17     0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  18   }
  19
  20 typedef struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL;
  21
  22 //
  23 // Prototypes for the Platform Driver Override Protocol
  24 //
  25
  26 /**
  27   Retrieves the image handle of the platform override driver for a controller in the system.
  28
  29   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  30                                 PROTOCOL instance.
  31   @param  ControllerHandle      The device handle of the controller to check if a driver override
  32                                 exists.
  33   @param  DriverImageHandle     On input, a pointer to the previous driver image handle returned
  34                                 by GetDriver(). On output, a pointer to the next driver
  35                                 image handle.
  36
  37   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
  38                                 DriverImageHandle.
  39   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
  40   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.
  41   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a handle that was returned on a
  42                                 previous call to GetDriver().
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER)(
  48   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
  49   IN     EFI_HANDLE                                     ControllerHandle,
  50   IN OUT EFI_HANDLE                                     *DriverImageHandle
  51   );
  52
  53 /**
  54   Retrieves the device path of the platform override driver for a controller in the system.
  55
  56   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
  57   @param  ControllerHandle      The device handle of the controller to check if a driver override
  58                                 exists.
  59   @param  DriverImagePath       On input, a pointer to the previous driver device path returned by
  60                                 GetDriverPath(). On output, a pointer to the next driver
  61                                 device path. Passing in a pointer to NULL will return the first
  62                                 driver device path for ControllerHandle.
  63
  64   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
  65                                 DriverImageHandle.
  66   @retval EFI_UNSUPPORTED       The operation is not supported.
  67   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
  68   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.
  69   @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a
  70                                 previous call to GetDriverPath().
  71
  72 **/
  73 typedef
  74 EFI_STATUS
  75 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH)(
  76   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
  77   IN     EFI_HANDLE                                     ControllerHandle,
  78   IN OUT EFI_DEVICE_PATH_PROTOCOL                       **DriverImagePath
  79   );
  80
  81 /**
  82   Used to associate a driver image handle with a device path that was returned on a prior call to the
  83   GetDriverPath() service. This driver image handle will then be available through the
  84   GetDriver() service.
  85
  86   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  87                                 PROTOCOL instance.
  88   @param  ControllerHandle      The device handle of the controller.
  89   @param  DriverImagePath       A pointer to the driver device path that was returned in a prior
  90                                 call to GetDriverPath().
  91   @param  DriverImageHandle     The driver image handle that was returned by LoadImage()
  92                                 when the driver specified by DriverImagePath was loaded
  93                                 into memory.
  94
  95   @retval EFI_SUCCESS           The association between DriverImagePath and
  96                                 DriverImageHandle was established for the controller specified
  97                                 by ControllerHandle.
  98   @retval EFI_UNSUPPORTED       The operation is not supported.
  99   @retval EFI_NOT_FOUND         DriverImagePath is not a device path that was returned on a prior
 100                                 call to GetDriverPath() for the controller specified by
 101                                 ControllerHandle.
 102   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 103   @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path.
 104   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle.
 105
 106 **/
 107 typedef
 108 EFI_STATUS
 109 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED)(
 110   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL          *This,
 111   IN EFI_HANDLE                                     ControllerHandle,
 112   IN EFI_DEVICE_PATH_PROTOCOL                       *DriverImagePath,
 113   IN EFI_HANDLE                                     DriverImageHandle
 114   );
 115
 116 ///
 117 /// This protocol matches one or more drivers to a controller. A platform driver
 118 /// produces this protocol, and it is installed on a separate handle. This protocol
 119 /// is used by the ConnectController() boot service to select the best driver
 120 /// for a controller. All of the drivers returned by this protocol have a higher
 121 /// precedence than drivers found from an EFI Bus Specific Driver Override Protocol
 122 /// or drivers found from the general UEFI driver Binding search algorithm. If more
 123 /// than one driver is returned by this protocol, then the drivers are returned in
 124 /// order from highest precedence to lowest precedence.
 125 ///
 126 struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL {
 127   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER         GetDriver;
 128   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH    GetDriverPath;
 129   EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED      DriverLoaded;
 130 };
 131
 132 extern EFI_GUID  gEfiPlatformDriverOverrideProtocolGuid;
 133
 134 #endif