OvmfPkg/Include/Library/PciCapPciSegmentLib.h

   1 /** @file
   2   Library class layered on top of PciCapLib that allows clients to plug a
   3   PciSegmentLib backend into PciCapLib, for config space access.
   4
   5   Copyright (C) 2018, Red Hat, Inc.
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8 **/
   9
  10 #ifndef __PCI_CAP_PCI_SEGMENT_LIB_H__
  11 #define __PCI_CAP_PCI_SEGMENT_LIB_H__
  12
  13 #include <Library/PciCapLib.h>
  14
  15
  16 /**
  17   Create a PCI_CAP_DEV object from the PCI Segment:Bus:Device.Function
  18   quadruplet. The config space accessors are based upon PciSegmentLib.
  19
  20   @param[in] MaxDomain   If MaxDomain is PciCapExtended, then
  21                          PciDevice->ReadConfig() and PciDevice->WriteConfig()
  22                          will delegate extended config space accesses too to
  23                          PciSegmentReadBuffer() and PciSegmentWriteBuffer(),
  24                          respectively. Otherwise, PciDevice->ReadConfig() and
  25                          PciDevice->WriteConfig() will reject accesses to
  26                          extended config space with RETURN_UNSUPPORTED, without
  27                          calling PciSegmentReadBuffer() or
  28                          PciSegmentWriteBuffer(). By setting MaxDomain to
  29                          PciCapNormal, the platform can prevent undefined
  30                          PciSegmentLib behavior when the PCI root bridge under
  31                          the PCI device at Segment:Bus:Device.Function doesn't
  32                          support extended config space.
  33
  34   @param[in] Segment     16-bit wide segment number.
  35
  36   @param[in] Bus         8-bit wide bus number.
  37
  38   @param[in] Device      5-bit wide device number.
  39
  40   @param[in] Function    3-bit wide function number.
  41
  42   @param[out] PciDevice  The PCI_CAP_DEV object constructed as described above.
  43                          PciDevice can be passed to the PciCapLib APIs.
  44
  45   @retval RETURN_SUCCESS            PciDevice has been constructed and output.
  46
  47   @retval RETURN_INVALID_PARAMETER  Device or Function does not fit in the
  48                                     permitted number of bits.
  49
  50   @retval RETURN_OUT_OF_RESOURCES   Memory allocation failed.
  51 **/
  52 RETURN_STATUS
  53 EFIAPI
  54 PciCapPciSegmentDeviceInit (
  55   IN  PCI_CAP_DOMAIN MaxDomain,
  56   IN  UINT16         Segment,
  57   IN  UINT8          Bus,
  58   IN  UINT8          Device,
  59   IN  UINT8          Function,
  60   OUT PCI_CAP_DEV    **PciDevice
  61   );
  62
  63
  64 /**
  65   Free the resources used by PciDevice.
  66
  67   @param[in] PciDevice  The PCI_CAP_DEV object to free, originally produced by
  68                         PciCapPciSegmentDeviceInit().
  69 **/
  70 VOID
  71 EFIAPI
  72 PciCapPciSegmentDeviceUninit (
  73   IN PCI_CAP_DEV *PciDevice
  74   );
  75
  76 #endif // __PCI_CAP_PCI_SEGMENT_LIB_H__