PCI: Deprecate pcim_iomap_table(), pcim_iomap_regions_request_all()

Deprecate pcim_iomap_table().  It returns a pointer to a table of
ioremapped BARs, or NULL if it fails.  This makes uses like this:

  addr = pcim_iomap_table(pdev)[0];

problematic because it causes a NULL pointer dereference on failure.
Callers should use pcim_iomap() instead.

Deprecate pcim_iomap_regions_request_all() because it is built on
__pci_request_region() and is managed if pcim_enable_device() has been
called, but unmanaged otherwise, which is prone to errors.

Callers should either use pcim_iomap_regions() to request and map BARs, or
use pcim_request_region() followed by pcim_iomap().

Link: https://lore.kernel.org/r/20240613115032.29098-5-pstanner@redhat.com
Signed-off-by: Philipp Stanner <pstanner@redhat.com>
Signed-off-by: Krzysztof Wilczyński <kwilczynski@kernel.org>
[bhelgaas: commit log, sphinx markup]
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>

diff --git a/drivers/pci/devres.c b/drivers/pci/devres.c
index 8388ca463a7a78e1185e72a5f905c14f127e9816..a5957b4cbc0e949b533889c8d77a66b058466898 100644 (file)
--- a/drivers/pci/devres.c
+++ b/drivers/pci/devres.c
@@ -510,7 +510,7 @@ static void pcim_iomap_release(struct device *gendev, void *res)
 }
 
 /**
- * pcim_iomap_table - access iomap allocation table
+ * pcim_iomap_table - access iomap allocation table (DEPRECATED)
  * @pdev: PCI device to access iomap table for
  *
  * Returns:
@@ -524,6 +524,11 @@ static void pcim_iomap_release(struct device *gendev, void *res)
  * This function might sleep when the table is first allocated but can
  * be safely called without context and guaranteed to succeed once
  * allocated.
+ *
+ * This function is DEPRECATED. Do not use it in new code. Instead, obtain a
+ * mapping's address directly from one of the pcim_* mapping functions. For
+ * example:
+ * void __iomem \*mappy = pcim_iomap(pdev, bar, length);
  */
 void __iomem * const *pcim_iomap_table(struct pci_dev *pdev)
 {
@@ -897,6 +902,7 @@ err:
 
 /**
  * pcim_iomap_regions_request_all - Request all BARs and iomap specified ones
+ *                     (DEPRECATED)
  * @pdev: PCI device to map IO resources for
  * @mask: Mask of BARs to iomap
  * @name: Name associated with the requests
@@ -907,6 +913,10 @@ err:
  *
  * To release these resources manually, call pcim_release_region() for the
  * regions and pcim_iounmap() for the mappings.
+ *
+ * This function is DEPRECATED. Don't use it in new code. Instead, use one
+ * of the pcim_* region request functions in combination with a pcim_*
+ * mapping function.
  */
 int pcim_iomap_regions_request_all(struct pci_dev *pdev, int mask,
                                   const char *name)