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