tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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: Koichiro Den <den@valinux.co.jp>
Signed-off-by: Manivannan Sadhasivam <mani@kernel.org>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Niklas Cassel <cassel@kernel.org>
Reviewed-by: Frank Li <Frank.Li@nxp.com>
Link: https://patch.msgid.link/20260124145012.2794108-6-den@valinux.co.jp

authored by

Koichiro Den and committed by
Bjorn Helgaas dd3ce166 cc839bef

+24
+24
Documentation/PCI/endpoint/pci-endpoint.rst
··· 95 95 Register space of the function driver is usually configured 96 96 using this API. 97 97 98 + Some endpoint controllers also support calling pci_epc_set_bar() again 99 + for the same BAR (without calling pci_epc_clear_bar()) to update inbound 100 + address translations after the host has programmed the BAR base address. 101 + Endpoint function drivers can check this capability via the 102 + dynamic_inbound_mapping EPC feature bit. 103 + 104 + When pci_epf_bar.num_submap is non-zero, the endpoint function driver is 105 + requesting BAR subrange mapping using pci_epf_bar.submap. This requires 106 + the EPC to advertise support via the subrange_mapping EPC feature bit. 107 + 108 + When an EPF driver wants to make use of the inbound subrange mapping 109 + feature, it requires that the BAR base address has been programmed by 110 + the host during enumeration. Thus, it needs to call pci_epc_set_bar() 111 + twice for the same BAR (requires dynamic_inbound_mapping): first with 112 + num_submap set to zero and configuring the BAR size, then after the PCIe 113 + link is up and the host enumerates the endpoint and programs the BAR 114 + base address, again with num_submap set to non-zero value. 115 + 116 + Note that when making use of the inbound subrange mapping feature, the 117 + EPF driver must not call pci_epc_clear_bar() between the two 118 + pci_epc_set_bar() calls, because clearing the BAR can clear/disable the 119 + BAR register or BAR decode on the endpoint while the host still expects 120 + the assigned BAR address to remain valid. 121 + 98 122 * pci_epc_clear_bar() 99 123 100 124 The PCI endpoint function driver should use pci_epc_clear_bar() to reset