Commit dd3ce166 authored by Koichiro Den's avatar Koichiro Den Committed by Bjorn Helgaas
Browse files

Documentation: PCI: endpoint: Clarify pci_epc_set_bar() usage 



The current documentation implies that pci_epc_set_bar() is only used
before the host enumerates the endpoint.

In practice, some Endpoint Controllers support calling pci_epc_set_bar()
multiple times for the same BAR (without clearing it) in order to update
inbound address translations after the host has programmed the BAR base
address, which some Endpoint Functions such as vNTB already rely on.
Add document text for that.

Also document the expected call flow for BAR subrange mapping
(pci_epf_bar.num_submap / pci_epf_bar.submap), which may require a
second pci_epc_set_bar() call after the host has programmed the BAR base
address.

Signed-off-by: default avatarKoichiro Den <den@valinux.co.jp>
Signed-off-by: default avatarManivannan Sadhasivam <mani@kernel.org>
Signed-off-by: default avatarBjorn Helgaas <bhelgaas@google.com>
Reviewed-by: default avatarNiklas Cassel <cassel@kernel.org>
Reviewed-by: default avatarFrank Li <Frank.Li@nxp.com>
Link: https://patch.msgid.link/20260124145012.2794108-6-den@valinux.co.jp
parent cc839bef

Documentation/PCI/endpoint/pci-endpoint.rst

+24 −0
Original line number Diff line number Diff line
@@ -95,6 +95,30 @@ by the PCI endpoint function driver. 
   Register space of the function driver is usually configured

   using this API.



   Some endpoint controllers also support calling pci_epc_set_bar() again

   for the same BAR (without calling pci_epc_clear_bar()) to update inbound

   address translations after the host has programmed the BAR base address.

   Endpoint function drivers can check this capability via the

   dynamic_inbound_mapping EPC feature bit.



   When pci_epf_bar.num_submap is non-zero, the endpoint function driver is

   requesting BAR subrange mapping using pci_epf_bar.submap. This requires

   the EPC to advertise support via the subrange_mapping EPC feature bit.



   When an EPF driver wants to make use of the inbound subrange mapping

   feature, it requires that the BAR base address has been programmed by

   the host during enumeration. Thus, it needs to call pci_epc_set_bar()

   twice for the same BAR (requires dynamic_inbound_mapping): first with

   num_submap set to zero and configuring the BAR size, then after the PCIe

   link is up and the host enumerates the endpoint and programs the BAR

   base address, again with num_submap set to non-zero value.



   Note that when making use of the inbound subrange mapping feature, the

   EPF driver must not call pci_epc_clear_bar() between the two

   pci_epc_set_bar() calls, because clearing the BAR can clear/disable the

   BAR register or BAR decode on the endpoint while the host still expects

   the assigned BAR address to remain valid.



* pci_epc_clear_bar()



   The PCI endpoint function driver should use pci_epc_clear_bar() to reset