MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h

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