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

/** @file\r
  This file declares Incompatible PCI Device Support Protocol\r
\r
  Allows the PCI bus driver to support resource allocation for some PCI devices\r
  that do not comply with the PCI Specification.\r
\r
  @par Note:\r
    This protocol is optional. Only those platforms that implement this protocol\r
    will have the capability to support incompatible PCI devices. The absence of\r
    this protocol can cause the PCI bus driver to configure these incompatible\r
    PCI devices incorrectly. As a result, these devices may not work properly.\r
\r
  The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver\r
  to support resource allocation for some PCI devices that do not comply with the\r
  PCI Specification.  This protocol can find some incompatible PCI devices and\r
  report their special resource requirements to the PCI bus driver. The generic\r
  PCI bus driver does not have prior knowledge of any incompatible PCI devices.\r
  It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out\r
  if a device is incompatible and to obtain the special configuration requirements\r
  for a specific incompatible PCI device.\r
\r
  This protocol is optional, and only one instance of this protocol can be present\r
  in the system. If a platform supports this protocol, this protocol is produced\r
  by a Driver Execution Environment (DXE) driver and must be made available before\r
  the Boot Device Selection (BDS) phase. The PCI bus driver will look for the\r
  presence of this protocol before it begins PCI enumeration.  If this protocol\r
  exists in a platform, it indicates that the platform has the capability to support\r
  those incompatible PCI devices. However, final support for incompatible PCI\r
  devices still depends on the implementation of the PCI bus driver. The PCI bus\r
  driver may fully, partially, or not even support these incompatible devices.\r
\r
  During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address\r
  Registers (BARs) for each PCI device regardless of whether the PCI device is\r
  incompatible or not to determine the resource requirements so that the PCI bus\r
  driver can invoke the proper PCI resources for them.  Generally, this resource\r
  information includes the following:\r
    - Resource type\r
    - Resource length\r
    - Alignment\r
\r
  However, some incompatible PCI devices may have special requirements. As a result,\r
  the length or the alignment that is derived through BAR probing may not be exactly\r
  the same as the actual resource requirement of the device. For example, there\r
  are some devices that request I/O resources at a length of 0x100 from their I/O\r
  BAR, but these incompatible devices will never work correctly if an odd I/O base\r
  address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these\r
  devices request an even base address, such as 0x200 or 0x400. The Incompatible\r
  PCI Device Support Protocol can then be used to obtain these special resource\r
  requirements for these incompatible PCI devices. In this way, the PCI bus driver\r
  will take special consideration for these devices during PCI resource allocation\r
  to ensure that they can work correctly.\r
\r
  This protocol may support the following incompatible PCI BAR types:\r
    - I/O or memory length that is different from what the BAR reports\r
    - I/O or memory alignment that is different from what the BAR reports\r
    - Fixed I/O or memory base address\r
\r
  See the Conventional PCI Specification 3.0 for the details of how a PCI BAR\r
  reports the resource length and the alignment that it requires.\r
\r
  Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Revision Reference:\r
  This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
  Volume 5: Standards\r
\r
**/\r
\r
#ifndef _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
#define _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
\r
///\r
/// Global ID for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
///\r
#define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \\r
  { \\r
    0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} \\r
  }\r
\r
///\r
/// Forward declaration for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
///\r
typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL;\r
\r
/**\r
  Returns a list of ACPI resource descriptors that detail the special resource\r
  configuration requirements for an incompatible PCI device.\r
\r
  This function returns a list of ACPI resource descriptors that detail the\r
  special resource configuration requirements for an incompatible PCI device.\r
\r
  Prior to bus enumeration, the PCI bus driver will look for the presence\r
  of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this\r
  protocol can be present in the system. For each PCI device that the PCI bus\r
  driver discovers, the PCI bus driver calls this function with the device's vendor\r
  ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the\r
  VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is\r
  set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1\r
  will be used to identify the current device.\r
\r
  This function will only return EFI_SUCCESS. However, if the device is an\r
  incompatible PCI device, a list of ACPI resource descriptors will be returned\r
  in Configuration. Otherwise, NULL will be returned in Configuration instead.\r
  The PCI bus driver does not need to allocate memory for Configuration. However,\r
  it is the PCI bus driver's responsibility to free it. The PCI bus driver then\r
  can configure this device with the information that is derived from this list\r
  of resource nodes, rather than the result of BAR probing.\r
\r
  Only the following two resource descriptor types from the ACPI Specification\r
  may be used to describe the incompatible PCI device resource requirements:\r
    - QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0)\r
    - End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0)\r
\r
  The QWORD Address Space Descriptor can describe memory, I/O, and bus number\r
  ranges for dynamic or fixed resources.  The configuration of a PCI root bridge\r
  is described with one or more QWORD Address Space Descriptors, followed by an\r
  End Tag. See the ACPI Specification for details on the field values.\r
\r
  @param[in]  This                Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
                                  instance.\r
  @param[in]  VendorId            A unique ID to identify the manufacturer of\r
                                  the PCI device.  See the Conventional PCI\r
                                  Specification 3.0 for details.\r
  @param[in]  DeviceId            A unique ID to identify the particular PCI\r
                                  device. See the Conventional PCI Specification\r
                                  3.0 for details.\r
  @param[in]  RevisionId          A PCI device-specific revision identifier.\r
                                  See the Conventional PCI Specification 3.0\r
                                  for details.\r
  @param[in]  SubsystemVendorId   Specifies the subsystem vendor ID. See the\r
                                  Conventional PCI Specification 3.0 for details.\r
  @param[in]  SubsystemDeviceId   Specifies the subsystem device ID. See the\r
                                  Conventional PCI Specification 3.0 for details.\r
  @param[out] Configuration       A list of ACPI resource descriptors that detail\r
                                  the configuration requirement.\r
\r
  @retval EFI_SUCCESS   The function always returns EFI_SUCCESS.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE)(\r
  IN  EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL  *This,\r
  IN  UINTN                                         VendorId,\r
  IN  UINTN                                         DeviceId,\r
  IN  UINTN                                         RevisionId,\r
  IN  UINTN                                         SubsystemVendorId,\r
  IN  UINTN                                         SubsystemDeviceId,\r
  OUT VOID                                          **Configuration\r
  );\r
\r
///\r
/// Interface structure for the Incompatible PCI Device Support Protocol\r
///\r
struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL {\r
  ///\r
  ///  Returns a list of ACPI resource descriptors that detail any special\r
  ///  resource configuration requirements if the specified device is a recognized\r
  ///  incompatible PCI device.\r
  ///\r
  EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE  CheckDevice;\r
};\r
\r
extern EFI_GUID gEfiIncompatiblePciDeviceSupportProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	This file declares Incompatible PCI Device Support Protocol\r
	3	\r
	4	Allows the PCI bus driver to support resource allocation for some PCI devices\r
	5	that do not comply with the PCI Specification.\r
	6	\r
	7	@par Note:\r
	8	This protocol is optional. Only those platforms that implement this protocol\r
	9	will have the capability to support incompatible PCI devices. The absence of\r
	10	this protocol can cause the PCI bus driver to configure these incompatible\r
	11	PCI devices incorrectly. As a result, these devices may not work properly.\r
	12	\r
	13	The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver\r
	14	to support resource allocation for some PCI devices that do not comply with the\r
	15	PCI Specification. This protocol can find some incompatible PCI devices and\r
	16	report their special resource requirements to the PCI bus driver. The generic\r
	17	PCI bus driver does not have prior knowledge of any incompatible PCI devices.\r
	18	It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out\r
	19	if a device is incompatible and to obtain the special configuration requirements\r
	20	for a specific incompatible PCI device.\r
	21	\r
	22	This protocol is optional, and only one instance of this protocol can be present\r
	23	in the system. If a platform supports this protocol, this protocol is produced\r
	24	by a Driver Execution Environment (DXE) driver and must be made available before\r
	25	the Boot Device Selection (BDS) phase. The PCI bus driver will look for the\r
	26	presence of this protocol before it begins PCI enumeration. If this protocol\r
	27	exists in a platform, it indicates that the platform has the capability to support\r
	28	those incompatible PCI devices. However, final support for incompatible PCI\r
	29	devices still depends on the implementation of the PCI bus driver. The PCI bus\r
	30	driver may fully, partially, or not even support these incompatible devices.\r
	31	\r
	32	During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address\r
	33	Registers (BARs) for each PCI device regardless of whether the PCI device is\r
	34	incompatible or not to determine the resource requirements so that the PCI bus\r
	35	driver can invoke the proper PCI resources for them. Generally, this resource\r
	36	information includes the following:\r
	37	- Resource type\r
	38	- Resource length\r
	39	- Alignment\r
	40	\r
	41	However, some incompatible PCI devices may have special requirements. As a result,\r
	42	the length or the alignment that is derived through BAR probing may not be exactly\r
	43	the same as the actual resource requirement of the device. For example, there\r
	44	are some devices that request I/O resources at a length of 0x100 from their I/O\r
	45	BAR, but these incompatible devices will never work correctly if an odd I/O base\r
	46	address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these\r
	47	devices request an even base address, such as 0x200 or 0x400. The Incompatible\r
	48	PCI Device Support Protocol can then be used to obtain these special resource\r
	49	requirements for these incompatible PCI devices. In this way, the PCI bus driver\r
	50	will take special consideration for these devices during PCI resource allocation\r
	51	to ensure that they can work correctly.\r
	52	\r
	53	This protocol may support the following incompatible PCI BAR types:\r
	54	- I/O or memory length that is different from what the BAR reports\r
	55	- I/O or memory alignment that is different from what the BAR reports\r
	56	- Fixed I/O or memory base address\r
	57	\r
	58	See the Conventional PCI Specification 3.0 for the details of how a PCI BAR\r
	59	reports the resource length and the alignment that it requires.\r
	60	\r
	61	Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
	62	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	63	\r
	64	@par Revision Reference:\r
	65	This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
	66	Volume 5: Standards\r
	67	\r
	68	**/\r
	69	\r
	70	#ifndef _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
	71	#define _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
	72	\r
	73	///\r
	74	/// Global ID for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
	75	///\r
	76	#define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \\r
	77	{ \\r
	78	0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} \\r
	79	}\r
	80	\r
	81	///\r
	82	/// Forward declaration for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
	83	///\r
	84	typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL;\r
	85	\r
	86	/**\r
	87	Returns a list of ACPI resource descriptors that detail the special resource\r
	88	configuration requirements for an incompatible PCI device.\r
	89	\r
	90	This function returns a list of ACPI resource descriptors that detail the\r
	91	special resource configuration requirements for an incompatible PCI device.\r
	92	\r
	93	Prior to bus enumeration, the PCI bus driver will look for the presence\r
	94	of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this\r
	95	protocol can be present in the system. For each PCI device that the PCI bus\r
	96	driver discovers, the PCI bus driver calls this function with the device's vendor\r
	97	ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the\r
	98	VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is\r
	99	set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1\r
	100	will be used to identify the current device.\r
	101	\r
	102	This function will only return EFI_SUCCESS. However, if the device is an\r
	103	incompatible PCI device, a list of ACPI resource descriptors will be returned\r
	104	in Configuration. Otherwise, NULL will be returned in Configuration instead.\r
	105	The PCI bus driver does not need to allocate memory for Configuration. However,\r
	106	it is the PCI bus driver's responsibility to free it. The PCI bus driver then\r
	107	can configure this device with the information that is derived from this list\r
	108	of resource nodes, rather than the result of BAR probing.\r
	109	\r
	110	Only the following two resource descriptor types from the ACPI Specification\r
	111	may be used to describe the incompatible PCI device resource requirements:\r
	112	- QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0)\r
	113	- End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0)\r
	114	\r
	115	The QWORD Address Space Descriptor can describe memory, I/O, and bus number\r
	116	ranges for dynamic or fixed resources. The configuration of a PCI root bridge\r
	117	is described with one or more QWORD Address Space Descriptors, followed by an\r
	118	End Tag. See the ACPI Specification for details on the field values.\r
	119	\r
	120	@param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
	121	instance.\r
	122	@param[in] VendorId A unique ID to identify the manufacturer of\r
	123	the PCI device. See the Conventional PCI\r
	124	Specification 3.0 for details.\r
	125	@param[in] DeviceId A unique ID to identify the particular PCI\r
	126	device. See the Conventional PCI Specification\r
	127	3.0 for details.\r
	128	@param[in] RevisionId A PCI device-specific revision identifier.\r
	129	See the Conventional PCI Specification 3.0\r
	130	for details.\r
	131	@param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the\r
	132	Conventional PCI Specification 3.0 for details.\r
	133	@param[in] SubsystemDeviceId Specifies the subsystem device ID. See the\r
	134	Conventional PCI Specification 3.0 for details.\r
	135	@param[out] Configuration A list of ACPI resource descriptors that detail\r
	136	the configuration requirement.\r
	137	\r
	138	@retval EFI_SUCCESS The function always returns EFI_SUCCESS.\r
	139	\r
	140	**/\r
	141	typedef\r
	142	EFI_STATUS\r
	143	(EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE)(\r
	144	IN EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL *This,\r
	145	IN UINTN VendorId,\r
	146	IN UINTN DeviceId,\r
	147	IN UINTN RevisionId,\r
	148	IN UINTN SubsystemVendorId,\r
	149	IN UINTN SubsystemDeviceId,\r
	150	OUT VOID **Configuration\r
	151	);\r
	152	\r
	153	///\r
	154	/// Interface structure for the Incompatible PCI Device Support Protocol\r
	155	///\r
	156	struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL {\r
	157	///\r
	158	/// Returns a list of ACPI resource descriptors that detail any special\r
	159	/// resource configuration requirements if the specified device is a recognized\r
	160	/// incompatible PCI device.\r
	161	///\r
	162	EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice;\r
	163	};\r
	164	\r
	165	extern EFI_GUID gEfiIncompatiblePciDeviceSupportProtocolGuid;\r
	166	\r
	167	#endif\r