linux-kernel - [PATCH 3/3] PCI: endpoint: Document pci_epc_set_bar() caller ownership and lifetime rules

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: <20260131133655.218018-4-den@valinux.co.jp>
Date: Sat, 31 Jan 2026 22:36:55 +0900
From: Koichiro Den <den@...inux.co.jp>
To: mani@...nel.org,
	cassel@...nel.org,
	kwilczynski@...nel.org,
	kishon@...nel.org,
	bhelgaas@...gle.com,
	corbet@....net,
	jingoohan1@...il.com,
	lpieralisi@...nel.org,
	robh@...nel.org,
	Frank.Li@....com
Cc: linux-pci@...r.kernel.org,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: [PATCH 3/3] PCI: endpoint: Document pci_epc_set_bar() caller ownership and lifetime rules

pci_epc_set_bar() may be called multiple times for a BAR when an
endpoint controller supports dynamic_inbound_mapping and/or
subrange_mapping.

Some EPC drivers keep a reference to the struct pci_epf_bar passed to
pci_epc_set_bar(), but the documentation does not describe the ownership
and lifetime rules for that object (and its submap array).

Document that the EPF driver retains ownership of these objects, must
keep them valid, and must not modify them after a successful
pci_epc_set_bar(). When updating an active mapping, the EPF driver must
pass a new pci_epf_bar instance and only free the old one after the
update succeeds.

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 4697377adeae..b2f5ad147ed8 100644
--- a/Documentation/PCI/endpoint/pci-endpoint.rst
+++ b/Documentation/PCI/endpoint/pci-endpoint.rst
@@ -119,6 +119,28 @@ by the PCI endpoint function driver.
    BAR register or BAR decode on the endpoint while the host still expects
    the assigned BAR address to remain valid.
 
+   The struct pci_epf_bar passed to pci_epc_set_bar() (and the optional
+   pci_epf_bar.submap array) is owned by the PCI endpoint function driver.
+   An EPC driver may keep a reference to these objects after
+   pci_epc_set_bar() returns. Therefore the EPF driver must ensure that:
+
+     * Ownership of the pci_epf_bar object passed to pci_epc_set_bar()
+       remains with the caller (the EPF driver). The caller is responsible
+       for ensuring it remains valid (and freeing it when dynamically
+       allocated).
+
+     * After pci_epc_set_bar() succeeds, the caller must not modify the
+       contents of the pci_epf_bar object (or its submap array) until a
+       later successful pci_epc_set_bar() for the same BAR replaces it, or
+       until pci_epc_clear_bar() succeeds. Otherwise, it could potentially
+       lead to use-after-free or undefined behavior.
+
+     * If the caller needs to update the mapping for a BAR and calls
+       pci_epc_set_bar() again, it should use a new pci_epf_bar instance
+       (and a new submap array, if used). If the call succeeds, the old
+       instance can then be freed by the caller. If the call fails, the old
+       instance must remain valid.
+
 * pci_epc_clear_bar()
 
    The PCI endpoint function driver should use pci_epc_clear_bar() to reset
-- 
2.51.0