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 - 2008, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
  16 #define __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
  17
  18 //
  19 // Global ID for the Platform Driver Override Protocol
  20 //
  21 #define EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_GUID \
  22   { \
  23     0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  24   }
  25
  26 typedef struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL  EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL;
  27
  28 //
  29 // Prototypes for the Platform Driver Override Protocol
  30 //
  31
  32 /**
  33   Retrieves the image handle of the platform override driver for a controller in the system.
  34
  35   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  36                                 PROTOCOL instance.
  37   @param  ControllerHandle      The device handle of the controller to check if a driver override
  38                                 exists.
  39   @param  DriverImageHandle     On input, a pointer to the previous driver image handle returned
  40                                 by GetDriver(). On output, a pointer to the next driver
  41                                 image handle.
  42
  43   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
  44                                 DriverImageHandle.
  45   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
  46   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not a valid handle.
  47   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a handle that was returned on a
  48                                 previous call to GetDriver().
  49
  50 **/
  51 typedef
  52 EFI_STATUS
  53 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER)(
  54   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
  55   IN     EFI_HANDLE                                     ControllerHandle,
  56   IN OUT EFI_HANDLE                                     *DriverImageHandle
  57   );
  58
  59 /**
  60   Retrieves the device path of the platform override driver for a controller in the system.
  61
  62   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  63                                 PROTOCOL instance.
  64   @param  ControllerHandle      The device handle of the controller to check if a driver override
  65                                 exists.
  66   @param  DriverImageHandle     On input, a pointer to the previous driver image handle returned
  67                                 by GetDriverPath(). On output, a pointer to the next driver
  68                                 device path.
  69
  70   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
  71                                 DriverImageHandle.
  72   @retval EFI_UNSUPPORTED       The operation is not supported.
  73   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
  74   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not a valid handle.
  75   @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a
  76                                 previous call to GetDriverPath().
  77
  78 **/
  79 typedef
  80 EFI_STATUS
  81 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH)(
  82   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
  83   IN     EFI_HANDLE                                     ControllerHandle,
  84   IN OUT EFI_DEVICE_PATH_PROTOCOL                       **DriverImagePath
  85   );
  86
  87 /**
  88   Used to associate a driver image handle with a device path that was returned on a prior call to the
  89   GetDriverPath() service. This driver image handle will then be available through the
  90   GetDriver() service.
  91
  92   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  93                                 PROTOCOL instance.
  94   @param  ControllerHandle      The device handle of the controller.
  95   @param  DriverImagePath       A pointer to the driver device path that was returned in a prior
  96                                 call to GetDriverPath().
  97   @param  DriverImageHandle     The driver image handle that was returned by LoadImage()
  98                                 when the driver specified by DriverImagePath was loaded
  99                                 into memory.
 100
 101   @retval EFI_SUCCESS           The association between DriverImagePath and
 102                                 DriverImageHandle was established for the controller specified
 103                                 by ControllerHandle.
 104   @retval EFI_UNSUPPORTED       The operation is not supported.
 105   @retval EFI_NOT_FOUND         DriverImagePath is not a device path that was returned on a prior
 106                                 call to GetDriverPath() for the controller specified by
 107                                 ControllerHandle.
 108   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid device handle.
 109   @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path.
 110   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED)(
 116   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL          *This,
 117   IN EFI_HANDLE                                     ControllerHandle,
 118   IN EFI_DEVICE_PATH_PROTOCOL                       *DriverImagePath,
 119   IN EFI_HANDLE                                     DriverImageHandle
 120   );
 121
 122 //
 123 // Interface structure for the Platform Driver Override Protocol
 124 //
 125 /**
 126   @par Protocol Description:
 127   This protocol matches one or more drivers to a controller. A platform driver
 128   produces this protocol, and it is installed on a separate handle. This protocol
 129   is used by the ConnectController() boot service to select the best driver
 130   for a controller. All of the drivers returned by this protocol have a higher
 131   precedence than drivers found from an EFI Bus Specific Driver Override Protocol
 132   or drivers found from the general UEFI driver Binding search algorithm. If more
 133   than one driver is returned by this protocol, then the drivers are returned in
 134   order from highest precedence to lowest precedence.
 135
 136   @param GetDriver
 137   Retrieves the image handle of a platform override driver for a controller in the system.
 138
 139   @param GetDriverPath
 140   Retrieves the device path of a platform override driver for a controller in the system.
 141
 142   @param DriverLoaded
 143   This function is used after a driver has been loaded using a device path returned
 144   by GetDriverPath(). This function associates a device path to an image handle,
 145   so the image handle can be returned the next time that GetDriver() is called for
 146   the same controller.
 147
 148 **/
 149 struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL {
 150   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER       GetDriver;
 151   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH  GetDriverPath;
 152   EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED    DriverLoaded;
 153 };
 154
 155 extern EFI_GUID gEfiPlatformDriverOverrideProtocolGuid;
 156
 157 #endif