pci-ep.yaml

  1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
  2%YAML 1.2
  3---
  4$id: http://devicetree.org/schemas/pci/pci-ep.yaml#
  5$schema: http://devicetree.org/meta-schemas/core.yaml#
  6
  7title: PCI Endpoint Controller
  8
  9description: |
 10  Common properties for PCI Endpoint Controller Nodes.
 11
 12maintainers:
 13  - Kishon Vijay Abraham I <kishon@kernel.org>
 14  - Manivannan Sadhasivam <mani@kernel.org>
 15
 16properties:
 17  $nodename:
 18    pattern: "^pcie-ep@"
 19
 20  iommu-map:
 21    $ref: /schemas/types.yaml#/definitions/uint32-matrix
 22    items:
 23      items:
 24        - description: Device ID (see msi-map) base
 25          maximum: 0x7ffff
 26        - description: phandle to IOMMU
 27        - description: IOMMU specifier base (currently always 1 cell)
 28        - description: Number of Device IDs
 29          maximum: 0x80000
 30
 31  iommu-map-mask:
 32    description:
 33      A mask to be applied to each Device ID prior to being mapped to an
 34      IOMMU specifier per the iommu-map property.
 35    $ref: /schemas/types.yaml#/definitions/uint32
 36    maximum: 0x7ffff
 37
 38  max-functions:
 39    description: Maximum number of functions that can be configured
 40    $ref: /schemas/types.yaml#/definitions/uint8
 41    minimum: 1
 42    default: 1
 43    maximum: 255
 44
 45  max-virtual-functions:
 46    description: Array representing the number of virtual functions corresponding to each physical
 47      function
 48    $ref: /schemas/types.yaml#/definitions/uint8-array
 49    minItems: 1
 50    maxItems: 255
 51
 52  max-link-speed:
 53    $ref: /schemas/types.yaml#/definitions/uint32
 54    enum: [ 1, 2, 3, 4, 5, 6 ]
 55
 56  msi-map:
 57    description: |
 58      Maps a Device ID to an MSI and associated MSI specifier data.
 59
 60      A PCI Endpoint (EP) can use MSI as a doorbell function. This is achieved by
 61      mapping the MSI controller's address into PCI BAR<n>. The PCI Root Complex
 62      can write to this BAR<n>, triggering the EP to generate IRQ. This notifies
 63      the EP-side driver of an event, eliminating the need for the driver to
 64      continuously poll for status changes.
 65
 66      However, the EP cannot rely on Requester ID (RID) because the RID is
 67      determined by the PCI topology of the host system. Since the EP may be
 68      connected to different PCI hosts, the RID can vary between systems and is
 69      therefore not a reliable identifier.
 70
 71      Each EP can support up to 8 physical functions and up to 65,536 virtual
 72      functions. To uniquely identify each child device, a device ID is defined
 73      as
 74         - Bits [2:0] for the function number (func)
 75         - Bits [18:3] for the virtual function index (vfunc)
 76
 77      The resulting device ID is computed as:
 78
 79        (func & 0x7) | (vfunc << 3)
 80
 81      The property is an arbitrary number of tuples of
 82      (device-id-base, msi, msi-base,length).
 83
 84      Any Device ID id in the interval [id-base, id-base + length) is
 85      associated with the listed MSI, with the MSI specifier
 86      (id - id-base + msi-base).
 87    $ref: /schemas/types.yaml#/definitions/uint32-matrix
 88    items:
 89      items:
 90        - description: The Device ID base matched by the entry
 91          maximum: 0x7ffff
 92        - description: phandle to msi-controller node
 93        - description: (optional) The msi-specifier produced for the first
 94            Device ID matched by the entry. Currently, msi-specifier is 0 or
 95            1 cells.
 96        - description: The length of consecutive Device IDs following the
 97            Device ID base
 98          maximum: 0x80000
 99
100  msi-map-mask:
101    description: A mask to be applied to each Device ID prior to being
102      mapped to an msi-specifier per the msi-map property.
103    $ref: /schemas/types.yaml#/definitions/uint32
104    maximum: 0x7ffff
105
106  num-lanes:
107    description: maximum number of lanes
108    $ref: /schemas/types.yaml#/definitions/uint32
109    minimum: 1
110    default: 1
111    maximum: 16
112
113  linux,pci-domain:
114    description:
115      If present this property assigns a fixed PCI domain number to a PCI
116      Endpoint Controller, otherwise an unstable (across boots) unique number
117      will be assigned. It is required to either not set this property at all
118      or set it for all PCI endpoint controllers in the system, otherwise
119      potentially conflicting domain numbers may be assigned to endpoint
120      controllers. The domain number for each endpoint controller in the system
121      must be unique.
122    $ref: /schemas/types.yaml#/definitions/uint32
123
124required:
125  - compatible
126
127additionalProperties: true