On Wed, Jan 14, 2026 at 01:27:19AM +0900, Koichiro Den wrote:
> 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 relies on.
> Add document text for that.
>
> Also document the expected call flow for BAR subrange mapping
> (pci_epf_bar.use_submap / pci_epf_bar.submap), which may require
> a second pci_epc_set_bar() call after the host has programmed the BAR base
> address.
>
> Reviewed-by: Niklas Cassel <[email protected]>
> Signed-off-by: Koichiro Den <[email protected]>
> ---
Reviewed-by: Frank Li <[email protected]>
> Documentation/PCI/endpoint/pci-endpoint.rst | 24 +++++++++++++++++++++
> 1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst
> b/Documentation/PCI/endpoint/pci-endpoint.rst
> index 0741c8cbd74e..09b892de9280 100644
> --- a/Documentation/PCI/endpoint/pci-endpoint.rst
> +++ b/Documentation/PCI/endpoint/pci-endpoint.rst
> @@ -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.use_submap is set, 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
> + use_submap cleared to configure the BAR size, then after the PCIe link
> + is up and the host enumerates the endpoint and programs the BAR base
> + address, again with use_submap set.
> +
> + 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
> --
> 2.51.0
>
