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 <manivannan.sadhasivam@linaro.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
128