linux-kernel - Re: [PATCH v6 5/5] Documentation: PCI: endpoint: Clarify pci_epc_set

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <aWYbzzAeDSLYJJcB@ryzen>
Date: Tue, 13 Jan 2026 11:17:51 +0100
From: Niklas Cassel <cassel@...nel.org>
To: Koichiro Den <den@...inux.co.jp>
Cc: jingoohan1@...il.com, mani@...nel.org, lpieralisi@...nel.org,
	kwilczynski@...nel.org, robh@...nel.org, bhelgaas@...gle.com,
	vigneshr@...com, s-vadapalli@...com, hongxing.zhu@....com,
	l.stach@...gutronix.de, shawnguo@...nel.org, s.hauer@...gutronix.de,
	kernel@...gutronix.de, festevam@...il.com, minghuan.Lian@....com,
	mingkai.hu@....com, roy.zang@....com, jesper.nilsson@...s.com,
	heiko@...ech.de, srikanth.thokala@...el.com,
	marek.vasut+renesas@...il.com, yoshihiro.shimoda.uh@...esas.com,
	geert+renesas@...der.be, magnus.damm@...il.com,
	christian.bruel@...s.st.com, mcoquelin.stm32@...il.com,
	alexandre.torgue@...s.st.com, thierry.reding@...il.com,
	jonathanh@...dia.com, hayashi.kunihiko@...ionext.com,
	mhiramat@...nel.org, kishon@...nel.org, jirislaby@...nel.org,
	rongqianfeng@...o.com, 18255117159@....com,
	shawn.lin@...k-chips.com, nicolas.frattaroli@...labora.com,
	linux.amoon@...il.com, vidyas@...dia.com, Frank.Li@....com,
	linux-omap@...r.kernel.org, linux-pci@...r.kernel.org,
	linux-arm-kernel@...ts.infradead.org, linux-kernel@...r.kernel.org,
	imx@...ts.linux.dev, linuxppc-dev@...ts.ozlabs.org,
	linux-arm-kernel@...s.com, linux-rockchip@...ts.infradead.org,
	linux-arm-msm@...r.kernel.org, linux-renesas-soc@...r.kernel.org,
	linux-stm32@...md-mailman.stormreply.com,
	linux-tegra@...r.kernel.org
Subject: Re: [PATCH v6 5/5] Documentation: PCI: endpoint: Clarify
 pci_epc_set_bar() usage

On Tue, Jan 13, 2026 at 11:37:15AM +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.
> 
> Signed-off-by: Koichiro Den <den@...inux.co.jp>
> ---
>  Documentation/PCI/endpoint/pci-endpoint.rst | 22 +++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst
> index 0741c8cbd74e..d3d9abbbc71e 100644
> --- a/Documentation/PCI/endpoint/pci-endpoint.rst
> +++ b/Documentation/PCI/endpoint/pci-endpoint.rst
> @@ -95,6 +95,28 @@ 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.
> +
> +   If the EPF driver wants to program inbound subrange mappings that are
> +   based on the BAR base address programmed by the host during enumeration,
> +   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.

"If the EPF driver wants to ..."

Here you have phrased it in a way where it almost seems like this is an
alternative way that you could use this feature.

But in reality, dw_pcie_ep_ib_atu_addr() will return an error if
dw_pcie_ep_read_bar_assigned() does not return an assigned PCI address.

So perhaps write it something like:
"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 ..."


> +
> +   Note that in this flow, 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.

"Note that in this flow, ..."

This also somehow sounds like this is an alternative way, when it is the
only way.

Perhaps simply something like:
"Note that when making use of the inbound subrange mapping feature,
the EPF driver must not call pci_epc_clear_bar() ..."


With that fixed, this looks good to me:
Reviewed-by: Niklas Cassel <cassel@...nel.org>