[mirror_edk2.git] / MdeModulePkg / Universal / PlatformDriOverrideDxe / InternalPlatDriOverrideDxe.h

/** @file\r
  Ihe internal heder file includes the required Protocol/Guid/Library\r
  and the shared function APIs.\r
\r
Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _INTERNAL_PLATFORM_DRIVER_OVERRIDE_H_\r
#define _INTERNAL_PLATFORM_DRIVER_OVERRIDE_H_\r
\r
#include <PiDxe.h>\r
\r
#include <Protocol/HiiConfigAccess.h>\r
#include <Protocol/HiiConfigRouting.h>\r
#include <Protocol/HiiDatabase.h>\r
#include <Protocol/FormBrowser2.h>\r
#include <Protocol/LoadedImage.h>\r
#include <Protocol/FirmwareVolume2.h>\r
#include <Protocol/PciIo.h>\r
#include <Protocol/BusSpecificDriverOverride.h>\r
#include <Protocol/ComponentName2.h>\r
#include <Protocol/ComponentName.h>\r
#include <Protocol/DriverBinding.h>\r
#include <Protocol/DevicePath.h>\r
#include <Protocol/PlatformDriverOverride.h>\r
#include <Guid/MdeModuleHii.h>\r
#include <Guid/VariableFormat.h>\r
\r
#include <Library/BaseLib.h>\r
#include <Library/DebugLib.h>\r
#include <Library/UefiLib.h>\r
#include <Library/PrintLib.h>\r
#include <Library/UefiDriverEntryPoint.h>\r
#include <Library/UefiBootServicesTableLib.h>\r
#include <Library/UefiRuntimeServicesTableLib.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
#include <Library/DevicePathLib.h>\r
#include <Library/DxeServicesTableLib.h>\r
#include <Library/HiiLib.h>\r
\r
/**\r
  Free all the mapping database memory resource and initialize the mapping list entry.\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    mapping database list entry is NULL\r
  @retval EFI_SUCCESS              Free success\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FreeMappingDatabase (\r
  IN  OUT  LIST_ENTRY            *MappingDataBase\r
  )\r
;\r
\r
/**\r
  Read the NV environment variable(s) that contain the override mappings from Controller Device Path to\r
  a set of Driver Device Paths, and create the mapping database in memory to contain these variable info.\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null\r
  @retval EFI_NOT_FOUND            Cannot find the 'PlatDriOver' NV variable\r
  @retval EFI_VOLUME_CORRUPTED     The found NV variable is corrupted\r
  @retval EFI_SUCCESS              Create the mapping database in memory successfully\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitOverridesMapping (\r
  OUT  LIST_ENTRY            *MappingDataBase\r
  )\r
;\r
\r
/**\r
  Save the memory mapping database into NV environment variable(s).\r
  If MappingDataBase list is empty, then delete all platform override NV variables.\r
\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    MappingDataBase pointer is null\r
  @retval EFI_SUCCESS              Save memory mapping database successfully\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SaveOverridesMapping (\r
  IN  LIST_ENTRY              *MappingDataBase\r
  )\r
;\r
\r
/**\r
  Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.\r
\r
  @param  ControllerHandle         The device handle of the controller to check if\r
                                   a driver override exists.\r
  @param  DriverImageHandle        On output, a pointer to the next driver handle.\r
                                   Passing in a pointer to NULL, will return the\r
                                   first driver handle for ControllerHandle.\r
  @param  MappingDataBase          MappingDataBase - Mapping database list entry\r
                                   pointer\r
  @param  CallerImageHandle        The caller driver's image handle, for\r
                                   UpdateFvFileDevicePath use.\r
\r
  @retval EFI_INVALID_PARAMETER    The handle specified by ControllerHandle is not\r
                                   a valid handle.  Or DriverImagePath is not a\r
                                   device path that was returned on a previous call\r
                                   to GetDriverPath().\r
  @retval EFI_NOT_FOUND            A driver override for ControllerHandle was not\r
                                   found.\r
  @retval EFI_UNSUPPORTED          The operation is not supported.\r
  @retval EFI_SUCCESS              The driver override for ControllerHandle was\r
                                   returned in DriverImagePath.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GetDriverFromMapping (\r
  IN     EFI_HANDLE                                     ControllerHandle,\r
  IN OUT EFI_HANDLE                                     *DriverImageHandle,\r
  IN     LIST_ENTRY                                     *MappingDataBase,\r
  IN     EFI_HANDLE                                     CallerImageHandle\r
  )\r
;\r
\r
/**\r
  Check mapping database whether already has the mapping info which\r
  records the input Controller to input DriverImage.\r
\r
  @param  ControllerDevicePath     The controller device path is to be check.\r
  @param  DriverImageDevicePath    The driver image device path is to be check.\r
  @param  MappingDataBase          Mapping database list entry pointer\r
  @param  DriverInfoNum            the controller's total override driver number\r
  @param  DriverImageNO            The driver order number for the input DriverImage.\r
                                   If the DriverImageDevicePath is NULL, DriverImageNO is not set.\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath or MappingDataBase is NULL.\r
  @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or\r
                                   DriverImageDevicePath is not found in the found DriverImage Info list.\r
  @retval EFI_SUCCESS              The controller's total override driver number and\r
                                   input DriverImage's order number is correctly return.\r
**/\r
EFI_STATUS\r
EFIAPI\r
CheckMapping (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath  OPTIONAL,\r
  IN     LIST_ENTRY                                     *MappingDataBase,\r
  OUT    UINT32                                         *DriverInfoNum  OPTIONAL,\r
  OUT    UINT32                                         *DriverImageNO  OPTIONAL\r
  )\r
;\r
\r
/**\r
  Insert a driver image as a controller's override driver into the mapping database.\r
  The driver image's order number is indicated by DriverImageNO.\r
\r
  @param  ControllerDevicePath     The controller device path need to add a\r
                                   override driver image item\r
  @param  DriverImageDevicePath    The driver image device path need to be insert\r
  @param  MappingDataBase          Mapping database list entry pointer\r
  @param  DriverImageNO            The inserted order number. If this number is taken,\r
                                   the larger available number will be used.\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or DriverImageDevicePath is NULL\r
                                   or MappingDataBase is NULL\r
  @retval EFI_ALREADY_STARTED      The input Controller to input DriverImage has been\r
                                   recorded into the mapping database.\r
  @retval EFI_SUCCESS              The Controller and DriverImage are inserted into\r
                                   the mapping database successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InsertDriverImage (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,\r
  IN     LIST_ENTRY                                     *MappingDataBase,\r
  IN     UINT32                                         DriverImageNO\r
  )\r
;\r
\r
/**\r
  Delete a controller's override driver from the mapping database.\r
\r
  @param  ControllerDevicePath     The controller device path will be deleted\r
                                   when all drivers images on it are removed.\r
  @param  DriverImageDevicePath    The driver image device path will be delete.\r
                                   If NULL, all driver image will be delete.\r
  @param  MappingDataBase          Mapping database list entry pointer\r
\r
  @retval EFI_INVALID_PARAMETER    ControllerDevicePath is NULL, or MappingDataBase is NULL\r
  @retval EFI_NOT_FOUND            ControllerDevicePath is not found in MappingDataBase or\r
                                   DriverImageDevicePath is not found in the found DriverImage Info list.\r
  @retval EFI_SUCCESS              Delete the specified driver successfully.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
DeleteDriverImage (\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *ControllerDevicePath,\r
  IN     EFI_DEVICE_PATH_PROTOCOL                       *DriverImageDevicePath,\r
  IN     LIST_ENTRY                                     *MappingDataBase\r
  )\r
;\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	Ihe internal heder file includes the required Protocol/Guid/Library\r
	3	and the shared function APIs.\r
	4	\r
	5	Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
	6	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	7	\r
	8	**/\r
	9	\r
	10	#ifndef _INTERNAL_PLATFORM_DRIVER_OVERRIDE_H_\r
	11	#define _INTERNAL_PLATFORM_DRIVER_OVERRIDE_H_\r
	12	\r
	13	#include <PiDxe.h>\r
	14	\r
	15	#include <Protocol/HiiConfigAccess.h>\r
	16	#include <Protocol/HiiConfigRouting.h>\r
	17	#include <Protocol/HiiDatabase.h>\r
	18	#include <Protocol/FormBrowser2.h>\r
	19	#include <Protocol/LoadedImage.h>\r
	20	#include <Protocol/FirmwareVolume2.h>\r
	21	#include <Protocol/PciIo.h>\r
	22	#include <Protocol/BusSpecificDriverOverride.h>\r
	23	#include <Protocol/ComponentName2.h>\r
	24	#include <Protocol/ComponentName.h>\r
	25	#include <Protocol/DriverBinding.h>\r
	26	#include <Protocol/DevicePath.h>\r
	27	#include <Protocol/PlatformDriverOverride.h>\r
	28	#include <Guid/MdeModuleHii.h>\r
	29	#include <Guid/VariableFormat.h>\r
	30	\r
	31	#include <Library/BaseLib.h>\r
	32	#include <Library/DebugLib.h>\r
	33	#include <Library/UefiLib.h>\r
	34	#include <Library/PrintLib.h>\r
	35	#include <Library/UefiDriverEntryPoint.h>\r
	36	#include <Library/UefiBootServicesTableLib.h>\r
	37	#include <Library/UefiRuntimeServicesTableLib.h>\r
	38	#include <Library/BaseMemoryLib.h>\r
	39	#include <Library/MemoryAllocationLib.h>\r
	40	#include <Library/DevicePathLib.h>\r
	41	#include <Library/DxeServicesTableLib.h>\r
	42	#include <Library/HiiLib.h>\r
	43	\r
	44	/**\r
	45	Free all the mapping database memory resource and initialize the mapping list entry.\r
	46	\r
	47	@param MappingDataBase Mapping database list entry pointer\r
	48	\r
	49	@retval EFI_INVALID_PARAMETER mapping database list entry is NULL\r
	50	@retval EFI_SUCCESS Free success\r
	51	\r
	52	**/\r
	53	EFI_STATUS\r
	54	EFIAPI\r
	55	FreeMappingDatabase (\r
	56	IN OUT LIST_ENTRY *MappingDataBase\r
	57	)\r
	58	;\r
	59	\r
	60	/**\r
	61	Read the NV environment variable(s) that contain the override mappings from Controller Device Path to\r
	62	a set of Driver Device Paths, and create the mapping database in memory to contain these variable info.\r
	63	\r
	64	@param MappingDataBase Mapping database list entry pointer\r
	65	\r
	66	@retval EFI_INVALID_PARAMETER MappingDataBase pointer is null\r
	67	@retval EFI_NOT_FOUND Cannot find the 'PlatDriOver' NV variable\r
	68	@retval EFI_VOLUME_CORRUPTED The found NV variable is corrupted\r
	69	@retval EFI_SUCCESS Create the mapping database in memory successfully\r
	70	\r
	71	**/\r
	72	EFI_STATUS\r
	73	EFIAPI\r
	74	InitOverridesMapping (\r
	75	OUT LIST_ENTRY *MappingDataBase\r
	76	)\r
	77	;\r
	78	\r
	79	/**\r
	80	Save the memory mapping database into NV environment variable(s).\r
	81	If MappingDataBase list is empty, then delete all platform override NV variables.\r
	82	\r
	83	@param MappingDataBase Mapping database list entry pointer\r
	84	\r
	85	@retval EFI_INVALID_PARAMETER MappingDataBase pointer is null\r
	86	@retval EFI_SUCCESS Save memory mapping database successfully\r
	87	\r
	88	**/\r
	89	EFI_STATUS\r
	90	EFIAPI\r
	91	SaveOverridesMapping (\r
	92	IN LIST_ENTRY *MappingDataBase\r
	93	)\r
	94	;\r
	95	\r
	96	/**\r
	97	Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.\r
	98	\r
	99	@param ControllerHandle The device handle of the controller to check if\r
	100	a driver override exists.\r
	101	@param DriverImageHandle On output, a pointer to the next driver handle.\r
	102	Passing in a pointer to NULL, will return the\r
	103	first driver handle for ControllerHandle.\r
	104	@param MappingDataBase MappingDataBase - Mapping database list entry\r
	105	pointer\r
	106	@param CallerImageHandle The caller driver's image handle, for\r
	107	UpdateFvFileDevicePath use.\r
	108	\r
	109	@retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not\r
	110	a valid handle. Or DriverImagePath is not a\r
	111	device path that was returned on a previous call\r
	112	to GetDriverPath().\r
	113	@retval EFI_NOT_FOUND A driver override for ControllerHandle was not\r
	114	found.\r
	115	@retval EFI_UNSUPPORTED The operation is not supported.\r
	116	@retval EFI_SUCCESS The driver override for ControllerHandle was\r
	117	returned in DriverImagePath.\r
	118	\r
	119	**/\r
	120	EFI_STATUS\r
	121	EFIAPI\r
	122	GetDriverFromMapping (\r
	123	IN EFI_HANDLE ControllerHandle,\r
	124	IN OUT EFI_HANDLE *DriverImageHandle,\r
	125	IN LIST_ENTRY *MappingDataBase,\r
	126	IN EFI_HANDLE CallerImageHandle\r
	127	)\r
	128	;\r
	129	\r
	130	/**\r
	131	Check mapping database whether already has the mapping info which\r
	132	records the input Controller to input DriverImage.\r
	133	\r
	134	@param ControllerDevicePath The controller device path is to be check.\r
	135	@param DriverImageDevicePath The driver image device path is to be check.\r
	136	@param MappingDataBase Mapping database list entry pointer\r
	137	@param DriverInfoNum the controller's total override driver number\r
	138	@param DriverImageNO The driver order number for the input DriverImage.\r
	139	If the DriverImageDevicePath is NULL, DriverImageNO is not set.\r
	140	\r
	141	@retval EFI_INVALID_PARAMETER ControllerDevicePath or MappingDataBase is NULL.\r
	142	@retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or\r
	143	DriverImageDevicePath is not found in the found DriverImage Info list.\r
	144	@retval EFI_SUCCESS The controller's total override driver number and\r
	145	input DriverImage's order number is correctly return.\r
	146	**/\r
	147	EFI_STATUS\r
	148	EFIAPI\r
	149	CheckMapping (\r
	150	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
	151	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath OPTIONAL,\r
	152	IN LIST_ENTRY *MappingDataBase,\r
	153	OUT UINT32 *DriverInfoNum OPTIONAL,\r
	154	OUT UINT32 *DriverImageNO OPTIONAL\r
	155	)\r
	156	;\r
	157	\r
	158	/**\r
	159	Insert a driver image as a controller's override driver into the mapping database.\r
	160	The driver image's order number is indicated by DriverImageNO.\r
	161	\r
	162	@param ControllerDevicePath The controller device path need to add a\r
	163	override driver image item\r
	164	@param DriverImageDevicePath The driver image device path need to be insert\r
	165	@param MappingDataBase Mapping database list entry pointer\r
	166	@param DriverImageNO The inserted order number. If this number is taken,\r
	167	the larger available number will be used.\r
	168	\r
	169	@retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or DriverImageDevicePath is NULL\r
	170	or MappingDataBase is NULL\r
	171	@retval EFI_ALREADY_STARTED The input Controller to input DriverImage has been\r
	172	recorded into the mapping database.\r
	173	@retval EFI_SUCCESS The Controller and DriverImage are inserted into\r
	174	the mapping database successfully.\r
	175	\r
	176	**/\r
	177	EFI_STATUS\r
	178	EFIAPI\r
	179	InsertDriverImage (\r
	180	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
	181	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,\r
	182	IN LIST_ENTRY *MappingDataBase,\r
	183	IN UINT32 DriverImageNO\r
	184	)\r
	185	;\r
	186	\r
	187	/**\r
	188	Delete a controller's override driver from the mapping database.\r
	189	\r
	190	@param ControllerDevicePath The controller device path will be deleted\r
	191	when all drivers images on it are removed.\r
	192	@param DriverImageDevicePath The driver image device path will be delete.\r
	193	If NULL, all driver image will be delete.\r
	194	@param MappingDataBase Mapping database list entry pointer\r
	195	\r
	196	@retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or MappingDataBase is NULL\r
	197	@retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or\r
	198	DriverImageDevicePath is not found in the found DriverImage Info list.\r
	199	@retval EFI_SUCCESS Delete the specified driver successfully.\r
	200	\r
	201	**/\r
	202	EFI_STATUS\r
	203	EFIAPI\r
	204	DeleteDriverImage (\r
	205	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
	206	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,\r
	207	IN LIST_ENTRY *MappingDataBase\r
	208	)\r
	209	;\r
	210	\r
	211	#endif\r