OvmfPkg: introduce PciCapPciSegmentLib
Add a library class, and a BASE lib instance, that are layered on top of
PciCapLib, and allow clients to plug a PciSegmentLib backend into
PciCapLib, for config space access.
(Side note:
The "MaxDomain" parameter is provided because, in practice, platforms
exist where a PCI Express device may show up on a root bridge such that
the root bridge doesn't support access to extended config space. Earlier
the same issue was handled for MdeModulePkg/PciHostBridgeDxe in commit
014b472053ae3. However, that solution does not apply to the PciSegmentLib
class, because:
(1) The config space accessor functions of the PciSegmentLib class, such
as PciSegmentReadBuffer(), have no way of informing the caller whether
access to extended config space actually succeeds.
(For example, in the UefiPciSegmentLibPciRootBridgeIo instace, which
could in theory benefit from commit 014b472053ae3, the
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() status code is explicitly
ignored, because there's no way for the lib instance to propagate it
to the PciSegmentLib caller. If the
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() call fails, then
DxePciSegmentLibPciRootBridgeIoReadWorker() returns Data with
indeterminate value.)
(2) There is no *general* way for any firmware platform to provide, or
use, a PciSegmentLib instance in which access to extended config space
always succeeds.
In brief, on a platform where config space may be limited to 256 bytes,
access to extended config space through PciSegmentLib may invoke undefined
behavior; therefore PciCapPciSegmentLib must give platforms a way to
prevent such access.)
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>
2018-04-28 23:22:59 +02:00
|
|
|
/** @file
|
|
|
|
|
Library class layered on top of PciCapLib that allows clients to plug a
|
|
|
|
|
PciSegmentLib backend into PciCapLib, for config space access.
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2018, Red Hat, Inc.
|
|
|
|
|
|
2019-04-04 01:06:33 +02:00
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
OvmfPkg: introduce PciCapPciSegmentLib
Add a library class, and a BASE lib instance, that are layered on top of
PciCapLib, and allow clients to plug a PciSegmentLib backend into
PciCapLib, for config space access.
(Side note:
The "MaxDomain" parameter is provided because, in practice, platforms
exist where a PCI Express device may show up on a root bridge such that
the root bridge doesn't support access to extended config space. Earlier
the same issue was handled for MdeModulePkg/PciHostBridgeDxe in commit
014b472053ae3. However, that solution does not apply to the PciSegmentLib
class, because:
(1) The config space accessor functions of the PciSegmentLib class, such
as PciSegmentReadBuffer(), have no way of informing the caller whether
access to extended config space actually succeeds.
(For example, in the UefiPciSegmentLibPciRootBridgeIo instace, which
could in theory benefit from commit 014b472053ae3, the
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() status code is explicitly
ignored, because there's no way for the lib instance to propagate it
to the PciSegmentLib caller. If the
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() call fails, then
DxePciSegmentLibPciRootBridgeIoReadWorker() returns Data with
indeterminate value.)
(2) There is no *general* way for any firmware platform to provide, or
use, a PciSegmentLib instance in which access to extended config space
always succeeds.
In brief, on a platform where config space may be limited to 256 bytes,
access to extended config space through PciSegmentLib may invoke undefined
behavior; therefore PciCapPciSegmentLib must give platforms a way to
prevent such access.)
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>
2018-04-28 23:22:59 +02:00
|
|
|
**/
|
|
|
|
|
|
|
|
|
|
#ifndef __PCI_CAP_PCI_SEGMENT_LIB_H__
|
|
|
|
|
#define __PCI_CAP_PCI_SEGMENT_LIB_H__
|
|
|
|
|
|
|
|
|
|
#include <Library/PciCapLib.h>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Create a PCI_CAP_DEV object from the PCI Segment:Bus:Device.Function
|
|
|
|
|
quadruplet. The config space accessors are based upon PciSegmentLib.
|
|
|
|
|
|
|
|
|
|
@param[in] MaxDomain If MaxDomain is PciCapExtended, then
|
|
|
|
|
PciDevice->ReadConfig() and PciDevice->WriteConfig()
|
|
|
|
|
will delegate extended config space accesses too to
|
|
|
|
|
PciSegmentReadBuffer() and PciSegmentWriteBuffer(),
|
|
|
|
|
respectively. Otherwise, PciDevice->ReadConfig() and
|
|
|
|
|
PciDevice->WriteConfig() will reject accesses to
|
|
|
|
|
extended config space with RETURN_UNSUPPORTED, without
|
|
|
|
|
calling PciSegmentReadBuffer() or
|
|
|
|
|
PciSegmentWriteBuffer(). By setting MaxDomain to
|
|
|
|
|
PciCapNormal, the platform can prevent undefined
|
|
|
|
|
PciSegmentLib behavior when the PCI root bridge under
|
|
|
|
|
the PCI device at Segment:Bus:Device.Function doesn't
|
|
|
|
|
support extended config space.
|
|
|
|
|
|
|
|
|
|
@param[in] Segment 16-bit wide segment number.
|
|
|
|
|
|
|
|
|
|
@param[in] Bus 8-bit wide bus number.
|
|
|
|
|
|
|
|
|
|
@param[in] Device 5-bit wide device number.
|
|
|
|
|
|
|
|
|
|
@param[in] Function 3-bit wide function number.
|
|
|
|
|
|
|
|
|
|
@param[out] PciDevice The PCI_CAP_DEV object constructed as described above.
|
|
|
|
|
PciDevice can be passed to the PciCapLib APIs.
|
|
|
|
|
|
|
|
|
|
@retval RETURN_SUCCESS PciDevice has been constructed and output.
|
|
|
|
|
|
|
|
|
|
@retval RETURN_INVALID_PARAMETER Device or Function does not fit in the
|
|
|
|
|
permitted number of bits.
|
|
|
|
|
|
|
|
|
|
@retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
|
|
|
|
|
**/
|
|
|
|
|
RETURN_STATUS
|
|
|
|
|
EFIAPI
|
|
|
|
|
PciCapPciSegmentDeviceInit (
|
|
|
|
|
IN PCI_CAP_DOMAIN MaxDomain,
|
|
|
|
|
IN UINT16 Segment,
|
|
|
|
|
IN UINT8 Bus,
|
|
|
|
|
IN UINT8 Device,
|
|
|
|
|
IN UINT8 Function,
|
|
|
|
|
OUT PCI_CAP_DEV **PciDevice
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Free the resources used by PciDevice.
|
|
|
|
|
|
|
|
|
|
@param[in] PciDevice The PCI_CAP_DEV object to free, originally produced by
|
|
|
|
|
PciCapPciSegmentDeviceInit().
|
|
|
|
|
**/
|
|
|
|
|
VOID
|
|
|
|
|
EFIAPI
|
|
|
|
|
PciCapPciSegmentDeviceUninit (
|
|
|
|
|
IN PCI_CAP_DEV *PciDevice
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
#endif // __PCI_CAP_PCI_SEGMENT_LIB_H__
|
