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

Frank Li
2026-01-15T15:24:34Z

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
>