OvmfPkg: introduce PciCapPciIoLib

Add a library class, and a UEFI_DRIVER lib instance, that are layered on
top of PciCapLib, and allow clients to plug an EFI_PCI_IO_PROTOCOL backend
into PciCapLib, for config space access.

(Side note:

Although the UEFI spec says that EFI_PCI_IO_PROTOCOL_CONFIG() returns
EFI_UNSUPPORTED if "[t]he address range specified by Offset, Width, and
Count is not valid for the PCI configuration header of the PCI
controller", this patch doesn't directly document the EFI_UNSUPPORTED
error code, for ProtoDevTransferConfig() and its callers
ProtoDevReadConfig() and ProtoDevWriteConfig(). Instead, the patch refers
to "unspecified error codes". The reason is that in edk2, the
PciIoConfigRead() and PciIoConfigWrite() functions [1] can also return
EFI_INVALID_PARAMETER for the above situation.

Namely, PciIoConfigRead() and PciIoConfigWrite() first call
PciIoVerifyConfigAccess(), which indeed produces the standard
EFI_UNSUPPORTED error code, if the device's config space is exceeded.
However, if PciIoVerifyConfigAccess() passes, and we reach
RootBridgeIoPciRead() and RootBridgeIoPciWrite() [2], then
RootBridgeIoCheckParameter() can still fail, e.g. if the root bridge
doesn't support extended config space (see commit 014b472053ae3).

For all kinds of Limit violations in IO, MMIO, and config space,
RootBridgeIoCheckParameter() returns EFI_INVALID_PARAMETER, not
EFI_UNSUPPORTED. That error code is then propagated up to, and out of,
PciIoConfigRead() and PciIoConfigWrite().

[1] MdeModulePkg/Bus/Pci/PciBusDxe/PciIo.c
[2] MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c
)

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>

1 files changed, 58 insertions, 0 deletions

diff --git a/OvmfPkg/Include/Library/PciCapPciIoLib.h b/OvmfPkg/Include/Library/PciCapPciIoLib.h
new file mode 100644
index 0000000000..553715fd50
--- /dev/null
+++ b/OvmfPkg/Include/Library/PciCapPciIoLib.h
@@ -0,0 +1,58 @@
+/** @file

+  Library class layered on top of PciCapLib that allows clients to plug an

+  EFI_PCI_IO_PROTOCOL backend into PciCapLib, for config space access.

+

+  Copyright (C) 2018, Red Hat, Inc.

+

+  This program and the accompanying materials are licensed and made available

+  under the terms and conditions of the BSD License which accompanies this

+  distribution.  The full text of the license may be found at

+  http://opensource.org/licenses/bsd-license.php

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT

+  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+**/

+

+#ifndef __PCI_CAP_PCI_IO_LIB_H__

+#define __PCI_CAP_PCI_IO_LIB_H__

+

+#include <Protocol/PciIo.h>

+

+#include <Library/PciCapLib.h>

+

+

+/**

+  Create a PCI_CAP_DEV object from an EFI_PCI_IO_PROTOCOL instance. The config

+  space accessors are based upon EFI_PCI_IO_PROTOCOL.Pci.Read() and

+  EFI_PCI_IO_PROTOCOL.Pci.Write().

+

+  @param[in] PciIo       EFI_PCI_IO_PROTOCOL representation of the PCI device.

+

+  @param[out] PciDevice  The PCI_CAP_DEV object constructed as described above.

+                         PciDevice can be passed to the PciCapLib APIs.

+

+  @retval EFI_SUCCESS           PciDevice has been constructed and output.

+

+  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.

+**/

+EFI_STATUS

+EFIAPI

+PciCapPciIoDeviceInit (

+  IN  EFI_PCI_IO_PROTOCOL *PciIo,

+  OUT PCI_CAP_DEV         **PciDevice

+  );

+

+

+/**

+  Free the resources used by PciDevice.

+

+  @param[in] PciDevice  The PCI_CAP_DEV object to free, originally produced by

+                        PciCapPciIoDeviceInit().

+**/

+VOID

+EFIAPI

+PciCapPciIoDeviceUninit (

+  IN PCI_CAP_DEV *PciDevice

+  );

+

+#endif // __PCI_CAP_PCI_IO_LIB_H__