dts/upstream/Bindings/pci/pci-ep.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/pci/pci-ep.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: PCI Endpoint Controller

description: |
  Common properties for PCI Endpoint Controller Nodes.

maintainers:
  - Kishon Vijay Abraham I <kishon@kernel.org>
  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>

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
    minimum: 1
    default: 1
    maximum: 255

  max-virtual-functions:
    description: Array representing the number of virtual functions corresponding to each physical
      function
    $ref: /schemas/types.yaml#/definitions/uint8-array
    minItems: 1
    maxItems: 255

  max-link-speed:
    $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
    minimum: 1
    default: 1
    maximum: 16

  linux,pci-domain:
    description:
      If present this property assigns a fixed PCI domain number to a PCI
      Endpoint Controller, otherwise an unstable (across boots) unique number
      will be assigned. It is required to either not set this property at all
      or set it for all PCI endpoint controllers in the system, otherwise
      potentially conflicting domain numbers may be assigned to endpoint
      controllers. The domain number for each endpoint controller in the system
      must be unique.
    $ref: /schemas/types.yaml#/definitions/uint32

required:
  - compatible

additionalProperties: true