Re: [PATCH v8 5/5] Documentation: PCI: endpoint: Clarify pci_epc_set_bar() usage

[Frank Li <Frank.li@nxp.com>]

On Thu, Jan 15, 2026 at 05:49:28PM +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 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>
> ---
Reviewed-by: Frank Li <Frank.Li@nxp.com>
>  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..4697377adeae 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.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
> --
> 2.51.0
>