MdePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdePkg / Include / Protocol / PlatformDriverOverride.h

/** @file\r
  Platform Driver Override protocol as defined in the UEFI 2.1 specification.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__\r
#define __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__\r
\r
///\r
/// Global ID for the Platform Driver Override Protocol\r
///\r
#define EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_GUID \\r
  { \\r
    0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \\r
  }\r
\r
typedef struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL  EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL;\r
\r
//\r
// Prototypes for the Platform Driver Override Protocol\r
//\r
\r
/**\r
  Retrieves the image handle of the platform override driver for a controller in the system.\r
\r
  @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_\r
                                PROTOCOL instance.\r
  @param  ControllerHandle      The device handle of the controller to check if a driver override\r
                                exists.\r
  @param  DriverImageHandle     On input, a pointer to the previous driver image handle returned\r
                                by GetDriver(). On output, a pointer to the next driver\r
                                image handle.\r
\r
  @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in\r
                                DriverImageHandle.\r
  @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.\r
  @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.\r
  @retval EFI_INVALID_PARAMETER DriverImageHandle is not a handle that was returned on a\r
                                previous call to GetDriver().\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER)(\r
  IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,\r
  IN     EFI_HANDLE                                     ControllerHandle,\r
  IN OUT EFI_HANDLE                                     *DriverImageHandle\r
  );\r
\r
/**\r
  Retrieves the device path of the platform override driver for a controller in the system.\r
\r
  @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.\r
  @param  ControllerHandle      The device handle of the controller to check if a driver override\r
                                exists.\r
  @param  DriverImagePath       On input, a pointer to the previous driver device path returned by\r
                                GetDriverPath(). On output, a pointer to the next driver\r
                                device path. Passing in a pointer to NULL will return the first\r
                                driver device path for ControllerHandle.\r
\r
  @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in\r
                                DriverImageHandle.\r
  @retval EFI_UNSUPPORTED       The operation is not supported.\r
  @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.\r
  @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.\r
  @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a\r
                                previous call to GetDriverPath().\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH)(\r
  IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,\r
  IN     EFI_HANDLE                                     ControllerHandle,\r
  IN OUT EFI_DEVICE_PATH_PROTOCOL                       **DriverImagePath\r
  );\r
\r
/**\r
  Used to associate a driver image handle with a device path that was returned on a prior call to the\r
  GetDriverPath() service. This driver image handle will then be available through the\r
  GetDriver() service.\r
\r
  @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_\r
                                PROTOCOL instance.\r
  @param  ControllerHandle      The device handle of the controller.\r
  @param  DriverImagePath       A pointer to the driver device path that was returned in a prior\r
                                call to GetDriverPath().\r
  @param  DriverImageHandle     The driver image handle that was returned by LoadImage()\r
                                when the driver specified by DriverImagePath was loaded\r
                                into memory.\r
\r
  @retval EFI_SUCCESS           The association between DriverImagePath and\r
                                DriverImageHandle was established for the controller specified\r
                                by ControllerHandle.\r
  @retval EFI_UNSUPPORTED       The operation is not supported.\r
  @retval EFI_NOT_FOUND         DriverImagePath is not a device path that was returned on a prior\r
                                call to GetDriverPath() for the controller specified by\r
                                ControllerHandle.\r
  @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
  @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path.\r
  @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED)(\r
  IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL          *This,\r
  IN EFI_HANDLE                                     ControllerHandle,\r
  IN EFI_DEVICE_PATH_PROTOCOL                       *DriverImagePath,\r
  IN EFI_HANDLE                                     DriverImageHandle\r
  );\r
\r
///\r
/// This protocol matches one or more drivers to a controller. A platform driver\r
/// produces this protocol, and it is installed on a separate handle. This protocol\r
/// is used by the ConnectController() boot service to select the best driver\r
/// for a controller. All of the drivers returned by this protocol have a higher\r
/// precedence than drivers found from an EFI Bus Specific Driver Override Protocol\r
/// or drivers found from the general UEFI driver Binding search algorithm. If more\r
/// than one driver is returned by this protocol, then the drivers are returned in\r
/// order from highest precedence to lowest precedence.\r
///\r
struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL {\r
  EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER       GetDriver;\r
  EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH  GetDriverPath;\r
  EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED    DriverLoaded;\r
};\r
\r
extern EFI_GUID gEfiPlatformDriverOverrideProtocolGuid;\r
\r
#endif\r