Commit a6aed6b9 authored by Frank Li's avatar Frank Li Committed by Thomas Gleixner
Browse files

dt-bindings: PCI: pci-ep: Add support for iommu-map and msi-map 



Document the use of (msi|iommu)-map for PCI Endpoint (EP) controllers,
which can use MSI as a doorbell mechanism. Each EP controller can support
up to 8 physical functions and 65,536 virtual functions.

Define how to construct device IDs using function bits [2:0] and virtual
function index bits [31:3], enabling (msi|iommu)-map to associate each
child device with a specific (msi|iommu)-specifier.

The EP cannot rely on PCI Requester ID (RID) because the RID is determined
by the PCI topology of the host system. Since the EP may be connected to
different PCI hosts, the RID can vary between systems and is therefore not
a reliable identifier.

Signed-off-by: default avatarFrank Li <Frank.Li@nxp.com>
Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Reviewed-by: default avatarRob Herring (Arm) <robh@kernel.org>
Link: https://lore.kernel.org/all/20250414-ep-msi-v18-4-f69b49917464@nxp.com
parent fd120c38

Documentation/devicetree/bindings/pci/pci-ep.yaml

+68 −0
Original line number Diff line number Diff line
@@ -17,6 +17,24 @@ properties: 
  $nodename:

    pattern: "^pcie-ep@"



  iommu-map:

    $ref: /schemas/types.yaml#/definitions/uint32-matrix

    items:

      items:

        - description: Device ID (see msi-map) base

          maximum: 0x7ffff

        - description: phandle to IOMMU

        - description: IOMMU specifier base (currently always 1 cell)

        - description: Number of Device IDs

          maximum: 0x80000



  iommu-map-mask:

    description:

      A mask to be applied to each Device ID prior to being mapped to an

      IOMMU specifier per the iommu-map property.

    $ref: /schemas/types.yaml#/definitions/uint32

    maximum: 0x7ffff



  max-functions:

    description: Maximum number of functions that can be configured

    $ref: /schemas/types.yaml#/definitions/uint8
@@ -35,6 +53,56 @@ properties: 
    $ref: /schemas/types.yaml#/definitions/uint32

    enum: [ 1, 2, 3, 4 ]



  msi-map:

    description: |

      Maps a Device ID to an MSI and associated MSI specifier data.



      A PCI Endpoint (EP) can use MSI as a doorbell function. This is achieved by

      mapping the MSI controller's address into PCI BAR<n>. The PCI Root Complex

      can write to this BAR<n>, triggering the EP to generate IRQ. This notifies

      the EP-side driver of an event, eliminating the need for the driver to

      continuously poll for status changes.



      However, the EP cannot rely on Requester ID (RID) because the RID is

      determined by the PCI topology of the host system. Since the EP may be

      connected to different PCI hosts, the RID can vary between systems and is

      therefore not a reliable identifier.



      Each EP can support up to 8 physical functions and up to 65,536 virtual

      functions. To uniquely identify each child device, a device ID is defined

      as

         - Bits [2:0] for the function number (func)

         - Bits [18:3] for the virtual function index (vfunc)



      The resulting device ID is computed as:



        (func & 0x7) | (vfunc << 3)



      The property is an arbitrary number of tuples of

      (device-id-base, msi, msi-base,length).



      Any Device ID id in the interval [id-base, id-base + length) is

      associated with the listed MSI, with the MSI specifier

      (id - id-base + msi-base).

    $ref: /schemas/types.yaml#/definitions/uint32-matrix

    items:

      items:

        - description: The Device ID base matched by the entry

          maximum: 0x7ffff

        - description: phandle to msi-controller node

        - description: (optional) The msi-specifier produced for the first

            Device ID matched by the entry. Currently, msi-specifier is 0 or

            1 cells.

        - description: The length of consecutive Device IDs following the

            Device ID base

          maximum: 0x80000



  msi-map-mask:

    description: A mask to be applied to each Device ID prior to being

      mapped to an msi-specifier per the msi-map property.

    $ref: /schemas/types.yaml#/definitions/uint32

    maximum: 0x7ffff



  num-lanes:

    description: maximum number of lanes

    $ref: /schemas/types.yaml#/definitions/uint32