PCI: endpoint: pci-epf-vntb: Document legacy MSI doorbell offset

vntb_epf_peer_db_set() raises an MSI interrupt to notify the RC side of
a doorbell event. pci_epc_raise_irq(..., PCI_IRQ_MSI, interrupt_num)
takes a 1-based MSI interrupt number.

The ntb_hw_epf driver reserves MSI #1 for link events, so doorbells
would naturally start at MSI #2 (doorbell bit 0 -> MSI #2). However,
pci-epf-vntb has historically applied an extra offset and mapped doorbell
bit 0 to MSI #3. This matches the legacy behavior of ntb_hw_epf and has
been preserved since commit e35f56bb0330 ("PCI: endpoint: Support NTB
transfer between RC and EP").

This offset has not surfaced as a functional issue because:

  - ntb_hw_epf typically allocates enough MSI vectors, so the off-by-one
    still hits a valid MSI vector, and

  - ntb_hw_epf does not implement .db_vector_count()/.db_vector_mask(), so
    client drivers such as ntb_transport effectively ignore the vector
    number and schedule all QPs.

Correcting the MSI number would break interoperability with peers
running older kernels.

Document the legacy offset to avoid confusion when enabling
per-db-vector handling.

Signed-off-by: Koichiro Den <den@valinux.co.jp>
Signed-off-by: Manivannan Sadhasivam <mani@kernel.org>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Frank Li <Frank.Li@nxp.com>
Link: https://patch.msgid.link/20260513024923.451765-2-den@valinux.co.jp

diff --git a/drivers/pci/endpoint/functions/pci-epf-vntb.c b/drivers/pci/endpoint/functions/pci-epf-vntb.c
index d59870fd34302875782f03e087ba43a860131ea3..668d25abc7f28f1dc968043a9ce90bc214ec0560 100644 (file)
--- a/drivers/pci/endpoint/functions/pci-epf-vntb.c
+++ b/drivers/pci/endpoint/functions/pci-epf-vntb.c
@@ -1419,6 +1419,25 @@ static int vntb_epf_peer_db_set(struct ntb_dev *ndev, u64 db_bits)
        func_no = ntb->epf->func_no;
        vfunc_no = ntb->epf->vfunc_no;
 
+       /*
+        * pci_epc_raise_irq() for MSI expects a 1-based interrupt number.
+        * ffs() returns a 1-based index (bit 0 -> 1). interrupt_num has already
+        * been computed as ffs(db_bits) + 1 above. Adding one more +1 when
+        * calling pci_epc_raise_irq() therefore results in:
+        *
+        *   doorbell bit 0 -> MSI #3
+        *
+        * Legacy mapping (kept for compatibility):
+        *
+        *   MSI #1 : link event (reserved)
+        *   MSI #2 : unused (historical offset)
+        *   MSI #3 : doorbell bit 0 (DB#0)
+        *   MSI #4 : doorbell bit 1 (DB#1)
+        *   ...
+        *
+        * Do not change this mapping to avoid breaking interoperability with
+        * older peers.
+        */
        ret = pci_epc_raise_irq(ntb->epf->epc, func_no, vfunc_no,
                                PCI_IRQ_MSI, interrupt_num + 1);
        if (ret)