[PATCH v16 04/15] dt-bindings: pci: pci-msi: Add support for PCI Endpoint msi-map

[Frank Li]

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@xxxxxxx>
---
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>,
+        };
+};

-- 
2.34.1