Document the use of msi-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-map to associate each child device with a specific msi-specifier.
Include a device tree example illustrating this configuration.
Signed-off-by: Frank Li Frank.Li@nxp.com --- change from v15 to v16 - new patch --- Documentation/devicetree/bindings/pci/pci-msi.txt | 51 +++++++++++++++++++++++ 1 file changed, 51 insertions(+)
diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt index b73d839657b66..6a356707d01fc 100644 --- a/Documentation/devicetree/bindings/pci/pci-msi.txt +++ b/Documentation/devicetree/bindings/pci/pci-msi.txt @@ -218,3 +218,54 @@ Example (5) <0x0000 &msi_b 0x0000 0x10000>; }; }; + +PCI Endpoint +============ + +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 [31:3] for the virtual function index (vfunc) + +The resulting device ID is computed as: + + (func & 0x7) | (vfunc << 3) + +msi-map can map it to an MSI controller and associated msi-specifier data. + +Example EP +========== +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci_ep: pci-ep@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-ep"; + + /* + * The sideband data provided to the MSI controller is + * the device id, function<n> maps to 0x80 + n. + */ + msi-map = <0x0 &msi_a 0x80 0x8>, + }; +};