On Mon, Apr 07, 2025 at 03:50:54PM -0400, Frank Li wrote: > 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: Frank Li <frank...@nxp.com> > --- > Change from v16 to v17 > - new patch > --- > Documentation/devicetree/bindings/pci/pci-ep.yaml | 67 > +++++++++++++++++++++++ > 1 file changed, 67 insertions(+) > > diff --git a/Documentation/devicetree/bindings/pci/pci-ep.yaml > b/Documentation/devicetree/bindings/pci/pci-ep.yaml > index f75000e3093db..a1a5b9b8ef859 100644 > --- a/Documentation/devicetree/bindings/pci/pci-ep.yaml > +++ b/Documentation/devicetree/bindings/pci/pci-ep.yaml > @@ -53,6 +53,73 @@ properties: > must be unique. > $ref: /schemas/types.yaml#/definitions/uint32 > > + msi-map:
Not that the rest of the file is alphabetized, but put i before m. > + 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 ? > + > + 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: 0xffff 0x7ffff ? > + > required: > - compatible > > > -- > 2.34.1 >
