[mirror_edk2.git] / MdeModulePkg / Include / Library / PlatDriOverLib.h

/** @file\r
\r
  This library provides basic platform driver override functions.\r
\r
Copyright (c) 2007 - 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 _PLAT_DRI_OVER_LIB_H_\r
#define _PLAT_DRI_OVER_LIB_H_\r
\r
#include <Protocol/DevicePath.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
  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
  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
  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
  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
  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
  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
#endif\r
Commit	Line	Data
5f597758 LG	1	/** @file\r
	2	\r
	3	This library provides basic platform driver override functions.\r
	4	\r
	5	Copyright (c) 2007 - 2008, Intel Corporation\r
	6	All rights reserved. This program and the accompanying materials\r
	7	are licensed and made available under the terms and conditions of the BSD License\r
	8	which accompanies this distribution. The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
	14	**/\r
	15	\r
	16	#ifndef _PLAT_DRI_OVER_LIB_H_\r
	17	#define _PLAT_DRI_OVER_LIB_H_\r
	18	\r
5f597758	19	#include <Protocol/DevicePath.h>\r
5f597758	20	\r
b290614d	21	/**\r
5f597758	22	Free all the mapping database memory resource and initialize the mapping list entry.\r
b290614d	23	\r
	24	@param MappingDataBase Mapping database list entry pointer\r
	25	\r
	26	@retval EFI_INVALID_PARAMETER mapping database list entry is NULL\r
	27	@retval EFI_SUCCESS Free success\r
	28	\r
5f597758 LG	29	**/\r
	30	EFI_STATUS\r
	31	EFIAPI\r
	32	FreeMappingDatabase (\r
	33	IN OUT LIST_ENTRY *MappingDataBase\r
b9982883 LG	34	)\r
b9982883 LG	35	;
5f597758	36	\r
b290614d	37	/**\r
68dbca6c LG	38	Read the NV environment variable(s) that contain the override mappings from Controller Device Path to\r
68dbca6c LG	39	a set of Driver Device Paths, and create the mapping database in memory to contain these variable info.\r
b290614d	40	\r
	41	@param MappingDataBase Mapping database list entry pointer\r
	42	\r
	43	@retval EFI_INVALID_PARAMETER MappingDataBase pointer is null\r
	44	@retval EFI_NOT_FOUND Cannot find the 'PlatDriOver' NV variable\r
	45	@retval EFI_VOLUME_CORRUPTED The found NV variable is corrupted\r
5f597758 LG	46	@retval EFI_SUCCESS Create the mapping database in memory successfully\r
	47	\r
	48	**/\r
	49	EFI_STATUS\r
	50	EFIAPI\r
	51	InitOverridesMapping (\r
	52	OUT LIST_ENTRY *MappingDataBase\r
b9982883 LG	53	)\r
b9982883 LG	54	;
5f597758	55	\r
b290614d	56	/**\r
5f597758	57	Save the memory mapping database into NV environment variable(s).\r
68dbca6c	58	If MappingDataBase list is empty, then delete all platform override NV variables.\r
b290614d	59	\r
	60	@param MappingDataBase Mapping database list entry pointer\r
	61	\r
	62	@retval EFI_INVALID_PARAMETER MappingDataBase pointer is null\r
	63	@retval EFI_SUCCESS Save memory mapping database successfully\r
	64	\r
5f597758 LG	65	**/\r
	66	EFI_STATUS\r
	67	EFIAPI\r
	68	SaveOverridesMapping (\r
	69	IN LIST_ENTRY *MappingDataBase\r
b9982883 LG	70	)\r
b9982883 LG	71	;
5f597758	72	\r
b290614d	73	/**\r
	74	Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.\r
	75	\r
b290614d	76	@param ControllerHandle The device handle of the controller to check if\r
	77	a driver override exists.\r
	78	@param DriverImageHandle On output, a pointer to the next driver handle.\r
	79	Passing in a pointer to NULL, will return the\r
	80	first driver handle for ControllerHandle.\r
	81	@param MappingDataBase MappingDataBase - Mapping database list entry\r
	82	pointer\r
	83	@param CallerImageHandle The caller driver's image handle, for\r
	84	UpdateFvFileDevicePath use.\r
	85	\r
	86	@retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not\r
	87	a valid handle. Or DriverImagePath is not a\r
	88	device path that was returned on a previous call\r
	89	to GetDriverPath().\r
	90	@retval EFI_NOT_FOUND A driver override for ControllerHandle was not\r
	91	found.\r
	92	@retval EFI_UNSUPPORTED The operation is not supported.\r
	93	@retval EFI_SUCCESS The driver override for ControllerHandle was\r
	94	returned in DriverImagePath.\r
	95	\r
5f597758 LG	96	**/\r
	97	EFI_STATUS\r
	98	EFIAPI\r
	99	GetDriverFromMapping (\r
5f597758	100	IN EFI_HANDLE ControllerHandle,\r
68dbca6c LG	101	IN OUT EFI_HANDLE *DriverImageHandle,\r
68dbca6c LG	102	IN LIST_ENTRY *MappingDataBase,\r
5f597758	103	IN EFI_HANDLE CallerImageHandle\r
b9982883 LG	104	)\r
b9982883 LG	105	;
5f597758 LG	106	\r
5f597758 LG	107	/**\r
68dbca6c	108	Check mapping database whether already has the mapping info which\r
b290614d	109	records the input Controller to input DriverImage.\r
b290614d	110	\r
5f597758 LG	111	@param ControllerDevicePath The controller device path is to be check.\r
5f597758 LG	112	@param DriverImageDevicePath The driver image device path is to be check.\r
b290614d	113	@param MappingDataBase Mapping database list entry pointer\r
b290614d	114	@param DriverInfoNum the controller's total override driver number\r
5f597758 LG	115	@param DriverImageNO The driver order number for the input DriverImage.\r
	116	If the DriverImageDevicePath is NULL, DriverImageNO is not set.\r
	117	\r
	118	@retval EFI_INVALID_PARAMETER ControllerDevicePath or MappingDataBase is NULL.\r
	119	@retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or\r
	120	DriverImageDevicePath is not found in the found DriverImage Info list. \r
	121	@retval EFI_SUCCESS The controller's total override driver number and \r
	122	input DriverImage's order number is correctly return.\r
	123	**/\r
	124	EFI_STATUS\r
	125	EFIAPI\r
	126	CheckMapping (\r
	127	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
0bcd9130	128	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath OPTIONAL,\r
	129	IN LIST_ENTRY *MappingDataBase,\r
	130	OUT UINT32 *DriverInfoNum OPTIONAL,\r
	131	OUT UINT32 *DriverImageNO OPTIONAL\r
b9982883 LG	132	)\r
b9982883 LG	133	;
5f597758	134	\r
b290614d	135	/**\r
	136	Insert a driver image as a controller's override driver into the mapping database.\r
	137	The driver image's order number is indicated by DriverImageNO.\r
	138	\r
	139	@param ControllerDevicePath The controller device path need to add a\r
	140	override driver image item\r
	141	@param DriverImageDevicePath The driver image device path need to be insert\r
	142	@param MappingDataBase Mapping database list entry pointer\r
5f597758 LG	143	@param DriverImageNO The inserted order number. If this number is taken, \r
	144	the larger available number will be used.\r
	145	\r
	146	@retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or DriverImageDevicePath is NULL\r
	147	or MappingDataBase is NULL\r
	148	@retval EFI_ALREADY_STARTED The input Controller to input DriverImage has been \r
	149	recorded into the mapping database.\r
	150	@retval EFI_SUCCESS The Controller and DriverImage are inserted into \r
	151	the mapping database successfully.\r
	152	\r
	153	**/\r
	154	EFI_STATUS\r
	155	EFIAPI\r
	156	InsertDriverImage (\r
	157	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
	158	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,\r
	159	IN LIST_ENTRY *MappingDataBase,\r
	160	IN UINT32 DriverImageNO\r
b9982883 LG	161	)\r
b9982883 LG	162	;
5f597758	163	\r
b290614d	164	/**\r
	165	Delete a controller's override driver from the mapping database.\r
	166	\r
5f597758 LG	167	@param ControllerDevicePath The controller device path will be deleted \r
	168	when all drivers images on it are removed.\r
	169	@param DriverImageDevicePath The driver image device path will be delete.\r
	170	If NULL, all driver image will be delete.\r
b290614d	171	@param MappingDataBase Mapping database list entry pointer\r
5f597758 LG	172	\r
	173	@retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or MappingDataBase is NULL\r
	174	@retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or\r
	175	DriverImageDevicePath is not found in the found DriverImage Info list. \r
	176	@retval EFI_SUCCESS Delete the specified driver successfully.\r
	177	\r
	178	**/\r
	179	EFI_STATUS\r
	180	EFIAPI\r
	181	DeleteDriverImage (\r
	182	IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,\r
	183	IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,\r
	184	IN LIST_ENTRY *MappingDataBase\r
b9982883 LG	185	)\r
b9982883 LG	186	;
5f597758	187	\r
5f597758	188	#endif\r