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  DriverImagePath       On input, a pointer to the previous driver device path returned by
  67                                 GetDriverPath(). On output, a pointer to the next driver
  68                                 device path. Passing in a pointer to NULL will return the first
  69                                 driver device path for ControllerHandle.
  70
  71   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
  72                                 DriverImageHandle.
  73   @retval EFI_UNSUPPORTED       The operation is not supported.
  74   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
  75   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not a valid handle.
  76   @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a
  77                                 previous call to GetDriverPath().
  78
  79 **/
  80 typedef
  81 EFI_STATUS
  82 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH)(
  83   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
  84   IN     EFI_HANDLE                                     ControllerHandle,
  85   IN OUT EFI_DEVICE_PATH_PROTOCOL                       **DriverImagePath
  86   );
  87
  88 /**
  89   Used to associate a driver image handle with a device path that was returned on a prior call to the
  90   GetDriverPath() service. This driver image handle will then be available through the
  91   GetDriver() service.
  92
  93   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
  94                                 PROTOCOL instance.
  95   @param  ControllerHandle      The device handle of the controller.
  96   @param  DriverImagePath       A pointer to the driver device path that was returned in a prior
  97                                 call to GetDriverPath().
  98   @param  DriverImageHandle     The driver image handle that was returned by LoadImage()
  99                                 when the driver specified by DriverImagePath was loaded
 100                                 into memory.
 101
 102   @retval EFI_SUCCESS           The association between DriverImagePath and
 103                                 DriverImageHandle was established for the controller specified
 104                                 by ControllerHandle.
 105   @retval EFI_UNSUPPORTED       The operation is not supported.
 106   @retval EFI_NOT_FOUND         DriverImagePath is not a device path that was returned on a prior
 107                                 call to GetDriverPath() for the controller specified by
 108                                 ControllerHandle.
 109   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid device handle.
 110   @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path.
 111   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle.
 112
 113 **/
 114 typedef
 115 EFI_STATUS
 116 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED)(
 117   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL          *This,
 118   IN EFI_HANDLE                                     ControllerHandle,
 119   IN EFI_DEVICE_PATH_PROTOCOL                       *DriverImagePath,
 120   IN EFI_HANDLE                                     DriverImageHandle
 121   );
 122
 123 ///
 124 /// This protocol matches one or more drivers to a controller. A platform driver
 125 /// produces this protocol, and it is installed on a separate handle. This protocol
 126 /// is used by the ConnectController() boot service to select the best driver
 127 /// for a controller. All of the drivers returned by this protocol have a higher
 128 /// precedence than drivers found from an EFI Bus Specific Driver Override Protocol
 129 /// or drivers found from the general UEFI driver Binding search algorithm. If more
 130 /// than one driver is returned by this protocol, then the drivers are returned in
 131 /// order from highest precedence to lowest precedence.
 132 ///
 133 struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL {
 134   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER       GetDriver;
 135   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH  GetDriverPath;
 136   EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED    DriverLoaded;
 137 };
 138
 139 extern EFI_GUID gEfiPlatformDriverOverrideProtocolGuid;
 140
 141 #endif